create-cogitator-app 0.2.0 → 0.2.1

package/README.md

@@ -1,6 +1,8 @@
 # create-cogitator-app
 
-Interactive CLI scaffolder for [Cogitator](https://cogitator.dev) — creates production-ready AI agent projects in seconds.
+Interactive scaffolder for [Cogitator](https://cogitator.app) — creates a ready-to-run TypeScript AI agent project from one of six templates.
+
+Guide: [cogitator.app/docs/getting-started/scaffolding](https://cogitator.app/docs/getting-started/scaffolding)
 
 ## Usage
 
@@ -11,44 +13,88 @@ npx create-cogitator-app
 # With arguments
 npx create-cogitator-app my-project --template basic --provider openai
 
-# Skip prompts with flags
+# Skip every prompt with flags
 npx create-cogitator-app my-project -t swarm -p ollama --pm pnpm --docker --no-git
+
+# Accept the defaults for everything not given
+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.
+
+Requires Node.js 22.12+.
+
 ## Templates
 
-| Template     | Description                               |
-| ------------ | ----------------------------------------- |
-| `basic`      | Single agent with tools                   |
-| `memory`     | Agent with Redis-backed persistent memory |
-| `swarm`      | Multi-agent hierarchical swarm            |
-| `workflow`   | DAG workflow with sequential agent nodes  |
-| `api-server` | Express REST API with Cogitator backend   |
-| `nextjs`     | Next.js chat app with streaming UI        |
+| Template     | Description                                                              |
+| ------------ | ------------------------------------------------------------------------ |
+| `basic`      | Single agent with tools                                                  |
+| `memory`     | Agent with Redis-backed persistent memory (`@cogitator-ai/redis`)        |
+| `swarm`      | Hierarchical swarm of researcher, writer and reviewer agents             |
+| `workflow`   | DAG workflow (`@cogitator-ai/workflows`) with sequential agent nodes     |
+| `api-server` | Express REST API with `CogitatorServer` from `@cogitator-ai/express`     |
+| `nextjs`     | Next.js App Router chat app with a streaming `/api/chat` route, Tailwind |
 
 ## CLI Flags
 
-| Flag                       | Shorthand | Description                                              |
-| -------------------------- | --------- | -------------------------------------------------------- |
-| `--template <name>`        | `-t`      | Template to use                                          |
-| `--provider <name>`        | `-p`      | LLM provider (`ollama`, `openai`, `anthropic`, `google`) |
-| `--pm <name>`              |           | Package manager (`pnpm`, `npm`, `yarn`, `bun`)           |
-| `--docker` / `--no-docker` |           | Include Docker Compose                                   |
-| `--git` / `--no-git`       |           | Initialize git repository                                |
+| Flag                       | Shorthand | Description                                               |
+| -------------------------- | --------- | --------------------------------------------------------- |
+| `[name]`                   |           | Project directory (its basename becomes the package name) |
+| `--template <name>`        | `-t`      | Template to use                                           |
+| `--provider <name>`        | `-p`      | LLM provider (`ollama`, `openai`, `anthropic`, `google`)  |
+| `--pm <name>`              |           | Package manager (`pnpm`, `npm`, `yarn`, `bun`)            |
+| `--docker` / `--no-docker` |           | Include Docker Compose (Redis, Postgres, plus Ollama)     |
+| `--git` / `--no-git`       |           | Initialize git repository                                 |
+| `--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`.
 
 ## Providers
 
-| Provider    | Default Model       | Requires                                       |
-| ----------- | ------------------- | ---------------------------------------------- |
-| `ollama`    | `qwen3:8b`          | [Ollama](https://ollama.com) installed locally |
-| `openai`    | `gpt-6.1-sol`       | `OPENAI_API_KEY`                               |
-| `anthropic` | `claude-sonnet-5-5` | `ANTHROPIC_API_KEY`                            |
-| `google`    | `gemini-3.8-flash`  | `GOOGLE_API_KEY`                               |
+| Provider    | Default Model       | Requires                                                                           |
+| ----------- | ------------------- | ---------------------------------------------------------------------------------- |
+| `ollama`    | `qwen3:8b`          | [Ollama](https://ollama.com) (`OLLAMA_BASE_URL`, default `http://localhost:11434`) |
+| `openai`    | `gpt-6.1-sol`       | `OPENAI_API_KEY`                                                                   |
+| `anthropic` | `claude-sonnet-5-5` | `ANTHROPIC_API_KEY`                                                                |
+| `google`    | `gemini-3.8-flash`  | `GOOGLE_API_KEY`                                                                   |
+
+## Generated Project Structure
+
+Every project gets these files (shown for the `basic` template):
+
+```
+my-project/
+├── src/
+│   ├── index.ts         # Main entry point
+│   └── tools.ts         # Tool definitions
+├── package.json         # dev / start / build / typecheck scripts
+├── tsconfig.json        # not for nextjs, which ships its own
+├── cogitator.yml        # provider and default model
+├── .env.example         # the provider's key (and REDIS_URL for memory)
+├── .gitignore
+├── README.md
+├── pnpm-workspace.yaml  # pnpm only
+└── docker-compose.yml   # with --docker
+```
+
+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 |
+
+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`).
 
 ## Programmatic API
 
 ```ts
-import { scaffold, parseArgs } from 'create-cogitator-app';
+import { scaffold, parseArgs, collectOptions } from 'create-cogitator-app';
 import type { ProjectOptions } from 'create-cogitator-app';
 
 const options: ProjectOptions = {
@@ -62,22 +108,15 @@ const options: ProjectOptions = {
 };
 
 await scaffold(options);
+
+// or: parse CLI arguments and prompt for the rest
+const fromCli = await collectOptions(parseArgs(process.argv.slice(2)));
+await scaffold(fromCli);
 ```
 
-## Generated Project Structure
+`scaffold()` writes the files, installs dependencies with `packageManager` and initializes git when `git` is `true`; it throws when `path` exists and is not empty.
 
-```
-my-project/
-├── src/
-│   ├── index.ts      # Main entry point
-│   └── tools.ts      # Tool definitions
-├── package.json
-├── tsconfig.json
-├── cogitator.yml     # Cogitator configuration
-├── .env.example
-├── .gitignore
-└── README.md
-```
+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`.
 
 ## License
 

package/dist/index.js

@@ -2,17 +2,31 @@
 
 // src/index.ts
 import * as p3 from "@clack/prompts";
+import { readFileSync } from "fs";
 import pc2 from "picocolors";
 
 // src/utils/logger.ts
 import pc from "picocolors";
-function banner() {
+var MIN_INNER_WIDTH = 39;
+function banner(version) {
+  const title = "create-cogitator-app";
+  const tagline = "Build AI agents in minutes";
+  const versionLabel = `v${version}`;
+  const lines = [
+    {
+      text: `${pc.bold(pc.white(title))}  ${pc.dim(versionLabel)}`,
+      width: title.length + 2 + versionLabel.length
+    },
+    { text: pc.dim(tagline), width: tagline.length }
+  ];
+  const inner = Math.max(MIN_INNER_WIDTH, ...lines.map((line) => line.width + 4));
   const art = [
     "",
-    `  ${pc.cyan("\u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557")}`,
-    `  ${pc.cyan("\u2551")}  ${pc.bold(pc.white("create-cogitator-app"))}  ${pc.dim("v0.1.0")}       ${pc.cyan("\u2551")}`,
-    `  ${pc.cyan("\u2551")}  ${pc.dim("Build AI agents in minutes")}          ${pc.cyan("\u2551")}`,
-    `  ${pc.cyan("\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D")}`,
+    `  ${pc.cyan(`\u2554${"\u2550".repeat(inner)}\u2557`)}`,
+    ...lines.map(
+      (line) => `  ${pc.cyan("\u2551")}  ${line.text}${" ".repeat(inner - 2 - line.width)}${pc.cyan("\u2551")}`
+    ),
+    `  ${pc.cyan(`\u255A${"\u2550".repeat(inner)}\u255D`)}`,
     ""
   ];
   console.log(art.join("\n"));
@@ -70,6 +84,9 @@ function providerConfig(provider) {
   }
 }
 
+// src/templates/versions.ts
+var ZOD_VERSION = "^4.6.5";
+
 // src/templates/basic.ts
 var basicTemplate = {
   files(options) {
@@ -138,7 +155,7 @@ var basicTemplate = {
   dependencies() {
     return {
       "@cogitator-ai/core": "latest",
-      zod: "^3.23.0"
+      zod: ZOD_VERSION
     };
   },
   devDependencies() {
@@ -247,7 +264,7 @@ var memoryTemplate = {
       "@cogitator-ai/core": "latest",
       "@cogitator-ai/memory": "latest",
       "@cogitator-ai/redis": "latest",
-      zod: "^3.23.0"
+      zod: ZOD_VERSION
     };
   },
   devDependencies() {
@@ -368,7 +385,7 @@ var swarmTemplate = {
       `  })`,
       ``,
       `  console.log('Result:', result.output)`,
-      `  console.log('Strategy:', result.strategy)`,
+      `  console.log('Strategy:', team.strategyType)`,
       ``,
       `  await team.close()`,
       `}`,
@@ -388,7 +405,7 @@ var swarmTemplate = {
     return {
       "@cogitator-ai/core": "latest",
       "@cogitator-ai/swarms": "latest",
-      zod: "^3.23.0"
+      zod: ZOD_VERSION
     };
   },
   devDependencies() {
@@ -451,7 +468,7 @@ var workflowTemplate = {
       providerConfig(options.provider),
       `})`,
       ``,
-      `interface WorkflowState {`,
+      `type WorkflowState = {`,
       `  input: string`,
       `  analysis?: string`,
       `  processed?: string`,
@@ -512,7 +529,7 @@ var workflowTemplate = {
     return {
       "@cogitator-ai/core": "latest",
       "@cogitator-ai/workflows": "latest",
-      zod: "^3.23.0"
+      zod: ZOD_VERSION
     };
   },
   devDependencies() {
@@ -617,7 +634,7 @@ var apiServerTemplate = {
       "@cogitator-ai/core": "latest",
       "@cogitator-ai/express": "latest",
       express: "^4.21.0",
-      zod: "^3.23.0"
+      zod: ZOD_VERSION
     };
   },
   devDependencies() {
@@ -859,7 +876,7 @@ var nextjsTemplate = {
       next: "^15.0.0",
       react: "^19.0.0",
       "react-dom": "^19.0.0",
-      zod: "^3.23.0"
+      zod: ZOD_VERSION
     };
   },
   devDependencies() {
@@ -974,78 +991,83 @@ function parseArgs(args) {
   }
   return parsed;
 }
-async function collectOptions(args) {
-  const rawName = args.name || await p.text({
-    message: "Where should we create your project?",
-    placeholder: "./my-agents",
-    defaultValue: "my-agents",
-    validate: (value) => {
-      if (value && !value.trim()) return "Project name is required";
-      return void 0;
-    }
-  });
-  if (p.isCancel(rawName)) {
+var defaultAnswers = {
+  name: "my-agents",
+  template: "basic",
+  provider: "ollama",
+  docker: true,
+  git: true
+};
+function unlessCancelled(answer) {
+  if (p.isCancel(answer)) {
     p.cancel("Operation cancelled.");
     process.exit(0);
   }
+  return answer;
+}
+async function collectOptions(args) {
+  const interactive = !args.yes;
+  const rawName = args.name || (interactive ? unlessCancelled(
+    await p.text({
+      message: "Where should we create your project?",
+      placeholder: `./${defaultAnswers.name}`,
+      defaultValue: defaultAnswers.name,
+      validate: (value) => {
+        if (value && !value.trim()) return "Project name is required";
+        return void 0;
+      }
+    })
+  ) : defaultAnswers.name);
   const name = rawName.trim();
   const projectName = path.basename(path.normalize(name).replace(/^\.\//, "").replace(/^\.\\/, ""));
   const projectPath = path.resolve(process.cwd(), name);
-  const template = args.template || await p.select({
-    message: "Which template would you like?",
-    options: templateChoices
-  });
-  if (p.isCancel(template)) {
-    p.cancel("Operation cancelled.");
-    process.exit(0);
-  }
-  const provider = args.provider || await p.select({
-    message: "Which LLM provider?",
-    options: [
-      {
-        value: "ollama",
-        label: "Ollama",
-        hint: "local, free \u2014 requires Ollama installed"
-      },
-      { value: "openai", label: "OpenAI", hint: "GPT-4o" },
-      { value: "anthropic", label: "Anthropic", hint: "Claude Sonnet" },
-      { value: "google", label: "Google Gemini", hint: "Gemini 2.5 Flash" }
-    ]
-  });
-  if (p.isCancel(provider)) {
-    p.cancel("Operation cancelled.");
-    process.exit(0);
-  }
-  const packageManager = args.packageManager || await p.select({
-    message: "Package manager?",
-    options: [
-      { value: "pnpm", label: "pnpm" },
-      { value: "npm", label: "npm" },
-      { value: "yarn", label: "yarn" },
-      { value: "bun", label: "bun" }
-    ],
-    initialValue: detectPackageManager()
-  });
-  if (p.isCancel(packageManager)) {
-    p.cancel("Operation cancelled.");
-    process.exit(0);
-  }
-  const docker = args.docker ?? await p.confirm({
-    message: "Include Docker Compose? (Redis + Postgres" + (provider === "ollama" ? " + Ollama)" : ")"),
-    initialValue: true
-  });
-  if (p.isCancel(docker)) {
-    p.cancel("Operation cancelled.");
-    process.exit(0);
-  }
-  const git = args.git ?? await p.confirm({
-    message: "Initialize git repository?",
-    initialValue: true
-  });
-  if (p.isCancel(git)) {
-    p.cancel("Operation cancelled.");
-    process.exit(0);
-  }
+  const template = args.template ?? (interactive ? unlessCancelled(
+    await p.select({
+      message: "Which template would you like?",
+      options: templateChoices,
+      initialValue: defaultAnswers.template
+    })
+  ) : defaultAnswers.template);
+  const provider = args.provider ?? (interactive ? unlessCancelled(
+    await p.select({
+      message: "Which LLM provider?",
+      options: [
+        {
+          value: "ollama",
+          label: "Ollama",
+          hint: `${defaultModels.ollama} \u2014 local, free, requires Ollama installed`
+        },
+        { value: "openai", label: "OpenAI", hint: defaultModels.openai },
+        { value: "anthropic", label: "Anthropic", hint: defaultModels.anthropic },
+        { value: "google", label: "Google Gemini", hint: defaultModels.google }
+      ],
+      initialValue: defaultAnswers.provider
+    })
+  ) : defaultAnswers.provider);
+  const packageManager = args.packageManager ?? (interactive ? unlessCancelled(
+    await p.select({
+      message: "Package manager?",
+      options: [
+        { value: "pnpm", label: "pnpm" },
+        { value: "npm", label: "npm" },
+        { value: "yarn", label: "yarn" },
+        { value: "bun", label: "bun" }
+      ],
+      initialValue: detectPackageManager()
+    })
+  ) : detectPackageManager());
+  const docker = args.docker ?? (interactive ? unlessCancelled(
+    await p.confirm({
+      message: "Include Docker Compose? (Redis + Postgres" + (provider === "ollama" ? " + Ollama)" : ")"),
+      initialValue: defaultAnswers.docker
+    })
+  ) : defaultAnswers.docker);
+  const git = args.git ?? (interactive ? unlessCancelled(
+    await p.confirm({
+      message: "Initialize git repository?",
+      initialValue: defaultAnswers.git
+    })
+  ) : defaultAnswers.git);
   return {
     name: projectName,
     path: projectPath,
@@ -1182,15 +1204,36 @@ function generateDockerCompose(provider) {
 }
 
 // src/templates/base/cogitator-yml.ts
-function generateCogitatorYml(provider) {
-  const model = defaultModels[provider];
-  const lines = [`provider: ${provider}`, `model: ${model}`, ""];
+function generateCogitatorYml(provider, template) {
+  const lines = [
+    "llm:",
+    `  defaultProvider: ${provider}`,
+    `  defaultModel: ${defaultModels[provider]}`
+  ];
   if (provider === "ollama") {
-    lines.push("ollama:", "  baseUrl: http://localhost:11434", "");
+    lines.push(
+      "  providers:",
+      "    ollama:",
+      "      baseUrl: ${OLLAMA_BASE_URL:-http://localhost:11434}"
+    );
   }
+  if (template === "memory") {
+    lines.push(
+      "",
+      "memory:",
+      "  adapter: redis",
+      "  redis:",
+      "    url: ${REDIS_URL:-redis://localhost:6379}"
+    );
+  }
+  lines.push("");
   return { path: "cogitator.yml", content: lines.join("\n") };
 }
 
+// src/utils/links.ts
+var DOCS_URL = "https://cogitator.app/docs";
+var REPO_URL = "https://github.com/cogitator-ai/Cogitator-AI";
+
 // src/templates/base/readme.ts
 var templateNames = {
   basic: "Basic Agent",
@@ -1206,7 +1249,7 @@ function generateReadme(options) {
   const content = [
     `# ${options.name}`,
     "",
-    `> Created with [create-cogitator-app](https://github.com/cogitator-ai/cogitator) \u2014 ${templateName} template`,
+    `> Created with [create-cogitator-app](${REPO_URL}) \u2014 ${templateName} template`,
     "",
     "## Getting Started",
     "",
@@ -1221,8 +1264,8 @@ function generateReadme(options) {
     ...options.docker ? ["## Docker Services", "", "```bash", "docker compose up -d", "```", ""] : [],
     "## Learn More",
     "",
-    "- [Cogitator Documentation](https://cogitator.dev/docs)",
-    "- [GitHub Repository](https://github.com/cogitator-ai/cogitator)",
+    `- [Cogitator Documentation](${DOCS_URL})`,
+    `- [GitHub Repository](${REPO_URL})`,
     ""
   ];
   return { path: "README.md", content: content.join("\n") };
@@ -1240,22 +1283,38 @@ function generatePnpmWorkspace() {
 }
 
 // src/utils/git.ts
-import { execSync as execSync2 } from "child_process";
+import { execFileSync } from "child_process";
+var FALLBACK_IDENTITY = [
+  "-c",
+  "user.name=create-cogitator-app",
+  "-c",
+  "user.email=create-cogitator-app@localhost"
+];
 function isGitInstalled() {
   try {
-    execSync2("git --version", { stdio: "ignore" });
+    execFileSync("git", ["--version"], { stdio: "ignore" });
     return true;
   } catch {
     return false;
   }
 }
+function hasIdentity(cwd) {
+  try {
+    const name = execFileSync("git", ["config", "user.name"], { cwd, encoding: "utf8" }).trim();
+    const email = execFileSync("git", ["config", "user.email"], { cwd, encoding: "utf8" }).trim();
+    return name.length > 0 && email.length > 0;
+  } catch {
+    return false;
+  }
+}
 function initGitRepo(cwd) {
-  execSync2("git init", { cwd, stdio: "ignore" });
-  execSync2("git add -A", { cwd, stdio: "ignore" });
-  execSync2(
-    'git -c user.name="Cogitator" -c user.email="init@cogitator.dev" commit -m "feat: initial project scaffold"',
-    { cwd, stdio: "ignore" }
-  );
+  execFileSync("git", ["init"], { cwd, stdio: "ignore" });
+  execFileSync("git", ["add", "-A"], { cwd, stdio: "ignore" });
+  const identity = hasIdentity(cwd) ? [] : FALLBACK_IDENTITY;
+  execFileSync("git", [...identity, "commit", "-m", "feat: initial project scaffold"], {
+    cwd,
+    stdio: "ignore"
+  });
 }
 
 // src/scaffold.ts
@@ -1267,7 +1326,7 @@ function writeFile(basePath, file) {
 function buildPackageJson(options) {
   const template = getTemplate(options.template);
   const isNextjs = options.template === "nextjs";
-  const pkg = {
+  const pkg2 = {
     name: options.name,
     version: "0.1.0",
     private: true,
@@ -1276,7 +1335,7 @@ function buildPackageJson(options) {
     dependencies: template.dependencies(),
     devDependencies: template.devDependencies()
   };
-  return JSON.stringify(pkg, null, 2) + "\n";
+  return JSON.stringify(pkg2, null, 2) + "\n";
 }
 function collectFiles(options) {
   const template = getTemplate(options.template);
@@ -1285,7 +1344,7 @@ function collectFiles(options) {
   files.push(...template.files(options));
   files.push(generateGitignore());
   files.push(generateEnvExample(options.provider, options.template));
-  files.push(generateCogitatorYml(options.provider));
+  files.push(generateCogitatorYml(options.provider, options.template));
   files.push(generateReadme(options));
   if (options.template !== "nextjs") {
     files.push(generateTsconfig());
@@ -1329,8 +1388,9 @@ async function scaffold(options) {
 }
 
 // src/index.ts
+var pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
 async function main() {
-  banner();
+  banner(pkg.version);
   p3.intro(pc2.cyan("Let's build something with AI agents"));
   const args = parseArgs(process.argv.slice(2));
   const options = await collectOptions(args);
@@ -1343,7 +1403,7 @@ async function main() {
       `  ${pc2.cyan("cd")} ${options.name}`,
       `  ${pc2.cyan(dev)}`,
       "",
-      pc2.dim("Docs: https://cogitator.dev/docs")
+      pc2.dim(`Docs: ${DOCS_URL}`)
     ].join("\n")
   );
 }