Skip to content

PLUGINS.md

Latest commit

 

History

History
106 lines (83 loc) · 3.34 KB

PLUGINS.md

File metadata and controls

106 lines (83 loc) · 3.34 KB
Raw

Veris Plugin Guide

Plugins extend Veris without forking. They live at <repo>/.veris/plugins/*.{js,mjs,cjs} and run in-process as local Node modules.

Trust model: same as require(). Veris does not sandbox plugins. Don't load plugins from sources you would not load any other Node module from.

Quick start

veris init
ls .veris/plugins/

Rename example.js.disabled to example.js, then re-run veris ..

API

interface PluginApi {
    addWorkflowRule(rule: ExternalWorkflowRule): void;
    addRuntimeRisks(kind: string, risks: string[]): void;
    addRiskHeuristic(fn: (ctx: HeuristicCtx) => RiskHeuristicPatch | null): void;
    addLanguageAdapter(adapter: LanguageAdapterPlugin): void;
    log(msg: string): void;
}

interface ExternalWorkflowRule {
    kind: string;              // 'Payments', 'Authentication', or any new string
    pathTokens?: string[];     // matched as case-insensitive substrings of file paths
    importTokens?: string[];   // matched as substrings of imported module specifiers
    symbolTokens?: string[];   // matched against class/method/function names (lowercased)
    weight?: number;           // default 1; path matches are 2× weighted, imports 3×, symbols 1×
}

Built-in WorkflowKinds

These are reserved kinds with built-in runtime risk templates:

Authentication, Authorization, Session, Billing, Payments, Checkout, Cart, Notifications, Webhooks, Messaging, Realtime, Queue, Caching, Persistence, Sync, Search, Onboarding, Profile, Admin, Analytics, AI, Routing, Orchestration, Reporting, Configuration, Infrastructure, Core, Uncategorized

Custom kinds work too — they appear in the dashboard, but without baseline runtime risks until you supply them with addRuntimeRisks.

Examples

Vertical reinforcement

module.exports.register = function (api) {
    api.addWorkflowRule({
        kind: 'Payments',
        pathTokens: ['ledger', 'reconcile'],
        importTokens: ['stripe', '@adyen/'],
        weight: 3
    });
    api.addRuntimeRisks('Payments', [
        '3DS challenge response lost on tab close',
        'settlement file double-import on resubmit'
    ]);
};

Custom kind

module.exports.register = function (api) {
    api.addWorkflowRule({
        kind: 'IoTFleet',
        pathTokens: ['fleet', 'device'],
        importTokens: ['aws-iot-device-sdk', '@azure/event-hubs'],
        symbolTokens: ['provision', 'rotatecert', 'firmwareupdate']
    });
    api.addRuntimeRisks('IoTFleet', [
        'cert rotation race with intermittent device',
        'OTA rollback on partial firmware apply'
    ]);
};

Risk heuristic

module.exports.register = function (api) {
    api.addRiskHeuristic((ctx) => {
        if (ctx.node.label.toLowerCase().endsWith('migration')) {
            return {
                nodeId: ctx.node.id,
                deltas: { runtimeCriticality: 20 },
                explanation: 'Schema migration: criticality boost.'
            };
        }
        return null;
    });
};

Disabling

VERIS_PLUGINS_DISABLED=1 skips plugin loading entirely. Useful in CI when you want deterministic runs.

Roadmap

  • Plugin manifest (veris-plugin.json) for versioning and capability declarations.
  • Plugin marketplace / index.
  • TypeScript plugin support without precompile (currently .js/.mjs/.cjs).
  • Hot-reload during veris watch (planned).