create-cogitator-app 0.2.1 → 0.3.0

package/README.md

@@ -21,7 +21,7 @@ npx create-cogitator-app -y
 npx create-cogitator-app my-project -p openai --yes
 ```
 
-Prompts are shown only for values not given on the command line: project directory, template, provider, package manager, Docker Compose and git. With `-y` / `--yes` nothing is asked and the defaults fill the gaps: `my-agents`, `basic`, `ollama`, the detected package manager, Docker Compose on, git on. The target directory must be empty or not exist. After writing the files the scaffolder runs `<pm> install` and, unless disabled, creates a git repository with an initial commit.
+Prompts are shown only for values not given on the command line: project directory, template, provider, package manager, Docker Compose and git. With `-y` / `--yes` nothing is asked and the defaults fill the gaps: `my-agents`, `basic`, `ollama`, the detected package manager, Docker Compose on, git on. The target directory must be empty or not exist. After writing the files the scaffolder runs `<pm> install` (skip it with `--no-install`) and, unless disabled, creates a git repository with an initial commit. A failed install or git step is reported and left for you to run by hand.
 
 Requires Node.js 22.12+.
 
@@ -46,6 +46,7 @@ Requires Node.js 22.12+.
 | `--pm <name>`              |           | Package manager (`pnpm`, `npm`, `yarn`, `bun`)            |
 | `--docker` / `--no-docker` |           | Include Docker Compose (Redis, Postgres, plus Ollama)     |
 | `--git` / `--no-git`       |           | Initialize git repository                                 |
+| `--no-install`             |           | Write the files without running `<pm> install`            |
 | `--yes`                    | `-y`      | Don't prompt; use the defaults for every missing value    |
 
 Unknown values for `--template`, `--provider` and `--pm` are ignored and asked for interactively (or replaced by the default with `--yes`). The package manager prompt defaults to the one that invoked the scaffolder (`npm_config_user_agent`), falling back to `pnpm`.
@@ -80,16 +81,16 @@ my-project/
 
 Template-specific sources:
 
-| Template     | Files                                                                                              |
-| ------------ | -------------------------------------------------------------------------------------------------- |
-| `basic`      | `src/index.ts`, `src/tools.ts`                                                                     |
-| `memory`     | `src/index.ts`, `src/tools.ts`                                                                     |
-| `swarm`      | `src/index.ts`, `src/tools.ts`, `src/agents/{researcher,writer,reviewer}.ts`                       |
-| `workflow`   | `src/index.ts`, `src/agents.ts`                                                                    |
-| `api-server` | `src/index.ts`, `src/agents.ts`                                                                    |
-| `nextjs`     | `src/lib/agent.ts`, `src/app/api/chat/route.ts`, `src/app/{page,layout}.tsx`, Next/Tailwind config |
+| Template     | Files                                                                                                       |
+| ------------ | ----------------------------------------------------------------------------------------------------------- |
+| `basic`      | `src/index.ts`, `src/tools.ts`                                                                              |
+| `memory`     | `src/index.ts`, `src/tools.ts`                                                                              |
+| `swarm`      | `src/index.ts`, `src/tools.ts`, `src/agents/{researcher,writer,reviewer}.ts`                                |
+| `workflow`   | `src/index.ts`, `src/agents.ts`                                                                             |
+| `api-server` | `src/index.ts`, `src/agents.ts`                                                                             |
+| `nextjs`     | `src/lib/agent.ts`, `src/app/api/{chat,health}/route.ts`, `src/app/{page,layout}.tsx`, Next/Tailwind config |
 
-The generated code configures `Cogitator` in `src/` itself, reading the provider key from the environment. Copy `.env.example` to `.env` and fill it in, then run `pnpm dev` (or `npm run dev`, `yarn dev`, `bun dev`).
+The generated code configures `Cogitator` in `src/` itself, reading the provider key from the environment. For the `api-server` and `nextjs` templates `cogitator.yml` also sets `deploy.health.path: /api/health`, the route the app serves, so `cogitator deploy` produces a container that reports healthy. Copy `.env.example` to `.env` and fill it in, then run `pnpm dev` (or `npm run dev`, `yarn dev`, `bun dev`).
 
 ## Programmatic API
 
@@ -105,18 +106,21 @@ const options: ProjectOptions = {
   packageManager: 'pnpm',
   docker: false,
   git: true,
+  install: false, // optional, default true
 };
 
-await scaffold(options);
+const result = await scaffold(options);
+// { files: ['package.json', 'src/index.ts', ...], install: { status: 'skipped' }, git: { status: 'done' } }
+if (result.install.status === 'failed') console.error(result.install.error);
 
 // or: parse CLI arguments and prompt for the rest
 const fromCli = await collectOptions(parseArgs(process.argv.slice(2)));
 await scaffold(fromCli);
 ```
 
