From d4ed8964d3000e8b2e77fab4cf58fd8f103df685 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 4 Jun 2026 12:37:56 -0400 Subject: [PATCH] docs: document onboarding helper comments --- src/commands/onboard-channels.ts | 1 + src/commands/onboard-config.ts | 5 +++++ src/commands/onboard-core-auth-flags.ts | 2 ++ src/commands/onboard-helpers.ts | 15 +++++++++++++++ src/commands/onboard-hooks.ts | 7 +++++-- 5 files changed, 28 insertions(+), 2 deletions(-) diff --git a/src/commands/onboard-channels.ts b/src/commands/onboard-channels.ts index 0b0a0afc8037..fd5bda26a4b7 100644 --- a/src/commands/onboard-channels.ts +++ b/src/commands/onboard-channels.ts @@ -1,3 +1,4 @@ +/** Re-export seam for channel onboarding flow helpers. */ export { createChannelOnboardingPostWriteHook, createChannelOnboardingPostWriteHookCollector, diff --git a/src/commands/onboard-config.ts b/src/commands/onboard-config.ts index ebf4ad2414df..d0a153c221ea 100644 --- a/src/commands/onboard-config.ts +++ b/src/commands/onboard-config.ts @@ -1,11 +1,15 @@ +/** Shared config mutations used by interactive and non-interactive onboarding. */ import { setConfigValueAtPath } from "../config/config-paths.js"; import type { DmScope } from "../config/types.base.js"; import type { OpenClawConfig } from "../config/types.openclaw.js"; import type { ToolProfileId } from "../config/types.tools.js"; +/** Default DM scoping selected during local onboarding. */ export const ONBOARDING_DEFAULT_DM_SCOPE: DmScope = "per-channel-peer"; +/** Default tool profile selected during local onboarding. */ export const ONBOARDING_DEFAULT_TOOLS_PROFILE: ToolProfileId = "coding"; +/** Applies local gateway/workspace defaults without overwriting explicit user defaults. */ export function applyLocalSetupWorkspaceConfig( baseConfig: OpenClawConfig, workspaceDir: string, @@ -34,6 +38,7 @@ export function applyLocalSetupWorkspaceConfig( }; } +/** Marks default agents to skip bootstrap file creation. */ export function applySkipBootstrapConfig(cfg: OpenClawConfig): OpenClawConfig { const next = structuredClone(cfg); setConfigValueAtPath( diff --git a/src/commands/onboard-core-auth-flags.ts b/src/commands/onboard-core-auth-flags.ts index 720aaca75bb0..17a6194a76f7 100644 --- a/src/commands/onboard-core-auth-flags.ts +++ b/src/commands/onboard-core-auth-flags.ts @@ -1,3 +1,4 @@ +/** Core auth flag registry for onboarding CLI help and routing. */ import type { AuthChoice, OnboardOptions } from "./onboard-types.js"; type OnboardCoreAuthOptionKey = Extract; @@ -10,4 +11,5 @@ type OnboardCoreAuthFlag = { description: string; }; +/** Auth-related CLI flags owned by core onboarding rather than provider plugins. */ export const CORE_ONBOARD_AUTH_FLAGS: ReadonlyArray = []; diff --git a/src/commands/onboard-helpers.ts b/src/commands/onboard-helpers.ts index be1bd9b27389..c6be9c7a5346 100644 --- a/src/commands/onboard-helpers.ts +++ b/src/commands/onboard-helpers.ts @@ -1,3 +1,4 @@ +/** Shared helpers for onboarding, reset, gateway checks, and wizard output. */ import fs from "node:fs/promises"; import path from "node:path"; import { inspect } from "node:util"; @@ -42,6 +43,7 @@ export { detectBinary }; export { detectBrowserOpenSupport, openUrl, resolveBrowserOpenCommand }; export { resolveControlUiLinks }; +/** Handles Clack cancellation by exiting through the runtime. */ export function guardCancel(value: T | symbol, runtime: RuntimeEnv): T { if (isCancel(value)) { cancel(stylePromptTitle("Setup cancelled.") ?? "Setup cancelled."); @@ -51,6 +53,7 @@ export function guardCancel(value: T | symbol, runtime: RuntimeEnv): T { return value; } +/** Summarizes existing config values before onboarding overwrites or reuses them. */ export function summarizeExistingConfig(config: OpenClawConfig): string { const rows: string[] = []; const defaults = config.agents?.defaults; @@ -127,6 +130,7 @@ function formatGatewayBind(value: string | undefined): string | undefined { } } +/** Normalizes gateway token prompts while rejecting JS stringification sentinels. */ export function normalizeGatewayTokenInput(value: unknown): string { if (typeof value !== "string") { return ""; @@ -140,6 +144,7 @@ export function normalizeGatewayTokenInput(value: unknown): string { return trimmed; } +/** Validates gateway password prompt input. */ export function validateGatewayPasswordInput(value: unknown): string | undefined { if (typeof value !== "string") { return "Required"; @@ -154,6 +159,7 @@ export function validateGatewayPasswordInput(value: unknown): string | undefined return undefined; } +/** Prints the onboarding banner. */ export function printWizardHeader(runtime: RuntimeEnv) { const bannerWidth = 54; const icon = decorativeEmoji("🦞"); @@ -172,6 +178,7 @@ export function printWizardHeader(runtime: RuntimeEnv) { runtime.log(header); } +/** Records wizard provenance metadata on config writes. */ export function applyWizardMetadata( cfg: OpenClawConfig, params: { command: string; mode: OnboardMode }, @@ -191,6 +198,7 @@ export function applyWizardMetadata( }; } +/** Formats the no-GUI SSH tunnel hint for opening the Control UI remotely. */ export function formatControlUiSshHint(params: { port: number; basePath?: string; @@ -226,6 +234,7 @@ function resolveSshTargetHint(): string { return `${user}@${host}`; } +/** Ensures workspace bootstrap files and session transcript directories exist. */ export async function ensureWorkspaceAndSessions( workspaceDir: string, runtime: RuntimeEnv, @@ -246,6 +255,7 @@ export async function ensureWorkspaceAndSessions( runtime.log(`Sessions OK: ${shortenHomePath(sessionsDir)}`); } +/** Returns package manager choices offered by onboarding. */ export function resolveNodeManagerOptions(): Array<{ value: NodeManagerChoice; label: string; @@ -257,6 +267,7 @@ export function resolveNodeManagerOptions(): Array<{ ]; } +/** Moves a path to Trash when it exists, logging a manual-delete fallback on failure. */ export async function moveToTrash(pathname: string, runtime: RuntimeEnv): Promise { if (!pathname) { return; @@ -297,6 +308,7 @@ async function resolveMoveToTrashAllowedRoots(targetPath: string): Promise 120 ? `${line.slice(0, 119)}…` : line; } +/** Default workspace path shown by onboarding prompts. */ export const DEFAULT_WORKSPACE = DEFAULT_AGENT_WORKSPACE_DIR; diff --git a/src/commands/onboard-hooks.ts b/src/commands/onboard-hooks.ts index 47bc2d74a085..65c74bf61104 100644 --- a/src/commands/onboard-hooks.ts +++ b/src/commands/onboard-hooks.ts @@ -1,3 +1,4 @@ +/** Interactive onboarding step for enabling workspace hooks. */ import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agents/agent-scope.js"; import { formatCliCommand } from "../cli/command-format.js"; import type { OpenClawConfig } from "../config/types.openclaw.js"; @@ -6,6 +7,7 @@ import type { RuntimeEnv } from "../runtime.js"; import { t } from "../wizard/i18n/index.js"; import type { WizardPrompter } from "../wizard/prompts.js"; +/** Prompts for loadable internal hooks and writes selected hook entries. */ export async function setupInternalHooks( cfg: OpenClawConfig, _runtime: RuntimeEnv, @@ -21,7 +23,8 @@ export async function setupInternalHooks( t("wizard.hooks.introTitle"), ); - // Discover available hooks using the hook discovery system + // Discover hooks through the same status path used by hook commands so setup + // only offers entries that would be loadable after onboarding finishes. const workspaceDir = resolveAgentWorkspaceDir(cfg, resolveDefaultAgentId(cfg)); const report = buildWorkspaceHookStatus(workspaceDir, { config: cfg }); @@ -50,7 +53,7 @@ export async function setupInternalHooks( return cfg; } - // Enable selected hooks using the new entries config format + // Use entries format so per-hook enablement survives future global defaults. const entries = { ...cfg.hooks?.internal?.entries }; for (const name of selected) { entries[name] = { enabled: true };