putpaws 0.0.9 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3af9788e3c54a5647c912f45ee76b78691c7f1ac7f7654e6af7b7f3ce51b16f4
-  data.tar.gz: 51d6ea019d08c1139e3a865743d4435a304125a3a3b7ee2052332fc83aa170a3
+  metadata.gz: cbb1de2cdc7c119427ca5dfa073f5e8d07f504ff73f93a464f2912a8ef5168ed
+  data.tar.gz: 042f6202ae3cb0396b0ab7210b2d299504f7e099e8a0cf43d9c6314f0b6384ba
 SHA512:
-  metadata.gz: 26c390300f9e4cb4fc2a970bbfbbc762e2de2bcfcd3fdb50ed8128e065caacecc99572e6f447ef244cb4c51a1cb4f844c0cc2a14aac361b678dc1e0b7ed20d54
-  data.tar.gz: 3370e8ffe872b93910f951f12c29447b28ca411062d31eb3281740b786297505cc6c12408f11f780d10eefdc57bc4d58b3b0a381079eef6ea56d6b312021f4f8
+  metadata.gz: 12b7e736fe78e9a49569627fd296e9f5540cbea849f8b78a7edbb56c8652de73b82d1b2ac92fef279a682f64e4e83e061ba20e2c3afe1b3c99dce7fd35526fe1
+  data.tar.gz: efad6347afdc46833694e48070afd0330fe42f8bb0bc16638b6b88a7d5b6d1a091ce50f5ce1ddec4f92cc07e54796f42cc9802c2b5aa07ed4af1d96ba5ebd171

data/README.md

