refactor(project): tighten the ProjectEvent and create() contracts

[notgitika]

Groundwork for agentcore project build, split out so the contract change is reviewable on its own.

What

ProjectEvent was a three-field bag with every field optional:

exporttypeProjectEvent={message?: string;subprocessOutput?: string;project?: Project;};

subprocessOutput and project were never written and never read — I checked every producer and consumer. Only message was ever used, and because it was optional the create handler had to guard it (if (event.message)) on every iteration. So the type is now just:

exporttypeProjectEvent={message: string};

and the guard in handlers/project/create/index.ts is gone.

create also declared AsyncGenerator<ProjectEvent>, leaving TReturn as the default any. It is now AsyncGenerator<ProjectEvent, Project>.

The type hole that tightening exposed

Naming the return type surfaced a real mismatch: create was building its return value out of TemplateSpec.runtimes, which is unknown[], while Project.runtimes is ProjectRuntime[]. any had been hiding it.

Rather than cast, create now reads the project back through resolve():

constproject=awaitthis.resolve({filePath: destination});

That honours a comment already sitting in the code ("Return the same shape resolve() would: a created project is a resolvable one"), and means the returned runtimes are schema-validated instead of being the template's loosely-typed spec sections passed through unchecked.

The matching as Project cast in manager.test.ts is dropped too, so the test now type-checks the real thing.

Verification

• bun test — 1061 pass, 0 fail
• tsc --noEmit clean, oxlint clean

No behaviour change; the only user-visible difference is that progress messages are no longer conditionally skipped, and they were never absent in practice.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.80%. Comparing base (d90fa2b) to head (049d64b).
⚠️ Report is 1 commits behind head on refactor.

Additional details and impacted files

@@ Coverage Diff @@## refactor #1969 +/- ##
=========================================
Coverage 96.80% 96.80% =========================================
Files 306 306 Lines 17073 17073 =========================================
Hits 16527 16527 Misses 546 546 

☔ 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]

LGTM!

[Hweinstock]

OOS here but ProjectStateError feels pretty vague to me. What do you think of replacing it with something like ProjectValidationError for when reading a project fails?

[notgitika]

Ahh yes that makes sense, I will make a note and have it out as a followup!

[notgitika]

Groundwork for agentcore project build, split out so the contract change is reviewable on its own.

What

ProjectEvent was a three-field bag with every field optional:

exporttypeProjectEvent={message?: string;subprocessOutput?: string;project?: Project;};

subprocessOutput and project were never written and never read — I checked every producer and consumer. Only message was ever used, and because it was optional the create handler had to guard it (if (event.message)) on every iteration. So the type is now just:

exporttypeProjectEvent={message: string};

and the guard in handlers/project/create/index.ts is gone.

create also declared AsyncGenerator<ProjectEvent>, leaving TReturn as the default any. It is now AsyncGenerator<ProjectEvent, Project>.

The type hole that tightening exposed

Naming the return type surfaced a real mismatch: create was building its return value out of TemplateSpec.runtimes, which is unknown[], while Project.runtimes is ProjectRuntime[]. any had been hiding it.

Rather than cast, create now reads the project back through resolve():

constproject=awaitthis.resolve({filePath: destination});

That honours a comment already sitting in the code ("Return the same shape resolve() would: a created project is a resolvable one"), and means the returned runtimes are schema-validated instead of being the template's loosely-typed spec sections passed through unchecked.

The matching as Project cast in manager.test.ts is dropped too, so the test now type-checks the real thing.

Verification

• bun test — 1061 pass, 0 fail
• tsc --noEmit clean, oxlint clean

No behaviour change; the only user-visible difference is that progress messages are no longer conditionally skipped, and they were never absent in practice.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.80%. Comparing base (d90fa2b) to head (049d64b).
⚠️ Report is 1 commits behind head on refactor.

Additional details and impacted files

@@ Coverage Diff @@## refactor #1969 +/- ##
=========================================
Coverage 96.80% 96.80% =========================================
Files 306 306 Lines 17073 17073 =========================================
Hits 16527 16527 Misses 546 546 

☔ 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]

LGTM!

[Hweinstock]

OOS here but ProjectStateError feels pretty vague to me. What do you think of replacing it with something like ProjectValidationError for when reading a project fails?

[notgitika]

