SDK workflows

omena-css exposes the same snapshot-bound workflows through NAPI, WASM, the omena process, and the Rust LSP. The IDL in contracts/engine-sdk-workflow/main.tsp owns request, response, partition, and typed error envelopes.

For CSS Modules, emitted tokens are not a contract; typed classExports, typed valueExports, family-tagged namedExports, and the generated .d.ts are. Same-named class and ICSS value exports remain separate instead of collapsing into one binding. Hand-writing an emitted token into markup, tests, or CSS is unsupported.

Registry Availability

The coordinated NAPI and WASM packages expose the snapshot-bound workflow surface at the same release version.

Install

npm install @omena/napi@0.5.0
npm install @omena/wasm@0.5.0
cargo install omena-cli --locked

Workflow Matrix

This table is generated from the TypeSpec request models and checked against the repository's four-surface parity matrix. It describes source-level contract coverage; it is not a registry-availability claim.

Every operation after snapshot carries its snapshotId. A request against a different or stale workspace snapshot fails as a typed workspace error instead of reading mutable state implicitly.

NAPI

The published NAPI package uses JSON strings at the binding edge:

const { checkStyleSourceJson } = require("@omena/napi");

const report = JSON.parse(
  checkStyleSourceJson(".button { color: royalblue; }", "button.module.css"),
);

The Node package also exposes a snapshot-bound Workspace for clients that need repeated queries against one immutable snapshot.

WASM

The published WASM package is a bundler-target module. Importing it starts the module; there is no default init() export. It uses in-memory JavaScript values and performs no filesystem access:

import { Workspace } from "@omena/wasm";

const sources = [{ stylePath: "button.module.css", styleSource: ".button {}" }];
const workspace = new Workspace("/workspace", sources);
const snapshot = workspace.snapshot();
const diagnostics = workspace.diagnostics({
  snapshotId: snapshot.snapshotId,
  stylePath: sources[0].stylePath,
  styleSource: sources[0].styleSource,
});

The browser playground loads a web-target build of this same crate and demonstrates workspace diagnostics, semantic transforms, and target-aware builds without uploading source. Its examples use caller-supplied in-memory files and deliberately omit filesystem discovery and host-specific workspace resolution.

CLI

The process surface accepts one workflow request file and returns a standard CLI response envelope:

omena sdk request.json

The request contains workspaceRoot, styleSources, operation, and the typed request payload. JSON output wraps the workflow response in omena-cli.sdk-workflow metadata.

workspaceRoot is required on bundler-host resolve requests. Clients upgrading from the earlier request shape must add it explicitly and keep the value stable across workspace relocation; Omena uses that boundary to derive portable CSS Module identity. A component-bounded path inside the root keeps its caller-visible spelling even when it traverses a link; a path outside that lexical boundary is accepted only when its canonical target is inside the canonical root.

CSS Module token-integrity enforcement is opt-in. Strict mode rejects output when selected interface tokens and emitted bytes disagree or ownership analysis is incomplete. Descriptive mode reports the same census and reasons without rejecting output, so callers that do not select Strict are not guaranteed to fail closed on an incomplete carrier.

LSP

After initialize, send omena/sdkWorkflow with workspaceRoot, operation, and request. The response uses the same public partition and snapshot identity as diagnostics published for the opened document.

Responses And Errors

Public responses contain stable workflow output. Debug partitions may include analysis details and are not a substitute for the public contract. Typed errors carry a class, code, severity, recoverability, and optional query/input evidence.

The shared classes cover input, workspace, resolution, analysis, transform, unsupported, internal, and unknown failures. Consumers should branch on typed fields, not parse message text.

Lower-Level Bindings

The workflow layer is the cross-surface starting point. Binding-specific and lower-level query/build calls remain documented in:

• omena-napi
• omena-wasm
• CLI commands
• Rust LSP API