feat(gadgets): add unified ToolDefinition type

[aaight]

Summary

• Adds ToolDefinition interface in src/gadgets/shared/toolDefinition.ts — single source of truth for all tool metadata (name, description, timeout, parameters, examples, CLI metadata, hooks)
• Defines ParameterDefinition union type covering string, number, boolean, enum, array, and object parameter types, each with required, optional, default, describe, and type-specific constraints
• Defines FileInputAlternative type for mapping text parameters to file-input CLI flags (e.g., text → text-file, body → body-file)
• Defines CLIAutoResolved type for marking params auto-resolved from env vars or git remote (e.g., owner/repo)
• Adds gadgetOnly flag on parameter definitions to exclude params like comment (rationale) from CLI flags and manifests
• Adds cliEnvVar field for params that can be auto-populated from environment variables (e.g., base from CASCADE_BASE_BRANCH)
• Adds GadgetPostExecuteHook and CLIPostExecuteHook function type placeholders for lifecycle hooks
• Exports all new types from src/gadgets/shared/index.ts
• Zero runtime code — purely TypeScript types and interfaces

Card: https://trello.com/c/6fenfE8R/270-as-a-developer-i-want-a-unified-tooldefinition-type-so-that-tool-metadata-has-a-single-source-of-truth

Test plan

• npm run typecheck passes with zero errors
• npm run lint — no new lint issues introduced (pre-existing error in web component unrelated to this change)
• Factory functions consuming these types will be validated in follow-up stories (chore: add .nvmrc for Node.js 22 #2–feat: add UpdateChecklistItem gadget and improve agent workflow #5)

[nhopeatall]

Summary

Clean type-only PR that establishes a well-designed ToolDefinition interface bridging gadget Zod schemas, oclif CLI flags, and JSON Schema manifests. The types accurately model existing patterns in the codebase (e.g., body-file / text-file alternatives, CASCADE_BASE_BRANCH env var resolution, allowNo boolean flags). No runtime code, all CI passes. Ready to merge.

Should Fix (non-blocking)

• required / optional dual booleans (line 96-98): BaseParameterDefinition has both required?: boolean and optional?: boolean with a JSDoc comment saying "Exactly one should be set to true." This invariant isn't enforced at the type level — { required: true, optional: true } compiles without error. Consider a discriminated union or a single required: boolean field instead. The factory functions in follow-up stories will need runtime validation for this either way, but catching it at compile time would be cleaner.

• Module cohesion (line 1-2 of index.ts): src/gadgets/shared/index.ts is described as "Shared utilities for file editing gadgets," but ToolDefinition is a cross-cutting concern for all tools (PM, SCM, file ops). This is fine as a starting point, but as the follow-up stories build out factory functions, consider whether this type belongs in a more central location (e.g., src/gadgets/types/ or similar) since CLI commands will also consume it.

[nhopeatall]

[SHOULD_FIX] The required + optional dual-boolean pattern creates an unenforceable invariant. A parameter definition like { type: "string", describe: "...", required: true, optional: true } compiles without error. Consider either:

1. A single required: boolean field (defaulting to true as stated in the JSDoc), or
2. A discriminated union: { mode: "required" } | { mode: "optional" }

This would let the type system prevent contradictory definitions rather than relying on runtime checks in factory functions.