Ahh yes that makes sense, I will make a note and have it out as a followup!

[notgitika]

Groundwork for agentcore project build, split out so the contract change is reviewable on its own.

What

ProjectEvent was a three-field bag with every field optional:

exporttypeProjectEvent={message?: string;subprocessOutput?: string;project?: Project;};

subprocessOutput and project were never written and never read — I checked every producer and consumer. Only message was ever used, and because it was optional the create handler had to guard it (if (event.message)) on every iteration. So the type is now just:

exporttypeProjectEvent={message: string};

and the guard in handlers/project/create/index.ts is gone.

create also declared AsyncGenerator<ProjectEvent>, leaving TReturn as the default any. It is now AsyncGenerator<ProjectEvent, Project>.

The type hole that tightening exposed

Naming the return type surfaced a real mismatch: create was building its return value out of TemplateSpec.runtimes, which is unknown[], while Project.runtimes is ProjectRuntime[]. any had been hiding it.

Rather than cast, create now reads the project back through resolve():

constproject=awaitthis.resolve({filePath: destination});

That honours a comment already sitting in the code ("Return the same shape resolve() would: a created project is a resolvable one"), and means the returned runtimes are schema-validated instead of being the template's loosely-typed spec sections passed through unchecked.

The matching as Project cast in manager.test.ts is dropped too, so the test now type-checks the real thing.

Verification

• bun test — 1061 pass, 0 fail
• tsc --noEmit clean, oxlint clean

No behaviour change; the only user-visible difference is that progress messages are no longer conditionally skipped, and they were never absent in practice.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.80%. Comparing base (d90fa2b) to head (049d64b).
⚠️ Report is 1 commits behind head on refactor.

Additional details and impacted files

@@ Coverage Diff @@## refactor #1969 +/- ##
=========================================
Coverage 96.80% 96.80% =========================================
Files 306 306 Lines 17073 17073 =========================================
Hits 16527 16527 Misses 546 546 

☔ 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]

LGTM!

[Hweinstock]

OOS here but ProjectStateError feels pretty vague to me. What do you think of replacing it with something like ProjectValidationError for when reading a project fails?

[notgitika]

Ahh yes that makes sense, I will make a note and have it out as a followup!

[notgitika]

Groundwork for agentcore project build, split out so the contract change is reviewable on its own.

What

ProjectEvent was a three-field bag with every field optional:

exporttypeProjectEvent={message?: string;subprocessOutput?: string;project?: Project;};

subprocessOutput and project were never written and never read — I checked every producer and consumer. Only message was ever used, and because it was optional the create handler had to guard it (if (event.message)) on every iteration. So the type is now just:

exporttypeProjectEvent={message: string};

and the guard in handlers/project/create/index.ts is gone.

create also declared AsyncGenerator<ProjectEvent>, leaving TReturn as the default any. It is now AsyncGenerator<ProjectEvent, Project>.

The type hole that tightening exposed

Naming the return type surfaced a real mismatch: create was building its return value out of TemplateSpec.runtimes, which is unknown[], while Project.runtimes is ProjectRuntime[]. any had been hiding it.

Rather than cast, create now reads the project back through resolve():

constproject=awaitthis.resolve({filePath: destination});

That honours a comment already sitting in the code ("Return the same shape resolve() would: a created project is a resolvable one"), and means the returned runtimes are schema-validated instead of being the template's loosely-typed spec sections passed through unchecked.

The matching as Project cast in manager.test.ts is dropped too, so the test now type-checks the real thing.

Verification

• bun test — 1061 pass, 0 fail
• tsc --noEmit clean, oxlint clean

No behaviour change; the only user-visible difference is that progress messages are no longer conditionally skipped, and they were never absent in practice.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.80%. Comparing base (d90fa2b) to head (049d64b).
⚠️ Report is 1 commits behind head on refactor.

Additional details and impacted files

@@ Coverage Diff @@## refactor #1969 +/- ##
=========================================
Coverage 96.80% 96.80% =========================================
Files 306 306 Lines 17073 17073 =========================================
Hits 16527 16527 Misses 546 546 

☔ 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]

LGTM!

[Hweinstock]

OOS here but ProjectStateError feels pretty vague to me. What do you think of replacing it with something like ProjectValidationError for when reading a project fails?

[notgitika]

Ahh yes that makes sense, I will make a note and have it out as a followup!

