Skip to content

Commit 58f7d7e

Browse files
steipetesteipete
committed
docs: document plugin scope state helpers
1 parent 0ad13b7 commit 58f7d7e

8 files changed

Lines changed: 35 additions & 0 deletions

‎src/plugins/channel-plugin-ids.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
/** Channel presence and gateway startup plugin id helpers. */
12
export {
23
hasConfiguredChannelsForReadOnlyScope,
34
hasExplicitChannelConfig,

‎src/plugins/channel-registry-state.types.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
/** Runtime shape needed to expose an active plugin channel registration. */
12
export type ActiveChannelPluginRuntimeShape = {
23
id?: string | null;
34
meta?: {
@@ -16,12 +17,14 @@ export type ActiveChannelPluginRuntimeShape = {
1617
} | null;
1718
};
1819

20+
/** Active channel registration with owning plugin metadata. */
1921
export type ActivePluginChannelRegistration = {
2022
plugin: ActiveChannelPluginRuntimeShape;
2123
pluginId?: string | null;
2224
origin?: string | null;
2325
};
2426

27+
/** Active runtime channel registry snapshot. */
2528
export type ActivePluginChannelRegistry = {
2629
channels: ActivePluginChannelRegistration[];
2730
};

‎src/plugins/install-paths.ts‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,12 @@ import {
77
} from "../infra/install-safe-path.js";
88
import { resolveConfigDir, resolveUserPath } from "../utils.js";
99

10+
/** Encodes arbitrary input as a safe plugin install filename. */
1011
export function safePluginInstallFileName(input: string): string {
1112
return safeDirName(input);
1213
}
1314

15+
/** Encodes a plugin id for use as an install directory name. */
1416
export function encodePluginInstallDirName(pluginId: string): string {
1517
const trimmed = pluginId.trim();
1618
if (!trimmed.includes("/")) {
@@ -21,6 +23,7 @@ export function encodePluginInstallDirName(pluginId: string): string {
2123
return `@${safePathSegmentHashed(trimmed)}`;
2224
}
2325

26+
/** Validates a plugin id for install path safety. */
2427
export function validatePluginId(pluginId: string): string | null {
2528
const trimmed = pluginId.trim();
2629
if (!trimmed) {
@@ -51,6 +54,7 @@ export function validatePluginId(pluginId: string): string | null {
5154
return null;
5255
}
5356

57+
/** Checks whether an installed plugin id matches the expected id, including old npm keying. */
5458
export function matchesExpectedPluginId(params: {
5559
expectedPluginId?: string;
5660
pluginId: string;
@@ -73,20 +77,23 @@ export function matchesExpectedPluginId(params: {
7377
);
7478
}
7579

80+
/** Resolves the default directory for path-installed plugin extensions. */
7681
export function resolveDefaultPluginExtensionsDir(
7782
env: NodeJS.ProcessEnv = process.env,
7883
homedir?: () => string,
7984
): string {
8085
return path.join(resolveConfigDir(env, homedir), "extensions");
8186
}
8287

88+
/** Resolves the default directory for managed npm plugin installs. */
8389
export function resolveDefaultPluginNpmDir(
8490
env: NodeJS.ProcessEnv = process.env,
8591
homedir?: () => string,
8692
): string {
8793
return path.join(resolveConfigDir(env, homedir), "npm");
8894
}
8995

96+
/** Encodes an npm package name into a managed npm project directory name. */
9097
export function encodePluginNpmProjectDirName(packageName: string): string {
9198
const trimmed = packageName.trim();
9299
if (!trimmed) {
@@ -95,11 +102,13 @@ export function encodePluginNpmProjectDirName(packageName: string): string {
95102
return safePathSegmentHashed(trimmed);
96103
}
97104

105+
/** Resolves the directory containing managed npm plugin projects. */
98106
export function resolvePluginNpmProjectsDir(npmDir?: string): string {
99107
const npmBase = npmDir ? resolveUserPath(npmDir) : resolveDefaultPluginNpmDir();
100108
return path.join(npmBase, "projects");
101109
}
102110

111+
/** Resolves the managed npm project directory for a package name. */
103112
export function resolvePluginNpmProjectDir(params: {
104113
packageName: string;
105114
npmDir?: string;
@@ -110,6 +119,7 @@ export function resolvePluginNpmProjectDir(params: {
110119
);
111120
}
112121

122+
/** Resolves the installed node_modules package directory for a managed npm plugin. */
113123
export function resolvePluginNpmPackageDir(params: {
114124
packageName: string;
115125
npmDir?: string;
@@ -121,13 +131,15 @@ export function resolvePluginNpmPackageDir(params: {
121131
);
122132
}
123133

134+
/** Resolves the default directory for git-installed plugins. */
124135
export function resolveDefaultPluginGitDir(
125136
env: NodeJS.ProcessEnv = process.env,
126137
homedir?: () => string,
127138
): string {
128139
return path.join(resolveConfigDir(env, homedir), "git");
129140
}
130141

142+
/** Resolves the safe install directory for one plugin id. */
131143
export function resolvePluginInstallDir(pluginId: string, extensionsDir?: string): string {
132144
const extensionsBase = extensionsDir
133145
? resolveUserPath(extensionsDir)

‎src/plugins/interactive-state.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import { createDedupeCache, resolveGlobalDedupeCache } from "../infra/dedupe.js"
22
import type { DedupeCache } from "../infra/dedupe.js";
33
import type { PluginInteractiveHandlerRegistration } from "./types.js";
44

5+
/** Registered interactive handler with owning plugin metadata. */
56
export type RegisteredInteractiveHandler = PluginInteractiveHandlerRegistration & {
67
pluginId: string;
78
pluginName?: string;
@@ -67,6 +68,7 @@ function getState() {
6768
return created;
6869
}
6970

71+
/** Returns the process-global plugin interactive handler registry. */
7072
export function getPluginInteractiveHandlersState() {
7173
return getState().interactiveHandlers;
7274
}
@@ -75,6 +77,7 @@ function getPluginInteractiveCallbackDedupeState() {
7577
return getState().callbackDedupe;
7678
}
7779

80+
/** Claims an interactive callback dedupe key while the callback is in flight. */
7881
export function claimPluginInteractiveCallbackDedupe(
7982
dedupeKey: string | undefined,
8083
now = Date.now(),
@@ -90,6 +93,7 @@ export function claimPluginInteractiveCallbackDedupe(
9093
return true;
9194
}
9295

96+
/** Commits an interactive callback dedupe key after successful handling. */
9397
export function commitPluginInteractiveCallbackDedupe(
9498
dedupeKey: string | undefined,
9599
now = Date.now(),
@@ -102,19 +106,22 @@ export function commitPluginInteractiveCallbackDedupe(
102106
state.callbackDedupe.check(dedupeKey, now);
103107
}
104108

109+
/** Releases an in-flight interactive callback dedupe claim without committing it. */
105110
export function releasePluginInteractiveCallbackDedupe(dedupeKey: string | undefined): void {
106111
if (!dedupeKey) {
107112
return;
108113
}
109114
getState().inflightCallbackDedupe.delete(dedupeKey);
110115
}
111116

117+
/** Clears plugin interactive handlers and callback dedupe state. */
112118
export function clearPluginInteractiveHandlersState(): void {
113119
clearPluginInteractiveHandlerRegistrationsState();
114120
getPluginInteractiveCallbackDedupeState().clear();
115121
getState().inflightCallbackDedupe.clear();
116122
}
117123

124+
/** Clears only plugin interactive handler registrations. */
118125
export function clearPluginInteractiveHandlerRegistrationsState(): void {
119126
getPluginInteractiveHandlersState().clear();
120127
}

‎src/plugins/plugin-kind.types.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,2 @@
1+
/** Plugin kind labels for non-provider plugin capability groups. */
12
export type PluginKind = "memory" | "context-engine";

‎src/plugins/plugin-scope.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
import { normalizeStringEntries } from "@openclaw/normalization-core/string-normalization";
22

3+
/** Optional scoped plugin id list; undefined means unscoped. */
34
export type PluginIdScope = readonly string[] | undefined;
45

6+
/** Normalizes plugin id scope input into a sorted unique string list. */
57
export function normalizePluginIdScope(ids?: readonly unknown[]): string[] | undefined {
68
if (ids === undefined) {
79
return undefined;
@@ -11,21 +13,25 @@ export function normalizePluginIdScope(ids?: readonly unknown[]): string[] | und
1113
).toSorted();
1214
}
1315

16+
/** True when plugin scope was explicitly provided, including an empty scope. */
1417
export function hasExplicitPluginIdScope(ids?: readonly string[]): boolean {
1518
return ids !== undefined;
1619
}
1720

21+
/** True when plugin scope was explicitly provided with at least one id. */
1822
export function hasNonEmptyPluginIdScope(ids?: readonly string[]): boolean {
1923
return ids !== undefined && ids.length > 0;
2024
}
2125

26+
/** Creates a lookup set for explicit plugin scope, or null when unscoped. */
2227
export function createPluginIdScopeSet(ids?: readonly string[]): ReadonlySet<string> | null {
2328
if (ids === undefined) {
2429
return null;
2530
}
2631
return new Set(ids);
2732
}
2833

34+
/** Serializes plugin scope for cache keys. */
2935
export function serializePluginIdScope(ids?: readonly string[]): string {
3036
return ids === undefined ? "__unscoped__" : JSON.stringify(ids);
3137
}

‎src/plugins/setup-descriptors.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ type SetupDescriptorRecord = Pick<
66
"providers" | "cliBackends" | "providerAuthAliases" | "setup"
77
>;
88

9+
/** Lists setup provider ids and auth aliases owned by one plugin manifest. */
910
export function listSetupProviderIds(record: SetupDescriptorRecord): readonly string[] {
1011
const providerIds = record.setup?.providers?.map((entry) => entry.id) ?? record.providers;
1112
const normalizedProviderIds = new Set(providerIds.map(normalizeProviderId));
@@ -15,6 +16,7 @@ export function listSetupProviderIds(record: SetupDescriptorRecord): readonly st
1516
return [...providerIds, ...aliases];
1617
}
1718

19+
/** Lists setup CLI backend ids from setup metadata or manifest contribution ids. */
1820
export function listSetupCliBackendIds(record: SetupDescriptorRecord): readonly string[] {
1921
return record.setup?.cliBackends ?? record.cliBackends;
2022
}

‎src/plugins/stale-local-bundled-plugin-install-records.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import { resolveUserPath } from "../utils.js";
44
import { normalizeBundledLookupPath } from "./bundled-load-path-aliases.js";
55
import { resolveBundledPluginSources, type BundledPluginSource } from "./bundled-sources.js";
66

7+
/** Stale install record that points at old compiled bundled plugin output. */
78
export type StaleLocalBundledPluginInstallRecord = {
89
pluginId: string;
910
record: PluginInstallRecord;
@@ -49,6 +50,7 @@ function hasStaleBundledVersion(
4950
return Boolean(recordVersion && bundledVersion && recordVersion !== bundledVersion);
5051
}
5152

53+
/** Lists path install records that still point at stale compiled bundled plugin output. */
5254
export function listStaleLocalBundledPluginInstallRecords(params: {
5355
installRecords: Record<string, PluginInstallRecord>;
5456
workspaceDir?: string;
@@ -100,6 +102,7 @@ export function listStaleLocalBundledPluginInstallRecords(params: {
100102
return stale;
101103
}
102104

105+
/** Removes stale compiled bundled plugin path records from an install record map. */
103106
export function pruneStaleLocalBundledPluginInstallRecords(params: {
104107
installRecords: Record<string, PluginInstallRecord>;
105108
workspaceDir?: string;

0 commit comments

Comments
 (0)