AppOS Plugin SDK

Developer-facing packages for building plugins for AppOS. Type-safe, ergonomic, zero runtime overhead where it matters.

Packages

Package	Purpose	Runtime
@appos.space/plugin-types	TypeScript definitions for the full Plugin API (43 namespaces, 135 canonical permission scopes).	declaration-only
@appos.space/view-builders	Typed builders for ViewDescriptor — vstack(), section(), listItem(), etc.	plain object literals (tree-shakeable)
@appos.space/plugin-utils	Pure utility functions — path conversion, formatting, action routing, debounce.	pure functions

Install (for plugin authors)

npm install --save-dev @appos.space/plugin-types
npm install @appos.space/view-builders @appos.space/plugin-utils

Minimal example:

import type { PluginContext } from "@appos.space/plugin-types";
import { vstack, section, listItem, button } from "@appos.space/view-builders";
import { formatSize } from "@appos.space/plugin-utils";

export async function activate(ctx: PluginContext) {
  const files = await ctx.fs.readDir(await ctx.fs.home());

  ctx.ui.render(
    vstack([
      section("Home", { icon: "house" },
        files.map((f) =>
          listItem(f.name, { badge: formatSize(f.size), action: `open:${f.name}` }),
        ),
      ),
      button("Refresh", { action: "refresh", style: "primary" }),
    ]),
  );
}

Repo layout

plugin-sdk/
├── packages/
│   ├── plugin-types/     # @appos.space/plugin-types
│   ├── view-builders/    # @appos.space/view-builders
│   └── plugin-utils/     # @appos.space/plugin-utils
├── schemas/              # JSON Schema for plugin.json
└── scripts/              # build / sync / validate helpers

Development

npm install          # install workspace deps
npm run build        # build all packages
npm test             # run all tests
npm run lint         # type-check all packages

Each package uses files: ["dist"] as its npm allowlist, so only compiled declarations (and JS, where applicable) ship to consumers.

Versioning

Package versions track the plugin API version. 3.0.x of plugin-types corresponds to the AppOS 1.0.0 host surface (waves fn-70 .. fn-101 + fn-118). Earlier 2.4.x releases cover only the pre-fn-70 legacy tier (22 namespaces).

License

MIT © InstantlyEasy — see LICENSE.