[notgitika]

Groundwork for agentcore project build, split out so the contract change is reviewable on its own.

What

ProjectEvent was a three-field bag with every field optional:

exporttypeProjectEvent={message?: string;subprocessOutput?: string;project?: Project;};

subprocessOutput and project were never written and never read — I checked every producer and consumer. Only message was ever used, and because it was optional the create handler had to guard it (if (event.message)) on every iteration. So the type is now just:

exporttypeProjectEvent={message: string};

and the guard in handlers/project/create/index.ts is gone.

create also declared AsyncGenerator<ProjectEvent>, leaving TReturn as the default any. It is now AsyncGenerator<ProjectEvent, Project>.

The type hole that tightening exposed

Naming the return type surfaced a real mismatch: create was building its return value out of TemplateSpec.runtimes, which is unknown[], while Project.runtimes is ProjectRuntime[]. any had been hiding it.

Rather than cast, create now reads the project back through resolve():

constproject=awaitthis.resolve({filePath: destination});

That honours a comment already sitting in the code ("Return the same shape resolve() would: a created project is a resolvable one"), and means the returned runtimes are schema-validated instead of being the template's loosely-typed spec sections passed through unchecked.

The matching as Project cast in manager.test.ts is dropped too, so the test now type-checks the real thing.

Verification

• bun test — 1061 pass, 0 fail
• tsc --noEmit clean, oxlint clean

No behaviour change; the only user-visible difference is that progress messages are no longer conditionally skipped, and they were never absent in practice.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.80%. Comparing base (d90fa2b) to head (049d64b).
⚠️ Report is 1 commits behind head on refactor.

Additional details and impacted files

@@ Coverage Diff @@## refactor #1969 +/- ##
=========================================
Coverage 96.80% 96.80% =========================================
Files 306 306 Lines 17073 17073 =========================================
Hits 16527 16527 Misses 546 546 

☔ 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]

LGTM!

[Hweinstock]

OOS here but ProjectStateError feels pretty vague to me. What do you think of replacing it with something like ProjectValidationError for when reading a project fails?

[notgitika]

Ahh yes that makes sense, I will make a note and have it out as a followup!

[notgitika]

Groundwork for agentcore project build, split out so the contract change is reviewable on its own.

What

ProjectEvent was a three-field bag with every field optional:

exporttypeProjectEvent={message?: string;subprocessOutput?: string;project?: Project;};

subprocessOutput and project were never written and never read — I checked every producer and consumer. Only message was ever used, and because it was optional the create handler had to guard it (if (event.message)) on every iteration. So the type is now just:

exporttypeProjectEvent={message: string};

and the guard in handlers/project/create/index.ts is gone.

create also declared AsyncGenerator<ProjectEvent>, leaving TReturn as the default any. It is now AsyncGenerator<ProjectEvent, Project>.

The type hole that tightening exposed

Naming the return type surfaced a real mismatch: create was building its return value out of TemplateSpec.runtimes, which is unknown[], while Project.runtimes is ProjectRuntime[]. any had been hiding it.

Rather than cast, create now reads the project back through resolve():

constproject=awaitthis.resolve({filePath: destination});

That honours a comment already sitting in the code ("Return the same shape resolve() would: a created project is a resolvable one"), and means the returned runtimes are schema-validated instead of being the template's loosely-typed spec sections passed through unchecked.

The matching as Project cast in manager.test.ts is dropped too, so the test now type-checks the real thing.

Verification

• bun test — 1061 pass, 0 fail
• tsc --noEmit clean, oxlint clean

No behaviour change; the only user-visible difference is that progress messages are no longer conditionally skipped, and they were never absent in practice.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.80%. Comparing base (d90fa2b) to head (049d64b).
⚠️ Report is 1 commits behind head on refactor.

Additional details and impacted files

@@ Coverage Diff @@## refactor #1969 +/- ##
=========================================
Coverage 96.80% 96.80% =========================================
Files 306 306 Lines 17073 17073 =========================================
Hits 16527 16527 Misses 546 546 

☔ 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]

LGTM!

[Hweinstock]

OOS here but ProjectStateError feels pretty vague to me. What do you think of replacing it with something like ProjectValidationError for when reading a project fails?

[notgitika]

Ahh yes that makes sense, I will make a note and have it out as a followup!

