feat(project): scaffold project manager interface by Hweinstock · Pull Request #1794 · aws/agentcore-cli

Hweinstock · 2026-07-20T16:54:54Z

Problem

We are currently missing a way to create and find existing projects on the local filesystem.

Solution

add ProjectManager interface to core interface with stub implementations.
migrate core input to a config object instead of positional arguments.
design re-usable withProject middleware for commands that requires an existing project.

Note: this PR does not implement e2e functionality, but sets up the scaffolding for future contributions.

We'll likely want a working create command before filling in all of these gaps.

Verification

added placeholder unit tests.
running agentcore project create --> Error: ProjectManager.create is not implemented yet

codecov-commenter · 2026-07-20T16:57:01Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.94%. Comparing base (951044e) to head (bfaf476).

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor    #1794      +/-   ##
============================================
+ Coverage     93.91%   93.94%   +0.02%     
============================================
  Files           118      122       +4     
  Lines          6423     6453      +30     
============================================
+ Hits           6032     6062      +30     
  Misses          391      391

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

tejaskash

I like that its available and injected through core.

tejaskash

LGTM, 1 clarification, not blocking

AlexanderRichey · 2026-07-21T15:04:36Z

+import type { ProjectManager } from "../../handlers/project/types";
+import type { Logger } from "../../logging";
+
+interface CreateProjectManagerConfig {


I think this should be a type and not an interface. Interfaces are used for things that can have multiple implementations, whereas types require specific, concrete/instantiated entities. That's what we need here for the input params for this constructor, so a standard type seems more appropriate.

I've always preferred interfaces to types since they tend to provide better error messages, and leave the door open if we want to extend them later on. The typescript language docs appear to recommend interfaces as the default here, but I do not have a strong preference here, especially since its very unlikely we'll want to extend these shapes.

I'll make the swap to types here.

There's an important distinction between types and interfaces that I think we should respect here. Types hold data of a determinate form. They're not implemented by anything else—they are the thing. They are, in this way, concrete. Interfaces, in contrast, are abstract; they don't have a concrete existence. They must be implemented and instantiated by something else that is concrete. In the case here, what we want is a concrete input with data, which makes a type the right tool for the current job. Making this an interface would bring in a bunch of unnecessary functionality and, as you said, make it possible to extend, which is precisely what we wouldn't want in this case.

AlexanderRichey · 2026-07-21T15:05:57Z

+export function createProjectManager(_config: CreateProjectManagerConfig): ProjectManager {
+  return {
+    find: (_input) => {
+      throw new Error(`ProjectManager.find is not implemented yet`);


I know we're just setting up the scaffolding here, but I tend to prefer class-based implementations of interfaces. They usually give you more flexibility going forward and, generally speaking, more developers are familiar with class-based patterns.

I definitely agree that more developers are familiar with classes, but I personally find them overly verbose in TS. One specific example is that when implementing an interface with an object, the compiler is able to infer the types (i.e. don't need type annotations on find here), which I find to be more readable and avoid defining the same types twice.

I tend to only reach for classes if I need inheritance or instanceof checks, but I don't think either is relevant here.

chatted with @tejaskash, sounds like I'm in the minority. swapping implementation to classes.

AlexanderRichey · 2026-07-21T15:07:47Z

  CreateIamClient,
 } from "./types";

+interface CoreClientConfig {


Like the above, this should be a type.

AlexanderRichey · 2026-07-21T15:09:57Z

+import { PROJECT_TEMPLATES, type ProjectManager } from "../types";

-export const PROJECT_TEMPLATES = ["placeholder"] as const;
+interface CreateProjectHandlerConfig {


I think this should be a type too. Or just make the ProjectManager a standard argument. I suspect we'll want to pass io as well here.

AlexanderRichey · 2026-07-21T15:11:51Z

+import type { ProjectManager } from "./types";

-export function createProjectHandler(): Router {
+interface ProjectHandlerConfig {


Same as above. Let's make this a type. I think we'll want io on here too as we move forward.

AlexanderRichey · 2026-07-21T15:15:21Z

+export interface FindProjectInput {
+  /** A path to search from when locating the project root. */
+  filePath: string;
+}


These two should be types as well.

AlexanderRichey · 2026-07-21T15:19:11Z

@@ -0,0 +1,28 @@
+/** Available project templates for scaffolding new AgentCore projects. */
+export const PROJECT_TEMPLATES = ["placeholder"] as const;


I tend to think this way of typing this stuff out would be easier to work with.

export type Template = "barebones" | "strands" | "langgraph"; export const TEMPLATE_BAREBONES: Template = "barebones";

I tried to keep the same types from #1793 since I didn't see this as part of the scope of this PR.

However, I do actually like this style of deriving the type from an array/object because it gives greater flexibility by allowing the values to be enumerated at runtime. What do you think of swapping to an object so that we can have named templates too (like TEMPLATE_BAREBONES above)?

Ex.

const TEMPLATES = { BAREBONES: 'barebones', STRANDS: 'strands, } as const; type Template = (typeof TEMPLATES)[keyof typeof TEMPLATES]

Nice! This approach looks good to me. 👍

AlexanderRichey · 2026-07-21T15:20:25Z

+/**
+ * Exposes the ability to configure, develop, and deploy a resolved AgentCore project.  
+ */
+export interface Project {}


Should project be abstract or concrete? I tend to think it should be concrete. However it might implement some or other abstract interface.

My understanding is that we need to define an interface here to preserve the existing dependency inversion pattern. If that interface isn't Project, what would it be?

I could imagine a capability split like Deployable, Buildable, etc. but that feels overly complex for what we're doing.

I could also imagine a java-like pattern of IProject or ProjectImpl, but that doesn't feel like idiomatic typescript.

Are you suggesting we break the dependency inversion pattern here, or is there a naming/structure option I'm missing here?

My understanding is that we need to define an interface here to preserve the existing dependency inversion pattern. If that interface isn't Project, what would it be?

I'm not sure this argument follows exactly. If you look at the interfaces defined for harness, for example, you'll see that the methods take types as input and output objects. The relevant interface is ProjectManager, not project itself.

Are you suggesting we break the dependency inversion pattern here, or is there a naming/structure option I'm missing here?

I'm suggesting that project has concrete thing, with concrete data, so it's not an abstract entity in the same way an interface is.

Ahh I think I understand. My original plan was:

With the project manager and project abstraction, we can start filling in the gaps (ex. add resources, deploy, dev, etc.) can all be exposed through the new Project interface.

However, based on your comments, it sounds like we're looking for Project to be pure data, and not deliver functionality itself with all functionality on the project manager class.

Let me address this to align with your comment below.

Hweinstock · 2026-07-21T21:27:09Z

Updated implementation to treat project as data instead of an interface. ProjectManager will host all project functionality.

github-actions Bot added agentcore-harness-reviewing AgentCore Harness review in progress and removed agentcore-harness-reviewing AgentCore Harness review in progress labels Jul 20, 2026

Hweinstock force-pushed the feat/project-stubs branch 2 times, most recently from 02c57e3 to 20fc2d6 Compare July 20, 2026 17:06

Hweinstock marked this pull request as ready for review July 20, 2026 17:08

tejaskash reviewed Jul 20, 2026

View reviewed changes

tejaskash previously approved these changes Jul 20, 2026

View reviewed changes

Comment thread src/handlers/project/types.ts Outdated

AlexanderRichey requested changes Jul 21, 2026

View reviewed changes

Hweinstock dismissed tejaskash’s stale review via 2d84ef5 July 21, 2026 17:11

Hweinstock force-pushed the feat/project-stubs branch from 2d84ef5 to a686c50 Compare July 21, 2026 17:12

Hweinstock mentioned this pull request Jul 21, 2026

feat(config): implement global config to wire up config command #1789

Open

Hweinstock added 4 commits July 21, 2026 20:00

feat(project): scaffold project manager interface

d0d2ea8

refactor(project): swap to using types instead of interfaces

e6ff78e

refactor(project): switch to enum object

b69d817

refactor(project): swap to class based implementation

c68e6ca

Hweinstock force-pushed the feat/project-stubs branch from 0048ccf to c68e6ca Compare July 21, 2026 20:11

fix: address formatting issues from rebase

69485f1

Hweinstock marked this pull request as draft July 21, 2026 21:12

refactor(project): make project concrete

bfaf476

Hweinstock force-pushed the feat/project-stubs branch from 5f39824 to bfaf476 Compare July 21, 2026 21:15

Hweinstock marked this pull request as ready for review July 21, 2026 21:21

AlexanderRichey approved these changes Jul 22, 2026

View reviewed changes

		@@ -0,0 +1,28 @@
		/** Available project templates for scaffolding new AgentCore projects. */
		export const PROJECT_TEMPLATES = ["placeholder"] as const;

Uh oh!

Conversation

Hweinstock commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Solution

Verification

Uh oh!

codecov-commenter commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

tejaskash left a comment

Choose a reason for hiding this comment

Uh oh!

tejaskash left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Hweinstock Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Hweinstock Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Hweinstock commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Hweinstock commented Jul 20, 2026 •

edited

Loading

codecov-commenter commented Jul 20, 2026 •

edited

Loading

Hweinstock Jul 21, 2026 •

edited

Loading

Hweinstock Jul 21, 2026 •

edited

Loading

Hweinstock commented Jul 21, 2026 •

edited

Loading