/*
<MODULE_CONTRACT>
<purpose>Register the werkstatt.commands.validate command with the kernel registry and module loader (RFC-0903, DNA-82).</purpose>

<non-goals>
  <item>Do not implement validation logic — delegate to plugin/commands-validate.ts.</item>
  <item>Do not add to PACKAGES_CHECK_PIPELINE — gated adoption per RFC-0903.</item>
</non-goals>
</MODULE_CONTRACT>
<CHANGE_SUMMARY>
  <item>RFC-1173: declare mutatesState on all kernel commands — collectDeclarationDiagnostics emits error-severity MUTATES-STATE-DECLARED, command.manifest.validate is the blocking consumer in packages.check, sweep declares the flag on every command definition (factories hardcode false for read-only check specs)</item>
  <item>RFC-1231: step 1 — rename supportsAllSites to acceptsAllFlag

Mechanical sweep: the field only ever gated --all argv acceptance; fan-out
follows the parsed selector. Guard renamed assertAllSitesAllowed ->
assertAllFlagAccepted, message updated. 417 declaration sites + type
surfaces (KernelCommandMetadata, ForgeCommandMetadata) in one atomic pass.</item>
  <item>RFC-1248: VITE-CLIENT-DEP-02 lazy-import gate + SCAN-02 validator reads-root existence check (RFC-1248)</item>
  <item>RFC-1304: shared fail-loud scanner — CMDGEN-04/05 diagnostics via werkstatt-shared/kernel/command-source-scan.ts, CMD-SCAN-01 coverage notices, rules[] lists every emitted rule id</item>
  <item>RFC-1321</item>
  <history>RFC-0903, RFC-1097</history>
</CHANGE_SUMMARY>
*/

import type {
  KernelCommandInput,
  KernelCommandResult,
  KernelRuntimeContext,
} from "../src/kernel/types.ts";
import type { ModuleExport } from "../src/runtime/desired-state.ts";
import {
  runCommandsValidate,
  type CommandsValidateResult,
} from "../src/plugin/commands-validate.ts";
import { loadValidationBaseline } from "@warpgogol/werkstatt-shared/kernel";

export const werkstattCommandsValidateModule: ModuleExport = {
  name: "werkstatt-commands-validate",
  version: "0.1.0",
  declarations: [],
  commands: [
    {
      name: "werkstatt.commands.validate",
      mutatesState: false,
      contract: "werkstatt",
      baselineEligible: true,
      rules: [
        "CMD-OUTPUT-01",
        "CMD-OUTPUT-02",
        "CMD-OUTPUT-03",
        "CMDGEN-04",
        "CMDGEN-05",
        "CMDGEN-06",
        "CMD-SCAN-01",
      ],
      modulePath: "packages/werkstatt-engine/os/werkstatt-commands-validate.module.ts",
      description:
        "Statically analyze kernel command handler return statements for DNA-82 compliance: explicit exitCode, [command.name]-prefixed summary, nextSteps on failure. Enforces RFC-0903.",
      scope: "workspace",
      acceptsAllFlag: false,
      flags: {
        mode: {
          kind: "string",
          description:
            "Violation severity: 'error' (blocking, default) or 'warning' (non-blocking).",
          default: "error",
        },
        json: {
          kind: "boolean",
          description: "Output diagnostics as JSON.",
          default: false,
        },
        strict: {
          kind: "boolean",
          description:
            "Ignore docs/validation-baseline.generated.yaml — report baseline-recorded debt as full violations (RFC-1316).",
          default: false,
        },
      },
      reads: [
        "packages/werkstatt-engine/src/**",
        "packages/werkstatt-site/src/**",
        "packages/werkstatt-shared/src/**",
        "docs/validation-baseline.generated.yaml",
      ],
      cacheable: false,
      async execute(
        input: KernelCommandInput,
        context: KernelRuntimeContext,
      ): Promise<KernelCommandResult<CommandsValidateResult>> {
        const mode = (input.flags.mode as "error" | "warning") ?? "error";
        const strict = input.flags.strict === true;
        const baseline = strict
          ? undefined
          : await loadValidationBaseline(context.workspaceRoot, context.io);
        return runCommandsValidate(context.workspaceRoot, mode, context.io, {
          strict,
          baseline,
        });
      },
    },
  ],
  pipelines: [],
};