feat(project): scaffold add runtime handler

[Hweinstock]

Project

runtimes cannot be added to a project post creation.

Solution

We mostly follow the pattern establish by harness, but with a few exceptions:

• mirroring API shapes doesn't work as well here since API shapes don't support local BYO, but we do. Also, API supports s3 code artifacts, but we don't. Therefore we mirror where possible, but diverge when describing code configuration.
• we extend the templates idea to runtime as well. This simplifies the command significantly. Rather than multiple flags for memory, language, protocol, etc. We can have a single one for template, that renders a preloaded template. This allows users to get started faster, without giving up on advanced configuration. This also leaves us flexible for folks to share runtime definitions across projects through custom templates (future feature). In the future we can add our templates here like strands-py-bedrock or strands-ts-gemini-no-memory. The help page would list all of these out so customers know their options.

Testing

Setup a table based test for verifying flag validation and parsing. Will follow up on these tests once functionality is implemented in a follow-up.

> agentcore project add runtime --name t --template hello-world-python
Error: runtime case not yet implemented in FsProjectManager.addResource

> agentcore project add runtime --help
Usage: agentcore project add runtime [options]
adds a runtime to the current project either from a template or from existing local code

Options:
  --name <name>                                                  the name of the runtime
  --description <description>                                    an optional description of the runtime
  --template <template>                                          template to scaffold from
  --role-arn <role-arn>                                          IAM role ARN that provides permissions for the runtime
  --code-location <code-location>                                path to existing agent source code (BYO path)
  --build <build>                                                build type: CodeZip or Container
  --entrypoint <entrypoint>                                      entrypoint file, e.g. main.py:handler (BYO only)
  --protocol <protocol>                                          server protocol ex. HTTP, MCP, A2A, AGUI
  --api-key <api-key>                                            API key source for non-bedrock model providers: '-' for stdin, 'file://path' for file
  --model-provider <model-provider>                              model provider (template only)
  --runtime-version <runtime-version>                            language runtime, e.g. PYTHON_3_13, NODE_22 (BYO CodeZip only)
  --dockerfile <dockerfile>                                      dockerfile path for the container build (BYO Container only)
  --build-context-path <build-context-path>                      docker build context directory relative to project root (BYO Container only)
  --custom-docker-build-args <custom-docker-build-args>          docker build args as JSON key/value object (BYO Container only)
  --additional-policies <additional-policies...>                 additional IAM policy ARNs or policy document paths for the execution role
  --network-configuration <network-configuration>                network configuration (JSON NetworkConfiguration)
  --vpc-id <vpc-id>                                              VPC ID for Container builds in VPC mode (CodeBuild cannot infer it from subnets)
  --authorizer-configuration <authorizer-configuration>          inbound authorizer configuration (JSON AuthorizerConfiguration)
  --protocol-configuration <protocol-configuration>              protocol configuration (JSON ProtocolConfiguration)
  --request-header-configuration <request-header-configuration>  request header passthrough configuration (JSON RequestHeaderConfiguration)
  --lifecycle-configuration <lifecycle-configuration>            lifecycle configuration (JSON LifecycleConfiguration)
  --environment-variables <environment-variables>                environment variables (JSON object of key/value strings)
  --filesystem-configurations <filesystem-configurations>        filesystem mount configurations (JSON FilesystemConfiguration[])
  --memory <memory>                                              memory configuration (JSON with mode: none | create | existing ) (template only)
  --tags <tags>                                                  tags to apply (JSON object of key/value strings)
  -h, --help       

Follow-up items

• implement add runtime add the project manager level.
• split out test file into resource specific cases.
• make entrypoint optional. Its weird that we require it for container agents. The old cli defaulted to main.py which is unnecessary.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 99.69789% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 97.08%. Comparing base (2dba459) to head (ef9de8d).
⚠️ Report is 2 commits behind head on refactor.

Files with missing lines	Patch %	Lines
src/handlers/project/add/runtime/index.ts	99.67%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor    #2018      +/-   ##
============================================
+ Coverage     97.04%   97.08%   +0.03%     
============================================
  Files           370      371       +1     
  Lines         22287    22616     +329     
============================================
+ Hits          21628    21956     +328     
- Misses          659      660       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Hweinstock]

this forced me to cast in the handler, so I removed it. I think its a relic from old CLI.

[Hweinstock]

as a follow-up i think I'll break up this file.

[Hweinstock]

this proposed structure would allow us to support existing memories (not supported today), and more advanced configuration. By default, I think we give them the same default memory as old CLI, and the customer can customize here.