# PortTracker Batch Operations Design

**Date:** 2026-02-27
**Status:** Approved

## Problem

The PortTracker CLI only supports one-at-a-time operations for status updates, mappings, and N/A marking. With ~3700 features and ~3300 tests, bulk operations require dropping to raw `sqlite3` commands. This is error-prone and bypasses any validation the CLI could provide.

## Design

### Approach

Add `batch-update` and `batch-map` subcommands under each existing entity command (`feature`, `test`, `module`, `library`). All batch commands share a common filter + dry-run infrastructure.

### Shared Batch Infrastructure

A new `BatchFilters` static class in `Commands/BatchFilters.cs` provides:

**Filter Options** (combined with AND logic):
- `--ids <range>` — ID range like `100-200`, comma-separated `1,5,10`, or mixed `1-5,10,20-25`
- `--module <id>` — filter by module_id (feature/test only)
- `--status <status>` — filter by current status value

**Dry-Run Default:**
- Without `--execute`, commands show a preview: "Would affect N items:" + table of matching rows
- With `--execute`, changes are applied inside a transaction and "Updated N items." is printed
- At least one filter is required (no accidental "update everything" with zero filters)

**Shared Methods:**
- `AddFilterOptions(Command cmd, bool includeModuleFilter)` — adds the common options to a command
- `BuildWhereClause(...)` — returns SQL WHERE clause + parameters from parsed filter values
- `PreviewOrExecute(Database db, string table, string selectSql, string updateSql, params[], bool execute)` — handles dry-run preview vs actual execution

### Feature Batch Commands

**`feature batch-update`**
- Filters: `--ids`, `--module`, `--status`
- Setters: `--set-status` (required), `--set-notes` (optional)
- Flag: `--execute`

**`feature batch-map`**
- Filters: `--ids`, `--module`, `--status`
- Setters: `--set-project`, `--set-class`, `--set-method` (at least one required)
- Flag: `--execute`

### Test Batch Commands

**`test batch-update`**
- Filters: `--ids`, `--module`, `--status`
- Setters: `--set-status` (required), `--set-notes` (optional)
- Flag: `--execute`

**`test batch-map`**
- Filters: `--ids`, `--module`, `--status`
- Setters: `--set-project`, `--set-class`, `--set-method` (at least one required)
- Flag: `--execute`

### Module Batch Commands

**`module batch-update`**
- Filters: `--ids`, `--status`
- Setters: `--set-status` (required), `--set-notes` (optional)
- Flag: `--execute`

**`module batch-map`**
- Filters: `--ids`, `--status`
- Setters: `--set-project`, `--set-namespace`, `--set-class` (at least one required)
- Flag: `--execute`

### Library Batch Commands

**`library batch-update`**
- Filters: `--ids`, `--status`
- Setters: `--set-status` (required), `--set-notes` (optional, maps to `dotnet_usage_notes`)
- Flag: `--execute`

**`library batch-map`**
- Filters: `--ids`, `--status`
- Setters: `--set-package`, `--set-namespace`, `--set-notes` (at least one required)
- Flag: `--execute`

## Examples

```bash
# Preview: which features in module 5 are not_started?
porttracker feature batch-update --module 5 --status not_started --set-status deferred

# Execute: defer all features in module 5 with a reason
porttracker feature batch-update --module 5 --status not_started --set-status deferred --set-notes "needs server runtime" --execute

# Execute: mark tests 500-750 as deferred
porttracker test batch-update --ids 500-750 --set-status deferred --set-notes "server-integration" --execute

# Execute: batch-map all features in module 3 to a .NET project
porttracker feature batch-map --module 3 --set-project "ZB.MOM.NatsNet.Server" --execute

# Preview: what libraries are unmapped?
porttracker library batch-update --status not_mapped --set-status mapped

# Execute: batch-map libraries
porttracker library batch-map --ids 1-20 --set-package "Microsoft.Extensions.Logging" --set-namespace "Microsoft.Extensions.Logging" --execute
```

## File Changes

| File | Change |
|------|--------|
| `Commands/BatchFilters.cs` | New — shared filter options, WHERE builder, preview/execute logic |
| `Commands/FeatureCommands.cs` | Add `batch-update` and `batch-map` subcommands |
| `Commands/TestCommands.cs` | Add `batch-update` and `batch-map` subcommands |
| `Commands/ModuleCommands.cs` | Add `batch-update` and `batch-map` subcommands |
| `Commands/LibraryCommands.cs` | Add `batch-update` and `batch-map` subcommands |
| `Data/Database.cs` | Add `ExecuteInTransaction` helper for batch safety |

## Non-Goals

- No batch create or batch delete — not needed for the porting workflow
- No raw `--where` SQL escape hatch — structured filters cover all use cases
- No interactive y/n prompts — dry-run + `--execute` flag is sufficient and scriptable