feat: add a project command menu to the TUI

src/components/Root.tsx

@@ -107,9 +107,15 @@ import { GatewayRuleScreen } from "../handlers/gateway/rule/screen.tsx";
 import { GatewayRuleListScreen } from "../handlers/gateway/rule/list/screen.tsx";
 import { GatewayRuleGetScreen } from "../handlers/gateway/rule/get/screen.tsx";
 import { GatewayInvokeScreen } from "../handlers/gateway/invoke/screen.tsx";
+import { ProjectScreen, ProjectCommandNotImplementedScreen } from "../handlers/project/screen.tsx";
 import { RootScreen, HelpScreen } from "../handlers/screen.tsx";
 import type { Context } from "../router";
 
+// PROJECT_COMMANDS are the `agentcore project` subcommands that are listed in
+// the menu but have no screen of their own yet. Each is routed explicitly so
+// selecting it reports "not implemented" error
+const PROJECT_COMMANDS = ["create", "add", "remove", "dev", "deploy", "status", "build"] as const;
+
 export interface RootProps {
  // path is the command path to the executing node (e.g. "/agentcore").
  path: string;
@@ -736,6 +742,16 @@ export function Root({ path, ctx, core, queryClient }: RootProps) {
  path="agentcore/identity/oauth2-credential-provider/get/:name/json"
  element={<Oauth2CredentialProviderGetJsonScreen ctx={ctx} core={core} />}
  />
+ <Route path="agentcore/project" element={<ProjectScreen ctx={ctx} core={core} />} />
+ {PROJECT_COMMANDS.map((command) => (
+ <Route
+ key={command}
+ path={`agentcore/project/${command}`}
+ element={
+ <ProjectCommandNotImplementedScreen ctx={ctx} core={core} command={command} />
+ }
+ />
+ ))}
  <Route path="*" element={<HelpScreen ctx={ctx} core={core} />} />
  </Routes>
  </MemoryRouter>

src/handlers/index.tsx

@@ -50,7 +50,7 @@ export function createRootHandler(core: Core, config: RootHandlerConfig): Router
  root.handler(createGatewayHandler(core, io));
  root.handler(createEvalHandler(core, io));
  root.handler(createConfigHandler());
- root.handler(createProjectHandler({ projectManager: core.projectManager, io }));
+ root.handler(createProjectHandler({ core, io }));
 
  // Invoking with no subcommand launches the interactive TUI.
  root.default(renderTui(core, io));

src/handlers/project/index.ts

@@ -5,6 +5,8 @@ import { ContainerDevRunner } from "../../core/dev/container";
 import { InspectorAssets } from "../../core/dev/inspectorAssets";
 import { startOtelCollector } from "../../core/dev/otel/collector";
 import { withProject } from "../../middleware";
+import { renderTui } from "../../tui";
+import type { Core } from "../types";
 import { createCreateProjectHandler } from "./create";
 import { createRemoveProjectHandler } from "./remove";
 import { createDevProjectHandler } from "./dev";
@@ -16,16 +18,20 @@ import type { ProjectManager } from "./types";
 import { createAddProjectResourceHandler } from "./add";
 
 type ProjectHandlerConfig = {
-projectManager: ProjectManager;
+core: Core;
  io: AppIO;
 };
 
-export function createProjectHandler(config: ProjectHandlerConfig): Router {
+export function createProjectHandler({ core, io }: ProjectHandlerConfig): Router {
+ const projectManager: ProjectManager = core.projectManager;
+ const config = { projectManager, io };
  const project = new Router("project", "manage an AgentCore project");
 
- project.handler(
- createCreateProjectHandler({ projectManager: config.projectManager, io: config.io }),
- );
+ // Without a default, a bare `agentcore project` falls back to Commander's help
+ // and a usage exit code instead of the menu every sibling router opens.
+ project.default(renderTui(core, io));
+
+ project.handler(createCreateProjectHandler({ projectManager, io }));
  project.handler(createAddProjectResourceHandler(config));
  project.handler(
  withProject({ projectManager: config.projectManager })(

src/handlers/project/project.screen.test.tsx

@@ -0,0 +1,158 @@
+import { test, expect, describe, afterEach } from "bun:test";
+import {
+ renderScreen,
+ waitForText,
+ cleanupScreens,
+ createSilentLogger,
+ TestCoreClient,
+ TestGlobalConfigAccessor,
+ testIO,
+ ttyTestIO,
+} from "../../testing";
+import { renderTuiAt } from "../../tui";
+import { InvalidEnvironmentError, NotImplementedError } from "../../errors";
+import { compile, ValueContext } from "../../router";
+import { ExitCode } from "../../runnable";
+import { createRootHandler } from "../index";
+
+afterEach(cleanupScreens);
+
+// projectSubcommands reads the project group's children off the compiled
+// Commander tree, so tests driven by it cover any subcommand added later.
+function projectSubcommands(): string[] {
+ const root = compile(
+ createRootHandler(new TestCoreClient(), {
+ io: testIO().io,
+ logger: createSilentLogger(),
+ globalConfigAccessor: new TestGlobalConfigAccessor(),
+ }),
+ ValueContext.EmptyContext(),
+ );
+ const project = root.commands.find((command) => command.name() === "project")!;
+ // `help` is Commander's own, not one of ours.
+ return project.commands.map((command) => command.name()).filter((name) => name !== "help");
+}
+
+describe("project menu", () => {
+ test("lists every project subcommand", async () => {
+ const r = renderScreen("/agentcore/project");
+
+ await waitForText(r.lastFrame, "manage an AgentCore project");
+ const frame = r.lastFrame()!;
+ for (const command of projectSubcommands()) {
+ expect(frame).toContain(command);
+ }
+ r.unmount();
+ });
+
+ test("is reachable from the root menu", async () => {
+ const r = renderScreen("/agentcore");
+
+ await waitForText(r.lastFrame, "manage an AgentCore project");
+ await r.write("project");
+ await waitForText(r.lastFrame, "❯ project");
+ await r.press("return");
+
+ await waitForText(r.lastFrame, "agentcore → project");
+ expect(r.lastFrame()).toContain("create");
+ r.unmount();
+ });
+
+ test("esc returns to the root menu", async () => {
+ const r = renderScreen("/agentcore/project");
+
+ await waitForText(r.lastFrame, "agentcore → project");
+ await r.press("escape");
+
+ await waitForText(r.lastFrame, "the platform for production AI agents");
+ r.unmount();
+ });
+});
+
+describe("project subcommands without a screen", () => {
+ // renderTuiAt rather than renderScreen: ink-testing-library exposes no
+ // waitUntilExit, so it cannot observe the rejection under test.
+ //
+ // Reading the cases off the router also guards Root's hand-written
+ // PROJECT_COMMANDS: an unrouted subcommand hits the catch-all, which resolves
+ // instead of rejecting. Frames can't detect that — the catch-all exits before
+ // painting, so it and this screen both render empty.
+ test.each(projectSubcommands())(
+ "%s tears down the TUI with NotImplementedError",
+ async (command) => {
+ const { streams } = ttyTestIO();
+
+ const rendering = renderTuiAt(
+ `/agentcore/project/${command}`,
+ ValueContext.EmptyContext(),
+ new TestCoreClient(),
+ streams.io,
+ );
+
+ await expect(rendering).rejects.toThrow(NotImplementedError);
+ await expect(rendering).rejects.toThrow(`'agentcore project ${command}'`);
+ },
+ );
+
+ test("the error names the command to run instead", async () => {
+ const { streams } = ttyTestIO();
+
+ const caught: unknown = await renderTuiAt(
+ "/agentcore/project/deploy",
+ ValueContext.EmptyContext(),
+ new TestCoreClient(),
+ streams.io,
+ ).then(
+ () => undefined,
+ (error: unknown) => error,
+ );
+
+ expect(caught).toBeInstanceOf(NotImplementedError);
+ const error = caught as NotImplementedError;
+ expect(error.message).toContain("agentcore project deploy --help");
+ // Surfaces as a plain CLI failure, not a crash.
+ expect(error.exitCode).toBe(1);
+ });
+});
+
+describe("agentcore project (no subcommand)", () => {
+ // Exercises the real CLI entrypoint; the screen tests mount a path directly
+ // and so never caught the missing default handler.
+ //
+ // Asserts renderTui's TTY guard rather than a rendered frame: Ink only writes
+ // frames incrementally when interactive (`!isInCi && isTTY`), so asserting on
+ // frames here would pass locally and time out under CI. Reaching the guard at
+ // all proves the group routed to the TUI — Commander help neither throws nor
+ // touches stderr.
+ test("routes to the TUI rather than printing Commander help", async () => {
+ const io = testIO();
+ const root = createRootHandler(new TestCoreClient(), {
+ io: io.io,
+ logger: createSilentLogger(),
+ globalConfigAccessor: new TestGlobalConfigAccessor(),
+ });
+
+ const caught: unknown = await root.route(["node", "agentcore", "project"]).then(
+ () => undefined,
+ (error: unknown) => error,
+ );
+
+ expect(caught).toBeInstanceOf(InvalidEnvironmentError);
+ expect((caught as InvalidEnvironmentError).exitCode).toBe(ExitCode.USAGE);
+ expect(io.stdout()).toBe("");
+ });
+
+ test("prints help instead of the TUI under --json", async () => {
+ const io = testIO();
+ const root = createRootHandler(new TestCoreClient(), {
+ io: io.io,
+ logger: createSilentLogger(),
+ globalConfigAccessor: new TestGlobalConfigAccessor(),
+ });
+
+ await root.route(["node", "agentcore", "project", "--json"]);
+
+ expect(io.stdout()).toContain("Usage:");
+ expect(io.stdout()).toContain("create");
+ });
+});

src/handlers/project/screen.tsx

@@ -0,0 +1,37 @@
+import { useEffect } from "react";
+import { useApp } from "ink";
+import { RouterScreen } from "../../components/RouterScreen";
+import { NotImplementedError } from "../../errors";
+import type { ScreenProps } from "../types";
+
+export function ProjectScreen(props: ScreenProps) {
+ return <RouterScreen {...props} path={["agentcore", "project"]} />;
+}
+
+export interface ProjectCommandNotImplementedScreenProps extends ScreenProps {
+ // command is the project subcommand the user selected, e.g. "deploy".
+ command: string;
+}
+
+// ProjectCommandNotImplementedScreen is the landing screen for a project
+// subcommand that is listed in the menu but has no screen yet.
+//
+// exit(error) rejects the waitUntilExit() that renderTuiAt awaits, so the TUI
+// tears down and the error takes the normal CLI path. Throwing during render
+// would surface a React stack trace instead.
+export function ProjectCommandNotImplementedScreen({
+ command,
+}: ProjectCommandNotImplementedScreenProps) {
+ const { exit } = useApp();
+
+ useEffect(() => {
+ exit(
+ new NotImplementedError(
+ `'agentcore project ${command}' has no interactive screen yet; ` +
+ `run 'agentcore project ${command} --help' to use it from the command line`,
+ ),
+ );
+ }, [exit, command]);
+
+ return null;
+}

src/testing/index.tsx

@@ -1,6 +1,6 @@
 export { parse, stringify } from "./serialization";
 export { fixtureFactories, fixtureFetch, isRecording, matchGolden, settle } from "./fixtures";
-export { testIO, type TestIO } from "./testIO";
+export { testIO, ttyTestIO, type TestIO, type TtyInput } from "./testIO";
 export { tick, waitFor, WaitForTimeoutError } from "./timing";
 export {
  TestCoreClient,

src/testing/testIO.tsx

@@ -53,3 +53,32 @@ export function testIO({ isTTY = false, stdin: stdinContent }: TestIOOptions = {
  stderr: err.read,
  };
 }
+
+// TtyInput is the writable stdin of a TTY TestIO: tests push raw key sequences
+// into it to drive a mounted TUI.
+export interface TtyInput extends NodeJS.ReadStream {
+ write(chunk: string): boolean;
+}
+
+// ttyTestIO builds a TestIO that Ink accepts as a real terminal: isTTY, the
+// no-op stdin methods Ink calls when it takes over, and a window size (Ink needs
+// columns/rows to lay out frames). For tests that mount the TUI through
+// renderTui/renderTuiAt rather than ink-testing-library.
+export function ttyTestIO(columns = 100, rows = 40): { streams: TestIO; stdin: TtyInput } {
+ const streams = testIO({ isTTY: true });
+ const stdin = streams.io.stdin as TtyInput;
+ stdin.setRawMode = function () {
+ return this;
+ };
+ stdin.ref = function () {
+ return this;
+ };
+ stdin.unref = function () {
+ return this;
+ };
+ Object.defineProperties(streams.io.stdout, {
+ columns: { configurable: true, value: columns },
+ rows: { configurable: true, value: rows },
+ });
+ return { streams, stdin };
+}

src/tui/tui.test.tsx

@@ -7,34 +7,12 @@ import {
  TestCoreClient,
  TestGlobalConfigAccessor,
  testIO,
+ ttyTestIO,
  tick,
  waitFor,
 } from "../testing";
 import { ExitCode } from "../runnable";
 
-interface TtyInput extends NodeJS.ReadStream {
- write(chunk: string): boolean;
-}
-
-function ttyTestIO(): { streams: ReturnType<typeof testIO>; stdin: TtyInput } {
- const streams = testIO({ isTTY: true });
- const stdin = streams.io.stdin as TtyInput;
- stdin.setRawMode = function () {
- return this;
- };
- stdin.ref = function () {
- return this;
- };
- stdin.unref = function () {
- return this;
- };
- Object.defineProperties(streams.io.stdout, {
- columns: { configurable: true, value: 100 },
- rows: { configurable: true, value: 40 },
- });
- return { streams, stdin };
-}
-
 describe("renderJson", () => {
  test("pretty-prints a value as indented JSON to the given writer", () => {
  const lines: string[] = [];

src/components/Root.tsx

@@ -107,9 +107,15 @@ import { GatewayRuleScreen } from "../handlers/gateway/rule/screen.tsx";
 import { GatewayRuleListScreen } from "../handlers/gateway/rule/list/screen.tsx";
 import { GatewayRuleGetScreen } from "../handlers/gateway/rule/get/screen.tsx";
 import { GatewayInvokeScreen } from "../handlers/gateway/invoke/screen.tsx";
+import { ProjectScreen, ProjectCommandNotImplementedScreen } from "../handlers/project/screen.tsx";
 import { RootScreen, HelpScreen } from "../handlers/screen.tsx";
 import type { Context } from "../router";
 
+// PROJECT_COMMANDS are the `agentcore project` subcommands that are listed in
+// the menu but have no screen of their own yet. Each is routed explicitly so
+// selecting it reports "not implemented" error
+const PROJECT_COMMANDS = ["create", "add", "remove", "dev", "deploy", "status", "build"] as const;
+
 export interface RootProps {
  // path is the command path to the executing node (e.g. "/agentcore").
  path: string;
@@ -736,6 +742,16 @@ export function Root({ path, ctx, core, queryClient }: RootProps) {
  path="agentcore/identity/oauth2-credential-provider/get/:name/json"
  element={<Oauth2CredentialProviderGetJsonScreen ctx={ctx} core={core} />}
  />
+ <Route path="agentcore/project" element={<ProjectScreen ctx={ctx} core={core} />} />
+ {PROJECT_COMMANDS.map((command) => (
+ <Route
+ key={command}
+ path={`agentcore/project/${command}`}
+ element={
+ <ProjectCommandNotImplementedScreen ctx={ctx} core={core} command={command} />
+ }
+ />
+ ))}
  <Route path="*" element={<HelpScreen ctx={ctx} core={core} />} />
  </Routes>
  </MemoryRouter>

src/handlers/index.tsx

@@ -50,7 +50,7 @@ export function createRootHandler(core: Core, config: RootHandlerConfig): Router
  root.handler(createGatewayHandler(core, io));
  root.handler(createEvalHandler(core, io));
  root.handler(createConfigHandler());
- root.handler(createProjectHandler({ projectManager: core.projectManager, io }));
+ root.handler(createProjectHandler({ core, io }));
 
  // Invoking with no subcommand launches the interactive TUI.
  root.default(renderTui(core, io));

src/handlers/project/index.ts

@@ -5,6 +5,8 @@ import { ContainerDevRunner } from "../../core/dev/container";
 import { InspectorAssets } from "../../core/dev/inspectorAssets";
 import { startOtelCollector } from "../../core/dev/otel/collector";
 import { withProject } from "../../middleware";
+import { renderTui } from "../../tui";
+import type { Core } from "../types";
 import { createCreateProjectHandler } from "./create";
 import { createRemoveProjectHandler } from "./remove";
 import { createDevProjectHandler } from "./dev";
@@ -16,16 +18,20 @@ import type { ProjectManager } from "./types";
 import { createAddProjectResourceHandler } from "./add";
 
 type ProjectHandlerConfig = {
-projectManager: ProjectManager;
+core: Core;
  io: AppIO;
 };
 
-export function createProjectHandler(config: ProjectHandlerConfig): Router {
+export function createProjectHandler({ core, io }: ProjectHandlerConfig): Router {
+ const projectManager: ProjectManager = core.projectManager;
+ const config = { projectManager, io };
  const project = new Router("project", "manage an AgentCore project");
 
- project.handler(
- createCreateProjectHandler({ projectManager: config.projectManager, io: config.io }),
- );
+ // Without a default, a bare `agentcore project` falls back to Commander's help
+ // and a usage exit code instead of the menu every sibling router opens.
+ project.default(renderTui(core, io));
+
+ project.handler(createCreateProjectHandler({ projectManager, io }));
  project.handler(createAddProjectResourceHandler(config));
  project.handler(
  withProject({ projectManager: config.projectManager })(

src/handlers/project/project.screen.test.tsx

@@ -0,0 +1,158 @@
+import { test, expect, describe, afterEach } from "bun:test";
+import {
+ renderScreen,
+ waitForText,
+ cleanupScreens,
+ createSilentLogger,
+ TestCoreClient,
+ TestGlobalConfigAccessor,
+ testIO,
+ ttyTestIO,
+} from "../../testing";
+import { renderTuiAt } from "../../tui";
+import { InvalidEnvironmentError, NotImplementedError } from "../../errors";
+import { compile, ValueContext } from "../../router";
+import { ExitCode } from "../../runnable";
+import { createRootHandler } from "../index";
+
+afterEach(cleanupScreens);
+
+// projectSubcommands reads the project group's children off the compiled
+// Commander tree, so tests driven by it cover any subcommand added later.
+function projectSubcommands(): string[] {
+ const root = compile(
+ createRootHandler(new TestCoreClient(), {
+ io: testIO().io,
+ logger: createSilentLogger(),
+ globalConfigAccessor: new TestGlobalConfigAccessor(),
+ }),
+ ValueContext.EmptyContext(),
+ );
+ const project = root.commands.find((command) => command.name() === "project")!;
+ // `help` is Commander's own, not one of ours.
+ return project.commands.map((command) => command.name()).filter((name) => name !== "help");
+}
+
+describe("project menu", () => {
+ test("lists every project subcommand", async () => {
+ const r = renderScreen("/agentcore/project");
+
+ await waitForText(r.lastFrame, "manage an AgentCore project");
+ const frame = r.lastFrame()!;
+ for (const command of projectSubcommands()) {
+ expect(frame).toContain(command);
+ }
+ r.unmount();
+ });
+
+ test("is reachable from the root menu", async () => {
+ const r = renderScreen("/agentcore");
+
+ await waitForText(r.lastFrame, "manage an AgentCore project");
+ await r.write("project");
+ await waitForText(r.lastFrame, "❯ project");
+ await r.press("return");
+
+ await waitForText(r.lastFrame, "agentcore → project");
+ expect(r.lastFrame()).toContain("create");
+ r.unmount();
+ });
+
+ test("esc returns to the root menu", async () => {
+ const r = renderScreen("/agentcore/project");
+
+ await waitForText(r.lastFrame, "agentcore → project");
+ await r.press("escape");
+
+ await waitForText(r.lastFrame, "the platform for production AI agents");
+ r.unmount();
+ });
+});
+
+describe("project subcommands without a screen", () => {
+ // renderTuiAt rather than renderScreen: ink-testing-library exposes no
+ // waitUntilExit, so it cannot observe the rejection under test.
+ //
+ // Reading the cases off the router also guards Root's hand-written
+ // PROJECT_COMMANDS: an unrouted subcommand hits the catch-all, which resolves
+ // instead of rejecting. Frames can't detect that — the catch-all exits before
+ // painting, so it and this screen both render empty.
+ test.each(projectSubcommands())(
+ "%s tears down the TUI with NotImplementedError",
+ async (command) => {
+ const { streams } = ttyTestIO();
+
+ const rendering = renderTuiAt(
+ `/agentcore/project/${command}`,
+ ValueContext.EmptyContext(),
+ new TestCoreClient(),
+ streams.io,
+ );
+
+ await expect(rendering).rejects.toThrow(NotImplementedError);
+ await expect(rendering).rejects.toThrow(`'agentcore project ${command}'`);
+ },
+ );
+
+ test("the error names the command to run instead", async () => {
+ const { streams } = ttyTestIO();
+
+ const caught: unknown = await renderTuiAt(
+ "/agentcore/project/deploy",
+ ValueContext.EmptyContext(),
+ new TestCoreClient(),
+ streams.io,
+ ).then(
+ () => undefined,
+ (error: unknown) => error,
+ );
+
+ expect(caught).toBeInstanceOf(NotImplementedError);
+ const error = caught as NotImplementedError;
+ expect(error.message).toContain("agentcore project deploy --help");
+ // Surfaces as a plain CLI failure, not a crash.
+ expect(error.exitCode).toBe(1);
+ });
+});
+
+describe("agentcore project (no subcommand)", () => {
+ // Exercises the real CLI entrypoint; the screen tests mount a path directly
+ // and so never caught the missing default handler.
+ //
+ // Asserts renderTui's TTY guard rather than a rendered frame: Ink only writes
+ // frames incrementally when interactive (`!isInCi && isTTY`), so asserting on
+ // frames here would pass locally and time out under CI. Reaching the guard at
+ // all proves the group routed to the TUI — Commander help neither throws nor
+ // touches stderr.
+ test("routes to the TUI rather than printing Commander help", async () => {
+ const io = testIO();
+ const root = createRootHandler(new TestCoreClient(), {
+ io: io.io,
+ logger: createSilentLogger(),
+ globalConfigAccessor: new TestGlobalConfigAccessor(),
+ });
+
+ const caught: unknown = await root.route(["node", "agentcore", "project"]).then(
+ () => undefined,
+ (error: unknown) => error,
+ );
+
+ expect(caught).toBeInstanceOf(InvalidEnvironmentError);
+ expect((caught as InvalidEnvironmentError).exitCode).toBe(ExitCode.USAGE);
+ expect(io.stdout()).toBe("");
+ });
+
+ test("prints help instead of the TUI under --json", async () => {
+ const io = testIO();
+ const root = createRootHandler(new TestCoreClient(), {
+ io: io.io,
+ logger: createSilentLogger(),
+ globalConfigAccessor: new TestGlobalConfigAccessor(),
+ });
+
+ await root.route(["node", "agentcore", "project", "--json"]);
+
+ expect(io.stdout()).toContain("Usage:");
+ expect(io.stdout()).toContain("create");
+ });
+});

src/handlers/project/screen.tsx

@@ -0,0 +1,37 @@
+import { useEffect } from "react";
+import { useApp } from "ink";
+import { RouterScreen } from "../../components/RouterScreen";
+import { NotImplementedError } from "../../errors";
+import type { ScreenProps } from "../types";
+
+export function ProjectScreen(props: ScreenProps) {
+ return <RouterScreen {...props} path={["agentcore", "project"]} />;
+}
+
+export interface ProjectCommandNotImplementedScreenProps extends ScreenProps {
+ // command is the project subcommand the user selected, e.g. "deploy".
+ command: string;
+}
+
+// ProjectCommandNotImplementedScreen is the landing screen for a project
+// subcommand that is listed in the menu but has no screen yet.
+//
+// exit(error) rejects the waitUntilExit() that renderTuiAt awaits, so the TUI
+// tears down and the error takes the normal CLI path. Throwing during render
+// would surface a React stack trace instead.
+export function ProjectCommandNotImplementedScreen({
+ command,
+}: ProjectCommandNotImplementedScreenProps) {
+ const { exit } = useApp();
+
+ useEffect(() => {
+ exit(
+ new NotImplementedError(
+ `'agentcore project ${command}' has no interactive screen yet; ` +
+ `run 'agentcore project ${command} --help' to use it from the command line`,
+ ),
+ );
+ }, [exit, command]);
+
+ return null;
+}

src/testing/index.tsx

@@ -1,6 +1,6 @@
 export { parse, stringify } from "./serialization";
 export { fixtureFactories, fixtureFetch, isRecording, matchGolden, settle } from "./fixtures";
-export { testIO, type TestIO } from "./testIO";
+export { testIO, ttyTestIO, type TestIO, type TtyInput } from "./testIO";
 export { tick, waitFor, WaitForTimeoutError } from "./timing";
 export {
  TestCoreClient,

src/testing/testIO.tsx

@@ -53,3 +53,32 @@ export function testIO({ isTTY = false, stdin: stdinContent }: TestIOOptions = {
  stderr: err.read,
  };
 }
+
+// TtyInput is the writable stdin of a TTY TestIO: tests push raw key sequences
+// into it to drive a mounted TUI.
+export interface TtyInput extends NodeJS.ReadStream {
+ write(chunk: string): boolean;
+}
+
+// ttyTestIO builds a TestIO that Ink accepts as a real terminal: isTTY, the
+// no-op stdin methods Ink calls when it takes over, and a window size (Ink needs
+// columns/rows to lay out frames). For tests that mount the TUI through
+// renderTui/renderTuiAt rather than ink-testing-library.
+export function ttyTestIO(columns = 100, rows = 40): { streams: TestIO; stdin: TtyInput } {
+ const streams = testIO({ isTTY: true });
+ const stdin = streams.io.stdin as TtyInput;
+ stdin.setRawMode = function () {
+ return this;
+ };
+ stdin.ref = function () {
+ return this;
+ };
+ stdin.unref = function () {
+ return this;
+ };
+ Object.defineProperties(streams.io.stdout, {
+ columns: { configurable: true, value: columns },
+ rows: { configurable: true, value: rows },
+ });
+ return { streams, stdin };
+}

src/tui/tui.test.tsx

@@ -7,34 +7,12 @@ import {
  TestCoreClient,
  TestGlobalConfigAccessor,
  testIO,
+ ttyTestIO,
  tick,
  waitFor,
 } from "../testing";
 import { ExitCode } from "../runnable";
 
-interface TtyInput extends NodeJS.ReadStream {
- write(chunk: string): boolean;
-}
-
-function ttyTestIO(): { streams: ReturnType<typeof testIO>; stdin: TtyInput } {
- const streams = testIO({ isTTY: true });
- const stdin = streams.io.stdin as TtyInput;
- stdin.setRawMode = function () {
- return this;
- };
- stdin.ref = function () {
- return this;
- };
- stdin.unref = function () {
- return this;
- };
- Object.defineProperties(streams.io.stdout, {
- columns: { configurable: true, value: 100 },
- rows: { configurable: true, value: 40 },
- });
- return { streams, stdin };
-}
-
 describe("renderJson", () => {
  test("pretty-prints a value as indented JSON to the given writer", () => {
  const lines: string[] = [];

src/components/Root.tsx

@@ -107,9 +107,15 @@ import { GatewayRuleScreen } from "../handlers/gateway/rule/screen.tsx";
 import { GatewayRuleListScreen } from "../handlers/gateway/rule/list/screen.tsx";
 import { GatewayRuleGetScreen } from "../handlers/gateway/rule/get/screen.tsx";
 import { GatewayInvokeScreen } from "../handlers/gateway/invoke/screen.tsx";
+import { ProjectScreen, ProjectCommandNotImplementedScreen } from "../handlers/project/screen.tsx";
 import { RootScreen, HelpScreen } from "../handlers/screen.tsx";
 import type { Context } from "../router";
 
+// PROJECT_COMMANDS are the `agentcore project` subcommands that are listed in
+// the menu but have no screen of their own yet. Each is routed explicitly so
+// selecting it reports "not implemented" error
+const PROJECT_COMMANDS = ["create", "add", "remove", "dev", "deploy", "status", "build"] as const;
+
 export interface RootProps {
  // path is the command path to the executing node (e.g. "/agentcore").
  path: string;
@@ -736,6 +742,16 @@ export function Root({ path, ctx, core, queryClient }: RootProps) {
  path="agentcore/identity/oauth2-credential-provider/get/:name/json"
  element={<Oauth2CredentialProviderGetJsonScreen ctx={ctx} core={core} />}
  />
+ <Route path="agentcore/project" element={<ProjectScreen ctx={ctx} core={core} />} />
+ {PROJECT_COMMANDS.map((command) => (
+ <Route
+ key={command}
+ path={`agentcore/project/${command}`}
+ element={
+ <ProjectCommandNotImplementedScreen ctx={ctx} core={core} command={command} />
+ }
+ />
+ ))}
  <Route path="*" element={<HelpScreen ctx={ctx} core={core} />} />
  </Routes>
  </MemoryRouter>

src/handlers/index.tsx

@@ -50,7 +50,7 @@ export function createRootHandler(core: Core, config: RootHandlerConfig): Router
  root.handler(createGatewayHandler(core, io));
  root.handler(createEvalHandler(core, io));
  root.handler(createConfigHandler());
- root.handler(createProjectHandler({ projectManager: core.projectManager, io }));
+ root.handler(createProjectHandler({ core, io }));
 
  // Invoking with no subcommand launches the interactive TUI.
  root.default(renderTui(core, io));

src/handlers/project/index.ts

@@ -5,6 +5,8 @@ import { ContainerDevRunner } from "../../core/dev/container";
 import { InspectorAssets } from "../../core/dev/inspectorAssets";
 import { startOtelCollector } from "../../core/dev/otel/collector";
 import { withProject } from "../../middleware";
+import { renderTui } from "../../tui";
+import type { Core } from "../types";
 import { createCreateProjectHandler } from "./create";
 import { createRemoveProjectHandler } from "./remove";
 import { createDevProjectHandler } from "./dev";
@@ -16,16 +18,20 @@ import type { ProjectManager } from "./types";
 import { createAddProjectResourceHandler } from "./add";
 
 type ProjectHandlerConfig = {
-projectManager: ProjectManager;
+core: Core;
  io: AppIO;
 };
 
-export function createProjectHandler(config: ProjectHandlerConfig): Router {
+export function createProjectHandler({ core, io }: ProjectHandlerConfig): Router {
+ const projectManager: ProjectManager = core.projectManager;
+ const config = { projectManager, io };
  const project = new Router("project", "manage an AgentCore project");
 
- project.handler(
- createCreateProjectHandler({ projectManager: config.projectManager, io: config.io }),
- );
+ // Without a default, a bare `agentcore project` falls back to Commander's help
+ // and a usage exit code instead of the menu every sibling router opens.
+ project.default(renderTui(core, io));
+
+ project.handler(createCreateProjectHandler({ projectManager, io }));
  project.handler(createAddProjectResourceHandler(config));
  project.handler(
  withProject({ projectManager: config.projectManager })(

src/handlers/project/project.screen.test.tsx

@@ -0,0 +1,158 @@
+import { test, expect, describe, afterEach } from "bun:test";
+import {
+ renderScreen,
+ waitForText,
+ cleanupScreens,
+ createSilentLogger,
+ TestCoreClient,
+ TestGlobalConfigAccessor,
+ testIO,
+ ttyTestIO,
+} from "../../testing";
+import { renderTuiAt } from "../../tui";
+import { InvalidEnvironmentError, NotImplementedError } from "../../errors";
+import { compile, ValueContext } from "../../router";
+import { ExitCode } from "../../runnable";
+import { createRootHandler } from "../index";
+
+afterEach(cleanupScreens);
+
+// projectSubcommands reads the project group's children off the compiled
+// Commander tree, so tests driven by it cover any subcommand added later.
+function projectSubcommands(): string[] {
+ const root = compile(
+ createRootHandler(new TestCoreClient(), {
+ io: testIO().io,
+ logger: createSilentLogger(),
+ globalConfigAccessor: new TestGlobalConfigAccessor(),
+ }),
+ ValueContext.EmptyContext(),
+ );
+ const project = root.commands.find((command) => command.name() === "project")!;
+ // `help` is Commander's own, not one of ours.
+ return project.commands.map((command) => command.name()).filter((name) => name !== "help");
+}
+
+describe("project menu", () => {
+ test("lists every project subcommand", async () => {
+ const r = renderScreen("/agentcore/project");
+
+ await waitForText(r.lastFrame, "manage an AgentCore project");
+ const frame = r.lastFrame()!;
+ for (const command of projectSubcommands()) {
+ expect(frame).toContain(command);
+ }
+ r.unmount();
+ });
+
+ test("is reachable from the root menu", async () => {
+ const r = renderScreen("/agentcore");
+
+ await waitForText(r.lastFrame, "manage an AgentCore project");
+ await r.write("project");
+ await waitForText(r.lastFrame, "❯ project");
+ await r.press("return");
+
+ await waitForText(r.lastFrame, "agentcore → project");
+ expect(r.lastFrame()).toContain("create");
+ r.unmount();
+ });
+
+ test("esc returns to the root menu", async () => {
+ const r = renderScreen("/agentcore/project");
+
+ await waitForText(r.lastFrame, "agentcore → project");
+ await r.press("escape");
+
+ await waitForText(r.lastFrame, "the platform for production AI agents");
+ r.unmount();
+ });
+});
+
+describe("project subcommands without a screen", () => {
+ // renderTuiAt rather than renderScreen: ink-testing-library exposes no
+ // waitUntilExit, so it cannot observe the rejection under test.
+ //
+ // Reading the cases off the router also guards Root's hand-written
+ // PROJECT_COMMANDS: an unrouted subcommand hits the catch-all, which resolves
+ // instead of rejecting. Frames can't detect that — the catch-all exits before
+ // painting, so it and this screen both render empty.
+ test.each(projectSubcommands())(
+ "%s tears down the TUI with NotImplementedError",
+ async (command) => {
+ const { streams } = ttyTestIO();
+
+ const rendering = renderTuiAt(
+ `/agentcore/project/${command}`,
+ ValueContext.EmptyContext(),
+ new TestCoreClient(),
+ streams.io,
+ );
+
+ await expect(rendering).rejects.toThrow(NotImplementedError);
+ await expect(rendering).rejects.toThrow(`'agentcore project ${command}'`);
+ },
+ );
+
+ test("the error names the command to run instead", async () => {
+ const { streams } = ttyTestIO();
+
+ const caught: unknown = await renderTuiAt(
+ "/agentcore/project/deploy",
+ ValueContext.EmptyContext(),
+ new TestCoreClient(),
+ streams.io,
+ ).then(
+ () => undefined,
+ (error: unknown) => error,
+ );
+
+ expect(caught).toBeInstanceOf(NotImplementedError);
+ const error = caught as NotImplementedError;
+ expect(error.message).toContain("agentcore project deploy --help");
+ // Surfaces as a plain CLI failure, not a crash.
+ expect(error.exitCode).toBe(1);
+ });
+});
+
+describe("agentcore project (no subcommand)", () => {
+ // Exercises the real CLI entrypoint; the screen tests mount a path directly
+ // and so never caught the missing default handler.
+ //
+ // Asserts renderTui's TTY guard rather than a rendered frame: Ink only writes
+ // frames incrementally when interactive (`!isInCi && isTTY`), so asserting on
+ // frames here would pass locally and time out under CI. Reaching the guard at
+ // all proves the group routed to the TUI — Commander help neither throws nor
+ // touches stderr.
+ test("routes to the TUI rather than printing Commander help", async () => {
+ const io = testIO();
+ const root = createRootHandler(new TestCoreClient(), {
+ io: io.io,
+ logger: createSilentLogger(),
+ globalConfigAccessor: new TestGlobalConfigAccessor(),
+ });
+
+ const caught: unknown = await root.route(["node", "agentcore", "project"]).then(
+ () => undefined,
+ (error: unknown) => error,
+ );
+
+ expect(caught).toBeInstanceOf(InvalidEnvironmentError);
+ expect((caught as InvalidEnvironmentError).exitCode).toBe(ExitCode.USAGE);
+ expect(io.stdout()).toBe("");
+ });
+
+ test("prints help instead of the TUI under --json", async () => {
+ const io = testIO();
+ const root = createRootHandler(new TestCoreClient(), {
+ io: io.io,
+ logger: createSilentLogger(),
+ globalConfigAccessor: new TestGlobalConfigAccessor(),
+ });
+
+ await root.route(["node", "agentcore", "project", "--json"]);
+
+ expect(io.stdout()).toContain("Usage:");
+ expect(io.stdout()).toContain("create");
+ });
+});

src/handlers/project/screen.tsx

@@ -0,0 +1,37 @@
+import { useEffect } from "react";
+import { useApp } from "ink";
+import { RouterScreen } from "../../components/RouterScreen";
+import { NotImplementedError } from "../../errors";
+import type { ScreenProps } from "../types";
+
+export function ProjectScreen(props: ScreenProps) {
+ return <RouterScreen {...props} path={["agentcore", "project"]} />;
+}
+
+export interface ProjectCommandNotImplementedScreenProps extends ScreenProps {
+ // command is the project subcommand the user selected, e.g. "deploy".
+ command: string;
+}
+
+// ProjectCommandNotImplementedScreen is the landing screen for a project
+// subcommand that is listed in the menu but has no screen yet.
+//
+// exit(error) rejects the waitUntilExit() that renderTuiAt awaits, so the TUI
+// tears down and the error takes the normal CLI path. Throwing during render
+// would surface a React stack trace instead.
+export function ProjectCommandNotImplementedScreen({
+ command,
+}: ProjectCommandNotImplementedScreenProps) {
+ const { exit } = useApp();
+
+ useEffect(() => {
+ exit(
+ new NotImplementedError(
+ `'agentcore project ${command}' has no interactive screen yet; ` +
+ `run 'agentcore project ${command} --help' to use it from the command line`,
+ ),
+ );
+ }, [exit, command]);
+
+ return null;
+}

src/testing/index.tsx

@@ -1,6 +1,6 @@
 export { parse, stringify } from "./serialization";
 export { fixtureFactories, fixtureFetch, isRecording, matchGolden, settle } from "./fixtures";
-export { testIO, type TestIO } from "./testIO";
+export { testIO, ttyTestIO, type TestIO, type TtyInput } from "./testIO";
 export { tick, waitFor, WaitForTimeoutError } from "./timing";
 export {
  TestCoreClient,

src/testing/testIO.tsx

@@ -53,3 +53,32 @@ export function testIO({ isTTY = false, stdin: stdinContent }: TestIOOptions = {
  stderr: err.read,
  };
 }
+
+// TtyInput is the writable stdin of a TTY TestIO: tests push raw key sequences
+// into it to drive a mounted TUI.
+export interface TtyInput extends NodeJS.ReadStream {
+ write(chunk: string): boolean;
+}
+
+// ttyTestIO builds a TestIO that Ink accepts as a real terminal: isTTY, the
+// no-op stdin methods Ink calls when it takes over, and a window size (Ink needs
+// columns/rows to lay out frames). For tests that mount the TUI through
+// renderTui/renderTuiAt rather than ink-testing-library.
+export function ttyTestIO(columns = 100, rows = 40): { streams: TestIO; stdin: TtyInput } {
+ const streams = testIO({ isTTY: true });
+ const stdin = streams.io.stdin as TtyInput;
+ stdin.setRawMode = function () {
+ return this;
+ };
+ stdin.ref = function () {
+ return this;
+ };
+ stdin.unref = function () {
+ return this;
+ };
+ Object.defineProperties(streams.io.stdout, {
+ columns: { configurable: true, value: columns },
+ rows: { configurable: true, value: rows },
+ });
+ return { streams, stdin };
+}

src/tui/tui.test.tsx

@@ -7,34 +7,12 @@ import {
  TestCoreClient,
  TestGlobalConfigAccessor,
  testIO,
+ ttyTestIO,
  tick,
  waitFor,
 } from "../testing";
 import { ExitCode } from "../runnable";
 
-interface TtyInput extends NodeJS.ReadStream {
- write(chunk: string): boolean;
-}
-
-function ttyTestIO(): { streams: ReturnType<typeof testIO>; stdin: TtyInput } {
- const streams = testIO({ isTTY: true });
- const stdin = streams.io.stdin as TtyInput;
- stdin.setRawMode = function () {
- return this;
- };
- stdin.ref = function () {
- return this;
- };
- stdin.unref = function () {
- return this;
- };
- Object.defineProperties(streams.io.stdout, {
- columns: { configurable: true, value: 100 },
- rows: { configurable: true, value: 40 },
- });
- return { streams, stdin };
-}
-
 describe("renderJson", () => {
  test("pretty-prints a value as indented JSON to the given writer", () => {
  const lines: string[] = [];

src/components/Root.tsx

@@ -107,9 +107,15 @@ import { GatewayRuleScreen } from "../handlers/gateway/rule/screen.tsx";
 import { GatewayRuleListScreen } from "../handlers/gateway/rule/list/screen.tsx";
 import { GatewayRuleGetScreen } from "../handlers/gateway/rule/get/screen.tsx";
 import { GatewayInvokeScreen } from "../handlers/gateway/invoke/screen.tsx";
+import { ProjectScreen, ProjectCommandNotImplementedScreen } from "../handlers/project/screen.tsx";
 import { RootScreen, HelpScreen } from "../handlers/screen.tsx";
 import type { Context } from "../router";
 
+// PROJECT_COMMANDS are the `agentcore project` subcommands that are listed in
+// the menu but have no screen of their own yet. Each is routed explicitly so
+// selecting it reports "not implemented" error
+const PROJECT_COMMANDS = ["create", "add", "remove", "dev", "deploy", "status", "build"] as const;
+
 export interface RootProps {
  // path is the command path to the executing node (e.g. "/agentcore").
  path: string;
@@ -736,6 +742,16 @@ export function Root({ path, ctx, core, queryClient }: RootProps) {
  path="agentcore/identity/oauth2-credential-provider/get/:name/json"
  element={<Oauth2CredentialProviderGetJsonScreen ctx={ctx} core={core} />}
  />
+ <Route path="agentcore/project" element={<ProjectScreen ctx={ctx} core={core} />} />
+ {PROJECT_COMMANDS.map((command) => (
+ <Route
+ key={command}
+ path={`agentcore/project/${command}`}
+ element={
+ <ProjectCommandNotImplementedScreen ctx={ctx} core={core} command={command} />
+ }
+ />
+ ))}
  <Route path="*" element={<HelpScreen ctx={ctx} core={core} />} />
  </Routes>
  </MemoryRouter>

src/handlers/index.tsx

@@ -50,7 +50,7 @@ export function createRootHandler(core: Core, config: RootHandlerConfig): Router
  root.handler(createGatewayHandler(core, io));
  root.handler(createEvalHandler(core, io));
  root.handler(createConfigHandler());
- root.handler(createProjectHandler({ projectManager: core.projectManager, io }));
+ root.handler(createProjectHandler({ core, io }));
 
  // Invoking with no subcommand launches the interactive TUI.
  root.default(renderTui(core, io));

src/handlers/project/index.ts

@@ -5,6 +5,8 @@ import { ContainerDevRunner } from "../../core/dev/container";
 import { InspectorAssets } from "../../core/dev/inspectorAssets";
 import { startOtelCollector } from "../../core/dev/otel/collector";
 import { withProject } from "../../middleware";
+import { renderTui } from "../../tui";
+import type { Core } from "../types";
 import { createCreateProjectHandler } from "./create";
 import { createRemoveProjectHandler } from "./remove";
 import { createDevProjectHandler } from "./dev";
@@ -16,16 +18,20 @@ import type { ProjectManager } from "./types";
 import { createAddProjectResourceHandler } from "./add";
 
 type ProjectHandlerConfig = {
-projectManager: ProjectManager;
+core: Core;
  io: AppIO;
 };
 
-export function createProjectHandler(config: ProjectHandlerConfig): Router {
+export function createProjectHandler({ core, io }: ProjectHandlerConfig): Router {
+ const projectManager: ProjectManager = core.projectManager;
+ const config = { projectManager, io };
  const project = new Router("project", "manage an AgentCore project");
 
- project.handler(
- createCreateProjectHandler({ projectManager: config.projectManager, io: config.io }),
- );
+ // Without a default, a bare `agentcore project` falls back to Commander's help
+ // and a usage exit code instead of the menu every sibling router opens.
+ project.default(renderTui(core, io));
+
+ project.handler(createCreateProjectHandler({ projectManager, io }));
  project.handler(createAddProjectResourceHandler(config));
  project.handler(
  withProject({ projectManager: config.projectManager })(

src/handlers/project/project.screen.test.tsx

@@ -0,0 +1,158 @@
+import { test, expect, describe, afterEach } from "bun:test";
+import {
+ renderScreen,
+ waitForText,
+ cleanupScreens,
+ createSilentLogger,
+ TestCoreClient,
+ TestGlobalConfigAccessor,
+ testIO,
+ ttyTestIO,
+} from "../../testing";
+import { renderTuiAt } from "../../tui";
+import { InvalidEnvironmentError, NotImplementedError } from "../../errors";
+import { compile, ValueContext } from "../../router";
+import { ExitCode } from "../../runnable";
+import { createRootHandler } from "../index";
+
+afterEach(cleanupScreens);
+
+// projectSubcommands reads the project group's children off the compiled
+// Commander tree, so tests driven by it cover any subcommand added later.
+function projectSubcommands(): string[] {
+ const root = compile(
+ createRootHandler(new TestCoreClient(), {
+ io: testIO().io,
+ logger: createSilentLogger(),
+ globalConfigAccessor: new TestGlobalConfigAccessor(),
+ }),
+ ValueContext.EmptyContext(),
+ );
+ const project = root.commands.find((command) => command.name() === "project")!;
+ // `help` is Commander's own, not one of ours.
+ return project.commands.map((command) => command.name()).filter((name) => name !== "help");
+}
+
+describe("project menu", () => {
+ test("lists every project subcommand", async () => {
+ const r = renderScreen("/agentcore/project");
+
+ await waitForText(r.lastFrame, "manage an AgentCore project");
+ const frame = r.lastFrame()!;
+ for (const command of projectSubcommands()) {
+ expect(frame).toContain(command);
+ }
+ r.unmount();
+ });
+
+ test("is reachable from the root menu", async () => {
+ const r = renderScreen("/agentcore");
+
+ await waitForText(r.lastFrame, "manage an AgentCore project");
+ await r.write("project");
+ await waitForText(r.lastFrame, "❯ project");
+ await r.press("return");
+
+ await waitForText(r.lastFrame, "agentcore → project");
+ expect(r.lastFrame()).toContain("create");
+ r.unmount();
+ });
+
+ test("esc returns to the root menu", async () => {
+ const r = renderScreen("/agentcore/project");
+
+ await waitForText(r.lastFrame, "agentcore → project");
+ await r.press("escape");
+
+ await waitForText(r.lastFrame, "the platform for production AI agents");
+ r.unmount();
+ });
+});
+
+describe("project subcommands without a screen", () => {
+ // renderTuiAt rather than renderScreen: ink-testing-library exposes no
+ // waitUntilExit, so it cannot observe the rejection under test.
+ //
+ // Reading the cases off the router also guards Root's hand-written
+ // PROJECT_COMMANDS: an unrouted subcommand hits the catch-all, which resolves
+ // instead of rejecting. Frames can't detect that — the catch-all exits before
+ // painting, so it and this screen both render empty.
+ test.each(projectSubcommands())(
+ "%s tears down the TUI with NotImplementedError",
+ async (command) => {
+ const { streams } = ttyTestIO();
+
+ const rendering = renderTuiAt(
+ `/agentcore/project/${command}`,
+ ValueContext.EmptyContext(),
+ new TestCoreClient(),
+ streams.io,
+ );
+
+ await expect(rendering).rejects.toThrow(NotImplementedError);
+ await expect(rendering).rejects.toThrow(`'agentcore project ${command}'`);
+ },
+ );
+
+ test("the error names the command to run instead", async () => {
+ const { streams } = ttyTestIO();
+
+ const caught: unknown = await renderTuiAt(
+ "/agentcore/project/deploy",
+ ValueContext.EmptyContext(),
+ new TestCoreClient(),
+ streams.io,
+ ).then(
+ () => undefined,
+ (error: unknown) => error,
+ );
+
+ expect(caught).toBeInstanceOf(NotImplementedError);
+ const error = caught as NotImplementedError;
+ expect(error.message).toContain("agentcore project deploy --help");
+ // Surfaces as a plain CLI failure, not a crash.
+ expect(error.exitCode).toBe(1);
+ });
+});
+
+describe("agentcore project (no subcommand)", () => {
+ // Exercises the real CLI entrypoint; the screen tests mount a path directly
+ // and so never caught the missing default handler.
+ //
+ // Asserts renderTui's TTY guard rather than a rendered frame: Ink only writes
+ // frames incrementally when interactive (`!isInCi && isTTY`), so asserting on
+ // frames here would pass locally and time out under CI. Reaching the guard at
+ // all proves the group routed to the TUI — Commander help neither throws nor
+ // touches stderr.
+ test("routes to the TUI rather than printing Commander help", async () => {
+ const io = testIO();
+ const root = createRootHandler(new TestCoreClient(), {
+ io: io.io,
+ logger: createSilentLogger(),
+ globalConfigAccessor: new TestGlobalConfigAccessor(),
+ });
+
+ const caught: unknown = await root.route(["node", "agentcore", "project"]).then(
+ () => undefined,
+ (error: unknown) => error,
+ );
+
+ expect(caught).toBeInstanceOf(InvalidEnvironmentError);
+ expect((caught as InvalidEnvironmentError).exitCode).toBe(ExitCode.USAGE);
+ expect(io.stdout()).toBe("");
+ });
+
+ test("prints help instead of the TUI under --json", async () => {
+ const io = testIO();
+ const root = createRootHandler(new TestCoreClient(), {
+ io: io.io,
+ logger: createSilentLogger(),
+ globalConfigAccessor: new TestGlobalConfigAccessor(),
+ });
+
+ await root.route(["node", "agentcore", "project", "--json"]);
+
+ expect(io.stdout()).toContain("Usage:");
+ expect(io.stdout()).toContain("create");
+ });
+});

src/handlers/project/screen.tsx

@@ -0,0 +1,37 @@
+import { useEffect } from "react";
+import { useApp } from "ink";
+import { RouterScreen } from "../../components/RouterScreen";
+import { NotImplementedError } from "../../errors";
+import type { ScreenProps } from "../types";
+
+export function ProjectScreen(props: ScreenProps) {
+ return <RouterScreen {...props} path={["agentcore", "project"]} />;
+}
+
+export interface ProjectCommandNotImplementedScreenProps extends ScreenProps {
+ // command is the project subcommand the user selected, e.g. "deploy".
+ command: string;
+}
+
+// ProjectCommandNotImplementedScreen is the landing screen for a project
+// subcommand that is listed in the menu but has no screen yet.
+//
+// exit(error) rejects the waitUntilExit() that renderTuiAt awaits, so the TUI
+// tears down and the error takes the normal CLI path. Throwing during render
+// would surface a React stack trace instead.
+export function ProjectCommandNotImplementedScreen({
+ command,
+}: ProjectCommandNotImplementedScreenProps) {
+ const { exit } = useApp();
+
+ useEffect(() => {
+ exit(
+ new NotImplementedError(
+ `'agentcore project ${command}' has no interactive screen yet; ` +
+ `run 'agentcore project ${command} --help' to use it from the command line`,
+ ),
+ );
+ }, [exit, command]);
+
+ return null;
+}

src/testing/index.tsx

@@ -1,6 +1,6 @@
 export { parse, stringify } from "./serialization";
 export { fixtureFactories, fixtureFetch, isRecording, matchGolden, settle } from "./fixtures";
-export { testIO, type TestIO } from "./testIO";
+export { testIO, ttyTestIO, type TestIO, type TtyInput } from "./testIO";
 export { tick, waitFor, WaitForTimeoutError } from "./timing";
 export {
  TestCoreClient,

src/testing/testIO.tsx

@@ -53,3 +53,32 @@ export function testIO({ isTTY = false, stdin: stdinContent }: TestIOOptions = {
  stderr: err.read,
  };
 }
+
+// TtyInput is the writable stdin of a TTY TestIO: tests push raw key sequences
+// into it to drive a mounted TUI.
+export interface TtyInput extends NodeJS.ReadStream {
+ write(chunk: string): boolean;
+}
+
+// ttyTestIO builds a TestIO that Ink accepts as a real terminal: isTTY, the
+// no-op stdin methods Ink calls when it takes over, and a window size (Ink needs
+// columns/rows to lay out frames). For tests that mount the TUI through
+// renderTui/renderTuiAt rather than ink-testing-library.
+export function ttyTestIO(columns = 100, rows = 40): { streams: TestIO; stdin: TtyInput } {
+ const streams = testIO({ isTTY: true });
+ const stdin = streams.io.stdin as TtyInput;
+ stdin.setRawMode = function () {
+ return this;
+ };
+ stdin.ref = function () {
+ return this;
+ };
+ stdin.unref = function () {
+ return this;
+ };
+ Object.defineProperties(streams.io.stdout, {
+ columns: { configurable: true, value: columns },
+ rows: { configurable: true, value: rows },
+ });
+ return { streams, stdin };
+}

src/tui/tui.test.tsx

@@ -7,34 +7,12 @@ import {
  TestCoreClient,
  TestGlobalConfigAccessor,
  testIO,
+ ttyTestIO,
  tick,
  waitFor,
 } from "../testing";
 import { ExitCode } from "../runnable";
 
-interface TtyInput extends NodeJS.ReadStream {
- write(chunk: string): boolean;
-}
-
-function ttyTestIO(): { streams: ReturnType<typeof testIO>; stdin: TtyInput } {
- const streams = testIO({ isTTY: true });
- const stdin = streams.io.stdin as TtyInput;
- stdin.setRawMode = function () {
- return this;
- };
- stdin.ref = function () {
- return this;
- };
- stdin.unref = function () {
- return this;
- };
- Object.defineProperties(streams.io.stdout, {
- columns: { configurable: true, value: 100 },
- rows: { configurable: true, value: 40 },
- });
- return { streams, stdin };
-}
-
 describe("renderJson", () => {
  test("pretty-prints a value as indented JSON to the given writer", () => {
  const lines: string[] = [];

src/components/Root.tsx

@@ -107,9 +107,15 @@ import { GatewayRuleScreen } from "../handlers/gateway/rule/screen.tsx";
 import { GatewayRuleListScreen } from "../handlers/gateway/rule/list/screen.tsx";
 import { GatewayRuleGetScreen } from "../handlers/gateway/rule/get/screen.tsx";
 import { GatewayInvokeScreen } from "../handlers/gateway/invoke/screen.tsx";
+import { ProjectScreen, ProjectCommandNotImplementedScreen } from "../handlers/project/screen.tsx";
 import { RootScreen, HelpScreen } from "../handlers/screen.tsx";
 import type { Context } from "../router";
 
+// PROJECT_COMMANDS are the `agentcore project` subcommands that are listed in
+// the menu but have no screen of their own yet. Each is routed explicitly so
+// selecting it reports "not implemented" error
+const PROJECT_COMMANDS = ["create", "add", "remove", "dev", "deploy", "status", "build"] as const;
+
 export interface RootProps {
  // path is the command path to the executing node (e.g. "/agentcore").
  path: string;
@@ -736,6 +742,16 @@ export function Root({ path, ctx, core, queryClient }: RootProps) {
  path="agentcore/identity/oauth2-credential-provider/get/:name/json"
  element={<Oauth2CredentialProviderGetJsonScreen ctx={ctx} core={core} />}
  />
+ <Route path="agentcore/project" element={<ProjectScreen ctx={ctx} core={core} />} />
+ {PROJECT_COMMANDS.map((command) => (
+ <Route
+ key={command}
+ path={`agentcore/project/${command}`}
+ element={
+ <ProjectCommandNotImplementedScreen ctx={ctx} core={core} command={command} />
+ }
+ />
+ ))}
  <Route path="*" element={<HelpScreen ctx={ctx} core={core} />} />
  </Routes>
  </MemoryRouter>

src/handlers/index.tsx

@@ -50,7 +50,7 @@ export function createRootHandler(core: Core, config: RootHandlerConfig): Router
  root.handler(createGatewayHandler(core, io));
  root.handler(createEvalHandler(core, io));
  root.handler(createConfigHandler());
- root.handler(createProjectHandler({ projectManager: core.projectManager, io }));
+ root.handler(createProjectHandler({ core, io }));
 
  // Invoking with no subcommand launches the interactive TUI.
  root.default(renderTui(core, io));

src/handlers/project/index.ts

@@ -5,6 +5,8 @@ import { ContainerDevRunner } from "../../core/dev/container";
 import { InspectorAssets } from "../../core/dev/inspectorAssets";
 import { startOtelCollector } from "../../core/dev/otel/collector";
 import { withProject } from "../../middleware";
+import { renderTui } from "../../tui";
+import type { Core } from "../types";
 import { createCreateProjectHandler } from "./create";
 import { createRemoveProjectHandler } from "./remove";
 import { createDevProjectHandler } from "./dev";
@@ -16,16 +18,20 @@ import type { ProjectManager } from "./types";
 import { createAddProjectResourceHandler } from "./add";
 
 type ProjectHandlerConfig = {
-projectManager: ProjectManager;
+core: Core;
  io: AppIO;
 };
 
-export function createProjectHandler(config: ProjectHandlerConfig): Router {
+export function createProjectHandler({ core, io }: ProjectHandlerConfig): Router {
+ const projectManager: ProjectManager = core.projectManager;
+ const config = { projectManager, io };
  const project = new Router("project", "manage an AgentCore project");
 
- project.handler(
- createCreateProjectHandler({ projectManager: config.projectManager, io: config.io }),
- );
+ // Without a default, a bare `agentcore project` falls back to Commander's help
+ // and a usage exit code instead of the menu every sibling router opens.
+ project.default(renderTui(core, io));
+
+ project.handler(createCreateProjectHandler({ projectManager, io }));
  project.handler(createAddProjectResourceHandler(config));
  project.handler(
  withProject({ projectManager: config.projectManager })(

src/handlers/project/project.screen.test.tsx

@@ -0,0 +1,158 @@
+import { test, expect, describe, afterEach } from "bun:test";
+import {
+ renderScreen,
+ waitForText,
+ cleanupScreens,
+ createSilentLogger,
+ TestCoreClient,
+ TestGlobalConfigAccessor,
+ testIO,
+ ttyTestIO,
+} from "../../testing";
+import { renderTuiAt } from "../../tui";
+import { InvalidEnvironmentError, NotImplementedError } from "../../errors";
+import { compile, ValueContext } from "../../router";
+import { ExitCode } from "../../runnable";
+import { createRootHandler } from "../index";
+
+afterEach(cleanupScreens);
+
+// projectSubcommands reads the project group's children off the compiled
+// Commander tree, so tests driven by it cover any subcommand added later.
+function projectSubcommands(): string[] {
+ const root = compile(
+ createRootHandler(new TestCoreClient(), {
+ io: testIO().io,
+ logger: createSilentLogger(),
+ globalConfigAccessor: new TestGlobalConfigAccessor(),
+ }),
+ ValueContext.EmptyContext(),
+ );
+ const project = root.commands.find((command) => command.name() === "project")!;
+ // `help` is Commander's own, not one of ours.
+ return project.commands.map((command) => command.name()).filter((name) => name !== "help");
+}
+
+describe("project menu", () => {
+ test("lists every project subcommand", async () => {
+ const r = renderScreen("/agentcore/project");
+
+ await waitForText(r.lastFrame, "manage an AgentCore project");
+ const frame = r.lastFrame()!;
+ for (const command of projectSubcommands()) {
+ expect(frame).toContain(command);
+ }
+ r.unmount();
+ });
+
+ test("is reachable from the root menu", async () => {
+ const r = renderScreen("/agentcore");
+
+ await waitForText(r.lastFrame, "manage an AgentCore project");
+ await r.write("project");
+ await waitForText(r.lastFrame, "❯ project");
+ await r.press("return");
+
+ await waitForText(r.lastFrame, "agentcore → project");
+ expect(r.lastFrame()).toContain("create");
+ r.unmount();
+ });
+
+ test("esc returns to the root menu", async () => {
+ const r = renderScreen("/agentcore/project");
+
+ await waitForText(r.lastFrame, "agentcore → project");
+ await r.press("escape");
+
+ await waitForText(r.lastFrame, "the platform for production AI agents");
+ r.unmount();
+ });
+});
+
+describe("project subcommands without a screen", () => {
+ // renderTuiAt rather than renderScreen: ink-testing-library exposes no
+ // waitUntilExit, so it cannot observe the rejection under test.
+ //
+ // Reading the cases off the router also guards Root's hand-written
+ // PROJECT_COMMANDS: an unrouted subcommand hits the catch-all, which resolves
+ // instead of rejecting. Frames can't detect that — the catch-all exits before
+ // painting, so it and this screen both render empty.
+ test.each(projectSubcommands())(
+ "%s tears down the TUI with NotImplementedError",
+ async (command) => {
+ const { streams } = ttyTestIO();
+
+ const rendering = renderTuiAt(
+ `/agentcore/project/${command}`,
+ ValueContext.EmptyContext(),
+ new TestCoreClient(),
+ streams.io,
+ );
+
+ await expect(rendering).rejects.toThrow(NotImplementedError);
+ await expect(rendering).rejects.toThrow(`'agentcore project ${command}'`);
+ },
+ );
+
+ test("the error names the command to run instead", async () => {
+ const { streams } = ttyTestIO();
+
+ const caught: unknown = await renderTuiAt(
+ "/agentcore/project/deploy",
+ ValueContext.EmptyContext(),
+ new TestCoreClient(),
+ streams.io,
+ ).then(
+ () => undefined,
+ (error: unknown) => error,
+ );
+
+ expect(caught).toBeInstanceOf(NotImplementedError);
+ const error = caught as NotImplementedError;
+ expect(error.message).toContain("agentcore project deploy --help");
+ // Surfaces as a plain CLI failure, not a crash.
+ expect(error.exitCode).toBe(1);
+ });
+});
+
+describe("agentcore project (no subcommand)", () => {
+ // Exercises the real CLI entrypoint; the screen tests mount a path directly
+ // and so never caught the missing default handler.
+ //
+ // Asserts renderTui's TTY guard rather than a rendered frame: Ink only writes
+ // frames incrementally when interactive (`!isInCi && isTTY`), so asserting on
+ // frames here would pass locally and time out under CI. Reaching the guard at
+ // all proves the group routed to the TUI — Commander help neither throws nor
+ // touches stderr.
+ test("routes to the TUI rather than printing Commander help", async () => {
+ const io = testIO();
+ const root = createRootHandler(new TestCoreClient(), {
+ io: io.io,
+ logger: createSilentLogger(),
+ globalConfigAccessor: new TestGlobalConfigAccessor(),
+ });
+
+ const caught: unknown = await root.route(["node", "agentcore", "project"]).then(
+ () => undefined,
+ (error: unknown) => error,
+ );
+
+ expect(caught).toBeInstanceOf(InvalidEnvironmentError);
+ expect((caught as InvalidEnvironmentError).exitCode).toBe(ExitCode.USAGE);
+ expect(io.stdout()).toBe("");
+ });
+
+ test("prints help instead of the TUI under --json", async () => {
+ const io = testIO();
+ const root = createRootHandler(new TestCoreClient(), {
+ io: io.io,
+ logger: createSilentLogger(),
+ globalConfigAccessor: new TestGlobalConfigAccessor(),
+ });
+
+ await root.route(["node", "agentcore", "project", "--json"]);
+
+ expect(io.stdout()).toContain("Usage:");
+ expect(io.stdout()).toContain("create");
+ });
+});

src/handlers/project/screen.tsx

@@ -0,0 +1,37 @@
+import { useEffect } from "react";
+import { useApp } from "ink";
+import { RouterScreen } from "../../components/RouterScreen";
+import { NotImplementedError } from "../../errors";
+import type { ScreenProps } from "../types";
+
+export function ProjectScreen(props: ScreenProps) {
+ return <RouterScreen {...props} path={["agentcore", "project"]} />;
+}
+
+export interface ProjectCommandNotImplementedScreenProps extends ScreenProps {
+ // command is the project subcommand the user selected, e.g. "deploy".
+ command: string;
+}
+
+// ProjectCommandNotImplementedScreen is the landing screen for a project
+// subcommand that is listed in the menu but has no screen yet.
+//
+// exit(error) rejects the waitUntilExit() that renderTuiAt awaits, so the TUI
+// tears down and the error takes the normal CLI path. Throwing during render
+// would surface a React stack trace instead.
+export function ProjectCommandNotImplementedScreen({
+ command,
+}: ProjectCommandNotImplementedScreenProps) {
+ const { exit } = useApp();
+
+ useEffect(() => {
+ exit(
+ new NotImplementedError(
+ `'agentcore project ${command}' has no interactive screen yet; ` +
+ `run 'agentcore project ${command} --help' to use it from the command line`,
+ ),
+ );
+ }, [exit, command]);
+
+ return null;
+}

src/testing/index.tsx

@@ -1,6 +1,6 @@
 export { parse, stringify } from "./serialization";
 export { fixtureFactories, fixtureFetch, isRecording, matchGolden, settle } from "./fixtures";
-export { testIO, type TestIO } from "./testIO";
+export { testIO, ttyTestIO, type TestIO, type TtyInput } from "./testIO";
 export { tick, waitFor, WaitForTimeoutError } from "./timing";
 export {
  TestCoreClient,

src/testing/testIO.tsx

@@ -53,3 +53,32 @@ export function testIO({ isTTY = false, stdin: stdinContent }: TestIOOptions = {
  stderr: err.read,
  };
 }
+
+// TtyInput is the writable stdin of a TTY TestIO: tests push raw key sequences
+// into it to drive a mounted TUI.
+export interface TtyInput extends NodeJS.ReadStream {
+ write(chunk: string): boolean;
+}
+
+// ttyTestIO builds a TestIO that Ink accepts as a real terminal: isTTY, the
+// no-op stdin methods Ink calls when it takes over, and a window size (Ink needs
+// columns/rows to lay out frames). For tests that mount the TUI through
+// renderTui/renderTuiAt rather than ink-testing-library.
+export function ttyTestIO(columns = 100, rows = 40): { streams: TestIO; stdin: TtyInput } {
+ const streams = testIO({ isTTY: true });
+ const stdin = streams.io.stdin as TtyInput;
+ stdin.setRawMode = function () {
+ return this;
+ };
+ stdin.ref = function () {
+ return this;
+ };
+ stdin.unref = function () {
+ return this;
+ };
+ Object.defineProperties(streams.io.stdout, {
+ columns: { configurable: true, value: columns },
+ rows: { configurable: true, value: rows },
+ });
+ return { streams, stdin };
+}

src/tui/tui.test.tsx

@@ -7,34 +7,12 @@ import {
  TestCoreClient,
  TestGlobalConfigAccessor,
  testIO,
+ ttyTestIO,
  tick,
  waitFor,
 } from "../testing";
 import { ExitCode } from "../runnable";
 
-interface TtyInput extends NodeJS.ReadStream {
- write(chunk: string): boolean;
-}
-
-function ttyTestIO(): { streams: ReturnType<typeof testIO>; stdin: TtyInput } {
- const streams = testIO({ isTTY: true });
- const stdin = streams.io.stdin as TtyInput;
- stdin.setRawMode = function () {
- return this;
- };
- stdin.ref = function () {
- return this;
- };
- stdin.unref = function () {
- return this;
- };
- Object.defineProperties(streams.io.stdout, {
- columns: { configurable: true, value: 100 },
- rows: { configurable: true, value: 40 },
- });
- return { streams, stdin };
-}
-
 describe("renderJson", () => {
  test("pretty-prints a value as indented JSON to the given writer", () => {
  const lines: string[] = [];

src/components/Root.tsx

@@ -107,9 +107,15 @@ import { GatewayRuleScreen } from "../handlers/gateway/rule/screen.tsx";
 import { GatewayRuleListScreen } from "../handlers/gateway/rule/list/screen.tsx";
 import { GatewayRuleGetScreen } from "../handlers/gateway/rule/get/screen.tsx";
 import { GatewayInvokeScreen } from "../handlers/gateway/invoke/screen.tsx";
+import { ProjectScreen, ProjectCommandNotImplementedScreen } from "../handlers/project/screen.tsx";
 import { RootScreen, HelpScreen } from "../handlers/screen.tsx";
 import type { Context } from "../router";
 
+// PROJECT_COMMANDS are the `agentcore project` subcommands that are listed in
+// the menu but have no screen of their own yet. Each is routed explicitly so
+// selecting it reports "not implemented" error
+const PROJECT_COMMANDS = ["create", "add", "remove", "dev", "deploy", "status", "build"] as const;
+
 export interface RootProps {
  // path is the command path to the executing node (e.g. "/agentcore").
  path: string;
@@ -736,6 +742,16 @@ export function Root({ path, ctx, core, queryClient }: RootProps) {
  path="agentcore/identity/oauth2-credential-provider/get/:name/json"
  element={<Oauth2CredentialProviderGetJsonScreen ctx={ctx} core={core} />}
  />
+ <Route path="agentcore/project" element={<ProjectScreen ctx={ctx} core={core} />} />
+ {PROJECT_COMMANDS.map((command) => (
+ <Route
+ key={command}
+ path={`agentcore/project/${command}`}
+ element={
+ <ProjectCommandNotImplementedScreen ctx={ctx} core={core} command={command} />
+ }
+ />
+ ))}
  <Route path="*" element={<HelpScreen ctx={ctx} core={core} />} />
  </Routes>
  </MemoryRouter>

src/handlers/index.tsx

@@ -50,7 +50,7 @@ export function createRootHandler(core: Core, config: RootHandlerConfig): Router
  root.handler(createGatewayHandler(core, io));
  root.handler(createEvalHandler(core, io));
  root.handler(createConfigHandler());
- root.handler(createProjectHandler({ projectManager: core.projectManager, io }));
+ root.handler(createProjectHandler({ core, io }));
 
  // Invoking with no subcommand launches the interactive TUI.
  root.default(renderTui(core, io));

src/handlers/project/index.ts

@@ -5,6 +5,8 @@ import { ContainerDevRunner } from "../../core/dev/container";
 import { InspectorAssets } from "../../core/dev/inspectorAssets";
 import { startOtelCollector } from "../../core/dev/otel/collector";
 import { withProject } from "../../middleware";
+import { renderTui } from "../../tui";
+import type { Core } from "../types";
 import { createCreateProjectHandler } from "./create";
 import { createRemoveProjectHandler } from "./remove";
 import { createDevProjectHandler } from "./dev";
@@ -16,16 +18,20 @@ import type { ProjectManager } from "./types";
 import { createAddProjectResourceHandler } from "./add";
 
 type ProjectHandlerConfig = {
-projectManager: ProjectManager;
+core: Core;
  io: AppIO;
 };
 
-export function createProjectHandler(config: ProjectHandlerConfig): Router {
+export function createProjectHandler({ core, io }: ProjectHandlerConfig): Router {
+ const projectManager: ProjectManager = core.projectManager;
+ const config = { projectManager, io };
  const project = new Router("project", "manage an AgentCore project");
 
- project.handler(
- createCreateProjectHandler({ projectManager: config.projectManager, io: config.io }),
- );
+ // Without a default, a bare `agentcore project` falls back to Commander's help
+ // and a usage exit code instead of the menu every sibling router opens.
+ project.default(renderTui(core, io));
+
+ project.handler(createCreateProjectHandler({ projectManager, io }));
  project.handler(createAddProjectResourceHandler(config));
  project.handler(
  withProject({ projectManager: config.projectManager })(

src/handlers/project/project.screen.test.tsx

@@ -0,0 +1,158 @@
+import { test, expect, describe, afterEach } from "bun:test";
+import {
+ renderScreen,
+ waitForText,
+ cleanupScreens,
+ createSilentLogger,
+ TestCoreClient,
+ TestGlobalConfigAccessor,
+ testIO,
+ ttyTestIO,
+} from "../../testing";
+import { renderTuiAt } from "../../tui";
+import { InvalidEnvironmentError, NotImplementedError } from "../../errors";
+import { compile, ValueContext } from "../../router";
+import { ExitCode } from "../../runnable";
+import { createRootHandler } from "../index";
+
+afterEach(cleanupScreens);
+
+// projectSubcommands reads the project group's children off the compiled
+// Commander tree, so tests driven by it cover any subcommand added later.
+function projectSubcommands(): string[] {
+ const root = compile(
+ createRootHandler(new TestCoreClient(), {
+ io: testIO().io,
+ logger: createSilentLogger(),
+ globalConfigAccessor: new TestGlobalConfigAccessor(),
+ }),
+ ValueContext.EmptyContext(),
+ );
+ const project = root.commands.find((command) => command.name() === "project")!;
+ // `help` is Commander's own, not one of ours.
+ return project.commands.map((command) => command.name()).filter((name) => name !== "help");
+}
+
+describe("project menu", () => {
+ test("lists every project subcommand", async () => {
+ const r = renderScreen("/agentcore/project");
+
+ await waitForText(r.lastFrame, "manage an AgentCore project");
+ const frame = r.lastFrame()!;
+ for (const command of projectSubcommands()) {
+ expect(frame).toContain(command);
+ }
+ r.unmount();
+ });
+
+ test("is reachable from the root menu", async () => {
+ const r = renderScreen("/agentcore");
+
+ await waitForText(r.lastFrame, "manage an AgentCore project");
+ await r.write("project");
+ await waitForText(r.lastFrame, "❯ project");
+ await r.press("return");
+
+ await waitForText(r.lastFrame, "agentcore → project");
+ expect(r.lastFrame()).toContain("create");
+ r.unmount();
+ });
+
+ test("esc returns to the root menu", async () => {
+ const r = renderScreen("/agentcore/project");
+
+ await waitForText(r.lastFrame, "agentcore → project");
+ await r.press("escape");
+
+ await waitForText(r.lastFrame, "the platform for production AI agents");
+ r.unmount();
+ });
+});
+
+describe("project subcommands without a screen", () => {
+ // renderTuiAt rather than renderScreen: ink-testing-library exposes no
+ // waitUntilExit, so it cannot observe the rejection under test.
+ //
+ // Reading the cases off the router also guards Root's hand-written
+ // PROJECT_COMMANDS: an unrouted subcommand hits the catch-all, which resolves
+ // instead of rejecting. Frames can't detect that — the catch-all exits before
+ // painting, so it and this screen both render empty.
+ test.each(projectSubcommands())(
+ "%s tears down the TUI with NotImplementedError",
+ async (command) => {
+ const { streams } = ttyTestIO();
+
+ const rendering = renderTuiAt(
+ `/agentcore/project/${command}`,
+ ValueContext.EmptyContext(),
+ new TestCoreClient(),
+ streams.io,
+ );
+
+ await expect(rendering).rejects.toThrow(NotImplementedError);
+ await expect(rendering).rejects.toThrow(`'agentcore project ${command}'`);
+ },
+ );
+
+ test("the error names the command to run instead", async () => {
+ const { streams } = ttyTestIO();
+
+ const caught: unknown = await renderTuiAt(
+ "/agentcore/project/deploy",
+ ValueContext.EmptyContext(),
+ new TestCoreClient(),
+ streams.io,
+ ).then(
+ () => undefined,
+ (error: unknown) => error,
+ );
+
+ expect(caught).toBeInstanceOf(NotImplementedError);
+ const error = caught as NotImplementedError;
+ expect(error.message).toContain("agentcore project deploy --help");
+ // Surfaces as a plain CLI failure, not a crash.
+ expect(error.exitCode).toBe(1);
+ });
+});
+
+describe("agentcore project (no subcommand)", () => {
+ // Exercises the real CLI entrypoint; the screen tests mount a path directly
+ // and so never caught the missing default handler.
+ //
+ // Asserts renderTui's TTY guard rather than a rendered frame: Ink only writes
+ // frames incrementally when interactive (`!isInCi && isTTY`), so asserting on
+ // frames here would pass locally and time out under CI. Reaching the guard at
+ // all proves the group routed to the TUI — Commander help neither throws nor
+ // touches stderr.
+ test("routes to the TUI rather than printing Commander help", async () => {
+ const io = testIO();
+ const root = createRootHandler(new TestCoreClient(), {
+ io: io.io,
+ logger: createSilentLogger(),
+ globalConfigAccessor: new TestGlobalConfigAccessor(),
+ });
+
+ const caught: unknown = await root.route(["node", "agentcore", "project"]).then(
+ () => undefined,
+ (error: unknown) => error,
+ );
+
+ expect(caught).toBeInstanceOf(InvalidEnvironmentError);
+ expect((caught as InvalidEnvironmentError).exitCode).toBe(ExitCode.USAGE);
+ expect(io.stdout()).toBe("");
+ });
+
+ test("prints help instead of the TUI under --json", async () => {
+ const io = testIO();
+ const root = createRootHandler(new TestCoreClient(), {
+ io: io.io,
+ logger: createSilentLogger(),
+ globalConfigAccessor: new TestGlobalConfigAccessor(),
+ });
+
+ await root.route(["node", "agentcore", "project", "--json"]);
+
+ expect(io.stdout()).toContain("Usage:");
+ expect(io.stdout()).toContain("create");
+ });
+});

src/handlers/project/screen.tsx

@@ -0,0 +1,37 @@
+import { useEffect } from "react";
+import { useApp } from "ink";
+import { RouterScreen } from "../../components/RouterScreen";
+import { NotImplementedError } from "../../errors";
+import type { ScreenProps } from "../types";
+
+export function ProjectScreen(props: ScreenProps) {
+ return <RouterScreen {...props} path={["agentcore", "project"]} />;
+}
+
+export interface ProjectCommandNotImplementedScreenProps extends ScreenProps {
+ // command is the project subcommand the user selected, e.g. "deploy".
+ command: string;
+}
+
+// ProjectCommandNotImplementedScreen is the landing screen for a project
+// subcommand that is listed in the menu but has no screen yet.
+//
+// exit(error) rejects the waitUntilExit() that renderTuiAt awaits, so the TUI
+// tears down and the error takes the normal CLI path. Throwing during render
+// would surface a React stack trace instead.
+export function ProjectCommandNotImplementedScreen({
+ command,
+}: ProjectCommandNotImplementedScreenProps) {
+ const { exit } = useApp();
+
+ useEffect(() => {
+ exit(
+ new NotImplementedError(
+ `'agentcore project ${command}' has no interactive screen yet; ` +
+ `run 'agentcore project ${command} --help' to use it from the command line`,
+ ),
+ );
+ }, [exit, command]);
+
+ return null;
+}

src/testing/index.tsx

@@ -1,6 +1,6 @@
 export { parse, stringify } from "./serialization";
 export { fixtureFactories, fixtureFetch, isRecording, matchGolden, settle } from "./fixtures";
-export { testIO, type TestIO } from "./testIO";
+export { testIO, ttyTestIO, type TestIO, type TtyInput } from "./testIO";
 export { tick, waitFor, WaitForTimeoutError } from "./timing";
 export {
  TestCoreClient,

src/testing/testIO.tsx

@@ -53,3 +53,32 @@ export function testIO({ isTTY = false, stdin: stdinContent }: TestIOOptions = {
  stderr: err.read,
  };
 }
+
+// TtyInput is the writable stdin of a TTY TestIO: tests push raw key sequences
+// into it to drive a mounted TUI.
+export interface TtyInput extends NodeJS.ReadStream {
+ write(chunk: string): boolean;
+}
+
+// ttyTestIO builds a TestIO that Ink accepts as a real terminal: isTTY, the
+// no-op stdin methods Ink calls when it takes over, and a window size (Ink needs
+// columns/rows to lay out frames). For tests that mount the TUI through
+// renderTui/renderTuiAt rather than ink-testing-library.
+export function ttyTestIO(columns = 100, rows = 40): { streams: TestIO; stdin: TtyInput } {
+ const streams = testIO({ isTTY: true });
+ const stdin = streams.io.stdin as TtyInput;
+ stdin.setRawMode = function () {
+ return this;
+ };
+ stdin.ref = function () {
+ return this;
+ };
+ stdin.unref = function () {
+ return this;
+ };
+ Object.defineProperties(streams.io.stdout, {
+ columns: { configurable: true, value: columns },
+ rows: { configurable: true, value: rows },
+ });
+ return { streams, stdin };
+}

src/tui/tui.test.tsx

@@ -7,34 +7,12 @@ import {
  TestCoreClient,
  TestGlobalConfigAccessor,
  testIO,
+ ttyTestIO,
  tick,
  waitFor,
 } from "../testing";
 import { ExitCode } from "../runnable";
 
-interface TtyInput extends NodeJS.ReadStream {
- write(chunk: string): boolean;
-}
-
-function ttyTestIO(): { streams: ReturnType<typeof testIO>; stdin: TtyInput } {
- const streams = testIO({ isTTY: true });
- const stdin = streams.io.stdin as TtyInput;
- stdin.setRawMode = function () {
- return this;
- };
- stdin.ref = function () {
- return this;
- };
- stdin.unref = function () {
- return this;
- };
- Object.defineProperties(streams.io.stdout, {
- columns: { configurable: true, value: 100 },
- rows: { configurable: true, value: 40 },
- });
- return { streams, stdin };
-}
-
 describe("renderJson", () => {
  test("pretty-prints a value as indented JSON to the given writer", () => {
  const lines: string[] = [];

src/components/Root.tsx

@@ -107,9 +107,15 @@ import { GatewayRuleScreen } from "../handlers/gateway/rule/screen.tsx";
 import { GatewayRuleListScreen } from "../handlers/gateway/rule/list/screen.tsx";
 import { GatewayRuleGetScreen } from "../handlers/gateway/rule/get/screen.tsx";
 import { GatewayInvokeScreen } from "../handlers/gateway/invoke/screen.tsx";
+import { ProjectScreen, ProjectCommandNotImplementedScreen } from "../handlers/project/screen.tsx";
 import { RootScreen, HelpScreen } from "../handlers/screen.tsx";
 import type { Context } from "../router";
 
+// PROJECT_COMMANDS are the `agentcore project` subcommands that are listed in
+// the menu but have no screen of their own yet. Each is routed explicitly so
+// selecting it reports "not implemented" error
+const PROJECT_COMMANDS = ["create", "add", "remove", "dev", "deploy", "status", "build"] as const;
+
 export interface RootProps {
  // path is the command path to the executing node (e.g. "/agentcore").
  path: string;
@@ -736,6 +742,16 @@ export function Root({ path, ctx, core, queryClient }: RootProps) {
  path="agentcore/identity/oauth2-credential-provider/get/:name/json"
  element={<Oauth2CredentialProviderGetJsonScreen ctx={ctx} core={core} />}
  />
+ <Route path="agentcore/project" element={<ProjectScreen ctx={ctx} core={core} />} />
+ {PROJECT_COMMANDS.map((command) => (
+ <Route
+ key={command}
+ path={`agentcore/project/${command}`}
+ element={
+ <ProjectCommandNotImplementedScreen ctx={ctx} core={core} command={command} />
+ }
+ />
+ ))}
  <Route path="*" element={<HelpScreen ctx={ctx} core={core} />} />
  </Routes>
  </MemoryRouter>

src/handlers/index.tsx

@@ -50,7 +50,7 @@ export function createRootHandler(core: Core, config: RootHandlerConfig): Router
  root.handler(createGatewayHandler(core, io));
  root.handler(createEvalHandler(core, io));
  root.handler(createConfigHandler());
- root.handler(createProjectHandler({ projectManager: core.projectManager, io }));
+ root.handler(createProjectHandler({ core, io }));
 
  // Invoking with no subcommand launches the interactive TUI.
  root.default(renderTui(core, io));

src/handlers/project/index.ts

@@ -5,6 +5,8 @@ import { ContainerDevRunner } from "../../core/dev/container";
 import { InspectorAssets } from "../../core/dev/inspectorAssets";
 import { startOtelCollector } from "../../core/dev/otel/collector";
 import { withProject } from "../../middleware";
+import { renderTui } from "../../tui";
+import type { Core } from "../types";
 import { createCreateProjectHandler } from "./create";
 import { createRemoveProjectHandler } from "./remove";
 import { createDevProjectHandler } from "./dev";
@@ -16,16 +18,20 @@ import type { ProjectManager } from "./types";
 import { createAddProjectResourceHandler } from "./add";
 
 type ProjectHandlerConfig = {
-projectManager: ProjectManager;
+core: Core;
  io: AppIO;
 };
 
-export function createProjectHandler(config: ProjectHandlerConfig): Router {
+export function createProjectHandler({ core, io }: ProjectHandlerConfig): Router {
+ const projectManager: ProjectManager = core.projectManager;
+ const config = { projectManager, io };
  const project = new Router("project", "manage an AgentCore project");
 
- project.handler(
- createCreateProjectHandler({ projectManager: config.projectManager, io: config.io }),
- );
+ // Without a default, a bare `agentcore project` falls back to Commander's help
+ // and a usage exit code instead of the menu every sibling router opens.
+ project.default(renderTui(core, io));
+
+ project.handler(createCreateProjectHandler({ projectManager, io }));
  project.handler(createAddProjectResourceHandler(config));
  project.handler(
  withProject({ projectManager: config.projectManager })(

src/handlers/project/project.screen.test.tsx

@@ -0,0 +1,158 @@
+import { test, expect, describe, afterEach } from "bun:test";
+import {
+ renderScreen,
+ waitForText,
+ cleanupScreens,
+ createSilentLogger,
+ TestCoreClient,
+ TestGlobalConfigAccessor,
+ testIO,
+ ttyTestIO,
+} from "../../testing";
+import { renderTuiAt } from "../../tui";
+import { InvalidEnvironmentError, NotImplementedError } from "../../errors";
+import { compile, ValueContext } from "../../router";
+import { ExitCode } from "../../runnable";
+import { createRootHandler } from "../index";
+
+afterEach(cleanupScreens);
+
+// projectSubcommands reads the project group's children off the compiled
+// Commander tree, so tests driven by it cover any subcommand added later.
+function projectSubcommands(): string[] {
+ const root = compile(
+ createRootHandler(new TestCoreClient(), {
+ io: testIO().io,
+ logger: createSilentLogger(),
+ globalConfigAccessor: new TestGlobalConfigAccessor(),
+ }),
+ ValueContext.EmptyContext(),
+ );
+ const project = root.commands.find((command) => command.name() === "project")!;
+ // `help` is Commander's own, not one of ours.
+ return project.commands.map((command) => command.name()).filter((name) => name !== "help");
+}
+
+describe("project menu", () => {
+ test("lists every project subcommand", async () => {
+ const r = renderScreen("/agentcore/project");
+
+ await waitForText(r.lastFrame, "manage an AgentCore project");
+ const frame = r.lastFrame()!;
+ for (const command of projectSubcommands()) {
+ expect(frame).toContain(command);
+ }
+ r.unmount();
+ });
+
+ test("is reachable from the root menu", async () => {
+ const r = renderScreen("/agentcore");
+
+ await waitForText(r.lastFrame, "manage an AgentCore project");
+ await r.write("project");
+ await waitForText(r.lastFrame, "❯ project");
+ await r.press("return");
+
+ await waitForText(r.lastFrame, "agentcore → project");
+ expect(r.lastFrame()).toContain("create");
+ r.unmount();
+ });
+
+ test("esc returns to the root menu", async () => {
+ const r = renderScreen("/agentcore/project");
+
+ await waitForText(r.lastFrame, "agentcore → project");
+ await r.press("escape");
+
+ await waitForText(r.lastFrame, "the platform for production AI agents");
+ r.unmount();
+ });
+});
+
+describe("project subcommands without a screen", () => {
+ // renderTuiAt rather than renderScreen: ink-testing-library exposes no
+ // waitUntilExit, so it cannot observe the rejection under test.
+ //
+ // Reading the cases off the router also guards Root's hand-written
+ // PROJECT_COMMANDS: an unrouted subcommand hits the catch-all, which resolves
+ // instead of rejecting. Frames can't detect that — the catch-all exits before
+ // painting, so it and this screen both render empty.
+ test.each(projectSubcommands())(
+ "%s tears down the TUI with NotImplementedError",
+ async (command) => {
+ const { streams } = ttyTestIO();
+
+ const rendering = renderTuiAt(
+ `/agentcore/project/${command}`,
+ ValueContext.EmptyContext(),
+ new TestCoreClient(),
+ streams.io,
+ );
+
+ await expect(rendering).rejects.toThrow(NotImplementedError);
+ await expect(rendering).rejects.toThrow(`'agentcore project ${command}'`);
+ },
+ );
+
+ test("the error names the command to run instead", async () => {
+ const { streams } = ttyTestIO();
+
+ const caught: unknown = await renderTuiAt(
+ "/agentcore/project/deploy",
+ ValueContext.EmptyContext(),
+ new TestCoreClient(),
+ streams.io,
+ ).then(
+ () => undefined,
+ (error: unknown) => error,
+ );
+
+ expect(caught).toBeInstanceOf(NotImplementedError);
+ const error = caught as NotImplementedError;
+ expect(error.message).toContain("agentcore project deploy --help");
+ // Surfaces as a plain CLI failure, not a crash.
+ expect(error.exitCode).toBe(1);
+ });
+});
+
+describe("agentcore project (no subcommand)", () => {
+ // Exercises the real CLI entrypoint; the screen tests mount a path directly
+ // and so never caught the missing default handler.
+ //
+ // Asserts renderTui's TTY guard rather than a rendered frame: Ink only writes
+ // frames incrementally when interactive (`!isInCi && isTTY`), so asserting on
+ // frames here would pass locally and time out under CI. Reaching the guard at
+ // all proves the group routed to the TUI — Commander help neither throws nor
+ // touches stderr.
+ test("routes to the TUI rather than printing Commander help", async () => {
+ const io = testIO();
+ const root = createRootHandler(new TestCoreClient(), {
+ io: io.io,
+ logger: createSilentLogger(),
+ globalConfigAccessor: new TestGlobalConfigAccessor(),
+ });
+
+ const caught: unknown = await root.route(["node", "agentcore", "project"]).then(
+ () => undefined,
+ (error: unknown) => error,
+ );
+
+ expect(caught).toBeInstanceOf(InvalidEnvironmentError);
+ expect((caught as InvalidEnvironmentError).exitCode).toBe(ExitCode.USAGE);
+ expect(io.stdout()).toBe("");
+ });
+
+ test("prints help instead of the TUI under --json", async () => {
+ const io = testIO();
+ const root = createRootHandler(new TestCoreClient(), {
+ io: io.io,
+ logger: createSilentLogger(),
+ globalConfigAccessor: new TestGlobalConfigAccessor(),
+ });
+
+ await root.route(["node", "agentcore", "project", "--json"]);
+
+ expect(io.stdout()).toContain("Usage:");
+ expect(io.stdout()).toContain("create");
+ });
+});

src/handlers/project/screen.tsx

@@ -0,0 +1,37 @@
+import { useEffect } from "react";
+import { useApp } from "ink";
+import { RouterScreen } from "../../components/RouterScreen";
+import { NotImplementedError } from "../../errors";
+import type { ScreenProps } from "../types";
+
+export function ProjectScreen(props: ScreenProps) {
+ return <RouterScreen {...props} path={["agentcore", "project"]} />;
+}
+
+export interface ProjectCommandNotImplementedScreenProps extends ScreenProps {
+ // command is the project subcommand the user selected, e.g. "deploy".
+ command: string;
+}
+
+// ProjectCommandNotImplementedScreen is the landing screen for a project
+// subcommand that is listed in the menu but has no screen yet.
+//
+// exit(error) rejects the waitUntilExit() that renderTuiAt awaits, so the TUI
+// tears down and the error takes the normal CLI path. Throwing during render
+// would surface a React stack trace instead.
+export function ProjectCommandNotImplementedScreen({
+ command,
+}: ProjectCommandNotImplementedScreenProps) {
+ const { exit } = useApp();
+
+ useEffect(() => {
+ exit(
+ new NotImplementedError(
+ `'agentcore project ${command}' has no interactive screen yet; ` +
+ `run 'agentcore project ${command} --help' to use it from the command line`,
+ ),
+ );
+ }, [exit, command]);
+
+ return null;
+}

src/testing/index.tsx

@@ -1,6 +1,6 @@
 export { parse, stringify } from "./serialization";
 export { fixtureFactories, fixtureFetch, isRecording, matchGolden, settle } from "./fixtures";
-export { testIO, type TestIO } from "./testIO";
+export { testIO, ttyTestIO, type TestIO, type TtyInput } from "./testIO";
 export { tick, waitFor, WaitForTimeoutError } from "./timing";
 export {
  TestCoreClient,

src/testing/testIO.tsx

@@ -53,3 +53,32 @@ export function testIO({ isTTY = false, stdin: stdinContent }: TestIOOptions = {
  stderr: err.read,
  };
 }
+
+// TtyInput is the writable stdin of a TTY TestIO: tests push raw key sequences
+// into it to drive a mounted TUI.
+export interface TtyInput extends NodeJS.ReadStream {
+ write(chunk: string): boolean;
+}
+
+// ttyTestIO builds a TestIO that Ink accepts as a real terminal: isTTY, the
+// no-op stdin methods Ink calls when it takes over, and a window size (Ink needs
+// columns/rows to lay out frames). For tests that mount the TUI through
+// renderTui/renderTuiAt rather than ink-testing-library.
+export function ttyTestIO(columns = 100, rows = 40): { streams: TestIO; stdin: TtyInput } {
+ const streams = testIO({ isTTY: true });
+ const stdin = streams.io.stdin as TtyInput;
+ stdin.setRawMode = function () {
+ return this;
+ };
+ stdin.ref = function () {
+ return this;
+ };
+ stdin.unref = function () {
+ return this;
+ };
+ Object.defineProperties(streams.io.stdout, {
+ columns: { configurable: true, value: columns },
+ rows: { configurable: true, value: rows },
+ });
+ return { streams, stdin };
+}

src/tui/tui.test.tsx

@@ -7,34 +7,12 @@ import {
  TestCoreClient,
  TestGlobalConfigAccessor,
  testIO,
+ ttyTestIO,
  tick,
  waitFor,
 } from "../testing";
 import { ExitCode } from "../runnable";
 
-interface TtyInput extends NodeJS.ReadStream {
- write(chunk: string): boolean;
-}
-
-function ttyTestIO(): { streams: ReturnType<typeof testIO>; stdin: TtyInput } {
- const streams = testIO({ isTTY: true });
- const stdin = streams.io.stdin as TtyInput;
- stdin.setRawMode = function () {
- return this;
- };
- stdin.ref = function () {
- return this;
- };
- stdin.unref = function () {
- return this;
- };
- Object.defineProperties(streams.io.stdout, {
- columns: { configurable: true, value: 100 },
- rows: { configurable: true, value: 40 },
- });
- return { streams, stdin };
-}
-
 describe("renderJson", () => {
  test("pretty-prints a value as indented JSON to the given writer", () => {
  const lines: string[] = [];

src/components/Root.tsx

@@ -107,9 +107,15 @@ import { GatewayRuleScreen } from "../handlers/gateway/rule/screen.tsx";
 import { GatewayRuleListScreen } from "../handlers/gateway/rule/list/screen.tsx";
 import { GatewayRuleGetScreen } from "../handlers/gateway/rule/get/screen.tsx";
 import { GatewayInvokeScreen } from "../handlers/gateway/invoke/screen.tsx";
+import { ProjectScreen, ProjectCommandNotImplementedScreen } from "../handlers/project/screen.tsx";
 import { RootScreen, HelpScreen } from "../handlers/screen.tsx";
 import type { Context } from "../router";
 
+// PROJECT_COMMANDS are the `agentcore project` subcommands that are listed in
+// the menu but have no screen of their own yet. Each is routed explicitly so
+// selecting it reports "not implemented" error
+const PROJECT_COMMANDS = ["create", "add", "remove", "dev", "deploy", "status", "build"] as const;
+
 export interface RootProps {
  // path is the command path to the executing node (e.g. "/agentcore").
  path: string;
@@ -736,6 +742,16 @@ export function Root({ path, ctx, core, queryClient }: RootProps) {
  path="agentcore/identity/oauth2-credential-provider/get/:name/json"
  element={<Oauth2CredentialProviderGetJsonScreen ctx={ctx} core={core} />}
  />
+ <Route path="agentcore/project" element={<ProjectScreen ctx={ctx} core={core} />} />
+ {PROJECT_COMMANDS.map((command) => (
+ <Route
+ key={command}
+ path={`agentcore/project/${command}`}
+ element={
+ <ProjectCommandNotImplementedScreen ctx={ctx} core={core} command={command} />
+ }
+ />
+ ))}
  <Route path="*" element={<HelpScreen ctx={ctx} core={core} />} />
  </Routes>
  </MemoryRouter>

src/handlers/index.tsx

@@ -50,7 +50,7 @@ export function createRootHandler(core: Core, config: RootHandlerConfig): Router
  root.handler(createGatewayHandler(core, io));
  root.handler(createEvalHandler(core, io));
  root.handler(createConfigHandler());
- root.handler(createProjectHandler({ projectManager: core.projectManager, io }));
+ root.handler(createProjectHandler({ core, io }));
 
  // Invoking with no subcommand launches the interactive TUI.
  root.default(renderTui(core, io));

src/handlers/project/index.ts

@@ -5,6 +5,8 @@ import { ContainerDevRunner } from "../../core/dev/container";
 import { InspectorAssets } from "../../core/dev/inspectorAssets";
 import { startOtelCollector } from "../../core/dev/otel/collector";
 import { withProject } from "../../middleware";
+import { renderTui } from "../../tui";
+import type { Core } from "../types";
 import { createCreateProjectHandler } from "./create";
 import { createRemoveProjectHandler } from "./remove";
 import { createDevProjectHandler } from "./dev";
@@ -16,16 +18,20 @@ import type { ProjectManager } from "./types";
 import { createAddProjectResourceHandler } from "./add";
 
 type ProjectHandlerConfig = {
-projectManager: ProjectManager;
+core: Core;
  io: AppIO;
 };
 
-export function createProjectHandler(config: ProjectHandlerConfig): Router {
+export function createProjectHandler({ core, io }: ProjectHandlerConfig): Router {
+ const projectManager: ProjectManager = core.projectManager;
+ const config = { projectManager, io };
  const project = new Router("project", "manage an AgentCore project");
 
- project.handler(
- createCreateProjectHandler({ projectManager: config.projectManager, io: config.io }),
- );
+ // Without a default, a bare `agentcore project` falls back to Commander's help
+ // and a usage exit code instead of the menu every sibling router opens.
+ project.default(renderTui(core, io));
+
+ project.handler(createCreateProjectHandler({ projectManager, io }));
  project.handler(createAddProjectResourceHandler(config));
  project.handler(
  withProject({ projectManager: config.projectManager })(

src/handlers/project/project.screen.test.tsx

@@ -0,0 +1,158 @@
+import { test, expect, describe, afterEach } from "bun:test";
+import {
+ renderScreen,
+ waitForText,
+ cleanupScreens,
+ createSilentLogger,
+ TestCoreClient,
+ TestGlobalConfigAccessor,
+ testIO,
+ ttyTestIO,
+} from "../../testing";
+import { renderTuiAt } from "../../tui";
+import { InvalidEnvironmentError, NotImplementedError } from "../../errors";
+import { compile, ValueContext } from "../../router";
+import { ExitCode } from "../../runnable";
+import { createRootHandler } from "../index";
+
+afterEach(cleanupScreens);
+
+// projectSubcommands reads the project group's children off the compiled
+// Commander tree, so tests driven by it cover any subcommand added later.
+function projectSubcommands(): string[] {
+ const root = compile(
+ createRootHandler(new TestCoreClient(), {
+ io: testIO().io,
+ logger: createSilentLogger(),
+ globalConfigAccessor: new TestGlobalConfigAccessor(),
+ }),
+ ValueContext.EmptyContext(),
+ );
+ const project = root.commands.find((command) => command.name() === "project")!;
+ // `help` is Commander's own, not one of ours.
+ return project.commands.map((command) => command.name()).filter((name) => name !== "help");
+}
+
+describe("project menu", () => {
+ test("lists every project subcommand", async () => {
+ const r = renderScreen("/agentcore/project");
+
+ await waitForText(r.lastFrame, "manage an AgentCore project");
+ const frame = r.lastFrame()!;
+ for (const command of projectSubcommands()) {
+ expect(frame).toContain(command);
+ }
+ r.unmount();
+ });
+
+ test("is reachable from the root menu", async () => {
+ const r = renderScreen("/agentcore");
+
+ await waitForText(r.lastFrame, "manage an AgentCore project");
+ await r.write("project");
+ await waitForText(r.lastFrame, "❯ project");
+ await r.press("return");
+
+ await waitForText(r.lastFrame, "agentcore → project");
+ expect(r.lastFrame()).toContain("create");
+ r.unmount();
+ });
+
+ test("esc returns to the root menu", async () => {
+ const r = renderScreen("/agentcore/project");
+
+ await waitForText(r.lastFrame, "agentcore → project");
+ await r.press("escape");
+
+ await waitForText(r.lastFrame, "the platform for production AI agents");
+ r.unmount();
+ });
+});
+
+describe("project subcommands without a screen", () => {
+ // renderTuiAt rather than renderScreen: ink-testing-library exposes no
+ // waitUntilExit, so it cannot observe the rejection under test.
+ //
+ // Reading the cases off the router also guards Root's hand-written
+ // PROJECT_COMMANDS: an unrouted subcommand hits the catch-all, which resolves
+ // instead of rejecting. Frames can't detect that — the catch-all exits before
+ // painting, so it and this screen both render empty.
+ test.each(projectSubcommands())(
+ "%s tears down the TUI with NotImplementedError",
+ async (command) => {
+ const { streams } = ttyTestIO();
+
+ const rendering = renderTuiAt(
+ `/agentcore/project/${command}`,
+ ValueContext.EmptyContext(),
+ new TestCoreClient(),
+ streams.io,
+ );
+
+ await expect(rendering).rejects.toThrow(NotImplementedError);
+ await expect(rendering).rejects.toThrow(`'agentcore project ${command}'`);
+ },
+ );
+
+ test("the error names the command to run instead", async () => {
+ const { streams } = ttyTestIO();
+
+ const caught: unknown = await renderTuiAt(
+ "/agentcore/project/deploy",
+ ValueContext.EmptyContext(),
+ new TestCoreClient(),
+ streams.io,
+ ).then(
+ () => undefined,
+ (error: unknown) => error,
+ );
+
+ expect(caught).toBeInstanceOf(NotImplementedError);
+ const error = caught as NotImplementedError;
+ expect(error.message).toContain("agentcore project deploy --help");
+ // Surfaces as a plain CLI failure, not a crash.
+ expect(error.exitCode).toBe(1);
+ });
+});
+
+describe("agentcore project (no subcommand)", () => {
+ // Exercises the real CLI entrypoint; the screen tests mount a path directly
+ // and so never caught the missing default handler.
+ //
+ // Asserts renderTui's TTY guard rather than a rendered frame: Ink only writes
+ // frames incrementally when interactive (`!isInCi && isTTY`), so asserting on
+ // frames here would pass locally and time out under CI. Reaching the guard at
+ // all proves the group routed to the TUI — Commander help neither throws nor
+ // touches stderr.
+ test("routes to the TUI rather than printing Commander help", async () => {
+ const io = testIO();
+ const root = createRootHandler(new TestCoreClient(), {
+ io: io.io,
+ logger: createSilentLogger(),
+ globalConfigAccessor: new TestGlobalConfigAccessor(),
+ });
+
+ const caught: unknown = await root.route(["node", "agentcore", "project"]).then(
+ () => undefined,
+ (error: unknown) => error,
+ );
+
+ expect(caught).toBeInstanceOf(InvalidEnvironmentError);
+ expect((caught as InvalidEnvironmentError).exitCode).toBe(ExitCode.USAGE);
+ expect(io.stdout()).toBe("");
+ });
+
+ test("prints help instead of the TUI under --json", async () => {
+ const io = testIO();
+ const root = createRootHandler(new TestCoreClient(), {
+ io: io.io,
+ logger: createSilentLogger(),
+ globalConfigAccessor: new TestGlobalConfigAccessor(),
+ });
+
+ await root.route(["node", "agentcore", "project", "--json"]);
+
+ expect(io.stdout()).toContain("Usage:");
+ expect(io.stdout()).toContain("create");
+ });
+});

src/handlers/project/screen.tsx

@@ -0,0 +1,37 @@
+import { useEffect } from "react";
+import { useApp } from "ink";
+import { RouterScreen } from "../../components/RouterScreen";
+import { NotImplementedError } from "../../errors";
+import type { ScreenProps } from "../types";
+
+export function ProjectScreen(props: ScreenProps) {
+ return <RouterScreen {...props} path={["agentcore", "project"]} />;
+}
+
+export interface ProjectCommandNotImplementedScreenProps extends ScreenProps {
+ // command is the project subcommand the user selected, e.g. "deploy".
+ command: string;
+}
+
+// ProjectCommandNotImplementedScreen is the landing screen for a project
+// subcommand that is listed in the menu but has no screen yet.
+//
+// exit(error) rejects the waitUntilExit() that renderTuiAt awaits, so the TUI
+// tears down and the error takes the normal CLI path. Throwing during render
+// would surface a React stack trace instead.
+export function ProjectCommandNotImplementedScreen({
+ command,
+}: ProjectCommandNotImplementedScreenProps) {
+ const { exit } = useApp();
+
+ useEffect(() => {
+ exit(
+ new NotImplementedError(
+ `'agentcore project ${command}' has no interactive screen yet; ` +
+ `run 'agentcore project ${command} --help' to use it from the command line`,
+ ),
+ );
+ }, [exit, command]);
+
+ return null;
+}

src/testing/index.tsx

@@ -1,6 +1,6 @@
 export { parse, stringify } from "./serialization";
 export { fixtureFactories, fixtureFetch, isRecording, matchGolden, settle } from "./fixtures";
-export { testIO, type TestIO } from "./testIO";
+export { testIO, ttyTestIO, type TestIO, type TtyInput } from "./testIO";
 export { tick, waitFor, WaitForTimeoutError } from "./timing";
 export {
  TestCoreClient,

src/testing/testIO.tsx

@@ -53,3 +53,32 @@ export function testIO({ isTTY = false, stdin: stdinContent }: TestIOOptions = {
  stderr: err.read,
  };
 }
+
+// TtyInput is the writable stdin of a TTY TestIO: tests push raw key sequences
+// into it to drive a mounted TUI.
+export interface TtyInput extends NodeJS.ReadStream {
+ write(chunk: string): boolean;
+}
+
+// ttyTestIO builds a TestIO that Ink accepts as a real terminal: isTTY, the
+// no-op stdin methods Ink calls when it takes over, and a window size (Ink needs
+// columns/rows to lay out frames). For tests that mount the TUI through
+// renderTui/renderTuiAt rather than ink-testing-library.
+export function ttyTestIO(columns = 100, rows = 40): { streams: TestIO; stdin: TtyInput } {
+ const streams = testIO({ isTTY: true });
+ const stdin = streams.io.stdin as TtyInput;
+ stdin.setRawMode = function () {
+ return this;
+ };
+ stdin.ref = function () {
+ return this;
+ };
+ stdin.unref = function () {
+ return this;
+ };
+ Object.defineProperties(streams.io.stdout, {
+ columns: { configurable: true, value: columns },
+ rows: { configurable: true, value: rows },
+ });
+ return { streams, stdin };
+}

src/tui/tui.test.tsx

@@ -7,34 +7,12 @@ import {
  TestCoreClient,
  TestGlobalConfigAccessor,
  testIO,
+ ttyTestIO,
  tick,
  waitFor,
 } from "../testing";
 import { ExitCode } from "../runnable";
 
-interface TtyInput extends NodeJS.ReadStream {
- write(chunk: string): boolean;
-}
-
-function ttyTestIO(): { streams: ReturnType<typeof testIO>; stdin: TtyInput } {
- const streams = testIO({ isTTY: true });
- const stdin = streams.io.stdin as TtyInput;
- stdin.setRawMode = function () {
- return this;
- };
- stdin.ref = function () {
- return this;
- };
- stdin.unref = function () {
- return this;
- };
- Object.defineProperties(streams.io.stdout, {
- columns: { configurable: true, value: 100 },
- rows: { configurable: true, value: 40 },
- });
- return { streams, stdin };
-}
-
 describe("renderJson", () => {
  test("pretty-prints a value as indented JSON to the given writer", () => {
  const lines: string[] = [];