Summary

Add --env-gates flag to yarn list-tools that shows which USE_* environment variable controls which tools. This automates the documentation of feature gates.

Motivation

Current README manually documents which tools each USE_* variable enables. This is error-prone and frequently out of sync (e.g., USE_LABELS lists 5 old tools instead of 2 CQRS tools).

Proposed Usage

# Show env gates table
yarn list-tools --env-gates

# Output as markdown for docs
yarn list-tools --env-gates --markdown > docs/ENV_GATES.md

# Output as JSON
yarn list-tools --env-gates --json

Expected Output

# Environment Variable Gates

| Variable | Default | Tools Controlled |
|----------|---------|------------------|
| `USE_LABELS` | `true` | `browse_labels`, `manage_label` |
| `USE_GITLAB_WIKI` | `false` | `browse_wiki`, `manage_wiki` |
| `USE_MILESTONE` | `false` | `browse_milestones`, `manage_milestone` |
| `USE_PIPELINE` | `false` | `browse_pipelines`, `manage_pipeline`, `manage_pipeline_job` |
| `USE_VARIABLES` | `true` | `browse_variables`, `manage_variable` |
| `USE_MRS` | `true` | `browse_merge_requests`, `browse_mr_discussions`, `manage_merge_request`, `manage_mr_discussion`, `manage_draft_notes` |
| `USE_FILES` | `true` | `browse_files`, `manage_files` |
| `USE_WORKITEMS` | `true` | `browse_work_items`, `manage_work_item` |
| `USE_WEBHOOKS` | `true` | `list_webhooks`, `manage_webhook` |
| `USE_SNIPPETS` | `true` | `list_snippets`, `manage_snippet` |
| `USE_INTEGRATIONS` | `true` | `list_integrations`, `manage_integration` |
| *(none - always on)* | - | Core tools (13) |

Implementation

1. Add gate metadata to EnhancedToolDefinition

interface EnhancedToolDefinition {
  name: string;
  description: string;
  inputSchema: JsonSchema;
  handler: ToolHandler;
  gate?: {
    envVar: string;      // e.g., "USE_LABELS"
    defaultValue: boolean;
  };
}

2. Update each entity registry

// src/entities/labels/registry.ts
export const labelsToolRegistry: ToolRegistry = new Map([
  ["browse_labels", {
    name: "browse_labels",
    description: "...",
    inputSchema: z.toJSONSchema(BrowseLabelsSchema),
    handler: handleBrowseLabels,
    gate: { envVar: "USE_LABELS", defaultValue: true },
  }],
  // ...
]);

3. Add CLI flag handler

// src/scripts/list-tools.ts
case "--env-gates":
  options.showEnvGates = true;
  break;

// In main():
if (options.showEnvGates) {
  const gates = extractEnvGates(tools);
  if (options.format === "json") {
    console.log(JSON.stringify(gates, null, 2));
  } else {
    printEnvGatesMarkdown(gates);
  }
  return;
}

4. Extract gates from registry

function extractEnvGates(tools: EnhancedToolDefinition[]): Map<string, GateInfo> {
  const gates = new Map<string, GateInfo>();
  
  for (const tool of tools) {
    if (tool.gate) {
      const existing = gates.get(tool.gate.envVar);
      if (existing) {
        existing.tools.push(tool.name);
      } else {
        gates.set(tool.gate.envVar, {
          envVar: tool.gate.envVar,
          defaultValue: tool.gate.defaultValue,
          tools: [tool.name],
        });
      }
    }
  }
  
  return gates;
}

Tasks

• Add gate field to EnhancedToolDefinition interface
• Update all entity registries with gate metadata:
  • Labels (USE_LABELS)
  • Wiki (USE_GITLAB_WIKI)
  • Milestones (USE_MILESTONE)
  • Pipelines (USE_PIPELINE)
  • Variables (USE_VARIABLES)
  • MRs (USE_MRS)
  • Files (USE_FILES)
  • Work Items (USE_WORKITEMS)
  • Webhooks (USE_WEBHOOKS)
  • Snippets (USE_SNIPPETS)
  • Integrations (USE_INTEGRATIONS)
• Add --env-gates flag to CLI parser
• Implement extractEnvGates() function
• Implement printEnvGatesMarkdown() function
• Add JSON output support
• Write unit tests
• Update CLI help text

Documentation

Update README.md CLI section:

yarn list-tools --env-gates    # Show which USE_* controls which tools

Acceptance Criteria

• yarn list-tools --env-gates outputs correct table
• All 11 USE_* variables documented with their tools
• Core tools shown as "always on"
• JSON output works for automation
• Output can be used directly in docs/CONFIGURATION.md

Priority

HIGH - Prerequisite for documentation automation (#24)

Dependencies

None