@zhin.js/plugin-runtime 1.1.1 → 1.1.2

package/lib/database-host.d.ts

@@ -1,3 +1,4 @@
+import { type PluginId } from './identity.js';
 export interface DatabaseHostSelection {
     where(query: Record<string, unknown>): DatabaseHostSelection;
     orderBy(field: string, direction?: 'ASC' | 'DESC'): DatabaseHostSelection;
@@ -83,4 +84,43 @@ export interface DatabaseHost {
     start(): Promise<void>;
     stop(): Promise<void>;
 }
-export declare const databaseHostToken: import("./token.js").Token<DatabaseHost>;
+/**
+ * Persistence surface visible to a plugin. Names are logical to the owner;
+ * the Runtime maps them to private physical table names before they reach the
+ * process-wide DatabaseHost.
+ */
+export interface PluginDatabaseHost {
+    readonly owner: PluginId;
+    readonly dialect: string;
+    readonly started: boolean;
+    define(name: string, definition: Record<string, unknown>): void;
+    tables(): readonly string[];
+    models: {
+        get(name: string): DatabaseHostModel | undefined;
+    };
+}
+/**
+ * Maps a plugin's logical resource name to its process-wide physical name.
+ * Root keeps its historical bare names so existing projects do not need a
+ * database migration merely to adopt scoped child plugins.
+ */
+export declare function qualifyPluginResourceName(owner: PluginId, name: string): string;
+/** Reverse `qualifyPluginResourceName` only when the name belongs to owner. */
+export declare function unqualifyPluginResourceName(owner: PluginId, name: string): string | undefined;
+/** Creates a tenant facade without exposing Console administration or raw DB access. */
+export declare function createPluginDatabaseHost(owner: PluginId, host: DatabaseHost): PluginDatabaseHost;
+/**
+ * Recovers a process host from the standard root token or a scoped facade.
+ * This keeps custom RootRuntime installers written against the pre-facade
+ * token working while child scopes begin receiving tenant boundaries.
+ */
+export declare function unwrapPluginDatabaseHost(host: DatabaseHost | PluginDatabaseHost): DatabaseHost | undefined;
+/**
+ * Plugin-facing scoped persistence token. Runtime replaces this binding for
+ * every Plugin Scope; plugin code must never receive the process-wide host.
+ * The owner encoding keeps `root/a` and `root/a/b` disjoint, so a parent
+ * facade cannot accidentally enumerate a descendant's tables.
+ */
+export declare const databaseHostToken: import("./token.js").Token<PluginDatabaseHost>;
+/** Root-only process host for CLI composition and Console administration. */
+export declare const databaseRootHostToken: import("./token.js").Token<DatabaseHost>;

package/lib/database-host.js

@@ -1,2 +1,71 @@
+import { pluginOwnerResourceKey, rootPluginId } from './identity.js';
 import { createToken } from './token.js';
-export const databaseHostToken = createToken('zhin.database.host', 'Plugin Runtime database host');
+const resourcePrefix = '__zhin_plugin__';
+const resourceSeparator = '__';
+const roots = new WeakMap();
+/**
+ * Maps a plugin's logical resource name to its process-wide physical name.
+ * Root keeps its historical bare names so existing projects do not need a
+ * database migration merely to adopt scoped child plugins.
+ */
+export function qualifyPluginResourceName(owner, name) {
+    assertLogicalResourceName(name);
+    if (owner === rootPluginId())
+        return name;
+    return `${resourcePrefix}${pluginOwnerResourceKey(owner)}${resourceSeparator}${name}`;
+}
+/** Reverse `qualifyPluginResourceName` only when the name belongs to owner. */
+export function unqualifyPluginResourceName(owner, name) {
+    if (owner === rootPluginId())
+        return name.startsWith(resourcePrefix) ? undefined : name;
+    const prefix = `${resourcePrefix}${pluginOwnerResourceKey(owner)}${resourceSeparator}`;
+    return name.startsWith(prefix) ? name.slice(prefix.length) : undefined;
+}
+/** Creates a tenant facade without exposing Console administration or raw DB access. */
+export function createPluginDatabaseHost(owner, host) {
+    const facade = Object.freeze({
+        owner,
+        get dialect() { return host.dialect; },
+        get started() { return host.started; },
+        define(name, definition) {
+            host.define(qualifyPluginResourceName(owner, name), definition);
+        },
+        tables() {
+            return Object.freeze(host.tables().flatMap((name) => {
+                const logical = unqualifyPluginResourceName(owner, name);
+                return logical === undefined ? [] : [logical];
+            }));
+        },
+        models: Object.freeze({
+            get(name) {
+                return host.models.get(qualifyPluginResourceName(owner, name));
+            },
+        }),
+    });
+    roots.set(facade, host);
+    return facade;
+}
+/**
+ * Recovers a process host from the standard root token or a scoped facade.
+ * This keeps custom RootRuntime installers written against the pre-facade
+ * token working while child scopes begin receiving tenant boundaries.
+ */
+export function unwrapPluginDatabaseHost(host) {
+    if ('getRawDatabase' in host)
+        return host;
+    return roots.get(host);
+}
+function assertLogicalResourceName(name) {
+    if (!name || name.startsWith(resourcePrefix)) {
+        throw new TypeError(`Invalid plugin resource name: ${name}`);
+    }
+}
+/**
+ * Plugin-facing scoped persistence token. Runtime replaces this binding for
+ * every Plugin Scope; plugin code must never receive the process-wide host.
+ * The owner encoding keeps `root/a` and `root/a/b` disjoint, so a parent
+ * facade cannot accidentally enumerate a descendant's tables.
+ */
+export const databaseHostToken = createToken('zhin.database.host', 'Plugin Runtime scoped database host');
+/** Root-only process host for CLI composition and Console administration. */
+export const databaseRootHostToken = createToken('zhin.database.root-host', 'Plugin Runtime root database host');

package/lib/identity.d.ts

@@ -18,5 +18,13 @@ export declare function tokenId(value: string): TokenId;
 export declare function featureId(value: string): FeatureId;
 export declare function rootPluginId(): PluginId;
 export declare function childPluginId(parent: PluginId, instanceKey: string): PluginId;
+/**
+ * Database-safe owner encoding used by process-wide plugin resources.
+ *
+ * Each path segment is length-prefixed and the final underscore is followed
+ * by a resource separator. A parent owner therefore cannot match a child
+ * owner merely because their PluginId has a common path prefix.
+ */
+export declare function pluginOwnerResourceKey(owner: PluginId): string;
 export declare function capabilityId(owner: PluginId, feature: FeatureId, localName: string): CapabilityId;
 export {};

package/lib/identity.js

@@ -24,6 +24,19 @@ export function childPluginId(parent, instanceKey) {
     }
     return `${parent}/${instanceKey}`;
 }