@@ -1,7 +1,116 @@
-# Put your paws up!!
+# Put your pAWS up!!
+
+## Command names
+
+The short commands follow a "put your paws ..." image:
+
+- `putpaws ready` ... put paws ready: — place your paws and prepare
+- `putpaws steady` ... put paws steady: — hold steady, right before the start
+- `putpaws up` ... put paws up: — everything is ready, raise them up
+- `putpaws ahead` ... put paws ahead: — reach ahead and probe (dry-run)
+- `putpaws away` ... put paws away: — take your paws off and let AI take over
+
+## Provisioning
+
+Build service infra (security group / ECS cluster / task definitions / service / log groups / CodeBuild) idempotently.
+Deletion is out of scope on purpose: putpaws only creates and updates.
+
+```
+# Interview basic infra (existing VPC / ECR / SES / S3 / SSM parameter prefix)
+# and generate provision.json + IAM role drafts
+bundle exec putpaws ready
+
+# After reviewing/editing the drafts under policies/, create the IAM roles
+# from them as-is and fill their ARNs into provision.json. Idempotent:
+# edit a draft and run again to update the role.
+bundle exec putpaws steady
+
+# Dry-run: show what would be created / updated / skipped
+bundle exec putpaws ahead
+
+# Build the rest as far as possible. `up` stops with instructions where a manual
+# step is required. Fix things by hand, then just run `up` again. Safe to re-run any time.
+bundle exec putpaws up
+```
+
+Running `steady` is your explicit confirmation of the drafts: `up` never touches IAM
+and stops until the role ARNs are filled. Filling in an existing role ARN in
+provision.json instead makes `steady` leave that role alone
+(useful when IAM is managed by another team).
+
+Files live under `.putpaws/provisioning/`:
+
+- `provisioning/{service_name}/provision.json` ... inputs (edit by hand; `steady` fills the role ARNs)
+- `provisioning/{service_name}/state.json` ... created resource info (written by putpaws)
+- `provisioning/{service_name}/policies/` ... IAM role drafts to review, applied as-is by `putpaws steady`
+- `provisioning/presets/{preset}/` ... defaults and task definition templates (copied here on `ready`, edit freely)
+
+Presets are searched in this order: project local (`.putpaws/provisioning/presets/`),
+user global (directories in `PUTPAWS_PRESETS_PATH`, then `~/.putpaws/presets/`), and the ones bundled in the gem.
+Whichever you pick on `ready` is copied into the project so the project owns its snapshot.
+
+Security groups are either specified (one or more existing ones; putpaws never touches their rules)
+or a new one is created for the service when left empty on `ready`.
+
+When the service step completes, the new service is reflected into
+`.putpaws/application.json` and `.putpaws/infra.json` (diff is shown and confirmed),
+so `ecs:attach`, `ecs:shell`, `ecs:run` and `log:*` work immediately.
+Secrets are handled by reference only: task definitions point to existing
+SSM parameters (Ex: `/{service_name}/RAILS_MASTER_KEY`) and putpaws never touches the values.
+
+A scheduler role is always created too, and the `target` entry of infra.json carries it,
+so `scheduler:deploy` works any time by just writing `.putpaws/schedule.json`.
+
+CodeBuild is created as CI: builds run inside the VPC with the same subnets and
+security group as the service, so `db:migrate` against RDS works from the build.
+Note that the private subnets need a NAT gateway (or VPC endpoints) so that
+builds can reach GitHub / ECR / CloudWatch Logs.
+
+## Operator permissions
+
+Declare named operator profiles in `.putpaws/operators.json` (generated with examples on first run),
+then resolve them into managed policies per service, idempotently
+(CREATE / UPDATE as a new policy version / SKIP — re-running never piles up policies):
+
+```
+bundle exec putpaws awesome-api-staging iam:grant profile=developer
+```
+
+```
+{
+  "developer": { "groups": ["attach", "shell", "deploy", "logs", "codebuild"] },
+  "viewer": { "groups": ["logs"] }
+}
+```
+
+Groups map to putpaws command namespaces: `attach` (ecs:attach/forward), `shell` (ecs:shell/run —
+note this implies reading all secrets of the service), `deploy` (ecs:deploy), `logs` (log:*),
+`codebuild` (code_build:build), `scheduler` (scheduler:deploy).
+`extra_statements` on a profile appends raw IAM statements.
+The policy is named `{service}-operator-{profile}`. Attaching it to users/groups is left to your admin
+(an attach command example is printed).
+
+## AI setup
+
+`putpaws away` installs a guide for AI agents (Claude Code etc.) into the project:
+`.claude/skills/putpaws/SKILL.md` (commands, read-only vs mutating classification,
+non-interactive recipes, suggested permission allowlist) and a pointer block in
+`CLAUDE.md` (or `AGENTS.md` when there is no CLAUDE.md). Re-run it after updating putpaws.
+
+```
+bundle exec putpaws away
+```
 
 ## Example
 
+### Info
+
+Show resolved settings for a service without touching AWS
+
+```
+bundle exec putpaws awesome-api-staging info
+```
+
 ### ECS
 
 Attach to staging specific container
