Tools and diagnostics

The @lomi-dev/plugin-cli package provides four commands: check, build, package and doctor. Run them inside the plugin project, next to package.json. This page describes CLI 0.1.0-alpha.2 with SDK 1.1.0-alpha.1.

Commands

Template script	Direct invocation	Result
`pnpm check`	`pnpm exec lomi-plugin check`	TypeScript, manifest and input assets; no bundle inspection
`pnpm build`	`pnpm exec lomi-plugin build`	Input checks, compilation and complete `package/` validation
`pnpm package`	`pnpm exec lomi-plugin package`	Build and verified ZIP, SHA-256 and JSON artifacts
`pnpm run doctor`	`pnpm exec lomi-plugin doctor`	Author environment and available application metadata

Supported flags are --json, --help / -h, --version / -v, and --app <path> for doctor only. There is no project-directory argument, --watch, dev or publish. Use cd to enter the project first.

Build configuration

The optional lomi-plugin.config.mjs is a Node module with a default export:

import { defineConfig } from '@lomi-dev/plugin-cli';

export default defineConfig({
  entry: 'src/index.tsx',
  manifest: 'plugin.json',
  assets: ['view.css', 'LICENSE'],
});

Field	Default	Meaning
`entry`	`src/index.tsx`	TypeScript/TSX or JavaScript source; used when the manifest has an `entry`
`manifest`	`plugin.json`	Input manifest; copied into output as `plugin.json`
`assets`	`[]`	Unique existing file or directory paths, copied without changing their relative paths

Globs and other configuration fields are unsupported. CLI output goes to package/. defineConfig() provides type assistance; CLI commands perform validation. Configuration executes in Node, so it is executable code.

Every declared stylesheet must be included in assets, directly or inside a copied directory. Include the entire theme directory with theme.jsonc and its resources. The CLI requires v2 JSONC themes even though Lomi’s importer also accepts the legacy format.

Do not copy src, tests, node_modules, .git, .github, .env, .ts, .tsx or manually supplied .map files. Assets cannot collide with generated plugin.json or dist/. Build-generated source maps are allowed.

Source versus output

Configuration entry selects the source; manifest entry selects the output. For example:

lomi-plugin.config.mjs → entry: src/main.tsx
plugin.json           → entry: dist/plugin.mjs
package/              → dist/plugin.mjs

The current build helper derives the output filename and extension from the manifest. Do not put a .tsx entry there. Dependencies must work in a browser: npm libraries are bundled, while React and the SDK use Lomi’s instances.

Local archives before npm publication

This workflow uses local sources without requiring published Lomi packages. Place matching plugin-sdk, plugin-tools and create-lomi-plugin checkouts in one directory. Start in their parent directory:

mkdir plugin-archives
pnpm --dir plugin-sdk install --frozen-lockfile
pnpm --dir plugin-sdk build
pnpm --dir plugin-sdk pack --pack-destination ../plugin-archives
pnpm --dir plugin-tools/packages/cli pack --pack-destination ../../../plugin-archives
node create-lomi-plugin/index.mjs my-plugin --id example.workspace-info --name "Workspace info" --template panel
cd my-plugin
pnpm add -D --save-exact --ignore-scripts @lomi-dev/plugin-sdk@file:../plugin-archives/lomi-dev-plugin-sdk-1.1.0-alpha.1.tgz @lomi-dev/plugin-cli@file:../plugin-archives/lomi-dev-plugin-cli-0.1.0-alpha.2.tgz
pnpm check
pnpm run doctor
pnpm package

pnpm add installs project dependencies and replaces the SDK/CLI pins with file: archive references. Keep those archives and the lockfile to reproduce the environment. Other dependencies still require registry access or a populated cache. The completed package/ needs neither source repositories nor node_modules.

This is a local development setup. Once the reviewed compatible package set is published, switch to exact npm versions and update the lockfile. Do not distribute author projects containing paths to your own source checkouts.

Doctor

pnpm exec lomi-plugin doctor --json --app /Applications/Lomi.app

On Windows or Linux, supply the application’s actual installed path. Without --app, doctor only attempts automatic detection of /Applications/Lomi.app on macOS. It neither launches nor repairs the application. On macOS it can read Info.plist; finding a file on other platforms does not establish compatibility.

Checks cover Node, SDK, TypeScript, React/React DOM versions and whether the project and SDK resolve the same React copy. Missing React in a theme-only project is a warning. Warnings can accompany exit code 0; HOST_UNVERIFIED does not confirm desktop behavior.

JSON and exit codes

pnpm exec lomi-plugin check --json

Success uses { schemaVersion: 1, command, ok: true, result }. Execution errors use { schemaVersion: 1, command, ok: false, diagnostics }. Each diagnostic has code, message, file and hint. Doctor stores checks in result.checks, with ok, warning or error statuses.

Exit code	Meaning
`0`	Command succeeded; also review doctor warnings
`1`	Project, execution or doctor check failure
`2`	Invalid CLI arguments

Common diagnostics

Code	Action
`CLI_ARGUMENT`	Check the command and flags with `--help`
`CLI_INTERRUPTED`	Command interrupted; inspect the last good output before retrying
`SDK_VERSION`	Install compatible SDK 1.1.0-alpha.1 from npm or a local archive
`PLUGIN_CONFIG`	Remove unsupported fields; check the default export and unique assets
`PLUGIN_MANIFEST`	Fix JSON, fields, namespaces and contribution references
`PLUGIN_ENTRY`	Check the configured source entry exists
`PLUGIN_TYPES`	Fix the reported TypeScript errors
`PLUGIN_ASSET`	Include missing resources; remove symlinks or disallowed package files
`PLUGIN_THEME`	Check `theme.jsonc`, `version: 2`, name and appearance
`PLUGIN_BUILD`	Check Node/private imports, nonliteral dynamic imports and output completeness
`PLUGIN_PACKAGE`	Ensure `artifacts/` is a regular directory
`PLUGIN_RELEASE_EXISTS`	Increase the manifest version or deliberately move previous artifacts
`NODE_VERSION`	Use Node 22.14+
`DEPENDENCY_VERSION`, `DEPENDENCY_MISSING`	Match or install the reported dependency
`REACT_DUPLICATE`	Align React and React DOM to 19.2.8 and reinstall
`HOST_MISSING`	Check `--app`; building remains possible without the application
`HOST_TOO_OLD`, `HOST_VERSION`	Check the application against the 0.4.0 source baseline and its runtime
`HOST_UNVERIFIED`	Complete manual desktop qualification in Lomi
`CLI_FAILURE`	Read `message` and `file`; this fallback can indicate filesystem errors

CI and interrupted builds

The generated workflow installs with the lockfile, runs check and package, then retains artifacts/. Commit the lockfile. Make local file: archives available in CI or switch to published versions. A successful CI ZIP still needs desktop qualification.

Ordinary build failures keep the last good package and clean up temporary files. After a process crash, first check that no build is running. Then inspect package.lomi-lock and .lomi-build-*; a directory ending in -previous may contain the previous output. Do not remove a running build’s lock or the only good package copy.