What the agent does
The agent reads the whole program first. In a project like the aws-ts-static-website example in pulumi/examples, index.ts is one file that does everything: it reads targetDomain, pathToWebsiteContents, an optional certificateArn and includeWWW from pulumi.Config, refuses placeholder domains outside a dry run, creates a content aws.s3.Bucket and its BucketWebsiteConfiguration, walks the www directory with a crawlDirectory helper creating one BucketObject per file with the bucket as parent, creates a logs bucket whose ACL acl.ts sets through BucketOwnershipControls, BucketPublicAccessBlock and BucketAcl, and then, only when no certificate ARN was given, creates an aws.Provider pinned to us-east-1, an acm.Certificate with DNS validation, one or two route53.Record validation entries and a CertificateValidation. After that come an OriginAccessIdentity, a cloudfront.Distribution with PriceClass_100, a ten-minute TTL, a custom 404 and logging to the logs bucket, a BucketPolicy that lets only the identity read, and the A records from createAliasRecord and createWWWAliasRecord. Four stack outputs close the file. Pulumi.yaml declares the template config, package.json pins @pulumi/aws 7.23.0 and @pulumi/pulumi 3.228.0 as an ES module, and tsconfig.json compiles index.ts alone under nodenext. The repository already shows the shape it prefers: aws-ts-s3-folder-component/s3folder.ts defines S3Folder extends pulumi.ComponentResource with type examples:S3Folder, passes { parent: this } to every child and ends with registerOutputs.
The agent carves the program along the lines the code already has. cert.ts gets a SiteCertificate component that owns the east-region provider, the certificate, the validation records and the CertificateValidation, and exposes certificateArn as an output; its constructor takes the domain, the includeWWW flag and the hosted zone id. site.ts gets a StaticSite component for the content bucket, its website configuration, the crawled objects, the logs bucket and its ACL resources, the origin access identity, the distribution and the bucket policy, with cloudFrontDomain, contentBucketUri and contentBucketWebsiteEndpoint as outputs. dns.ts gets a SiteDns component for the alias records. index.ts shrinks to config, the three constructors and the exports, and getDomainAndSubdomain moves to a shared domain.ts because both the certificate and the DNS code call it. Each component registers a type under the examples: prefix the repository uses, passes { parent: this } down, and calls registerOutputs at the end.
The part that decides whether this is safe for an existing stack is the aliases. A resource's URN includes its parent's type, so moving cdn under a StaticSite would make pulumi up delete the distribution and create a new one. The agent adds aliases: [{ parent: pulumi.rootStackResource }] to the options of every child that used to be top-level, and for the bucket objects, which already had the content bucket as parent, keeps that parent so their URNs do not move. The eslint configuration at the repository root, with the header rule and @stylistic plugin, is run on the new files, and the copyright header the lint checks for is on each one.
Proof comes without a cloud account. A new index.test.ts, run with Mocha the way the repository's testing-unit-ts project does, calls pulumi.runtime.setMocks and instantiates the program, then asserts that every expected resource type is registered, that each child's parent is its component, and that every former top-level resource carries a root-stack alias. tsc --noEmit with the project's tsconfig.json type-checks the split. In a stack that already exists, the check a reader runs is pulumi preview --diff, which should list only the new component resources as creates and no replacements; the agent writes that expectation into the pull request as the condition for merging.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Refactor this Pulumi TypeScript program into ComponentResource classes without replacing any deployed resource. Read index.ts, acl.ts, Pulumi.yaml, package.json and tsconfig.json first, and read how the repository's existing component example structures a ComponentResource. Split the program into a certificate component, a static site component for the buckets, objects, origin access identity, distribution and bucket policy, and a DNS component for the alias records, with the domain helper shared; keep index.ts to config, the three constructors and the stack outputs. Pass parent: this to every child, call registerOutputs, and add aliases pointing at the root stack resource to every resource that was previously top-level so URNs do not change; keep the existing parent on the bucket objects. Put the repository's copyright header on new files and run its eslint config on them. Write a Mocha test with pulumi.runtime.setMocks that asserts resource types, parents and aliases, run it and tsc --noEmit, and open a pull request whose description says that pulumi preview --diff on an existing stack must show only the component resources as creates and no replacements.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request that adds cert.ts, site.ts, dns.ts, domain.ts and index.test.ts, rewrites index.ts to a short composition, and adjusts tsconfig.json and package.json so the new files compile and the test runs. The description lists each component, the resources it owns, the outputs it exposes, and the alias rule that keeps every URN stable.
The run's record keeps the tsc --noEmit result, the Mocha output with the parent and alias assertions named, and the eslint run on the new files, so a reviewer can see the refactor type-checks and that no resource lost its alias on the way into a component.
Before merging, a reviewer runs pulumi preview --diff against a real stack: the expected output is three or four create lines for the component resources and ~ or no-change for everything else. A replace on the distribution or a bucket means an alias is missing, and the pull request names that as the stop condition.
Run it on every Pulumi program that outgrows one file
The setup is one POST /o/{org}/sessions with this body and the repository in resources, started from a terminal; the run keeps working in its sandbox after you close the window, and a follow-up through POST /o/{org}/sessions/{id}/messages can ask for the components to move into a shared package or for a different split without starting over. A team with several programs sends one request per repository, each with a fresh UUID as request_id, so a retried script returns the run it already started.
Set a webhook_url on the API key and Rush posts run.completed or run.failed when a run's turn finishes, with session_url so your server can read the pull request link and the test output.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Moving resources into components is a refactor whose cost shows up at pulumi up: a missing alias replaces a CloudFront distribution and takes the site down while the new one deploys. The agent reads the program as a whole in its own sandbox, applies the alias rule to every moved resource, and writes a mock-backed test that checks the rule instead of relying on a reviewer to spot one missing option among a dozen.
Every command and its output stay with the run, so the pull request can point at the assertion that found all the former top-level resources aliased, and the reviewer's own pulumi preview --diff becomes a confirmation rather than the first time anyone finds out.
Frequently asked questions
Will pulumi up replace my distribution or bucket?
Not if every moved resource carries an alias to its old parent, which the mock test checks. The expected pulumi preview --diff shows the component resources as creates and nothing else as a replace; a replace line means an alias is missing and the pull request should not merge until it is added.
Why keep the bucket objects under the content bucket?
They already had the bucket as parent, so their URNs include it. Re-parenting them to the component would move every object's URN and need an alias per file; leaving them where they are costs nothing and keeps the diff small.
Can the aliases be removed later?
Yes, once every stack has been updated with them in place. An alias is read during the update that adopts the new URN; after that the state holds the new URN and the option can go. The pull request says to remove them in a follow-up after all stacks have run pulumi up.
Does the test need AWS credentials?
No. pulumi.runtime.setMocks replaces the engine, so the program runs in-process and the test inspects the resources it registered. The only cloud step is the reader's own pulumi preview against an existing stack, which the agent cannot run and does not claim to.
More Pulumi jobs
More jobs like this: Hand off a long task
- Add Compose Profiles for Optional Services (Docker Compose)
- Add Compose Watch to a Docker Compose Project (Docker Compose)
- Add Response Compression to an Axum API (Axum)