pikasTech-unidesk/scripts/src/hwlab-node-help.ts

// SPEC: PJ2026-01060505 Workbench Performance draft-2026-06-17-p0.
// SPEC: PJ2026-01060508 Web哨兵 draft-2026-06-26-p9-multi-web-probe-sentinel.
// Responsibility: Help payloads for HWLAB node/lane and web-probe CLI entries.
import { hwlabRuntimeLaneConfigPath } from "./hwlab-node-lanes";

export function hwlabNodeHelp(): Record<string, unknown> {
  return {
    ok: true,
    command: "hwlab nodes",
    description: "Node/lane oriented HWLAB runtime operations. Web probes moved to the top-level web-probe command.",
    configPath: hwlabRuntimeLaneConfigPath(),
    examples: [
      "bun scripts/cli.ts hwlab nodes control-plane infra plan --node D601 --lane v03",
      "bun scripts/cli.ts hwlab nodes control-plane status --node D601 --lane v03",
      "bun scripts/cli.ts hwlab nodes git-mirror status --node G14 --lane v03",
      "bun scripts/cli.ts hwlab nodes hwpod-preinstall plan --node D601 --lane v03 --dry-run",
      "bun scripts/cli.ts hwlab nodes secret status --node G14 --lane v03 --name <secret>",
      "bun scripts/cli.ts hwlab nodes test-accounts status --node D601 --lane v03",
      "bun scripts/cli.ts hwlab nodes observability performance-summary --node D601 --lane v03",
      "bun scripts/cli.ts web-probe --help",
    ],
    actions: {
      "control-plane": "YAML-first node-local CI/CD, git-mirror, public exposure, runtime-image, Argo and PipelineRun operations.",
      "git-mirror": "Inspect or operate the selected node/lane source mirror.",
      "hwpod-preinstall": "Render YAML-first HWPOD preinstall configRefs, runtime mount targets, PM MDTODO source, and gateway profile status.",
      secret: "Inspect and sync YAML-declared runtime Secrets without printing secret values.",
      "test-accounts": "Prepare YAML-declared HWLAB admin/test account API keys with redacted sourceRef/fingerprint output.",
      observability: "Read runtime metrics and authenticated Web Performance summaries.",
    },
    notes: [
      "`web-probe` is no longer under `hwlab nodes`; use `bun scripts/cli.ts web-probe ...`.",
      "`--node` and `--lane` remain data arguments resolved from YAML for node/lane operations.",
      "`trigger-current --confirm --wait` is the one-command CICD path for current node/lane runtime publish.",
    ],
  };
}