-`scaffold()` writes the files, installs dependencies with `packageManager` and initializes git when `git` is `true`; it throws when `path` exists and is not empty.
+`scaffold()` writes the files, installs dependencies with `packageManager` unless `install` is `false`, and initializes git when `git` is `true`. It throws when `path` exists and is not empty. A failed install or git step does not throw: the returned `ScaffoldResult` lists the generated `files` and reports each step as `{ status: 'done' }`, `{ status: 'skipped' }` or `{ status: 'failed', error }`, and the project stays on disk.
 
-Other exports: `getTemplate(name)` and `templateChoices` (template generators and their labels), `detectPackageManager()`, `devCommand(pm)`, `defaultModels`, `providerConfig(provider)` and `providerEnvKey(provider)`, and the types `ProjectOptions`, `Template`, `LLMProvider`, `PackageManager` and `TemplateFile`.
+Other exports: `getTemplate(name)` and `templateChoices` (template generators and their labels), `detectPackageManager()`, `devCommand(pm)`, `defaultModels`, `providerConfig(provider)` and `providerEnvKey(provider)`, and the types `ProjectOptions`, `ScaffoldResult`, `ScaffoldStep`, `Template`, `LLMProvider`, `PackageManager` and `TemplateFile`.
 
 ## License
 

package/dist/index.js

@@ -550,7 +550,9 @@ var workflowTemplate = {
 };
 
 // src/templates/api-server.ts
