@systemlabs/foundation-plugin-sdk

@systemlabs/foundation-plugin-sdk

The public contract for building Foundation CLI plugins and modules.

This package contains zero runtime dependencies beyond AJV for schema validation. It is the only package you need to import when authoring a plugin — it defines all types, the manifest schema, and the validateManifest() helper.

npm install @systemlabs/foundation-plugin-sdk

What's in this package

Export	Description
PluginDefinition	Top-level type you export from your plugin entry point
ModuleManifest	Full manifest schema interface
validateManifest()	Validates a manifest object against the JSON Schema
All hook types	OnRegisterHook, OnFinalizeHook, OnGenerateHook, etc.
ORMModelDefinition	Provider-agnostic model format for ORM integration
ORMRelationDefinition	Relation type (many-to-one, one-to-many, etc.)
FileEntry, ConfigPatch	File and config contribution types

Defining a plugin

import type { PluginDefinition } from '@systemlabs/foundation-plugin-sdk';

const plugin: PluginDefinition = {
  manifest: {
    id:          'my-plugin',
    name:        'My Plugin',
    version:     '1.0.0',
    category:    'addon',
    description: 'Does something useful.',
    runtime:     'node',
    provides:    ['my-plugin:client'],
    requires:    [],
    dependencies: [
      { name: 'some-package', version: '^2.0.0', dev: false }
    ],
    files: [
      { path: 'src/my-plugin/client.ts', template: 'client.ts.ejs' }
    ],
    configPatches: [],
    compatibility: {},
  },

  hooks: {
    onFinalize: async (ctx) => {
      ctx.logger.info('my-plugin installed — add YOUR_API_KEY to .env');
    },
  },
};

export default plugin;

Manifest fields

interface ModuleManifest {
  id:          string;                  // unique, kebab-case
  name:        string;                  // human-readable
  version:     string;                  // semver
  category:    ModuleCategory;          // see below
  description: string;
  runtime?:    'node' | 'python' | 'multi';
  provides?:   string[];               // capability tokens this module satisfies
  requires?:   string[];               // capability tokens this module needs
  dependencies:   PackageDependency[];
  files:          FileEntry[];
  configPatches:  ConfigPatch[];
  compatibility: {
    conflicts?:       string[];         // module IDs that cannot coexist
    compatibleWith?:  Record<string, string[]>;
    peerFrameworks?:  Record<string, string>;
  };
}

type ModuleCategory =
  | 'frontend' | 'backend' | 'database' | 'orm'
  | 'auth'     | 'ui'      | 'state'    | 'deployment'
  | 'addon'    | 'generate'| 'testing'  | 'tooling';

Lifecycle hooks

Your plugin can export any of these hooks from the hooks key:

Hook	Fires when
onRegister	Registry loads your plugin — register ORM providers here
onBeforeCompose	Before template rendering — inject dynamic template variables
onAfterTemplate	After render, before file merge — post-process rendered files
onMerge	During config merge — supply custom merge logic
onAfterCompose	After all files are staged — cross-module wiring
beforeWrite	Before the file-write transaction commits
afterWrite	After the file-write transaction commits
beforeInstall	Before the package manager runs
afterInstall	After package installation completes
onFinalize	After full success — print post-install instructions
onRollback	On any failure — clean up side-effects
onGenerate	Before generator writes files — extend generated output
onStart	When foundation dev is invoked
onBuild	When foundation build is invoked

Validating a manifest

import { validateManifest } from '@systemlabs/foundation-plugin-sdk';

const result = validateManifest(myManifest);
if (!result.valid) {
  console.error(result.errors);
}

ORM integration

If your plugin contributes a model to the active ORM, use the portable model format — the active ORM provider will translate it to provider-specific output automatically:

hooks: {
  onRegister: async (ctx) => {
    ctx.registry.orm.registerModel({
      id:   'my-plugin.Record',
      name: 'Record',
      fields: [
        { name: 'id',        type: 'uuid',   primaryKey: true, generated: true },
        { name: 'payload',   type: 'string', required: true },
        { name: 'createdAt', type: 'date',   generated: true },
      ],
      relations: [],
    }, 'my-plugin');
  },
}

Publishing a plugin to npm

Your plugin package must include foundation-plugin in its keywords array so foundation search can discover it:

{
  "name": "foundation-plugin-my-plugin",
  "keywords": ["foundation-plugin"]
}

Install it in any Foundation project with:

foundation add foundation-plugin-my-plugin

Part of the Foundation CLI ecosystem

Package	Description
@systemlabs/foundation-cli	User-facing CLI — foundation create, add, generate, etc.
@systemlabs/foundation-core	Engine: dependency resolver, composition planner, file transaction
@systemlabs/foundation-modules	All built-in modules (frontend, backend, database, auth, …)
@systemlabs/foundation-plugin-sdk	← you are here — plugin contract, types, manifest schema
@systemlabs/foundation-testing	Test utilities for module and plugin authors

License

MIT — see LICENSE