export function hwlabNodeWebProbeHelp(): Record<string, unknown> {
  return {
    ok: true,
    command: "web-probe",
    description: "Run target node/lane HWLAB Cloud Web probes with YAML-selected origin and one-shot bootstrap Web credentials.",
    examples: [
      "bun scripts/cli.ts web-probe run --node D601 --lane v03 --wait-messages-ms 1000",
      "bun scripts/cli.ts web-probe run --node D601 --lane v03 --fresh-session --message 'ping'",
      "bun scripts/cli.ts web-probe script --node D601 --lane v03 --script-file .state/probes/workbench.mjs",
      "bun scripts/cli.ts web-probe screenshot --node D601 --lane v03 --url https://monitor.pikapython.com --viewport 1440x900",
      "bun scripts/cli.ts web-probe screenshot --node D601 --lane v03 --url https://monitor.pikapython.com --viewport 390x844 --name monitor-mobile.png",
      "bun scripts/cli.ts web-probe observe start --node D601 --lane v03 --target-path /workbench --sample-interval-ms 5000",
      "bun scripts/cli.ts web-probe observe start --node D601 --lane v03 --target-path /projects/mdtodo --sample-interval-ms 5000",
      "bun scripts/cli.ts web-probe observe command webobs-xxxx --type sendPrompt --text 'ping'",
      "bun scripts/cli.ts web-probe observe command webobs-xxxx --type closeMdtodoSourceConfig",
      "bun scripts/cli.ts web-probe observe command webobs-xxxx --type selectMdtodoFile --filename 20260609_频率判断_用户反馈.md",
      "bun scripts/cli.ts web-probe observe command webobs-xxxx --type openMdtodoReportPreview --task R1 --link R1.1",
      "bun scripts/cli.ts web-probe observe command webobs-xxxx --type toggleMdtodoReportFullscreen --text toggle",
      "bun scripts/cli.ts web-probe observe command webobs-xxxx --type editMdtodoTaskInline --task R1 --field body --text 'body updated through web-probe command'",
      "bun scripts/cli.ts web-probe observe command webobs-xxxx --type launchWorkbenchFromMdtodo --task R1.1",
      "bun scripts/cli.ts web-probe observe status webobs-xxxx",
      "bun scripts/cli.ts web-probe observe collect webobs-xxxx --view turn-summary",
      "bun scripts/cli.ts web-probe observe collect webobs-xxxx --view timeline --command-id cmd-xxxx",
      "bun scripts/cli.ts web-probe observe collect webobs-xxxx --view project-mdtodo-summary",
      "bun scripts/cli.ts web-probe observe analyze webobs-xxxx",
      "bun scripts/cli.ts web-probe sentinel plan --node D601 --lane v03 --dry-run",
      "bun scripts/cli.ts web-probe sentinel plan --node D601 --lane v03 --sentinel workbench-auth-session-switch-2users",
      "bun scripts/cli.ts web-probe sentinel dashboard verify --node D601 --lane v03 --sentinel workbench-dsflash-go-tool-call-10x",
      "bun scripts/cli.ts web-probe sentinel dashboard screenshot --node D601 --lane v03 --sentinel workbench-auth-session-switch-2users",
      "bun scripts/cli.ts web-probe sentinel maintenance stop --node D601 --lane v03 --sentinel workbench-dsflash-go-tool-call-10x --confirm --wait --release-id <id>",
    ],
    actions: {
      run: "Run the repo-owned scripts/web-live-dom-probe.mjs helper.",
      script: "Run caller-provided Playwright JS after CLI-managed /auth/login; scripts must not handle secrets themselves.",
      screenshot: "Capture a no-auth or public page through the selected node/lane remote browser and download PNG artifacts to the caller /tmp by default.",
      observe: "Start, inspect, control, stop, collect, and analyze a long-running observer that writes JSONL artifacts.",
      sentinel: "Render and operate the YAML-first web-probe sentinel wrapper, image, GitOps, dashboard verification, maintenance and report views.",
    },
    notes: [
      "Default URL, browser proxy mode, observe/analyze thresholds, and project-management command allowlist come from config/hwlab-node-lanes.yaml webProbe.",
      "`web-probe script` is an ad-hoc exploration escape hatch; repeated/high-frequency workflows must become `web-probe observe command` types or repo-owned web-probe commands.",
      "observe is passive by default; user actions must be explicit observe command entries in control.jsonl.",
      "After observe start, prefer observe status|command|stop|collect|analyze <id> instead of repeating --node/--lane/--state-dir.",
      "collect views render bounded summaries from existing artifacts and do not create a second source of truth.",
      "analyze is offline-only: it reads artifact JSONL and writes analysis/report.md plus analysis/report.json.",
      "When multiple web-probe sentinels are declared, sentinel image/control-plane/validate/maintenance/dashboard/report require `--sentinel <id>`; plan/status without it show the registry drill-down.",
      "Issue evidence should cite observer id, stateDir, report SHA, screenshot SHA, command ids and concise summaries, not prompt/provider/secret payloads.",
    ],
  };
}

export function hwlabNodeObservabilityHelp(): Record<string, unknown> {
  return {
    ok: true,
    command: "hwlab nodes observability",
    description: "YAML-first node/lane observability control for HWLAB Workbench metrics. Runtime is queried only for presence, boundary, and summary evidence.",
    configPath: hwlabRuntimeLaneConfigPath(),
    examples: [
      "bun scripts/cli.ts hwlab nodes observability plan --node D601 --lane v03",
      "bun scripts/cli.ts hwlab nodes observability apply --node D601 --lane v03 --dry-run",
      "bun scripts/cli.ts hwlab nodes observability apply --node D601 --lane v03 --confirm",
      "bun scripts/cli.ts hwlab nodes observability status --node D601 --lane v03",
      "bun scripts/cli.ts hwlab nodes observability workbench-summary --node D601 --lane v03",
      "bun scripts/cli.ts hwlab nodes observability performance-summary --node D601 --lane v03",
    ],
    actions: {
      plan: "Render the YAML-declared collection mode, scrape target, boundary, and required Workbench metric series.",
      apply: "Apply the YAML-declared observability control plane. D601 pod-loopback mode validates the boundary and metrics without creating ad-hoc cluster objects.",
      status: "Check Kubernetes service/pod presence, public raw metrics denial, and Workbench metric readiness.",
      "workbench-summary": "Read the YAML-declared metrics endpoint via pod loopback and summarize required Workbench series.",
      "performance-summary": "Fetch the authenticated same-origin Web Performance summary for the selected node/lane and return a compact ops interpretation.",
    },
  };
}