+var BASE_PATH = "/api";
 var apiServerTemplate = {
+  healthPath: `${BASE_PATH}/health`,
   files(options) {
     const model = defaultModels[options.provider];
     const agentsTs = [
@@ -602,7 +604,7 @@ var apiServerTemplate = {
       `  cogitator,`,
       `  agents: { assistant, coder },`,
       `  config: {`,
-      `    basePath: '/api',`,
+      `    basePath: '${BASE_PATH}',`,
       `    enableSwagger: true,`,
       `    cors: { origin: '*' },`,
       `    swagger: {`,
@@ -617,7 +619,7 @@ var apiServerTemplate = {
       ``,
       `  app.listen(port, () => {`,
       `    console.log(\`Server running at http://localhost:\${port}\`)`,
-      `    console.log(\`Swagger docs at http://localhost:\${port}/api/docs\`)`,
+      `    console.log(\`Swagger docs at http://localhost:\${port}${BASE_PATH}/docs\`)`,
       `  })`,
       `}`,
       ``,
@@ -633,7 +635,7 @@ var apiServerTemplate = {
     return {
       "@cogitator-ai/core": "latest",
       "@cogitator-ai/express": "latest",
-      express: "^4.21.0",
+      express: "^5.2.1",
       zod: ZOD_VERSION
     };
   },
@@ -642,7 +644,7 @@ var apiServerTemplate = {
       typescript: "^5.8.0",
       tsx: "^4.19.0",
       "@types/node": "^22.0.0",
-      "@types/express": "^5.0.0"
+      "@types/express": "^5.0.6"
     };
   },
   scripts() {
@@ -657,6 +659,7 @@ var apiServerTemplate = {
 
 // src/templates/nextjs.ts
 var nextjsTemplate = {
+  healthPath: "/api/health",
   files(options) {
     const model = defaultModels[options.provider];
     const agentTs = [
@@ -694,6 +697,12 @@ var nextjsTemplate = {
       `export const POST = createChatHandler(cogitator, agent)`,
       ``
     ].join("\n");
+    const healthRouteTs = [
+      `export function GET() {`,
+      `  return Response.json({ status: 'ok' })`,
+      `}`,
+      ``
+    ].join("\n");
     const pageTsx = [
       `'use client'`,
       ``,
@@ -860,6 +869,7 @@ var nextjsTemplate = {
     return [
       { path: "src/lib/agent.ts", content: agentTs },
       { path: "src/app/api/chat/route.ts", content: routeTs },
+      { path: "src/app/api/health/route.ts", content: healthRouteTs },
       { path: "src/app/page.tsx", content: pageTsx },
       { path: "src/app/layout.tsx", content: layoutTsx },
       { path: "src/app/globals.css", content: globalsCss },
@@ -983,6 +993,10 @@ function parseArgs(args) {
       parsed.git = true;
     } else if (arg === "--no-git") {
       parsed.git = false;
+    } else if (arg === "--install") {
+      parsed.install = true;
+    } else if (arg === "--no-install") {
+      parsed.install = false;
     } else if (arg === "-y" || arg === "--yes") {
       parsed.yes = true;
     } else if (!arg.startsWith("-") && !parsed.name) {
@@ -1075,7 +1089,8 @@ async function collectOptions(args) {
     provider,
     packageManager,
     docker,
-    git
+    git,
+    ...args.install !== void 0 && { install: args.install }
   };
 }
 
@@ -1226,6 +1241,10 @@ function generateCogitatorYml(provider, template) {
       "    url: ${REDIS_URL:-redis://localhost:6379}"
     );
   }
+  const healthPath = template ? getTemplate(template).healthPath : void 0;
+  if (healthPath) {
+    lines.push("", "deploy:", "  health:", `    path: ${healthPath}`);
+  }
   lines.push("");
   return { path: "cogitator.yml", content: lines.join("\n") };
 }
@@ -1357,6 +1376,17 @@ function collectFiles(options) {
   }
   return files;
 }
+function runStep(spinner2, messages, step) {
+  spinner2.start(messages.start);
+  try {
+    step();
+    spinner2.stop(messages.done);
+    return { status: "done" };
+  } catch (error) {
+    spinner2.stop(messages.failed);
+    return { status: "failed", error: error instanceof Error ? error : new Error(String(error)) };
+  }
+}
 async function scaffold(options) {
   if (fs.existsSync(options.path) && fs.readdirSync(options.path).length > 0) {
     throw new Error(`Directory "${options.path}" already exists and is not empty`);
@@ -1369,22 +1399,25 @@ async function scaffold(options) {
     writeFile(options.path, file);
   }
   s.stop("Generated project files");
-  s.start("Installing dependencies");
-  try {
-    installDependencies(options.path, options.packageManager);
-    s.stop("Installed dependencies");
-  } catch {
-    s.stop("Failed to install dependencies \u2014 run manually");
-  }
-  if (options.git && isGitInstalled()) {
-    s.start("Initializing git repository");
-    try {
-      initGitRepo(options.path);
-      s.stop("Initialized git repository");
-    } catch {
-      s.stop("Failed to initialize git \u2014 run manually");
-    }
-  }
+  const install = options.install === false ? { status: "skipped" } : runStep(
+    s,
+    {
+      start: "Installing dependencies",
+      done: "Installed dependencies",
+      failed: `Failed to install dependencies, run "${options.packageManager} install" yourself`
+    },
+    () => installDependencies(options.path, options.packageManager)
+  );
+  const git = options.git && isGitInstalled() ? runStep(
+    s,
+    {
+      start: "Initializing git repository",
+      done: "Initialized git repository",
+      failed: 'Failed to initialize git, run "git init" yourself'
+    },
+    () => initGitRepo(options.path)
+  ) : { status: "skipped" };
+  return { files: files.map((file) => file.path), install, git };
 }
 
 // src/index.ts
@@ -1394,13 +1427,21 @@ async function main() {
   p3.intro(pc2.cyan("Let's build something with AI agents"));
   const args = parseArgs(process.argv.slice(2));
   const options = await collectOptions(args);
-  await scaffold(options);
+  const result = await scaffold(options);
+  if (result.install.status === "failed") {
+    p3.log.warn(`${options.packageManager} install failed: ${result.install.error.message}`);
+  }
+  if (result.git.status === "failed") {
+    p3.log.warn(`git init failed: ${result.git.error.message}`);
+  }
   const dev = devCommand(options.packageManager);
+  const install = result.install.status === "done" ? [] : [`  ${pc2.cyan(`${options.packageManager} install`)}`];
   p3.outro(
     [
       pc2.green("Done! ") + "Next steps:",
       "",
       `  ${pc2.cyan("cd")} ${options.name}`,
+      ...install,
       `  ${pc2.cyan(dev)}`,
       "",
       pc2.dim(`Docs: ${DOCS_URL}`)