From 4eba70b532f8b54c6cceac20c407526c9ea9121d Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Tue, 28 Apr 2026 23:06:45 -0700 Subject: [PATCH] docs(types): mark legacy aliases deprecated --- src/auto-reply/templating.ts | 2 ++ src/channels/plugins/types.core.ts | 4 +++- src/cli/config-set-input.ts | 1 + src/cli/gateway-cli/run.ts | 1 + src/cli/plugins-cli.ts | 1 + src/commands/onboard-types.ts | 4 ++-- src/config/types.base.ts | 4 ++-- src/config/types.cron.ts | 2 +- src/config/types.models.ts | 18 ++++++++++++++++-- src/extensionAPI.ts | 7 +++++-- src/infra/session-cost-usage.ts | 3 ++- src/plugin-sdk/channel-config-schema-legacy.ts | 2 +- src/plugin-sdk/compat.ts | 7 +++++-- src/plugin-sdk/ssrf-policy.ts | 2 +- src/plugins/types.ts | 2 ++ 15 files changed, 45 insertions(+), 15 deletions(-) diff --git a/src/auto-reply/templating.ts b/src/auto-reply/templating.ts index 1dc0fe25865..0c2f08bb0db 100644 --- a/src/auto-reply/templating.ts +++ b/src/auto-reply/templating.ts @@ -45,6 +45,8 @@ export type MsgContext = { timestamp?: number; }>; /** + * @deprecated Use CommandBody. + * * Raw message body without structural context (history, sender labels). * Legacy alias for CommandBody. Falls back to Body if not set. */ diff --git a/src/channels/plugins/types.core.ts b/src/channels/plugins/types.core.ts index d99b371c411..ccc59ed83cb 100644 --- a/src/channels/plugins/types.core.ts +++ b/src/channels/plugins/types.core.ts @@ -112,7 +112,7 @@ export type ChannelSetupInput = { useEnv?: boolean; homeserver?: string; dangerouslyAllowPrivateNetwork?: boolean; - /** Compatibility alias for legacy setup callers; prefer dangerouslyAllowPrivateNetwork. */ + /** @deprecated Compatibility alias; prefer dangerouslyAllowPrivateNetwork. */ allowPrivateNetwork?: boolean; proxy?: string; userId?: string; @@ -407,6 +407,8 @@ export type ChannelThreadingAdapter = { */ allowExplicitReplyTagsWhenOff?: boolean; /** + * @deprecated Use allowExplicitReplyTagsWhenOff. + * * Deprecated alias for allowExplicitReplyTagsWhenOff. * Kept for compatibility with older plugin surfaces. */ diff --git a/src/cli/config-set-input.ts b/src/cli/config-set-input.ts index 924a17f9066..679923311a7 100644 --- a/src/cli/config-set-input.ts +++ b/src/cli/config-set-input.ts @@ -7,6 +7,7 @@ import { export type ConfigSetOptions = { strictJson?: boolean; + /** @deprecated Use strictJson. */ json?: boolean; dryRun?: boolean; allowExec?: boolean; diff --git a/src/cli/gateway-cli/run.ts b/src/cli/gateway-cli/run.ts index 44d08b5ba28..38701c56054 100644 --- a/src/cli/gateway-cli/run.ts +++ b/src/cli/gateway-cli/run.ts @@ -49,6 +49,7 @@ type GatewayRunOpts = { force?: boolean; verbose?: boolean; cliBackendLogs?: boolean; + /** @deprecated Use cliBackendLogs. */ claudeCliLogs?: boolean; wsLog?: unknown; compact?: boolean; diff --git a/src/cli/plugins-cli.ts b/src/cli/plugins-cli.ts index f4958441b2b..1529fc308c1 100644 --- a/src/cli/plugins-cli.ts +++ b/src/cli/plugins-cli.ts @@ -42,6 +42,7 @@ export type PluginMarketplaceListOptions = { export type PluginUninstallOptions = { keepFiles?: boolean; + /** @deprecated Use keepFiles. */ keepConfig?: boolean; force?: boolean; dryRun?: boolean; diff --git a/src/commands/onboard-types.ts b/src/commands/onboard-types.ts index 4c40a9b43db..6d69d58e3e1 100644 --- a/src/commands/onboard-types.ts +++ b/src/commands/onboard-types.ts @@ -8,7 +8,7 @@ export type OnboardMode = "local" | "remote"; * are normalized elsewhere (for example `oauth` -> `setup-token`). */ export type BuiltInAuthChoice = - // Legacy alias for `setup-token` (kept for backwards CLI compatibility). + /** @deprecated Use `setup-token`. */ "oauth" | "setup-token" | "token" | "apiKey" | "custom-api-key" | "skip"; export type AuthChoice = BuiltInAuthChoice | (string & {}); @@ -20,7 +20,7 @@ export type GatewayBind = "loopback" | "lan" | "auto" | "custom" | "tailnet"; export type TailscaleMode = "off" | "serve" | "funnel"; export type NodeManagerChoice = "npm" | "pnpm" | "bun"; export type ChannelChoice = ChannelId; -// Legacy alias (pre-rename). +/** @deprecated Use ChannelChoice. */ export type ProviderChoice = ChannelChoice; export type { SecretInputMode } from "../plugins/provider-auth-types.js"; diff --git a/src/config/types.base.ts b/src/config/types.base.ts index bb29d1e2a23..198f2bdabc8 100644 --- a/src/config/types.base.ts +++ b/src/config/types.base.ts @@ -195,11 +195,11 @@ export type SessionMaintenanceConfig = { mode?: SessionMaintenanceMode; /** Remove session entries older than this duration (e.g. "30d", "12h"). Default: "30d". */ pruneAfter?: string | number; - /** Deprecated. Use pruneAfter instead. */ + /** @deprecated Use pruneAfter instead. */ pruneDays?: number; /** Maximum number of session entries to keep. Default: 500. */ maxEntries?: number; - /** Deprecated and ignored. Run `openclaw doctor --fix` to remove. */ + /** @deprecated Ignored. Run `openclaw doctor --fix` to remove. */ rotateBytes?: number | string; /** * Retention for archived reset transcripts (`*.reset.`). diff --git a/src/config/types.cron.ts b/src/config/types.cron.ts index 049f813e5dd..2e7d8ec3615 100644 --- a/src/config/types.cron.ts +++ b/src/config/types.cron.ts @@ -35,7 +35,7 @@ export type CronConfig = { /** Override default retry policy for one-shot jobs on transient errors. */ retry?: CronRetryConfig; /** - * Deprecated legacy fallback webhook URL used only for stored jobs with notify=true. + * @deprecated Legacy fallback webhook URL used only for stored jobs with notify=true. * Prefer per-job delivery.mode="webhook" with delivery.to. */ webhook?: string; diff --git a/src/config/types.models.ts b/src/config/types.models.ts index cc7ccb8814e..8d494cee851 100644 --- a/src/config/types.models.ts +++ b/src/config/types.models.ts @@ -151,10 +151,24 @@ export type ModelsConfig = { mode?: "merge" | "replace"; providers?: Record; pricing?: ModelPricingConfig; - // Deprecated legacy compat aliases. Kept in the runtime type surface so - // doctor/runtime fallbacks can read older configs until migration completes. + /** + * @deprecated Legacy compat alias. Kept so doctor/runtime fallbacks can read + * older configs until migration completes. + */ bedrockDiscovery?: BedrockDiscoveryConfig; + /** + * @deprecated Legacy compat alias. Kept so doctor/runtime fallbacks can read + * older configs until migration completes. + */ copilotDiscovery?: DiscoveryToggleConfig; + /** + * @deprecated Legacy compat alias. Kept so doctor/runtime fallbacks can read + * older configs until migration completes. + */ huggingfaceDiscovery?: DiscoveryToggleConfig; + /** + * @deprecated Legacy compat alias. Kept so doctor/runtime fallbacks can read + * older configs until migration completes. + */ ollamaDiscovery?: DiscoveryToggleConfig; }; diff --git a/src/extensionAPI.ts b/src/extensionAPI.ts index 267ba27ab3c..46da1b0284c 100644 --- a/src/extensionAPI.ts +++ b/src/extensionAPI.ts @@ -1,5 +1,8 @@ -// Legacy compat surface for plugins that still import openclaw/extension-api. -// Keep this file intentionally narrow and forward-only. +/** + * @deprecated Legacy compat surface for plugins that still import + * openclaw/extension-api. Use the injected plugin runtime or focused + * openclaw/plugin-sdk subpaths instead. + */ const shouldWarnExtensionApiImport = process.env.VITEST !== "true" && diff --git a/src/infra/session-cost-usage.ts b/src/infra/session-cost-usage.ts index 8598cfc9e54..f69f6cdb481 100644 --- a/src/infra/session-cost-usage.ts +++ b/src/infra/session-cost-usage.ts @@ -362,7 +362,8 @@ export function resolveExistingUsageSessionFile(params: { export async function loadCostUsageSummary(params?: { startMs?: number; endMs?: number; - days?: number; // Deprecated, for backwards compatibility + /** @deprecated Use startMs/endMs. */ + days?: number; config?: OpenClawConfig; agentId?: string; }): Promise { diff --git a/src/plugin-sdk/channel-config-schema-legacy.ts b/src/plugin-sdk/channel-config-schema-legacy.ts index fe19e213208..a09fadd3bf6 100644 --- a/src/plugin-sdk/channel-config-schema-legacy.ts +++ b/src/plugin-sdk/channel-config-schema-legacy.ts @@ -1,5 +1,5 @@ /** - * @deprecated Deprecated bundled-channel compatibility surface. Compatibility surface for bundled channel schemas. + * @deprecated Compatibility surface for bundled channel schemas. * * OpenClaw-maintained bundled plugins should import * openclaw/plugin-sdk/bundled-channel-config-schema. Third-party plugins should diff --git a/src/plugin-sdk/compat.ts b/src/plugin-sdk/compat.ts index 84e0c04a550..62648b419d8 100644 --- a/src/plugin-sdk/compat.ts +++ b/src/plugin-sdk/compat.ts @@ -1,5 +1,8 @@ -// Legacy compat surface for external plugins that still depend on older -// broad plugin-sdk imports. Keep this file intentionally small. +/** + * @deprecated Legacy compat surface for external plugins that still depend on + * older broad plugin-sdk imports. Use focused openclaw/plugin-sdk subpaths + * instead. + */ const shouldWarnCompatImport = process.env.VITEST !== "true" && diff --git a/src/plugin-sdk/ssrf-policy.ts b/src/plugin-sdk/ssrf-policy.ts index 9e0465a5e79..ca49ccfe236 100644 --- a/src/plugin-sdk/ssrf-policy.ts +++ b/src/plugin-sdk/ssrf-policy.ts @@ -23,7 +23,7 @@ export type PrivateNetworkOptInInput = | Pick | { dangerouslyAllowPrivateNetwork?: boolean | null; - /** Compatibility alias for legacy callers; prefer dangerouslyAllowPrivateNetwork. */ + /** @deprecated Compatibility alias; prefer dangerouslyAllowPrivateNetwork. */ allowPrivateNetwork?: boolean | null; network?: | Pick diff --git a/src/plugins/types.ts b/src/plugins/types.ts index affc846212a..76e0daf49a3 100644 --- a/src/plugins/types.ts +++ b/src/plugins/types.ts @@ -1214,6 +1214,8 @@ export type ProviderPlugin = { */ staticCatalog?: ProviderPluginCatalog; /** + * @deprecated Use catalog. + * * Legacy alias for catalog. * Kept for compatibility with existing provider plugins. */