feat(scripts): add operational utility scripts

- code-quality-report.sh: unified static analysis report
- cycle-customer-instance.sh: customer instance lifecycle management
- validate-secrets.sh: pre-deployment secrets validation
- README documenting available scripts

Author: cristim

scripts/README.md

@@ -0,0 +1,279 @@
+# AutoSpotting Migration Scripts
+
+This directory contains scripts for migrating and managing AutoSpotting data.
+
+## Company Memberships Backfill Script
+
+### Overview
+
+The `backfill_company_memberships.go` script migrates existing AutoSpotting deployments to the new multi-company SaaS model. It:
+
+1. Creates a default company for all existing users and accounts
+2. Creates company memberships for all existing users
+3. Sets the active company for each user
+4. Assigns all existing customer accounts to the default company
+5. Auto-approves accounts if the company is pre-approved
+
+### Prerequisites
+
+- Go 1.21 or later
+- AWS credentials configured (via environment variables, AWS CLI, or IAM role)
+- Proper IAM permissions to read/write DynamoDB tables
+
+### Required IAM Permissions
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "dynamodb:Scan",
+        "dynamodb:GetItem",
+        "dynamodb:PutItem",
+        "dynamodb:UpdateItem"
+      ],
+      "Resource": [
+        "arn:aws:dynamodb:*:*:table/autospotting-Users",
+        "arn:aws:dynamodb:*:*:table/autospotting-Companies",
+        "arn:aws:dynamodb:*:*:table/autospotting-CompanyMemberships",
+        "arn:aws:dynamodb:*:*:table/autospotting-CustomerAccounts"
+      ]
+    }
+  ]
+}
+```
+
+### Usage
+
+#### Environment Variables
+
+Set the following environment variables (or use command-line flags):
+
+```bash
+export USERS_TABLE="autospotting-Users"
+export COMPANIES_TABLE="autospotting-Companies"
+export COMPANY_MEMBERSHIPS_TABLE="autospotting-CompanyMemberships"
+export CUSTOMER_ACCOUNTS_TABLE="autospotting-CustomerAccounts"
+```
+
+#### Running the Script
+
+**Dry Run (recommended first):**
+
+```bash
+cd scripts
+go run backfill_company_memberships.go \
+  --dry-run \
+  --company-name "AutoSpotting Legacy" \
+  --owner-email "admin@example.com"
+```
+
+**Actual Execution:**
+
+```bash
+go run backfill_company_memberships.go \
+  --company-name "AutoSpotting Legacy" \
+  --owner-email "admin@example.com"
+```
+
+#### Command-Line Flags
+
+- `--users-table`: DynamoDB Users table name (default: from `USERS_TABLE` env var)
+- `--companies-table`: DynamoDB Companies table name (default: from `COMPANIES_TABLE` env var)
+- `--memberships-table`: DynamoDB Company Memberships table name (default: from `COMPANY_MEMBERSHIPS_TABLE` env var)
+- `--accounts-table`: DynamoDB Customer Accounts table name (default: from `CUSTOMER_ACCOUNTS_TABLE` env var)
+- `--dry-run`: Run without making changes (default: `false`)
+- `--company-name`: Name for the default company (default: `"AutoSpotting Legacy"`)
+- `--owner-email`: Email of the company owner (default: first admin user found)
+
+### Example
+
+```bash
+# Dry run with custom company name
+go run backfill_company_memberships.go \
+  --users-table "autospotting-Users" \
+  --companies-table "autospotting-Companies" \
+  --memberships-table "autospotting-CompanyMemberships" \
+  --accounts-table "autospotting-CustomerAccounts" \
+  --dry-run \
+  --company-name "ACME Corporation" \
+  --owner-email "cto@acme.com"
+
+# Actual execution
+go run backfill_company_memberships.go \
+  --users-table "autospotting-Users" \
+  --companies-table "autospotting-Companies" \
+  --memberships-table "autospotting-CompanyMemberships" \
+  --accounts-table "autospotting-CustomerAccounts" \
+  --company-name "ACME Corporation" \
+  --owner-email "cto@acme.com"
+```
+
+### What the Script Does
+
+1. **Scans Users Table**: Finds all existing users with PK and SK starting with `USER#`
+
+2. **Creates Default Company**:
+   - Generates an 8-character random company ID
+   - Sets the first admin user (or first user) as owner
+   - Marks company as pre-approved (auto-approves new accounts)
+   - Sets invoicing to disabled by default
+
+3. **Creates Memberships**:
+   - Creates a company membership record for each user
+   - Maps user roles:
+     - `admin` → `admin` role in company
+     - `operator` → `operator` role in company
+     - `viewer` → `viewer` role in company
+   - Uses DynamoDB patterns:
+     - PK: `USER#<userId>`
+     - SK: `COMPANY#<companyId>`
+     - GSI1PK: `COMPANY#<companyId>` (for reverse lookup)
+     - GSI1SK: `USER#<userId>`
+
+4. **Updates Users**:
+   - Sets `active_company_id` field for each user
+   - This ensures users see their accounts when they log in
+
+5. **Assigns Accounts**:
+   - Scans all customer accounts
+   - Updates each with `CompanyId` and `CompanyName`
+   - Auto-approves pending accounts if company is pre-approved
+
+### Output Example
+
+```
+Starting backfill process...
+Users table: autospotting-Users
+Companies table: autospotting-Companies
+Memberships table: autospotting-CompanyMemberships
+Accounts table: autospotting-CustomerAccounts
+Dry run: false
+
+Found 5 existing users
+Created default company: AutoSpotting Legacy (ID: x7y2z9k4)
+Created 5 company memberships
+Updated 5 users with active company
+Found 12 total accounts
+Assigned 12 accounts to default company
+
+Backfill completed successfully!
+Summary:
+  - Created company: AutoSpotting Legacy
+  - Created memberships: 5/5
+  - Updated users: 5/5
+  - Assigned accounts: 12
+```
+
+### Safety Features
+
+- **Dry Run Mode**: Test the migration without making changes
+- **Detailed Logging**: Shows all operations being performed
+- **Error Handling**: Continues processing even if individual operations fail
+- **Idempotent**: Can be run multiple times (will overwrite existing data)
+
+### Troubleshooting
+
+**Error: "Missing required table names"**
+- Ensure all table name environment variables or flags are set
+
+**Error: "scan failed: AccessDeniedException"**
+- Check IAM permissions for DynamoDB access
+
+**Warning: "Failed to create membership for user X"**
+- Check CloudWatch Logs for detailed error messages
+- Verify table schemas match expected structure
+
+**No users found**
+- Verify the Users table name is correct
+- Ensure users exist in the table with proper PK/SK format
+
+### Post-Migration Verification
+
+After running the backfill script, verify:
+
+1. **Company Created**:
+   ```bash
+   aws dynamodb get-item \
+     --table-name autospotting-Companies \
+     --key '{"CompanyId": {"S": "x7y2z9k4"}}'
+   ```
+
+2. **Memberships Created**:
+   ```bash
+   aws dynamodb query \
+     --table-name autospotting-CompanyMemberships \
+     --key-condition-expression "PK = :pk" \
+     --expression-attribute-values '{":pk": {"S": "USER#<userId>"}}'
+   ```
+
+3. **Accounts Assigned**:
+   ```bash
+   aws dynamodb scan \
+     --table-name autospotting-CustomerAccounts \
+     --filter-expression "attribute_exists(CompanyId)"
+   ```
+
+4. **Frontend Access**:
+   - Log in to the dashboard
+   - Verify company selector appears in header
+   - Verify accounts are visible in dropdown
+   - Check that all tabs load correctly
+
+### Rollback
+
+If you need to rollback the migration:
+
+1. **Remove Company**:
+   ```bash
+   aws dynamodb delete-item \
+     --table-name autospotting-Companies \
+     --key '{"CompanyId": {"S": "x7y2z9k4"}}'
+   ```
+
+2. **Remove Memberships**:
+   ```bash
+   # Query and delete all memberships for the company
+   aws dynamodb scan \
+     --table-name autospotting-CompanyMemberships \
+     --filter-expression "CompanyId = :cid" \
+     --expression-attribute-values '{":cid": {"S": "x7y2z9k4"}}'
+   ```
+
+3. **Remove Company Data from Users**:
+   ```bash
+   # Update each user to remove active_company_id
+   aws dynamodb update-item \
+     --table-name autospotting-Users \
+     --key '{"PK": {"S": "USER#<userId>"}, "SK": {"S": "USER#<userId>"}}' \
+     --update-expression "REMOVE active_company_id"
+   ```
+
+4. **Remove Company Data from Accounts**:
+   ```bash
+   # Update each account to remove CompanyId and CompanyName
+   aws dynamodb update-item \
+     --table-name autospotting-CustomerAccounts \
+     --key '{"AccountId": {"S": "<accountId>"}}' \
+     --update-expression "REMOVE CompanyId, CompanyName"
+   ```
+
+### Support
+
+For issues or questions:
+- Check CloudWatch Logs for detailed error messages
+- Review the [Implementation Plan](../IMPLEMENTATION_PLAN.md)
+- Open an issue on GitHub
+
+## Building for Production
+
+To build a standalone binary:
+
+```bash
+cd scripts
+GOOS=linux GOARCH=amd64 go build -o backfill-linux-amd64 backfill_company_memberships.go
+```
+
+This creates a portable executable that can be run on any Linux system without Go installed.