`swamp vault put` fails when value contains special characters from GCP access tokens

[bixu]

Description

`swamp vault put` fails with `TooManyArgumentsError` when the secret value contains characters that the CLI argument parser interprets as separate arguments. GCP access tokens (from `gcloud auth print-access-token`) consistently trigger this.

Steps to Reproduce

```bash
TOKEN=$(gcloud auth print-access-token)
swamp vault put gcp-oauth GCP_ACCESS_TOKEN "$TOKEN"
```

Error:
```
TooManyArgumentsError: Too many arguments: ya29.a0Aa7MYio7IUnvZ...
```

Also fails with:

• `swamp vault put gcp-oauth GCP_ACCESS_TOKEN "'$TOKEN'"`
• `gcloud auth print-access-token | swamp vault put gcp-oauth GCP_ACCESS_TOKEN --stdin` (no `--stdin` flag exists)

Workaround

Store directly in 1Password, bypassing swamp:
```bash
op item edit GCP_ACCESS_TOKEN --vault swamp "password=$(gcloud auth print-access-token)"
```

Proposed Solution

Either:

1. Accept the value as a single positional argument regardless of content (stop parsing after the third positional arg)
2. Add `--stdin` or `--value-file` support for piping secret values
3. Both

Environment

• swamp: `20260325.232536.0-sha.eb02760e`
• Shell: zsh
• OS: macOS Darwin 25.4.0

[github-actions]

Hi @bixu, thanks for opening this issue!

We appreciate you taking the time to report it. A maintainer will review it as soon as possible.

In the meantime, please make sure you've included all relevant details (steps to reproduce, expected vs actual behaviour, swamp version, etc.) to help us triage it quickly.

[stack72]

🔍 Triage started — fetching issue context

[stack72]

📋 Classified as bug (high) — The vault put command defines exactly 2 positional arguments (vault_name, key_value). Users naturally pass 3 args (vault, key, value) which Cliffy rejects with TooManyArgumentsError. The KEY=VALUE format is unintuitive for secrets, and shell expansion of special characters in GCP tokens compounds the problem. Stdin support exists but is undiscoverable.

[stack72]

📝 Implementation plan generated (v1) — Change vault put from 2 positional args (vault_name, key_value) to 3 positional args (vault_name, key, [value]). This lets users naturally write 'swamp vault put myVault KEY secret' without needing KEY=VALUE format. Maintain backward compat with KEY=VALUE. Add --value-stdin flag for explicit stdin piping.

[stack72]

🔍 Adversarial review (plan v1)

• ADV-1 [medium/scope]: Step 3 (--value-stdin flag) is unnecessary. Stdin auto-detection already works via !isStdinTty() check. The issue reporter tried --stdin which doesn't exist, but piping works fine (echo val | swamp vault put vault KEY). Adding a flag for something that already auto-detects adds API surface with no benefit. Remove this step — just improve help text and error messages to mention piping.
• ADV-2 [medium/correctness]: Plan doesn't define behavior when second arg contains '=' AND third arg is provided (e.g., 'swamp vault put vault KEY=old newvalue'). Should error to avoid ambiguity, or ignore the '=' parse and treat arg2 as key, arg3 as value.
• ADV-3 [low/scope]: Step 5 (renderer update) is unnecessary — the vault_put renderer only handles event output (storing/completed/error), not help text or argument formats. No changes needed there.

✅ No blocking findings — ready for approval

[stack72]

✅ Findings resolved (3)

• ADV-1: Dropped step 3 (--value-stdin flag). Will improve error messages to mention piping instead.
• ADV-2: When 3 args given, always treat arg2 as key and arg3 as value (ignore = parsing). This is less surprising.
• ADV-3: Dropped step 5 (renderer update). No changes needed there.

✅ All blocking findings resolved — ready for approval

[stack72]

Approved Implementation Plan (v1)

Summary: Change vault put from 2 positional args (vault_name, key_value) to 3 positional args (vault_name, key, [value]). This lets users naturally write 'swamp vault put myVault KEY secret' without needing KEY=VALUE format. Maintain backward compat with KEY=VALUE. Add --value-stdin flag for explicit stdin piping.

DDD Analysis

Changes are confined to the CLI presentation layer (vault_put.ts command). No domain or libswamp changes needed — the underlying vaultPut operation already accepts separate key and value parameters. The parseKeyValue/resolveKeyValue functions in the command module handle the translation from CLI args to domain inputs.

Implementation Steps

1. Change CLI argument signature from 2 to 3 positional args: <vault_name> [value] (risk: Breaking change for KEY=VALUE format — must maintain backward compatibility)
2. Update resolveKeyValue and action handler to support 3-arg form while keeping KEY=VALUE and stdin/interactive fallback (risk: Argument resolution priority must be clear: explicit value arg > KEY=VALUE > stdin > interactive prompt)
3. Add --value-stdin flag as explicit opt-in for stdin reading (in addition to auto-detection) (risk: Must not conflict with existing auto-detected stdin behavior)
4. Update unit tests for new 3-arg form, --value-stdin flag, and backward compatibility with KEY=VALUE (risk: None)
5. Update vault put renderer/output if help text or error messages reference old argument format (risk: Minimal — presentation layer changes only)

Files

• src/cli/commands/vault_put.ts
• src/cli/commands/vault_put_test.ts
• src/presentation/renderers/vault_put.ts

Testing Strategy

Update vault_put_test.ts with tests for: 3-arg form (vault, key, value), backward compat with KEY=VALUE 2-arg form, --value-stdin flag, values containing special characters and spaces in 3-arg form, priority resolution (explicit value > KEY=VALUE > stdin > interactive).

Potential Challenges

• Backward compatibility: existing KEY=VALUE users must not break
• Argument ambiguity: when 2 args given, need to detect KEY=VALUE vs key-only correctly (already handled by parseKeyValue)
• Shell quoting: values with spaces/special chars in 3-arg form still need shell quoting, but this is standard shell behavior users understand

Approved via swamp @si/issue-lifecycle