feature: add `--plan-id` flag to deploy to a specific plan by ID

[codxbrexx]

Background

The CLI currently selects a plan in two ways:

1. --plan Essential — you pass the tier name and plan.ts checks it against the keys returned by api.listSubscriptions() (Record<planName, slotCount>).
2. Interactively — if you have multiple tiers available, the CLI prompts you to pick one.

This works fine when a user has one subscription per tier. But a user with multiple subscriptions of the same tier (e.g. two "Essential" plans) has no way to target a specific one. The backend already tracks subscription instances: api.listSubscriptionsDeploys() returns SubscriptionDeploy[] where each entry has:

interface SubscriptionDeploy {
    id: string;  
    plan: Plans;  
    date: number;
    deploy: string; 
}
//   id === the SHA-like instance ID e.g. "a3f9c2d1..."
//   plan === tier: "Essential" | "Standard" | "Premium"
//    deploy === deployment suffix using this subscription

The id field is the subscription instance ID — that's what --plan-id should target.

What's needed

A --planId flag so a CI pipeline or power user can pin a deploy to an exact subscription instance:

metacall-deploy --planId a3f9c2d1... --workdir ./my-project

What has to change

CLI side (src/):

1. Add planId?: string to CLIArgs in src/cli/args.ts.

   • Note: the TODO listed -d as the alias but -d is already taken by --dev. A new alias (e.g. --planId with no short alias, or -S for subscription) needs to be agreed on.

2. In src/plan.ts, after fetching availPlans, check for args['planId'] and validate it exists in listSubscriptionsDeploys() before using it.

3. In src/deploy.ts, api.deploy() today receives a Plans tier string:

   api.deploy(name, env, plan: Plans, resourceType, release, version)

   It would need a new optional planId parameter threaded through to the POST /api/deploy/create body.

4. src/force.ts already reads repoSubscriptionDetails[0].plan to recover the tier on re-deploy. With this change it should also propagate repoSubscriptionDetails[0].id when available.

Backend side (/api/deploy/create):

The deploy endpoint currently accepts plan (tier name). It needs to optionally accept planId (subscription instance ID) and use it to pick the right subscription slot when provided.

This is the blocking part — the CLI work can be prepared, but the feature isn't useful until the backend supports it.

Why it matters

• Users with multiple active subscriptions of the same tier can't automate targeted deploys today.
• CI pipelines can't hard-pin a specific subscription instance across runs.

Alias conflict to resolve

The original TODO says (-d, --plan-id) but -d is already owned by --dev. This needs to be decided before implementation starts.

Next Steps

• Maintainer review needed on alias decision (--planId vs -S vs alternative)
• Backend support for planId parameter in /api/deploy/create
• CLI implementation (args parsing, validation, threading through deploy)
• Update src/force.ts to propagate subscription instance ID on re-deploy

Willing to Implement

I'm ready to contribute! I can handle:

• CLI-side changes (src/cli/args.ts, src/plan.ts, src/deploy.ts, src/force.ts)
• Backend endpoint updates
• Tests and documentation

Blocking: Awaiting maintainer feedback on the alias conflict before starting.