fix(cli): clear error for intrinsic certificateArn in domain commands

[sid88in]

What

Give a clear, actionable error when a CloudFormation intrinsic function (e.g. Fn::ImportValue) is passed as domain.certificateArn to the appsync domain CLI commands, instead of the cryptic SDK error Expected params.certificateArn to be a string.

Closes #532.

Why

domain.certificateArn is validated as stringOrIntrinsicFunction, which accepts any object — intentionally, because in the CloudFormation path the value is written straight into the AWS::AppSync::DomainName resource, where an intrinsic like Fn::ImportValue is valid and gets resolved at deploy time.

The CLI path is different. createDomain() calls the AppSync SDK's CreateDomainNameCommand directly, which needs a resolved string ARN. There is no CloudFormation context to resolve an intrinsic client‑side, so passing one currently fails deep in the SDK with Expected params.certificateArn to be a string — which gives the user no hint about the actual problem (as reported in #532).

This is the CloudFormation‑passthrough vs. CLI/synth‑time distinction: an intrinsic certificateArn is meaningful only for values written through to the template, not for a value the CLI must hand to the SDK.

The fix

• createDomain() (src/index.ts): after resolving certificateArn, throw a plugin error if it is not a string, explaining that the CLI requires a literal ARN and that intrinsic functions are only resolved via the CloudFormation integration (the default domain.useCloudFormation: true). The check sits before the SDK call, so we fail fast with guidance instead of a SDK type error.
• DomainConfig.certificateArn type (src/types/common.ts): widened from string to string | IntrinsicFunction to match what validation actually accepts. This also makes the runtime guard type‑meaningful (it narrows the union) and matches the convention used for other intrinsic‑capable fields in the codebase. (IntrinsicFunction is already imported in this file.)
• Docs (doc/custom-domain.md): a note in the "Using CloudFormation vs the CLI commands" section that the CLI requires a literal ARN and that intrinsic functions are only resolved when the domain is managed by CloudFormation.

What this does NOT change (intentional)

• Validation still accepts an intrinsic certificateArn — that is correct for the CloudFormation path and must not be tightened.
• The CloudFormation synthesis path is untouched: an imported/intrinsic ARN continues to flow into the AWS::AppSync::DomainName CertificateArn property and is resolved by CloudFormation. So the real answer to "how do I use an imported cert ARN?" — use the CloudFormation integration — keeps working; this PR just makes the CLI fail clearly instead of cryptically.
• IntrinsicFunction is not broadened to add Fn::ImportValue (it currently models Fn::GetAtt/Fn::Join/Ref/Fn::Sub). That's a pre‑existing, separate limitation; validation already accepts any object at runtime, and the new guard catches every non‑string regardless of the exact union, so the fix is correct without touching the shared type.

Testing

• Added a negative unit test: appsync domain create with certificateArn: { 'Fn::ImportValue': ... } and useCloudFormation: false rejects with the new message, and CreateDomainNameCommand is never sent.
• The existing positive create tests (literal ARN, ACM exact/wildcard match) still pass unchanged.
• Gates: npm run build, npm run lint (0 errors), npm test (332 passing), npm run test:e2e (84 passing), and prettier --check doc/custom-domain.md all pass.

Confidence

• The CLI‑vs‑CloudFormation behavior is verified against the source paths (createDomain → SDK vs compileCustomDomain → template) and the validation schema.
• I could not exercise the live SDK error string from this environment; the new error is thrown by the plugin before the SDK call, so it does not depend on the SDK's wording. Live AWS resolution of an imported ARN via the CloudFormation path is unchanged but was not deployed from here.

Summary by CodeRabbit

• Documentation

  • Added clarification that custom domains managed via CLI require a literal ARN string for certificates, not CloudFormation intrinsic functions.

• Bug Fixes

  • CLI now validates that certificate ARN values are plain strings and rejects CloudFormation functions with a helpful error message directing users to enable CloudFormation-based domain management if needed.

• Tests

  • Added test coverage for certificate ARN validation in CLI domain creation.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 742fa2cb-f1bc-429f-b185-b1d550c9b395

📥 Commits

Reviewing files that changed from the base of the PR and between d71c3b5 and b706af2.

📒 Files selected for processing (4)

• doc/custom-domain.md
• src/__tests__/commands.test.ts
• src/index.ts
• src/types/common.ts

---

📝 Walkthrough

Walkthrough

The PR adds runtime validation to enforce that when using the CLI to manage custom domains, the certificateArn must be a plain string ARN, not a CloudFormation intrinsic function. The type definition is broadened to accept both string and intrinsic function shapes, but the implementation validates and rejects the latter during CLI execution.

Changes

CLI Domain ARN Validation

Layer / File(s)

Summary

Type definition and validation logic src/types/common.ts, src/index.ts, src/__tests__/commands.test.ts, doc/custom-domain.md

DomainConfig.certificateArn type is expanded to accept string | IntrinsicFunction. The createDomain() function adds a guard that throws an error if certificateArn is not a plain string and useCloudFormation is false. A test verifies the error is thrown when an intrinsic function is provided to the CLI. Documentation clarifies that CLI commands require literal ARN strings and that CloudFormation intrinsic functions are only resolved when useCloudFormation: true.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 ARNs must be plain when CLI does the work,
But CloudFormation's intrinsic magic won't shirk—
A string for the CLI, a function for CF,
This validation keeps both paths safe and aloof! 🎀

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix(cli): clear error for intrinsic certificateArn in domain commands' accurately describes the main change: providing a clear error message when intrinsic functions are passed to CLI domain commands.
Linked Issues check	✅ Passed	The PR addresses issue #532 by detecting and rejecting intrinsic functions in CLI domain commands with a clear error message, and documenting the CloudFormation-based workaround.
Out of Scope Changes check	✅ Passed	All changes are directly related to addressing issue #532: validation in CLI path, type broadening to match runtime, documentation, and test coverage for the new error handling.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/532-cli-cert-arn-intrinsic

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}