@@ -21,6 +130,46 @@ bundle exec putpaws awesome-api-staging ecs:forward container=app remote=example
 mysql -u awesome_user -p --port 1050 -h 127.0.0.1
 ```
 
+Redeploy the service (update-service with force new deployment).
+With a mutable image tag like `latest`, this rolls out the newly pushed image.
+
+```
+bundle exec putpaws awesome-api-staging ecs:deploy
+
+# Optionally change desired count / task definition, and wait until stable
+bundle exec putpaws awesome-api-staging ecs:deploy desired=2 taskdef=awesome-api-staging-web wait=true
+```
+
+Run a command on a temporary task. The task terminates itself when the command finishes.
+
+```
+bundle exec putpaws awesome-api-staging ecs:run cmd='bundle exec rake db:migrate'
+
+# Pass wait=true to wait until the task stops and check the exit code
+bundle exec putpaws awesome-api-staging ecs:run cmd='bundle exec rake db:migrate' wait=true
+```
+
+Launch a temporary task for operation and attach to it (like SSH-ing into the environment).
+The task is launched with its command overridden by `sleep <ttl>`, so it always terminates itself when ttl passes even if your shell is gone.
+
+```
+# ttl is 30 minutes by default
+bundle exec putpaws awesome-api-staging ecs:shell
+
+# Specify ttl: "45" and "45m" mean 45 minutes, "90s" and "2h" also work
+bundle exec putpaws awesome-api-staging ecs:shell ttl=45m
+
+# The task is stopped immediately when you exit the shell.
+# Pass keep=true to keep it running until ttl passes.
+bundle exec putpaws awesome-api-staging ecs:shell keep=true
+```
+
+Temporary tasks are launched with `group` / `started_by` set to `putpaws-run` or `putpaws-shell`,
+so you can identify them on the AWS console and on the task list of `ecs:attach` / `ecs:forward`.
+
+`ecs:run` and `ecs:shell` require `network` and `target` in `.putpaws/application.json`,
+which refer to the `network` / `target` sections of `.putpaws/infra.json` (the same ones used by scheduler).
+
 ### CloudWatch Logs
 
 `tail -f`
@@ -65,7 +214,9 @@ gem 'putpaws'
     "log_group_prefix": "/ecs/awesome/awesome-api-staging",
     "log_region": null,
     "build_log_group_prefix": "/aws/codebuild/awesome-api-staging",
-    "build_project_name_prefix": "awesome-api-staging"
+    "build_project_name_prefix": "awesome-api-staging",
+    "network": "awesome-private-staging",
+    "target": "awesome-staging"
   },
   "awesome-api-production": {
     "region": "ap-northeast-1",

data/lib/Putpawsfile

@@ -6,3 +6,7 @@ require "putpaws/ecs/ecs_task"
 require "putpaws/cloud_watch/log_task"
 require "putpaws/scheduler/scheduler_task"
 require "putpaws/code_build/build_task"
+require "putpaws/provision/provision_task"
+require "putpaws/iam/iam_task"
+require "putpaws/info"
+require "putpaws/ai/ai_task"

data/lib/putpaws/ai/ai_task.rb

@@ -0,0 +1 @@
+load File.expand_path("../tasks/ai_task.rake", __FILE__)

data/lib/putpaws/ai/guide.rb

@@ -0,0 +1,119 @@
+require 'fileutils'
+require 'putpaws/version'
+
+module Putpaws
+  module Ai
+    # `putpaws away`: put paws away — take your paws off and let AI take over.
+    # Installs a guide for AI agents (Claude Code etc.) into the host project:
+    # a skill file plus a pointer block in CLAUDE.md / AGENTS.md.
+    # Re-runnable: everything is regenerated in place.
+    class Guide
+      SKILL_PATH = File.join('.claude', 'skills', 'putpaws', 'SKILL.md')
+      BEGIN_MARK = '<!-- putpaws:begin -->'
+      END_MARK = '<!-- putpaws:end -->'
+
+      def self.install!(root: '.', services: nil)
+        services ||= Putpaws::ApplicationConfig.all.map(&:name)
+        skill_path = File.join(root, SKILL_PATH)
+        FileUtils.mkdir_p(File.dirname(skill_path))
+        File.write(skill_path, skill_content(services: services))
+        pointer_path = pointer_target(root)
+        update_pointer!(pointer_path)
+        [skill_path, pointer_path]
+      end
+
+      # Prefer an existing CLAUDE.md; otherwise use AGENTS.md (created if absent).
+      def self.pointer_target(root)
+        claude = File.join(root, 'CLAUDE.md')
+        return claude if File.exist?(claude)
+        File.join(root, 'AGENTS.md')
+      end
+
+      def self.update_pointer!(path)
+        block = pointer_block
+        content = File.exist?(path) ? File.read(path) : ''
+        if content.include?(BEGIN_MARK)
+          content = content.sub(/#{Regexp.escape(BEGIN_MARK)}.*#{Regexp.escape(END_MARK)}/m, block.strip)
+        else
+          content = content.empty? ? block : content.rstrip + "\n\n" + block
+        end
+        File.write(path, content)
+      end
+
+      def self.pointer_block
+        <<~MD
+          #{BEGIN_MARK}
+          ## putpaws (AWS operations)
+
+          This project uses the putpaws gem for AWS/ECS operations (logs, deploy, migrations, one-off tasks).
+          Read `.claude/skills/putpaws/SKILL.md` for commands and safety notes before running AWS operations.
+          Quick reference: services are the top-level keys of `.putpaws/application.json`;
+          `bundle exec putpaws <service> info` shows resolved settings without touching AWS.
+          #{END_MARK}
+        MD
+      end
+
+      def self.skill_content(services: [])
+        services_line = services.empty? ? '(none configured yet — check .putpaws/application.json)' : services.join(', ')
+        <<~MD
+          ---
+          name: putpaws
+          description: AWS operations for this project (CloudWatch logs, ECS deploy, db:migrate and one-off tasks on Fargate, CodeBuild CI) via the putpaws CLI. Use when asked to investigate logs, deploy, run rake tasks on AWS, or inspect ECS services.
+          ---
+
+          # putpaws
+
+          Capistrano-style AWS operation commands. General form:
+
+              bundle exec putpaws <service> <command> key=value
+
+          Services in this project: #{services_line}
+          (services are the top-level keys of `.putpaws/application.json`)
+
+          Discover commands with `bundle exec putpaws -T` (or `-D` for full descriptions).
+
+          ## Read-only commands (safe to run without asking)
+
+          - `bundle exec putpaws <service> info` — resolved settings, no AWS access
+          - `bundle exec putpaws <service> log:tail since=2h` — CloudWatch logs (units: s/m/h/d/w, add `for=1h` to bound the range)
+          - `bundle exec putpaws <service> log:tailf` — follow logs (long-running; prefer `log:tail` in automation)
+          - `bundle exec putpaws ahead` — dry-run of provisioning (CREATE/UPDATE/SKIP)
+
+          ## Mutating commands (confirm with the user before running)
+
+          - `bundle exec putpaws <service> ecs:run cmd='bundle exec rake db:migrate' wait=true`
+            — runs a one-off command on a temporary Fargate task and exits non-zero on failure.
+            The best choice for migrations and rake tasks. Fully non-interactive.
+          - `bundle exec putpaws <service> ecs:deploy wait=true` — redeploy the service (force new deployment)
+          - `bundle exec putpaws <service> code_build:build branch=main` — start the CI build (build + push + deploy per buildspec)
+          - `bundle exec putpaws <service> scheduler:deploy` — deploy schedules from `.putpaws/schedule.json`
+
+          ## Interactive commands (avoid in non-TTY sessions; meant for humans)
+
+          - `ecs:attach`, `ecs:shell`, `ecs:forward` — open live sessions into containers
+          - `ready`, `steady`, `up`, `iam:grant` — provisioning flows with confirmation prompts
+
+          ## Config files (source of truth, safe to read)
+
+          - `.putpaws/application.json` — services and their cluster/log/build settings
+          - `.putpaws/infra.json` — network (subnets/security groups) and target (cluster/taskdef) definitions
+          - `.putpaws/schedule.json` — named schedules, `.putpaws/operators.json` — operator permission profiles
+          - `.putpaws/provisioning/<service>/` — provisioning inputs (provision.json), state, IAM role drafts
+
+          ## Suggested permission allowlist (.claude/settings.json)
+
+              "permissions": {
+                "allow": [
+                  "Bash(bundle exec putpaws -T*)",
+                  "Bash(bundle exec putpaws * info)",
+                  "Bash(bundle exec putpaws * log:*)"
+                ]
+              }
+
+          ---
+          Generated by putpaws #{Putpaws::VERSION}. Refresh with `bundle exec putpaws away` after updating the gem.
+        MD
+      end
+    end
+  end
+end

data/lib/putpaws/ai/tasks/ai_task.rake

@@ -0,0 +1,14 @@
+require "putpaws/ai/guide"
+
+namespace :ai do
+  desc "Install the AI agent guide (.claude/skills/putpaws/SKILL.md + a pointer in CLAUDE.md/AGENTS.md). Re-runnable. (alias: away)"
+  task :install do
+    files = Putpaws::Ai::Guide.install!
+    puts "Generated:"
+    files.each{|f| puts "  #{f}"}
+    puts "Re-run `bundle exec putpaws away` after updating putpaws to refresh the guide."
+  end
+end
+
+desc "Alias of ai:install"
+task away: 'ai:install'

data/lib/putpaws/application_config.rb

@@ -1,13 +1,16 @@
 require 'json'
 require 'pathname'
 require "putpaws/schedule_config"
+require "putpaws/infra_network_config"
+require "putpaws/infra_target_config"
 
 class Putpaws::ApplicationConfig < Struct.new(
-  :name, :region, 
+  :name, :region,
   :cluster, :service, :task_name_prefix, :ecs_region,
   :log_group_prefix, :log_region,
   :build_project_name_prefix, :build_log_group_prefix, :build_region,
   :schedules,
+  :network, :target,
   keyword_init: true)
   def self.load(path_prefix: '.putpaws')
     @application_data ||= begin
@@ -37,7 +40,7 @@ class Putpaws::ApplicationConfig < Struct.new(
     {
       region: ecs_region || region,
       cluster: cluster,
-      # service: service,
+      service: service,
       task_name_prefix: task_name_prefix,
     }
   end
@@ -60,6 +63,16 @@ class Putpaws::ApplicationConfig < Struct.new(
     @schedules ||= (self[:schedules] || []).map{|x| Putpaws::ScheduleConfig.find(x)}.compact
   end
 
+  def network
+    return nil unless self[:network]
+    @network ||= Putpaws::InfraNetworkConfig.find(self[:network])
+  end
+
+  def target
+    return nil unless self[:target]
+    @target ||= Putpaws::InfraTargetConfig.find(self[:target])
+  end
+
   def codebuild_command_params
     {
       region: build_region || region,

data/lib/putpaws/ecs/run_command.rb

@@ -0,0 +1,115 @@
+require 'aws-sdk-ecs'
+
+module Putpaws::Ecs
+  class RunCommand
+    DEFAULT_TTL = '30m'
+    SECONDS = {
+      's' => 1,
+      'm' => 60,
+      'h' => 60 * 60,
+    }
+
+    def self.config(config)
+      unless config.network && config.target
+        raise "Please set `network` and `target` at .putpaws/application.json\n" +
+          "They refer to `network` and `target` sections at .putpaws/infra.json\n" +
+          "(Ex) \"network\": \"awesome-private-staging\", \"target\": \"awesome-staging\""
+      end
+      new(
+        region: config.ecs_region || config.region,
+        network: config.network,
+        target: config.target,
+      )
+    end
+
+    # "45" and "45m" mean 45 minutes. "90s" and "2h" are also acceptable.
+    def self.parse_ttl(ut)
+      ut = DEFAULT_TTL if ut.nil? || ut.strip.empty?
+      matched, number, unit = ut.strip.match(/\A(\d+)([smh])?\z/).to_a
+      raise "Invalid ttl: #{ut} (Ex) ttl=30m ttl=2h ttl=90s" unless matched
+      number.to_i * SECONDS[unit || 'm']
+    end
+
+    attr_reader :ecs_client
+    attr_reader :region, :network, :target
+    def initialize(region:, network:, target:)
+      @ecs_client = Aws::ECS::Client.new({region: region})
+      @region = region
+      @network = network
+      @target = target
+    end
+
+    def cluster_name
+      target.cluster.split('/').last
+    end
+
+    def container_name
+      target.container_name || 'app'
+    end
+
+    # Launch a temporary task whose main process is overridden with the given
+    # command, so that the task terminates itself when the command finishes.
+    # started_by and group are set so that temporary tasks are identifiable.
+    def run_ecs_task(command:, started_by:, group:, container: nil)
+      res = ecs_client.run_task({
+        cluster: target.cluster,
+        task_definition: target.task_definition,
+        count: 1,
+        launch_type: 'FARGATE',
+        enable_execute_command: true,
+        started_by: started_by,
+        group: group,
+        network_configuration: {
+          awsvpc_configuration: {
+            subnets: network.subnets,
+            security_groups: network.security_groups,
+            assign_public_ip: network.assign_public_ip,
+          }
+        },
+        overrides: {
+          container_overrides: [
+            {
+              name: container || container_name,
+              command: ['/bin/sh', '-c', command],
+            }
+          ]
+        },
+      })
+      failure = res.failures.first
+      raise "Failed to run task: #{failure.reason} #{failure.detail}" if failure
+      res.tasks.first
+    end
+
+    def wait_until_attachable(task_arn, timeout: 600, interval: 5)
+      deadline = Time.now + timeout
+      loop do
+        res = ecs_client.describe_tasks(cluster: target.cluster, tasks: [task_arn])
+        task = res.tasks.first
+        if task.nil? || task.last_status == 'STOPPED'
+          raise "Task was stopped: #{task && task.stopped_reason}"
+        end
+        ctn = task.containers.detect{|c| c.name == container_name}
+        agent = ctn && (ctn.managed_agents || []).detect{|a| a.name == 'ExecuteCommandAgent'}
+        return task if task.last_status == 'RUNNING' && agent && agent.last_status == 'RUNNING'
+        raise "Timed out waiting for task to be attachable: #{task_arn}" if Time.now > deadline
+        sleep interval
+      end
+    end
+
+    def wait_until_stopped(task_arn, timeout: 3600, interval: 10)
+      deadline = Time.now + timeout
+      loop do
+        res = ecs_client.describe_tasks(cluster: target.cluster, tasks: [task_arn])
+        task = res.tasks.first
+        raise "Task not found: #{task_arn}" unless task
+        return task if task.last_status == 'STOPPED'
+        raise "Timed out waiting for task to stop: #{task_arn}" if Time.now > deadline
+        sleep interval
+      end
+    end
+
+    def stop_ecs_task(task_arn, reason: 'Stopped by putpaws')
+      ecs_client.stop_task(cluster: target.cluster, task: task_arn, reason: reason)
+    end
+  end
+end

data/lib/putpaws/ecs/task_command.rb

@@ -1,3 +1,4 @@
+require 'socket'
 require 'aws-sdk-ecs'
 require 'aws-sdk-ssm'
 
@@ -8,18 +9,20 @@ module Putpaws::Ecs
     end
 
     attr_reader :ecs_client
-    attr_reader :region, :cluster, :task_name_prefix
+    attr_reader :region, :cluster, :service, :task_name_prefix
     attr_accessor :ecs_task
-    def initialize(region:, cluster:, task_name_prefix: nil)
+    def initialize(region:, cluster:, service: nil, task_name_prefix: nil)
       @ecs_client = Aws::ECS::Client.new({region: region})
       @region = region
       @cluster = cluster
+      @service = service
       @task_name_prefix = task_name_prefix
       @ecs_task = nil
     end
 
     def list_ecs_tasks
       res = ecs_client.list_tasks(cluster: cluster)
+      return [] if res.task_arns.empty?
       res = ecs_client.describe_tasks(tasks: res.task_arns, cluster: cluster)
       return res.tasks unless task_name_prefix
       res.tasks.select{|t| 
@@ -28,6 +31,36 @@ module Putpaws::Ecs
       }
     end
 
+    def list_ecs_services
+      res = ecs_client.list_services(cluster: cluster, max_results: 100)
+      return [] if res.service_arns.empty?
+      res = ecs_client.describe_services(cluster: cluster, services: res.service_arns)
+      services = res.services.select{|s| s.status == 'ACTIVE'}
+      return services unless task_name_prefix
+      filtered = services.select{|s| s.service_name.start_with?(task_name_prefix)}
+      filtered.empty? ? services : filtered
+    end
+
+    def update_ecs_service(service:, desired_count: nil, task_definition: nil)
+      params = {
+        cluster: cluster,
+        service: service,
+        force_new_deployment: true,
+      }
+      params[:desired_count] = desired_count.to_i if desired_count
+      params[:task_definition] = task_definition if task_definition
+      res = ecs_client.update_service(**params)
+      res.service
+    end
+
+    def wait_ecs_service_stable(service:, timeout: 600)
+      ecs_client.wait_until(
+        :services_stable,
+        {cluster: cluster, services: [service]},
+        {delay: 15, max_attempts: (timeout / 15.0).ceil}
+      )
+    end
+
     def get_session_target(container: 'app')
       raise "ECS Task Not Set" unless ecs_task
       ctn = ecs_task.containers.detect{|c| c.name == container}
@@ -36,11 +69,31 @@ module Putpaws::Ecs
       "ecs:#{cluster}_#{task_id}_#{ctn.runtime_id}"
     end
 
+    def local_port_available?(port)
+      TCPServer.new('127.0.0.1', port.to_i).close
+      true
+    rescue Errno::EADDRINUSE, Errno::EACCES
+      false
+    end
+
+    def resolve_local_port(local_port)
+      if local_port
+        unless local_port_available?(local_port)
+          raise "Local port #{local_port} is already in use"
+        end
+        local_port.to_s
+      else
+        port = (1050..1079).to_a.shuffle.detect{|p| local_port_available?(p)}
+        raise "No available local port between 1050 and 1079. Please specify one like: local=:8080" unless port
+        port.to_s
+      end
+    end
+
     def get_port_forwarding_command(container: nil, remote_port:, remote_host:, local_port: nil)
       container ||= 'app'
       target = get_session_target(container: container)
       ssm_client = Aws::SSM::Client.new({region: region})
-      local_port ||= (1050..1079).map(&:to_s).shuffle.first
+      local_port = resolve_local_port(local_port)
       puts "Starting to use local port: #{local_port}"
       res = ssm_client.start_session({
         target: target,
@@ -67,10 +120,12 @@ module Putpaws::Ecs
       build_session_manager_plugin_command(session: res.session, target: target)
     end
 
+    # Returns an argument array so that callers can spawn session-manager-plugin
+    # without a shell like `system(*cmd)`.
+    # https://github.com/aws/aws-cli/blob/2a6136010d8656a605d41d1e7b5fdab3c2930cad/awscli/customizations/ecs/executecommand.py#L105
     def build_session_manager_plugin_command(session:, target:)
       ssm_region = ENV['AWS_REGION_SSM'] || @region
 
-      # https://github.com/aws/aws-cli/blob/2a6136010d8656a605d41d1e7b5fdab3c2930cad/awscli/customizations/ecs/executecommand.py#L105
       session_json = if session.respond_to?(:session_id)
         {
           "SessionId" => session.session_id,
@@ -85,16 +140,15 @@ module Putpaws::Ecs
       target_json = {
         "Target" => target
       }.to_json
-      cmd = [
+      [
         "session-manager-plugin",
-        session_json.dump,
+        session_json,
         @region,
         "StartSession",
-        'test',
-        target_json.dump,
+        ENV['AWS_PROFILE'].to_s,
+        target_json,
         "https://ssm.#{ssm_region}.amazonaws.com"
       ]
-      cmd.join(' ')
     end
   end
 end