feat(export): allow harness exports outside a project

[aidandaly24]

Description

Allow agentcore export harness --arn outside a project by creating a project through the existing bootstrap flow. Add --project-name, deployable default names, safe destination refusal and prefetch before creation. Newly created projects default deployment targets to the source ARN's account and region; existing project targets remain unchanged.

Scope: eight files only. No IAM capture, preservation schema/assets, backend or CDK capability changes. The existing export semantics and vended @aws/agentcore-cdk 1.0.0-rc.3 remain unchanged.

Separate preservation work: #2532 and its CDK companion https://github.com/aws/agentcore-l3-cdk-constructs/pull/415. All three remain drafts; this PR does not require that unpublished capability.

Related Issue

N/A. The user explicitly requested no new issues.

Documentation PR

Included here: Harness configuration guide and generated command reference.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Other (please describe):

Testing

Prior scoped TEST-LOCAL gate at 6e1a8d52a60a41d92e3664e2d0ad79bb509607be: 211 focused tests passed; typecheck, lint, format, secrets and build passed. No checks were rerun during SHIP.

Supplemental full suite: 3889 pass / 101 fail / 3 errors in unchanged environment/IO paths; not a full pass. No fresh AWS validation for this split. Historical results are not claimed as live validation of this head; resource-preservation validation limits belong to #2532.

Temporary combined gate with #2532: 336 focused tests and type/lint/format/secrets/build passed after manually resolving four conflicts: the Harness guide, harness.test.ts, harness.ts and project types.ts. Resolution was only in a temporary clone. Future integration needs manual resolution and validation; automatic merge readiness is not claimed.

• I ran bun test (focused gate above; full-suite failures disclosed)
• I ran the relevant end-to-end tests with bun run test:e2e, or explained why they are not applicable (no fresh live run in this split)
• I ran bun run typecheck
• I ran bun run lint:check
• I ran bun run format:check
• I ran bun run build
• If I modified src/assets/, I updated affected snapshots with bun test <test-file> --update-snapshots and committed them (assets unchanged)

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published (N/A: this PR uses the unchanged public CDK and has no unpublished preservation dependency)

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the
terms of your choice.

[agentcore-devx-automation]

AgentCore Harness Review

Verdict: Looks good

I did not find any blocking issues. A few observations worth noting (non-blocking):

• Partial-state cleanup after project creation (edge case). In src/core/project/manager.tsx (around L928–L1114), once yield* this.create({ name: projectName }) succeeds, a subsequent failure inside the export body only runs cleanupAgentDir() + envFile.rollback(). The newly-created project directory itself is left on disk. In practice, the steps after create() (template render → spec parse → write) are unlikely to fail — invalid inputs and service failures are all caught beforehand, and the tests cover those pre-creation paths well — so this is a rare case. If you want to tighten it, you could either (a) track whether the project was created in this call and rm -rf the destination on failure, or (b) run project creation last after you have a validated plan in hand. Up to you.

• AgentCoreRegionSchema is a strict enum. If a future/unsupported region appears in the source ARN, AwsDeploymentTargetsSchema.parse(...) at L914 will throw after the GetHarness fetch has already happened. That's before this.create(...), so there's no partial state, but the user sees a validation failure after a successful service call. Probably fine since GetHarness would also fail in a region AgentCore doesn't support, but worth noting.

The test suite looks solid — real temp dirs, mocking kept at the harness SDK boundary, and good coverage of the "did we create a project when we shouldn't have" cases.

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.45%. Comparing base (a5a9ca6) to head (31ecb98).

Additional details and impacted files

@@            Coverage Diff            @@
##           refactor    #2542   +/-   ##
=========================================
  Coverage     97.44%   97.45%           
=========================================
  Files           644      644           
  Lines         47688    47759   +71     
=========================================
+ Hits          46471    46543   +72     
+ Misses         1217     1216    -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.