+/**
+ * Database-safe owner encoding used by process-wide plugin resources.
+ *
+ * Each path segment is length-prefixed and the final underscore is followed
+ * by a resource separator. A parent owner therefore cannot match a child
+ * owner merely because their PluginId has a common path prefix.
+ */
+export function pluginOwnerResourceKey(owner) {
+    return `${String(owner)
+        .split('/')
+        .map((segment) => `${segment.length}_${segment}`)
+        .join('_')}_`;
+}
 export function capabilityId(owner, feature, localName) {
     if (!capabilityLocalNamePattern.test(localName)) {
         throw new TypeError(`Invalid capability local name: ${localName}`);

package/lib/schedule-host.d.ts

@@ -1,9 +1,12 @@
+import { type PluginId } from './identity.js';
 /**
  * Thin Host Resource for Plugin Runtime cron jobs.
  * Implementations typically wrap `@zhin.js/schedule` CalendarScheduler (solar cron).
  */
 export interface ScheduleJobRegistration {
     readonly id: string;
+    /** Runtime-assigned owner for diagnostics and Console inventory. */
+    readonly owner?: PluginId;
     /** 6-field solar cron: `秒 分 时 日 月 周` */
     readonly cron: string;
     readonly description?: string;
@@ -16,6 +19,25 @@ export interface ScheduleHost {
         readonly id: string;
         readonly cron: string;
         readonly description?: string;
+        readonly owner?: PluginId;
     }[];
 }
-export declare const scheduleHostToken: import("./token.js").Token<ScheduleHost>;
+/** Scoped scheduling surface exposed to a Plugin setup function. */
+export interface PluginScheduleHost {
+    readonly owner: PluginId;
+    register(job: ScheduleJobRegistration): () => void;
+    list(): readonly {
+        readonly id: string;
+        readonly cron: string;
+        readonly description?: string;
+    }[];
+}
+export declare function qualifyPluginScheduleId(owner: PluginId, id: string): string;
+export declare function unqualifyPluginScheduleId(owner: PluginId, id: string): string | undefined;
+export declare function createPluginScheduleHost(owner: PluginId, host: ScheduleHost): PluginScheduleHost;
+/** See unwrapPluginDatabaseHost: preserves legacy custom RootResource installers. */
+export declare function unwrapPluginScheduleHost(host: ScheduleHost | PluginScheduleHost): ScheduleHost;
+/** Plugin-facing token; Runtime injects a facade bound to the current owner. */
+export declare const scheduleHostToken: import("./token.js").Token<PluginScheduleHost>;
+/** Root-only process scheduler for CLI composition and Console administration. */
+export declare const scheduleRootHostToken: import("./token.js").Token<ScheduleHost>;

package/lib/schedule-host.js

@@ -1,2 +1,52 @@
+import { pluginOwnerResourceKey, rootPluginId } from './identity.js';
 import { createToken } from './token.js';
-export const scheduleHostToken = createToken('zhin.schedule.host', 'Plugin Runtime solar cron host');
+const jobPrefix = '__zhin_plugin__';
+const jobSeparator = '__';
+const roots = new WeakMap();
+export function qualifyPluginScheduleId(owner, id) {
+    assertLogicalJobId(id);
+    if (owner === rootPluginId())
+        return id;
+    return `${jobPrefix}${pluginOwnerResourceKey(owner)}${jobSeparator}${id}`;
+}
+export function unqualifyPluginScheduleId(owner, id) {
+    if (owner === rootPluginId())
+        return id.startsWith(jobPrefix) ? undefined : id;
+    const prefix = `${jobPrefix}${pluginOwnerResourceKey(owner)}${jobSeparator}`;
+    return id.startsWith(prefix) ? id.slice(prefix.length) : undefined;
+}
+export function createPluginScheduleHost(owner, host) {
+    const facade = Object.freeze({
+        owner,
+        register(job) {
+            return host.register({ ...job, id: qualifyPluginScheduleId(owner, job.id), owner });
+        },
+        list() {
+            return Object.freeze(host.list().flatMap((job) => {
+                const id = unqualifyPluginScheduleId(owner, job.id);
+                if (id === undefined)
+                    return [];
+                return [Object.freeze({
+                        id,
+                        cron: job.cron,
+                        ...(job.description === undefined ? {} : { description: job.description }),
+                    })];
+            }));
+        },
+    });
+    roots.set(facade, host);
+    return facade;
+}
+/** See unwrapPluginDatabaseHost: preserves legacy custom RootResource installers. */
+export function unwrapPluginScheduleHost(host) {
+    return roots.get(host) ?? host;
+}
+function assertLogicalJobId(id) {
+    if (!id || id.startsWith(jobPrefix)) {
+        throw new TypeError(`Invalid plugin schedule id: ${id}`);
+    }
+}
+/** Plugin-facing token; Runtime injects a facade bound to the current owner. */
+export const scheduleHostToken = createToken('zhin.schedule.host', 'Plugin Runtime scoped solar cron host');
+/** Root-only process scheduler for CLI composition and Console administration. */
+export const scheduleRootHostToken = createToken('zhin.schedule.root-host', 'Plugin Runtime root solar cron host');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/plugin-runtime",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Zero-dependency Plugin tree, Scope and atomic generation runtime for Zhin",
   "type": "module",
   "main": "./lib/index.js",
@@ -16,7 +16,7 @@
     "lib"
   ],
   "devDependencies": {
-    "@types/node": "^26.1.0",
+    "@types/node": "^26.1.2",
     "typescript": "^6.0.3"
   },
   "engines": {