feat(dev): wire project dev to the CodeZip runner

Minimal headless wiring so the runner is drivable from the CLI: resolve
the project via middleware, pick the first (or --runtime) runtime, spawn
it on --port (default 8080), stream logs to stderr until Ctrl+C. The
richer dev experience (Container, .env.local, OTEL, Inspector) layers on
in the later PRs of the stack.

Author: tejaskash

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 }));
+  root.handler(createProjectHandler({ projectManager: core.projectManager, io }));
 
   // Invoking with no subcommand launches the interactive TUI.
   root.default(renderTui(core, io));

src/handlers/project/dev/index.ts

@@ -1,11 +1,63 @@
-import { createHandler } from "../../../router";
-import { NotImplementedError } from "../../../errors";
+import z from "zod";
+import { InputValidationError } from "../../../errors";
+import type { AppIO } from "../../../io";
+import { CodeZipDevRunner } from "../../../core/dev";
+import { createHandler, flag, LoggerKey, ProjectKey } from "../../../router";
+import type { DevRunner } from "./types";
 
-export const createDevProjectHandler = () =>
+type DevProjectHandlerConfig = {
+  io: AppIO;
+  /** Injectable for tests; defaults to the CodeZip runner. */
+  runner?: DevRunner;
+};
+
+// TEMPORARY WIRING: runs the first (or --runtime) CodeZip runtime headlessly,
+// streaming logs to stderr until Ctrl+C. The full dev experience (Container,
+// .env.local, OTEL, Agent Inspector) arrives with the later PRs in the stack.
+export const createDevProjectHandler = (config: DevProjectHandlerConfig) =>
   createHandler({
     name: "dev",
     description: "run the project locally for development",
-    handle: async () => {
-      throw new NotImplementedError("agentcore project dev is not implemented yet");
+    flags: [
+      flag("runtime", "runtime to run (defaults to the only runtime)", z.string().optional()),
+      flag("port", "port for the dev server", z.coerce.number().int().min(1).default(8080)),
+    ],
+    handle: async (ctx, flags) => {
+      const project = ctx.require(ProjectKey);
+      const logger = ctx.require(LoggerKey);
+
+      const runtime = flags.runtime
+        ? project.runtimes.find((r) => r.name === flags.runtime)
+        : project.runtimes[0];
+      if (!runtime) {
+        const available = project.runtimes.map((r) => r.name).join(", ") || "none";
+        throw new InputValidationError(
+          flags.runtime
+            ? `runtime "${flags.runtime}" not found in project (available: ${available})`
+            : "the project has no runtimes; run `agentcore project add` to add one",
+        );
+      }
+
+      const runner = config.runner ?? new CodeZipDevRunner({ logger });
+      const handle = await runner.start({
+        runtime,
+        projectRoot: project.rootPath,
+        port: flags.port,
+        onLog: (level, message) => config.io.stderr.write(`[${level}] ${message}\n`),
+      });
+
+      config.io.stderr.write(
+        `Dev server for "${runtime.name}" on port ${flags.port}. Ctrl+C to stop.\n`,
+      );
+      const interrupt = () => void handle.stop();
+      process.once("SIGINT", interrupt);
+      try {
+        const exit = await handle.exited;
+        if (exit.kind === "exited" && exit.code !== 0) {
+          throw new InputValidationError(`dev server exited with code ${exit.code}`);
+        }
+      } finally {
+        process.off("SIGINT", interrupt);
+      }
     },
   });

src/handlers/project/index.ts

@@ -7,10 +7,12 @@ import { createDevProjectHandler } from "./dev";
 import { createDeployProjectHandler } from "./deploy";
 import { createStatusProjectHandler } from "./status";
 import { createBuildProjectHandler } from "./build";
+import type { AppIO } from "../../io";
 import type { ProjectManager } from "./types";
 
 type ProjectHandlerConfig = {
   projectManager: ProjectManager;
+  io: AppIO;
 };
 
 export function createProjectHandler(config: ProjectHandlerConfig): Router {
@@ -26,7 +28,7 @@ export function createProjectHandler(config: ProjectHandlerConfig): Router {
   project.handler(createCreateProjectHandler({ projectManager: config.projectManager }));
   project.handler(inProject(createAddProjectHandler()));
   project.handler(inProject(createRemoveProjectHandler()));
-  project.handler(inProject(createDevProjectHandler()));
+  project.handler(inProject(createDevProjectHandler({ io: config.io })));
   project.handler(inProject(createDeployProjectHandler()));
   project.handler(inProject(createStatusProjectHandler()));
   project.handler(inProject(createBuildProjectHandler()));

src/handlers/project/project.test.ts

@@ -20,7 +20,7 @@ async function run(args: string[]): Promise<void> {
   await root.route(["node", "agentcore", "project", ...args]);
 }
 
-describe.each(["add", "remove", "dev", "deploy", "status", "build"])("project %s", (command) => {
+describe.each(["add", "remove", "deploy", "status", "build"])("project %s", (command) => {
   test("refuses to run outside a project", async () => {
     await inTempDirectory();
     await expect(run([command])).rejects.toThrow(/no AgentCore project found/);
@@ -35,6 +35,21 @@ describe.each(["add", "remove", "dev", "deploy", "status", "build"])("project %s
   });
 });
 
+describe("project dev", () => {
+  test("refuses to run outside a project", async () => {
+    await inTempDirectory();
+    await expect(run(["dev"])).rejects.toThrow(/no AgentCore project found/);
+  });
+
+  test("rejects an unknown --runtime", async () => {
+    const directory = await inTempDirectory();
+    await run(["create", "--project-name", "MyAgent"]);
+    process.chdir(join(directory, "MyAgent"));
+
+    await expect(run(["dev", "--runtime", "nope"])).rejects.toThrow(/not found in project/);
+  });
+});
+
 const originalCwd = process.cwd();
 const tempDirectories: string[] = [];