feat(api): add per-request `--timeout` for raw and generated service commands

Summary

Add a request-level --timeout <duration> option to the raw lark-cli api command and all metadata-generated service method commands.

The timeout applies to one HTTP request. For paginated operations, each page receives a fresh timeout budget. It is not a total deadline for the entire command or pagination sequence.

Motivation

The internal client can already enforce request-level deadlines and classify transport timeouts as typed network/timeout errors. However, raw API commands and generated service commands do not expose this capability to users.

Agents, CI jobs, and scripts currently have to rely on an external process timeout. Forcefully terminating the CLI loses its structured error response, recovery information, and normal cleanup behavior. A native request timeout allows automation to fail predictably while preserving the CLI's typed error and exit-code contracts.

Proposed CLI

lark-cli api GET /open-apis/calendar/v4/calendars --timeout 5s
lark-cli contact users list --timeout 30s

The new option must:

• Accept Go duration syntax, such as 500ms, 5s, and 2m.
• Default to 0, which preserves the current client-default behavior.
• Apply to a single HTTP request.
• Apply independently to every page request during pagination.
• Be available on both paginating and non-paginating generated service methods.

Expected Behavior

Request execution

• A positive timeout creates a request-scoped context deadline immediately before the HTTP request is executed.
• A zero timeout does not create a new deadline.
• If the caller context already has a deadline, the CLI must preserve it rather than replacing or extending it.
• Paginated calls must carry the configured duration to every page and create a fresh deadline for each page.
• The timeout must not be written to a shared http.Client.Timeout, because that would affect unrelated calls using the same client.

Validation and errors

• Negative values must return a typed validation error with:
  • type=validation
  • subtype=invalid_argument
  • param=--timeout
• Unparseable values such as --timeout nope must produce the same typed validation attribution.
• Transport timeouts must continue to use the existing typed error contract:
  • type=network
  • subtype=timeout
• The underlying timeout cause must remain discoverable through errors.Is or errors.As.
• No new error category, subtype, or exit code should be introduced.

Dry-run output

Dry-run must show the normalized timeout on the individual API call without creating a timer or sending a network request:

{
  "data": {
    "api": [
      {
        "method": "GET",
        "url": "/open-apis/calendar/v4/calendars",
        "timeout": "5s"
      }
    ]
  }
}

• The field belongs at data.api[n].timeout, not at the envelope or context level.
• The field must be omitted when the timeout is zero or unspecified.
• Standard and file-upload dry-runs must follow the same contract.

Generated service schema

Generated service method input schemas must expose a CLI-only property:

{
  "timeout": {
    "type": "string",
    "format": "duration",
    "flag": "--timeout",
    "default": "0s",
    "description": "Per-request timeout in Go duration format. 0 uses the client default; pagination applies it to each page."
  }
}

The property must not:

• Appear in inputSchema.required.
• Be sent as an API query parameter, request body field, file field, or header.
• Be derived from remote service metadata.

Scope

• Raw lark-cli api requests.
• Metadata-generated service method commands.
• Normal JSON requests, binary operations, file-upload dry-runs, and pagination.
• Help, dry-run, schema, validation, and typed transport-error contracts.

Non-goals

• Adding a total command or total pagination time budget.
• Changing the default client timeout.
• Automatically retrying timed-out requests.
• Adding timeout behavior to auth login, event consume, shortcuts, or other long-lived commands.
• Changing existing pagination partial-output behavior.
• Adding a new dependency or modifying generated service metadata by hand.

Test Plan

• Add client tests for positive timeout injection, zero-value behavior, parent-deadline preservation, typed timeout classification, and cause preservation.
• Add a deterministic three-page pagination test proving that the timeout is applied per page rather than to the complete loop.
• Add raw API command tests for parsing, zero and negative values, malformed duration attribution, request propagation, and dry-run output.
• Add equivalent generated service command tests, including help grouping and pagination propagation.
• Add dry-run tests covering positive values, zero-value omission, and file uploads.
• Add schema assembly and lint tests for the complete timeout property and optional-field contract.
• Use local fake transports or test servers only; tests must not require public network access or real credentials.

Compatibility

This is an additive CLI option. Commands that do not pass --timeout retain their existing execution and output behavior. The implementation must not change shared client state, public client method signatures, generated metadata, or the existing error taxonomy.

Start at the raw lark-cli api command and the metadata-generated service method command path, then trace request execution, pagination, dry-run output, and schema assembly. Use local fake transports or test servers to cover timeout parsing, parent-deadline preservation, typed errors, per-page propagation, and zero-value omission. Done means both command families and their schemas, help, validation, dry-runs, uploads, and pagination satisfy the stated contracts without changing shared client state.