[notgitika]

Groundwork for agentcore project build, split out so the contract change is reviewable on its own.

What

ProjectEvent was a three-field bag with every field optional:

exporttypeProjectEvent={message?: string;subprocessOutput?: string;project?: Project;};

subprocessOutput and project were never written and never read — I checked every producer and consumer. Only message was ever used, and because it was optional the create handler had to guard it (if (event.message)) on every iteration. So the type is now just:

exporttypeProjectEvent={message: string};

and the guard in handlers/project/create/index.ts is gone.

create also declared AsyncGenerator<ProjectEvent>, leaving TReturn as the default any. It is now AsyncGenerator<ProjectEvent, Project>.

The type hole that tightening exposed

Naming the return type surfaced a real mismatch: create was building its return value out of TemplateSpec.runtimes, which is unknown[], while Project.runtimes is ProjectRuntime[]. any had been hiding it.

Rather than cast, create now reads the project back through resolve():

constproject=awaitthis.resolve({filePath: destination});

That honours a comment already sitting in the code ("Return the same shape resolve() would: a created project is a resolvable one"), and means the returned runtimes are schema-validated instead of being the template's loosely-typed spec sections passed through unchecked.

The matching as Project cast in manager.test.ts is dropped too, so the test now type-checks the real thing.

Verification

• bun test — 1061 pass, 0 fail
• tsc --noEmit clean, oxlint clean

No behaviour change; the only user-visible difference is that progress messages are no longer conditionally skipped, and they were never absent in practice.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.80%. Comparing base (d90fa2b) to head (049d64b).
⚠️ Report is 1 commits behind head on refactor.

Additional details and impacted files

@@ Coverage Diff @@## refactor #1969 +/- ##
=========================================
Coverage 96.80% 96.80% =========================================
Files 306 306 Lines 17073 17073 =========================================
Hits 16527 16527 Misses 546 546 

☔ 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]

LGTM!

[Hweinstock]

OOS here but ProjectStateError feels pretty vague to me. What do you think of replacing it with something like ProjectValidationError for when reading a project fails?

[notgitika]

Ahh yes that makes sense, I will make a note and have it out as a followup!

[notgitika]

Groundwork for agentcore project build, split out so the contract change is reviewable on its own.

What

ProjectEvent was a three-field bag with every field optional:

exporttypeProjectEvent={message?: string;subprocessOutput?: string;project?: Project;};

subprocessOutput and project were never written and never read — I checked every producer and consumer. Only message was ever used, and because it was optional the create handler had to guard it (if (event.message)) on every iteration. So the type is now just:

exporttypeProjectEvent={message: string};

and the guard in handlers/project/create/index.ts is gone.

create also declared AsyncGenerator<ProjectEvent>, leaving TReturn as the default any. It is now AsyncGenerator<ProjectEvent, Project>.

The type hole that tightening exposed

Naming the return type surfaced a real mismatch: create was building its return value out of TemplateSpec.runtimes, which is unknown[], while Project.runtimes is ProjectRuntime[]. any had been hiding it.

Rather than cast, create now reads the project back through resolve():

constproject=awaitthis.resolve({filePath: destination});

That honours a comment already sitting in the code ("Return the same shape resolve() would: a created project is a resolvable one"), and means the returned runtimes are schema-validated instead of being the template's loosely-typed spec sections passed through unchecked.

The matching as Project cast in manager.test.ts is dropped too, so the test now type-checks the real thing.

Verification

• bun test — 1061 pass, 0 fail
• tsc --noEmit clean, oxlint clean

No behaviour change; the only user-visible difference is that progress messages are no longer conditionally skipped, and they were never absent in practice.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.80%. Comparing base (d90fa2b) to head (049d64b).
⚠️ Report is 1 commits behind head on refactor.

Additional details and impacted files

@@ Coverage Diff @@## refactor #1969 +/- ##
=========================================
Coverage 96.80% 96.80% =========================================
Files 306 306 Lines 17073 17073 =========================================
Hits 16527 16527 Misses 546 546 

☔ 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]

LGTM!

[Hweinstock]

OOS here but ProjectStateError feels pretty vague to me. What do you think of replacing it with something like ProjectValidationError for when reading a project fails?

[notgitika]

Ahh yes that makes sense, I will make a note and have it out as a followup!