@nself/plugin-sdk 1.2.4

package/README.md

@@ -0,0 +1,45 @@
+# @nself/plugin-sdk
+
+TypeScript/Node.js plugin authoring SDK for [nSelf](https://nself.org). Parity with
+[plugin-sdk-go](https://github.com/nself-org/plugin-sdk-go) v0.1.0.
+
+## Install
+
+```bash
+pnpm add @nself/plugin-sdk
+```
+
+## Quick start
+
+```ts
+import { definePlugin, type PluginContext } from '@nself/plugin-sdk'
+
+export default definePlugin({
+  name: 'my-notify',
+  version: '1.0.0',
+
+  async install(ctx: PluginContext) {
+    await ctx.env.require(['SMTP_HOST', 'SMTP_PORT'])
+  },
+
+  async start(ctx: PluginContext) {
+    const app = ctx.http.createApp()
+    app.post('/notify/send', myHandler)
+    ctx.http.listen(ctx.port)
+  },
+
+  async health(ctx: PluginContext) {
+    return ctx.http.ping('/notify/healthz')
+  },
+})
+```
+
+## Scaffold a plugin
+
+```bash
+nself plugin new my-plugin --lang typescript
+```
+
+## License
+
+MIT

package/dist/context/db.d.ts

@@ -0,0 +1,26 @@
+/**
+ * PostgreSQL helper — migration-time DDL only.
+ * Mirrors db.Pool in plugin-sdk-go: wraps pg driver, exposes runSQL().
+ * NOT for query-time use — plugins must talk to Hasura GraphQL at runtime.
+ */
+/** Minimal row result from a migration query. */
+export interface SqlResult {
+    rowCount: number;
+    rows: Record<string, unknown>[];
+}
+export interface DatabaseHelper {
+    /**
+     * runSQL executes raw SQL. Use only in install/migrate/uninstall hooks.
+     * Never call during request handling — that goes through Hasura.
+     */
+    runSQL(sql: string, params?: unknown[]): Promise<SqlResult>;
+    /** Close the underlying connection pool. Called automatically by the runner. */
+    close(): Promise<void>;
+}
+export interface DatabaseHelperOptions {
+    databaseUrl: string;
+}
+export declare function createDatabaseHelper(opts: DatabaseHelperOptions): Promise<DatabaseHelper>;
+/** Stub implementation for use in unit tests — no real DB needed. */
+export declare function createDatabaseHelperStub(): DatabaseHelper;
+//# sourceMappingURL=db.d.ts.map

package/dist/context/db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/context/db.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,iDAAiD;AACjD,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAA;CAChC;AAED,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA;IAE3D,gFAAgF;IAChF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AAED,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,cAAc,CAAC,CAoB/F;AAED,qEAAqE;AACrE,wBAAgB,wBAAwB,IAAI,cAAc,CAOzD"}

package/dist/context/db.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * PostgreSQL helper — migration-time DDL only.
+ * Mirrors db.Pool in plugin-sdk-go: wraps pg driver, exposes runSQL().
+ * NOT for query-time use — plugins must talk to Hasura GraphQL at runtime.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDatabaseHelper = createDatabaseHelper;
+exports.createDatabaseHelperStub = createDatabaseHelperStub;
+async function createDatabaseHelper(opts) {
+    // Dynamic import so pg remains a peer dep (optional at install time).
+    // Plugins that don't run migrations never need pg installed.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { Pool } = require('pg');
+    const pool = new Pool({ connectionString: opts.databaseUrl });
+    return {
+        async runSQL(sql, params) {
+            const res = await pool.query(sql, params);
+            return {
+                rowCount: res.rowCount ?? 0,
+                rows: res.rows,
+            };
+        },
+        async close() {
+            await pool.end();
+        },
+    };
+}
+/** Stub implementation for use in unit tests — no real DB needed. */
+function createDatabaseHelperStub() {
+    return {
+        async runSQL(_sql, _params) {
+            return { rowCount: 0, rows: [] };
+        },
+        async close() { },
+    };
+}
+//# sourceMappingURL=db.js.map

package/dist/context/db.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.js","sourceRoot":"","sources":["../../src/context/db.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AAuBH,oDAoBC;AAGD,4DAOC;AA9BM,KAAK,UAAU,oBAAoB,CAAC,IAA2B;IACpE,sEAAsE;IACtE,6DAA6D;IAC7D,iEAAiE;IACjE,MAAM,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,IAAI,CAAwB,CAAA;IACrD,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,EAAE,gBAAgB,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAA;IAE7D,OAAO;QACL,KAAK,CAAC,MAAM,CAAC,GAAW,EAAE,MAAkB;YAC1C,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;YACzC,OAAO;gBACL,QAAQ,EAAE,GAAG,CAAC,QAAQ,IAAI,CAAC;gBAC3B,IAAI,EAAE,GAAG,CAAC,IAAiC;aAC5C,CAAA;QACH,CAAC;QAED,KAAK,CAAC,KAAK;YACT,MAAM,IAAI,CAAC,GAAG,EAAE,CAAA;QAClB,CAAC;KACF,CAAA;AACH,CAAC;AAED,qEAAqE;AACrE,SAAgB,wBAAwB;IACtC,OAAO;QACL,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO;YACxB,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAA;QAClC,CAAC;QACD,KAAK,CAAC,KAAK,KAAI,CAAC;KACjB,CAAA;AACH,CAAC"}

package/dist/context/env.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Env var helpers — mirrors config.Env / config.EnvRequired in plugin-sdk-go.
+ */
+/** Env helper interface exposed in PluginContext. */
+export interface EnvHelper {
+    /**
+     * get returns the env var value or the default.
+     * Missing + no default → undefined.
+     */
+    get(key: string, defaultValue?: string): string | undefined;
+    /**
+     * require asserts that all named env vars are non-empty.
+     * Throws on first missing var — fail-fast at install/start time.
+     */
+    require(keys: string[]): void;
+    /** getInt returns the env var parsed as an integer, or the default. */
+    getInt(key: string, defaultValue: number): number;
+    /** getBool returns the env var parsed as boolean ("1"/"true"/"yes" → true). */
+    getBool(key: string, defaultValue: boolean): boolean;
+    /** getList splits the env var on commas and trims whitespace. */
+    getList(key: string): string[];
+}
+export declare function createEnvHelper(): EnvHelper;
+//# sourceMappingURL=env.d.ts.map

package/dist/context/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/context/env.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,qDAAqD;AACrD,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;IAE3D;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;IAE7B,uEAAuE;IACvE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAAA;IAEjD,+EAA+E;IAC/E,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,GAAG,OAAO,CAAA;IAEpD,iEAAiE;IACjE,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;CAC/B;AAED,wBAAgB,eAAe,IAAI,SAAS,CAuC3C"}

package/dist/context/env.js

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * Env var helpers — mirrors config.Env / config.EnvRequired in plugin-sdk-go.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEnvHelper = createEnvHelper;
+function createEnvHelper() {
+    return {
+        get(key, defaultValue) {
+            const v = process.env[key];
+            if (v !== undefined && v !== '')
+                return v;
+            return defaultValue;
+        },
+        require(keys) {
+            for (const key of keys) {
+                if (!process.env[key] || process.env[key] === '') {
+                    throw new Error(`plugin SDK: required env var ${key} is not set`);
+                }
+            }
+        },
+        getInt(key, defaultValue) {
+            const v = process.env[key];
+            if (!v)
+                return defaultValue;
+            const n = parseInt(v, 10);
+            return isNaN(n) ? defaultValue : n;
+        },
+        getBool(key, defaultValue) {
+            const v = (process.env[key] ?? '').toLowerCase();
+            if (['true', '1', 'yes', 'y', 'on'].includes(v))
+                return true;
+            if (['false', '0', 'no', 'n', 'off'].includes(v))
+                return false;
+            return defaultValue;
+        },
+        getList(key) {
+            const v = process.env[key];
+            if (!v)
+                return [];
+            return v
+                .split(',')
+                .map((s) => s.trim())
+                .filter(Boolean);
+        },
+    };
+}
+//# sourceMappingURL=env.js.map

package/dist/context/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/context/env.ts"],"names":[],"mappings":";AAAA;;GAEG;;AA0BH,0CAuCC;AAvCD,SAAgB,eAAe;IAC7B,OAAO;QACL,GAAG,CAAC,GAAW,EAAE,YAAqB;YACpC,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YAC1B,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,EAAE;gBAAE,OAAO,CAAC,CAAA;YACzC,OAAO,YAAY,CAAA;QACrB,CAAC;QAED,OAAO,CAAC,IAAc;YACpB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;gBACvB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC;oBACjD,MAAM,IAAI,KAAK,CAAC,gCAAgC,GAAG,aAAa,CAAC,CAAA;gBACnE,CAAC;YACH,CAAC;QACH,CAAC;QAED,MAAM,CAAC,GAAW,EAAE,YAAoB;YACtC,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YAC1B,IAAI,CAAC,CAAC;gBAAE,OAAO,YAAY,CAAA;YAC3B,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;YACzB,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;QACpC,CAAC;QAED,OAAO,CAAC,GAAW,EAAE,YAAqB;YACxC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAA;YAChD,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;gBAAE,OAAO,IAAI,CAAA;YAC5D,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;gBAAE,OAAO,KAAK,CAAA;YAC9D,OAAO,YAAY,CAAA;QACrB,CAAC;QAED,OAAO,CAAC,GAAW;YACjB,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YAC1B,IAAI,CAAC,CAAC;gBAAE,OAAO,EAAE,CAAA;YACjB,OAAO,CAAC;iBACL,KAAK,CAAC,GAAG,CAAC;iBACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;iBACpB,MAAM,CAAC,OAAO,CAAC,CAAA;QACpB,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/context/hasura.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Hasura metadata API wrapper for install/migrate/uninstall hooks.
+ * Mirrors the HasuraHelper concept from the spec: addTable, trackRelationship,
+ * runMigration. Uses the Hasura Metadata API v3.
+ */
+export interface TrackRelationshipOptions {
+    fromTable: string;
+    name: string;
+    type: 'object' | 'array';
+    toTable: string;
+    fromColumn: string;
+    toColumn: string;
+}
+export interface HasuraHelper {
+    /** Track a new table in Hasura metadata. */
+    addTable(schema: string, table: string): Promise<void>;
+    /** Untrack a table from Hasura metadata. */
+    removeTable(schema: string, table: string): Promise<void>;
+    /** Add a relationship between two tracked tables. */
+    trackRelationship(opts: TrackRelationshipOptions): Promise<void>;
+    /** Run raw Hasura metadata API request (escape hatch). */
+    runMetadata(type: string, args: Record<string, unknown>): Promise<unknown>;
+    /** Run a SQL migration via Hasura's run_sql API. */
+    runSql(sql: string): Promise<void>;
+}
+export declare function createHasuraHelper(adminSecret: string, endpoint: string): HasuraHelper;
+//# sourceMappingURL=hasura.d.ts.map

package/dist/context/hasura.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hasura.d.ts","sourceRoot":"","sources":["../../src/context/hasura.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAA;IACxB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEtD,4CAA4C;IAC5C,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEzD,qDAAqD;IACrD,iBAAiB,CAAC,IAAI,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEhE,0DAA0D;IAC1D,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAE1E,oDAAoD;IACpD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACnC;AAED,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,CAsEtF"}

package/dist/context/hasura.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Hasura metadata API wrapper for install/migrate/uninstall hooks.
+ * Mirrors the HasuraHelper concept from the spec: addTable, trackRelationship,
+ * runMigration. Uses the Hasura Metadata API v3.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHasuraHelper = createHasuraHelper;
+function createHasuraHelper(adminSecret, endpoint) {
+    async function post(path, body) {
+        const url = `${endpoint}${path}`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-hasura-admin-secret': adminSecret,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`hasura: POST ${path} failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    return {
+        async addTable(schema, table) {
+            await post('/v1/metadata', {
+                type: 'pg_track_table',
+                args: {
+                    source: 'default',
+                    schema,
+                    name: table,
+                },
+            });
+        },
+        async removeTable(schema, table) {
+            await post('/v1/metadata', {
+                type: 'pg_untrack_table',
+                args: {
+                    table: { schema, name: table },
+                    cascade: false,
+                },
+            });
+        },
+        async trackRelationship(opts) {
+            const apiType = opts.type === 'object' ? 'pg_create_object_relationship' : 'pg_create_array_relationship';
+            await post('/v1/metadata', {
+                type: apiType,
+                args: {
+                    source: 'default',
+                    table: opts.fromTable,
+                    name: opts.name,
+                    using: {
+                        foreign_key_constraint_on: {
+                            table: opts.toTable,
+                            columns: [opts.toColumn],
+                        },
+                    },
+                },
+            });
+        },
+        async runMetadata(type, args) {
+            return post('/v1/metadata', { type, args });
+        },
+        async runSql(sql) {
+            await post('/v2/query', {
+                type: 'run_sql',
+                args: { source: 'default', sql },
+            });
+        },
+    };
+}
+//# sourceMappingURL=hasura.js.map

package/dist/context/hasura.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hasura.js","sourceRoot":"","sources":["../../src/context/hasura.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AA4BH,gDAsEC;AAtED,SAAgB,kBAAkB,CAAC,WAAmB,EAAE,QAAgB;IACtE,KAAK,UAAU,IAAI,CAAC,IAAY,EAAE,IAAa;QAC7C,MAAM,GAAG,GAAG,GAAG,QAAQ,GAAG,IAAI,EAAE,CAAA;QAChC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAC3B,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,uBAAuB,EAAE,WAAW;aACrC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;SAC3B,CAAC,CAAA;QACF,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAA;YAC7B,MAAM,IAAI,KAAK,CAAC,gBAAgB,IAAI,YAAY,GAAG,CAAC,MAAM,MAAM,IAAI,EAAE,CAAC,CAAA;QACzE,CAAC;QACD,OAAO,GAAG,CAAC,IAAI,EAAE,CAAA;IACnB,CAAC;IAED,OAAO;QACL,KAAK,CAAC,QAAQ,CAAC,MAAc,EAAE,KAAa;YAC1C,MAAM,IAAI,CAAC,cAAc,EAAE;gBACzB,IAAI,EAAE,gBAAgB;gBACtB,IAAI,EAAE;oBACJ,MAAM,EAAE,SAAS;oBACjB,MAAM;oBACN,IAAI,EAAE,KAAK;iBACZ;aACF,CAAC,CAAA;QACJ,CAAC;QAED,KAAK,CAAC,WAAW,CAAC,MAAc,EAAE,KAAa;YAC7C,MAAM,IAAI,CAAC,cAAc,EAAE;gBACzB,IAAI,EAAE,kBAAkB;gBACxB,IAAI,EAAE;oBACJ,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE;oBAC9B,OAAO,EAAE,KAAK;iBACf;aACF,CAAC,CAAA;QACJ,CAAC;QAED,KAAK,CAAC,iBAAiB,CAAC,IAA8B;YACpD,MAAM,OAAO,GACX,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,+BAA+B,CAAC,CAAC,CAAC,8BAA8B,CAAA;YAC3F,MAAM,IAAI,CAAC,cAAc,EAAE;gBACzB,IAAI,EAAE,OAAO;gBACb,IAAI,EAAE;oBACJ,MAAM,EAAE,SAAS;oBACjB,KAAK,EAAE,IAAI,CAAC,SAAS;oBACrB,IAAI,EAAE,IAAI,CAAC,IAAI;oBACf,KAAK,EAAE;wBACL,yBAAyB,EAAE;4BACzB,KAAK,EAAE,IAAI,CAAC,OAAO;4BACnB,OAAO,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC;yBACzB;qBACF;iBACF;aACF,CAAC,CAAA;QACJ,CAAC;QAED,KAAK,CAAC,WAAW,CAAC,IAAY,EAAE,IAA6B;YAC3D,OAAO,IAAI,CAAC,cAAc,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;QAC7C,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,GAAW;YACtB,MAAM,IAAI,CAAC,WAAW,EAAE;gBACtB,IAAI,EAAE,SAAS;gBACf,IAAI,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE;aACjC,CAAC,CAAA;QACJ,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/context/http.d.ts

@@ -0,0 +1,34 @@
+/**
+ * HTTP helper: express app factory + health ping client.
+ * Mirrors server.New() in plugin-sdk-go: auto-mounts /healthz, /readyz,
+ * /version, /metrics on every plugin server.
+ */
+import { type Express } from 'express';
+import type { HealthStatus } from '../runner';
+export interface HttpHelper {
+    /**
+     * createApp returns an Express application pre-configured with:
+     * - GET /healthz  → liveness (always 200)
+     * - GET /readyz   → delegates to the health hook
+     * - GET /version  → plugin name + version JSON
+     */
+    createApp(): Express;
+    /**
+     * listen starts the HTTP server on the given port. Returns the net.Server
+     * so callers can shut it down gracefully in the uninstall hook.
+     */
+    listen(port: number): ReturnType<Express['listen']>;
+    /**
+     * ping sends GET to path on localhost:port and returns a HealthStatus.
+     * Used in the health hook to check this plugin's own /healthz endpoint.
+     */
+    ping(path: string): Promise<HealthStatus>;
+}
+export interface HttpHelperOptions {
+    pluginName: string;
+    pluginVersion: string;
+    port: number;
+    healthCheck?: () => Promise<HealthStatus>;
+}
+export declare function createHttpHelper(opts: HttpHelperOptions): HttpHelper;
+//# sourceMappingURL=http.d.ts.map

package/dist/context/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/context/http.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAgB,EAAE,KAAK,OAAO,EAA+B,MAAM,SAAS,CAAA;AAC5E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAE7C,MAAM,WAAW,UAAU;IACzB;;;;;OAKG;IACH,SAAS,IAAI,OAAO,CAAA;IAEpB;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAA;IAEnD;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;CAC1C;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,EAAE,MAAM,CAAA;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,CAAA;CAC1C;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,UAAU,CAqEpE"}

package/dist/context/http.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * HTTP helper: express app factory + health ping client.
+ * Mirrors server.New() in plugin-sdk-go: auto-mounts /healthz, /readyz,
+ * /version, /metrics on every plugin server.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHttpHelper = createHttpHelper;
+const express_1 = __importDefault(require("express"));
+function createHttpHelper(opts) {
+    let app = null;
+    function getOrCreateApp() {
+        if (app)
+            return app;
+        app = (0, express_1.default)();
+        app.use(express_1.default.json());
+        // Liveness
+        app.get('/healthz', (_req, res) => {
+            res.json({ status: 'ok', plugin: opts.pluginName, version: opts.pluginVersion });
+        });
+        // Readiness — delegates to health hook if provided
+        app.get('/readyz', async (_req, res) => {
+            if (opts.healthCheck) {
+                try {
+                    const result = await opts.healthCheck();
+                    const code = result.status === 'ok' ? 200 : 503;
+                    res.status(code).json(result);
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    res.status(503).json({ status: 'unavailable', message });
+                }
+            }
+            else {
+                res.json({ status: 'ready' });
+            }
+        });
+        // Version
+        app.get('/version', (_req, res) => {
+            res.json({
+                plugin: opts.pluginName,
+                version: opts.pluginVersion,
+                sdk: '@nself/plugin-sdk',
+            });
+        });
+        return app;
+    }
+    return {
+        createApp() {
+            return getOrCreateApp();
+        },
+        listen(port) {
+            const application = getOrCreateApp();
+            return application.listen(port);
+        },
+        async ping(path) {
+            const url = `http://127.0.0.1:${opts.port}${path}`;
+            try {
+                const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
+                if (res.ok) {
+                    return { status: 'ok' };
+                }
+                return {
+                    status: 'degraded',
+                    message: `GET ${path} returned HTTP ${res.status}`,
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return { status: 'unavailable', message };
+            }
+        },
+    };
+}
+//# sourceMappingURL=http.js.map

package/dist/context/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/context/http.ts"],"names":[],"mappings":"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"}

package/dist/context/logger.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Structured JSON logger interface and default pino implementation.
+ * Mirrors logger.New() in plugin-sdk-go: every record carries plugin + version.
+ */
+/** Logger interface exposed in PluginContext — mirrors slog.Logger API shape. */
+export interface Logger {
+    info(msg: string, attrs?: Record<string, unknown>): void;
+    warn(msg: string, attrs?: Record<string, unknown>): void;
+    error(msg: string, attrs?: Record<string, unknown>): void;
+    debug(msg: string, attrs?: Record<string, unknown>): void;
+}
+/** Factory — creates a structured JSON logger keyed to a plugin name. */
+export declare function createLogger(plugin: string, version: string): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/context/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/context/logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,iFAAiF;AACjF,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IACxD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IACxD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IACzD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CAC1D;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAoBpE"}

package/dist/context/logger.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * Structured JSON logger interface and default pino implementation.
+ * Mirrors logger.New() in plugin-sdk-go: every record carries plugin + version.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLogger = createLogger;
+/** Factory — creates a structured JSON logger keyed to a plugin name. */
+function createLogger(plugin, version) {
+    const base = { plugin, version };
+    function log(level, msg, attrs) {
+        const entry = {
+            time: new Date().toISOString(),
+            level,
+            msg,
+            ...base,
+            ...(attrs ?? {}),
+        };
+        process.stderr.write(JSON.stringify(entry) + '\n');
+    }
+    return {
+        info: (msg, attrs) => log('INFO', msg, attrs),
+        warn: (msg, attrs) => log('WARN', msg, attrs),
+        error: (msg, attrs) => log('ERROR', msg, attrs),
+        debug: (msg, attrs) => log('DEBUG', msg, attrs),
+    };
+}
+//# sourceMappingURL=logger.js.map

package/dist/context/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/context/logger.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAWH,oCAoBC;AArBD,yEAAyE;AACzE,SAAgB,YAAY,CAAC,MAAc,EAAE,OAAe;IAC1D,MAAM,IAAI,GAA4B,EAAE,MAAM,EAAE,OAAO,EAAE,CAAA;IAEzD,SAAS,GAAG,CAAC,KAAa,EAAE,GAAW,EAAE,KAA+B;QACtE,MAAM,KAAK,GAAG;YACZ,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YAC9B,KAAK;YACL,GAAG;YACH,GAAG,IAAI;YACP,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;SACjB,CAAA;QACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAA;IACpD,CAAC;IAED,OAAO;QACL,IAAI,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,CAAC;QAC7C,IAAI,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,CAAC;QAC7C,KAAK,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC;QAC/C,KAAK,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC;KAChD,CAAA;AACH,CAAC"}

package/dist/context/nginx.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Nginx route injection helper.
+ * nSelf generates nginx/conf.d/<plugin>.conf at build time; this helper
+ * provides the typed interface for plugins to declare their routes.
+ * At runtime the CLI reads plugin.yaml for routes — this helper is used
+ * during install hooks to validate / extend the manifest-declared routes.
+ */
+export interface RouteOptions {
+    /** Location path, e.g. "/notify/" */
+    location: string;
+    /** Upstream host:port, e.g. "127.0.0.1:3830" */
+    upstream: string;
+    /** Extra nginx directives injected inside the location block. */
+    extraDirectives?: string[];
+}
+export interface NginxHelper {
+    /** Register a proxy_pass route to the plugin's upstream. */
+    addRoute(opts: RouteOptions): void;
+    /** Remove a previously registered route (used in uninstall). */
+    removeRoute(location: string): void;
+    /** Returns all routes registered in this session. */
+    getRoutes(): RouteOptions[];
+}
+export declare function createNginxHelper(): NginxHelper;
+//# sourceMappingURL=nginx.d.ts.map

package/dist/context/nginx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nginx.d.ts","sourceRoot":"","sources":["../../src/context/nginx.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,YAAY;IAC3B,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAA;IAChB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAA;IAChB,iEAAiE;IACjE,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAAA;IAElC,gEAAgE;IAChE,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAEnC,qDAAqD;IACrD,SAAS,IAAI,YAAY,EAAE,CAAA;CAC5B;AAED,wBAAgB,iBAAiB,IAAI,WAAW,CAoB/C"}

package/dist/context/nginx.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * Nginx route injection helper.
+ * nSelf generates nginx/conf.d/<plugin>.conf at build time; this helper
+ * provides the typed interface for plugins to declare their routes.
+ * At runtime the CLI reads plugin.yaml for routes — this helper is used
+ * during install hooks to validate / extend the manifest-declared routes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createNginxHelper = createNginxHelper;
+function createNginxHelper() {
+    const routes = [];
+    return {
+        addRoute(opts) {
+            if (!opts.location.startsWith('/')) {
+                throw new Error(`nginx: location must start with "/", got "${opts.location}"`);
+            }
+            routes.push(opts);
+        },
+        removeRoute(location) {
+            const idx = routes.findIndex((r) => r.location === location);
+            if (idx !== -1)
+                routes.splice(idx, 1);
+        },
+        getRoutes() {
+            return [...routes];
+        },
+    };
+}
+//# sourceMappingURL=nginx.js.map

package/dist/context/nginx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nginx.js","sourceRoot":"","sources":["../../src/context/nginx.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;AAsBH,8CAoBC;AApBD,SAAgB,iBAAiB;IAC/B,MAAM,MAAM,GAAmB,EAAE,CAAA;IAEjC,OAAO;QACL,QAAQ,CAAC,IAAkB;YACzB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBACnC,MAAM,IAAI,KAAK,CAAC,6CAA6C,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAA;YAChF,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACnB,CAAC;QAED,WAAW,CAAC,QAAgB;YAC1B,MAAM,GAAG,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAA;YAC5D,IAAI,GAAG,KAAK,CAAC,CAAC;gBAAE,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;QACvC,CAAC;QAED,SAAS;YACP,OAAO,CAAC,GAAG,MAAM,CAAC,CAAA;QACpB,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @nself/plugin-sdk — TypeScript plugin authoring SDK for nSelf.
+ *
+ * Mirror of plugin-sdk-go v0.1.0: lifecycle hooks (install, start, health,
+ * migrate, uninstall), PluginContext with env/hasura/nginx/db/http/logger
+ * helpers, and a plugin.yaml manifest parser.
+ *
+ * @example
+ * ```ts
+ * import { definePlugin, type PluginContext } from '@nself/plugin-sdk'
+ *
+ * export default definePlugin({
+ *   name: 'my-notify',
+ *   version: '1.0.0',
+ *
+ *   async install(ctx: PluginContext) {
+ *     await ctx.env.require(['SMTP_HOST', 'SMTP_PORT'])
+ *   },
+ *
+ *   async start(ctx: PluginContext) {
+ *     const app = ctx.http.createApp()
+ *     app.get('/notify/healthz', (_req, res) => res.json({ status: 'ok' }))
+ *     ctx.http.listen(ctx.port)
+ *   },
+ *
+ *   async health(ctx: PluginContext) {
+ *     return ctx.http.ping('/notify/healthz')
+ *   },
+ * })
+ * ```
+ */
+export { definePlugin } from './runner';
+export type { PluginDefinition, PluginContext, HealthStatus, PluginInfo, } from './runner';
+export type { EnvHelper } from './context/env';
+export type { HasuraHelper } from './context/hasura';
+export type { NginxHelper } from './context/nginx';
+export type { DatabaseHelper } from './context/db';
+export type { HttpHelper } from './context/http';
+export type { Logger } from './context/logger';
+export { parseManifest, type PluginManifest } from './manifest/parser';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AACvC,YAAY,EACV,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,UAAU,GACX,MAAM,UAAU,CAAA;AACjB,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AACpD,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAClD,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAClD,YAAY,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAChD,YAAY,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/index.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * @nself/plugin-sdk — TypeScript plugin authoring SDK for nSelf.
+ *
+ * Mirror of plugin-sdk-go v0.1.0: lifecycle hooks (install, start, health,
+ * migrate, uninstall), PluginContext with env/hasura/nginx/db/http/logger
+ * helpers, and a plugin.yaml manifest parser.
+ *
+ * @example
+ * ```ts
+ * import { definePlugin, type PluginContext } from '@nself/plugin-sdk'
+ *
+ * export default definePlugin({
+ *   name: 'my-notify',
+ *   version: '1.0.0',
+ *
+ *   async install(ctx: PluginContext) {
+ *     await ctx.env.require(['SMTP_HOST', 'SMTP_PORT'])
+ *   },
+ *
+ *   async start(ctx: PluginContext) {
+ *     const app = ctx.http.createApp()
+ *     app.get('/notify/healthz', (_req, res) => res.json({ status: 'ok' }))
+ *     ctx.http.listen(ctx.port)
+ *   },
+ *
+ *   async health(ctx: PluginContext) {
+ *     return ctx.http.ping('/notify/healthz')
+ *   },
+ * })
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseManifest = exports.definePlugin = void 0;
+var runner_1 = require("./runner");
+Object.defineProperty(exports, "definePlugin", { enumerable: true, get: function () { return runner_1.definePlugin; } });
+var parser_1 = require("./manifest/parser");
+Object.defineProperty(exports, "parseManifest", { enumerable: true, get: function () { return parser_1.parseManifest; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;;;AAEH,mCAAuC;AAA9B,sGAAA,YAAY,OAAA;AAarB,4CAAsE;AAA7D,uGAAA,aAAa,OAAA"}

package/dist/manifest/parser.d.ts

@@ -0,0 +1,43 @@
+/**
+ * plugin.yaml manifest parser and validator.
+ * The manifest is the schema the nSelf CLI reads to register a plugin.
+ * Mirrors the manifest parser in plugin-sdk-go (config/config.go + plugin.Info).
+ */
+/** Full plugin manifest shape as declared in plugin.yaml. */
+export interface PluginManifest {
+    name: string;
+    version: string;
+    description?: string;
+    tier: 'free' | 'pro';
+    bundle?: string;
+    minCli?: string;
+    minSdk?: string;
+    port?: number;
+    /** Hasura GraphQL routes provided by this plugin. */
+    routes?: Array<{
+        path: string;
+        upstream: string;
+    }>;
+    /** Env vars required at install time. */
+    requiredEnv?: string[];
+    /** Free-form metadata extension slot. */
+    metadata?: Record<string, string>;
+}
+/** Validation error returned when the manifest is malformed. */
+export declare class ManifestValidationError extends Error {
+    readonly field?: string | undefined;
+    constructor(message: string, field?: string | undefined);
+}
+/**
+ * parseManifest reads and validates a plugin.yaml file.
+ * Throws ManifestValidationError on missing required fields.
+ *
+ * @param filePath - path to plugin.yaml (defaults to ./plugin.yaml)
+ */
+export declare function parseManifest(filePath?: string): PluginManifest;
+/**
+ * parseManifestFromString parses plugin.yaml content from a string.
+ * Useful in tests.
+ */
+export declare function parseManifestFromString(content: string): PluginManifest;
+//# sourceMappingURL=parser.d.ts.map

package/dist/manifest/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/manifest/parser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,6DAA6D;AAC7D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,EAAE,MAAM,GAAG,KAAK,CAAA;IACpB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb,qDAAqD;IACrD,MAAM,CAAC,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,CAAA;QACZ,QAAQ,EAAE,MAAM,CAAA;KACjB,CAAC,CAAA;IAEF,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IAEtB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAClC;AAED,gEAAgE;AAChE,qBAAa,uBAAwB,SAAQ,KAAK;aAG9B,KAAK,CAAC,EAAE,MAAM;gBAD9B,OAAO,EAAE,MAAM,EACC,KAAK,CAAC,EAAE,MAAM,YAAA;CAKjC;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,cAAc,CAkB/D;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CASvE"}

package/dist/manifest/parser.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * plugin.yaml manifest parser and validator.
+ * The manifest is the schema the nSelf CLI reads to register a plugin.
+ * Mirrors the manifest parser in plugin-sdk-go (config/config.go + plugin.Info).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ManifestValidationError = void 0;
+exports.parseManifest = parseManifest;
+exports.parseManifestFromString = parseManifestFromString;
+const yaml_1 = require("yaml");
+const fs_1 = require("fs");
+const path_1 = require("path");
+/** Validation error returned when the manifest is malformed. */
+class ManifestValidationError extends Error {
+    constructor(message, field) {
+        super(`plugin manifest: ${message}`);
+        this.field = field;
+        this.name = 'ManifestValidationError';
+    }
+}
+exports.ManifestValidationError = ManifestValidationError;
+/**
+ * parseManifest reads and validates a plugin.yaml file.
+ * Throws ManifestValidationError on missing required fields.
+ *
+ * @param filePath - path to plugin.yaml (defaults to ./plugin.yaml)
+ */
+function parseManifest(filePath) {
+    const resolvedPath = (0, path_1.resolve)(filePath ?? 'plugin.yaml');
+    let raw;
+    try {
+        raw = (0, fs_1.readFileSync)(resolvedPath, 'utf-8');
+    }
+    catch {
+        throw new ManifestValidationError(`cannot read file: ${resolvedPath}`);
+    }
+    let parsed;
+    try {
+        parsed = (0, yaml_1.parse)(raw);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new ManifestValidationError(`YAML parse error: ${msg}`);
+    }
+    return validateManifest(parsed);
+}
+/**
+ * parseManifestFromString parses plugin.yaml content from a string.
+ * Useful in tests.
+ */
+function parseManifestFromString(content) {
+    let parsed;
+    try {
+        parsed = (0, yaml_1.parse)(content);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new ManifestValidationError(`YAML parse error: ${msg}`);
+    }
+    return validateManifest(parsed);
+}
+function validateManifest(raw) {
+    if (typeof raw !== 'object' || raw === null) {
+        throw new ManifestValidationError('manifest must be a YAML object');
+    }
+    const m = raw;
+    if (!m['name'] || typeof m['name'] !== 'string') {
+        throw new ManifestValidationError('name is required and must be a string', 'name');
+    }
+    if (!m['version'] || typeof m['version'] !== 'string') {
+        throw new ManifestValidationError('version is required and must be a string', 'version');
+    }
+    if (m['tier'] !== 'free' && m['tier'] !== 'pro') {
+        throw new ManifestValidationError('tier must be "free" or "pro"', 'tier');
+    }
+    return m;
+}
+//# sourceMappingURL=parser.js.map

package/dist/manifest/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../src/manifest/parser.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AA+CH,sCAkBC;AAMD,0DASC;AA9ED,+BAA4B;AAC5B,2BAAiC;AACjC,+BAA8B;AA0B9B,gEAAgE;AAChE,MAAa,uBAAwB,SAAQ,KAAK;IAChD,YACE,OAAe,EACC,KAAc;QAE9B,KAAK,CAAC,oBAAoB,OAAO,EAAE,CAAC,CAAA;QAFpB,UAAK,GAAL,KAAK,CAAS;QAG9B,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAA;IACvC,CAAC;CACF;AARD,0DAQC;AAED;;;;;GAKG;AACH,SAAgB,aAAa,CAAC,QAAiB;IAC7C,MAAM,YAAY,GAAG,IAAA,cAAO,EAAC,QAAQ,IAAI,aAAa,CAAC,CAAA;IACvD,IAAI,GAAW,CAAA;IACf,IAAI,CAAC;QACH,GAAG,GAAG,IAAA,iBAAY,EAAC,YAAY,EAAE,OAAO,CAAC,CAAA;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,uBAAuB,CAAC,qBAAqB,YAAY,EAAE,CAAC,CAAA;IACxE,CAAC;IAED,IAAI,MAAe,CAAA;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,IAAA,YAAK,EAAC,GAAG,CAAC,CAAA;IACrB,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QAC5D,MAAM,IAAI,uBAAuB,CAAC,qBAAqB,GAAG,EAAE,CAAC,CAAA;IAC/D,CAAC;IAED,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAA;AACjC,CAAC;AAED;;;GAGG;AACH,SAAgB,uBAAuB,CAAC,OAAe;IACrD,IAAI,MAAe,CAAA;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,IAAA,YAAK,EAAC,OAAO,CAAC,CAAA;IACzB,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QAC5D,MAAM,IAAI,uBAAuB,CAAC,qBAAqB,GAAG,EAAE,CAAC,CAAA;IAC/D,CAAC;IACD,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAA;AACjC,CAAC;AAED,SAAS,gBAAgB,CAAC,GAAY;IACpC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QAC5C,MAAM,IAAI,uBAAuB,CAAC,gCAAgC,CAAC,CAAA;IACrE,CAAC;IAED,MAAM,CAAC,GAAG,GAA8B,CAAA;IAExC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,QAAQ,EAAE,CAAC;QAChD,MAAM,IAAI,uBAAuB,CAAC,uCAAuC,EAAE,MAAM,CAAC,CAAA;IACpF,CAAC;IACD,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,OAAO,CAAC,CAAC,SAAS,CAAC,KAAK,QAAQ,EAAE,CAAC;QACtD,MAAM,IAAI,uBAAuB,CAAC,0CAA0C,EAAE,SAAS,CAAC,CAAA;IAC1F,CAAC;IACD,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,MAAM,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,KAAK,EAAE,CAAC;QAChD,MAAM,IAAI,uBAAuB,CAAC,8BAA8B,EAAE,MAAM,CAAC,CAAA;IAC3E,CAAC;IAED,OAAO,CAA8B,CAAA;AACvC,CAAC"}

package/dist/runner.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Lifecycle orchestrator: defines PluginDefinition, PluginContext, and the
+ * definePlugin() factory. Mirrors the plugin.Plugin interface in plugin-sdk-go.
+ */
+import type { EnvHelper } from './context/env';
+import type { HasuraHelper } from './context/hasura';
+import type { NginxHelper } from './context/nginx';
+import type { DatabaseHelper } from './context/db';
+import type { HttpHelper } from './context/http';
+import type { Logger } from './context/logger';
+/** Identity metadata for a plugin — mirrors plugin-sdk-go plugin.Info. */
+export interface PluginInfo {
+    name: string;
+    version: string;
+    description?: string;
+    tier?: 'free' | 'pro';
+    bundle?: string;
+    minCli?: string;
+    minSdk?: string;
+}
+/** Health check result returned by the health hook. */
+export interface HealthStatus {
+    status: 'ok' | 'degraded' | 'unavailable';
+    message?: string;
+    checks?: Record<string, boolean>;
+}
+/**
+ * Runtime context passed to every lifecycle hook.
+ * Mirrors the PluginContext struct in the spec and the helpers in plugin-sdk-go.
+ */
+export interface PluginContext {
+    /** TCP port the plugin should bind to (from NSELF_PLUGIN_PORT env var). */
+    port: number;
+    /** Structured JSON logger keyed to the plugin name. */
+    logger: Logger;
+    /** Env var helpers: require(), get(), getInt(), getBool(). */
+    env: EnvHelper;
+    /** Hasura metadata API wrapper. */
+    hasura: HasuraHelper;
+    /** Nginx route injection helper. */
+    nginx: NginxHelper;
+    /**
+     * PostgreSQL helper for migration-time DDL only.
+     * Not for query-time use — plugins talk to Hasura GraphQL.
+     */
+    db: DatabaseHelper;
+    /** Express app factory + health ping client. */
+    http: HttpHelper;
+}
+/**
+ * The shape a plugin author fills in with definePlugin().
+ * All hooks are optional except name + version.
+ */
+export interface PluginDefinition {
+    /** Plugin name — must match the plugin.yaml `name` field. */
+    name: string;
+    /** SemVer string, e.g. "1.0.0". */
+    version: string;
+    /** Short human description. */
+    description?: string;
+    /** Tier reported in /version endpoint. */
+    tier?: 'free' | 'pro';
+    /** Bundle this plugin belongs to, e.g. "nClaw". */
+    bundle?: string;
+    /**
+     * install — runs on `nself plugin install`.
+     * Use to apply Hasura metadata, verify env vars, and register Nginx routes.
+     */
+    install?: (ctx: PluginContext) => Promise<void>;
+    /**
+     * start — runs when `nself start` brings the plugin container up.
+     * Should create an HTTP app and call ctx.http.listen(ctx.port).
+     */
+    start?: (ctx: PluginContext) => Promise<void>;
+    /**
+     * health — polled by `nself doctor`. Return status 'ok' when fully ready.
+     * The runner builds a /healthz endpoint automatically; health() is used for
+     * deeper readiness checks surfaced via /readyz.
+     */
+    health?: (ctx: PluginContext) => Promise<HealthStatus>;
+    /**
+     * migrate — runs Hasura metadata + SQL migrations during `nself start` before
+     * the plugin begins serving traffic.
+     */
+    migrate?: (ctx: PluginContext) => Promise<void>;
+    /**
+     * uninstall — runs on `nself plugin remove`.
+     * Clean up Hasura metadata and Nginx routes; preserve user data by default.
+     */
+    uninstall?: (ctx: PluginContext) => Promise<void>;
+}
+/**
+ * definePlugin registers a plugin definition and returns it for use by the
+ * nSelf CLI runner. Acts as the primary authoring entry point.
+ *
+ * @example
+ * ```ts
+ * export default definePlugin({
+ *   name: 'notify',
+ *   version: '1.0.0',
+ *   async start(ctx) {
+ *     const app = ctx.http.createApp()
+ *     app.post('/notify/send', myHandler)
+ *     ctx.http.listen(ctx.port)
+ *   },
+ * })
+ * ```
+ */
+export declare function definePlugin(definition: PluginDefinition): PluginDefinition;
+//# sourceMappingURL=runner.d.ts.map

package/dist/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAE9C,0EAA0E;AAC1E,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;IACrB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,uDAAuD;AACvD,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,IAAI,GAAG,UAAU,GAAG,aAAa,CAAA;IACzC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAA;IACZ,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAA;IACd,8DAA8D;IAC9D,GAAG,EAAE,SAAS,CAAA;IACd,mCAAmC;IACnC,MAAM,EAAE,YAAY,CAAA;IACpB,oCAAoC;IACpC,KAAK,EAAE,WAAW,CAAA;IAClB;;;OAGG;IACH,EAAE,EAAE,cAAc,CAAA;IAClB,gDAAgD;IAChD,IAAI,EAAE,UAAU,CAAA;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAA;IACZ,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAA;IACf,+BAA+B;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;IACrB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAE/C;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAE7C;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,YAAY,CAAC,CAAA;IAEtD;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAE/C;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAClD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,gBAAgB,GAAG,gBAAgB,CAI3E"}

package/dist/runner.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * Lifecycle orchestrator: defines PluginDefinition, PluginContext, and the
+ * definePlugin() factory. Mirrors the plugin.Plugin interface in plugin-sdk-go.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.definePlugin = definePlugin;
+/**
+ * definePlugin registers a plugin definition and returns it for use by the
+ * nSelf CLI runner. Acts as the primary authoring entry point.
+ *
+ * @example
+ * ```ts
+ * export default definePlugin({
+ *   name: 'notify',
+ *   version: '1.0.0',
+ *   async start(ctx) {
+ *     const app = ctx.http.createApp()
+ *     app.post('/notify/send', myHandler)
+ *     ctx.http.listen(ctx.port)
+ *   },
+ * })
+ * ```
+ */
+function definePlugin(definition) {
+    if (!definition.name)
+        throw new Error('plugin SDK: name is required');
+    if (!definition.version)
+        throw new Error('plugin SDK: version is required');
+    return definition;
+}
+//# sourceMappingURL=runner.js.map

package/dist/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAoHH,oCAIC;AArBD;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,YAAY,CAAC,UAA4B;IACvD,IAAI,CAAC,UAAU,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAA;IACrE,IAAI,CAAC,UAAU,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAA;IAC3E,OAAO,UAAU,CAAA;AACnB,CAAC"}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@nself/plugin-sdk",
+  "version": "1.2.4",
+  "description": "TypeScript/Node.js plugin authoring SDK for nSelf",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "dependencies": {
+    "express": "^4.18.3",
+    "pino": "^9.1.0",
+    "yaml": "^2.4.1"
+  },
+  "peerDependencies": {
+    "pg": "^8.11.0"
+  },
+  "peerDependenciesMeta": {
+    "pg": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^25.8.0",
+    "@types/pg": "^8.11.0",
+    "@typescript-eslint/eslint-plugin": "^8.59.3",
+    "@typescript-eslint/parser": "^8.59.3",
+    "eslint": "^10.4.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.2",
+    "typescript": "^6.0.3"
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "testMatch": [
+      "**/*.test.ts"
+    ],
+    "transform": {
+      "^.+\\.ts$": [
+        "ts-jest",
+        {
+          "tsconfig": "tsconfig.test.json"
+        }
+      ]
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nself-org/cli.git",
+    "directory": "sdk/ts"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src test"
+  }
+}

package/templates/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "description": "My nSelf plugin",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "ts-node src/index.ts"
+  },
+  "dependencies": {
+    "@nself/plugin-sdk": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^6.0.3"
+  }
+}

package/templates/plugin.yaml

@@ -0,0 +1,11 @@
+name: my-plugin
+version: 1.0.0
+description: My nSelf plugin built with @nself/plugin-sdk
+tier: free
+port: 3850
+
+# Required environment variables (checked at install time)
+requiredEnv: []
+
+# Nginx routes this plugin exposes (populated by the CLI at build time)
+routes: []

package/templates/src/index.ts

@@ -0,0 +1,42 @@
+import { definePlugin, type PluginContext, type HealthStatus } from '@nself/plugin-sdk'
+
+export default definePlugin({
+  name: 'my-plugin',
+  version: '1.0.0',
+
+  async install(ctx: PluginContext): Promise<void> {
+    ctx.logger.info('installing my-plugin')
+    // Verify required env vars
+    ctx.env.require([])
+    // Register Nginx route
+    ctx.nginx.addRoute({
+      location: '/my-plugin/',
+      upstream: `127.0.0.1:${ctx.port}`,
+    })
+  },
+
+  async start(ctx: PluginContext): Promise<void> {
+    ctx.logger.info('starting my-plugin', { port: ctx.port })
+    const app = ctx.http.createApp()
+
+    // Add your routes here
+    app.get('/my-plugin/hello', (_req, res) => {
+      res.json({ message: 'Hello from my-plugin!' })
+    })
+
+    ctx.http.listen(ctx.port)
+  },
+
+  async health(ctx: PluginContext): Promise<HealthStatus> {
+    return ctx.http.ping('/my-plugin/healthz')
+  },
+
+  async migrate(_ctx: PluginContext): Promise<void> {
+    // Run Hasura metadata or SQL migrations here
+  },
+
+  async uninstall(ctx: PluginContext): Promise<void> {
+    ctx.logger.info('uninstalling my-plugin')
+    ctx.nginx.removeRoute('/my-plugin/')
+  },
+})