create-cogitator-app 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +81 -38
  2. package/dist/index.js +222 -121
  3. package/dist/index.js.map +1 -1
  4. package/dist/lib.d.ts +39 -2
  5. package/dist/lib.js +189 -111
  6. package/dist/lib.js.map +1 -1
  7. package/package.json +2 -2
package/README.md CHANGED
@@ -1,6 +1,8 @@
1
1
  # create-cogitator-app
2
2
 
3
- Interactive CLI scaffolder for [Cogitator](https://cogitator.dev) — creates production-ready AI agent projects in seconds.
3
+ Interactive scaffolder for [Cogitator](https://cogitator.app) — creates a ready-to-run TypeScript AI agent project from one of six templates.
4
+
5
+ Guide: [cogitator.app/docs/getting-started/scaffolding](https://cogitator.app/docs/getting-started/scaffolding)
4
6
 
5
7
  ## Usage
6
8
 
@@ -11,44 +13,89 @@ npx create-cogitator-app
11
13
  # With arguments
12
14
  npx create-cogitator-app my-project --template basic --provider openai
13
15
 
14
- # Skip prompts with flags
16
+ # Skip every prompt with flags
15
17
  npx create-cogitator-app my-project -t swarm -p ollama --pm pnpm --docker --no-git
18
+
19
+ # Accept the defaults for everything not given
20
+ npx create-cogitator-app -y
21
+ npx create-cogitator-app my-project -p openai --yes
16
22
  ```
17
23
 
24
+ 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.
25
+
26
+ Requires Node.js 22.12+.
27
+
18
28
  ## Templates
19
29
 
20
- | Template | Description |
21
- | ------------ | ----------------------------------------- |
22
- | `basic` | Single agent with tools |
23
- | `memory` | Agent with Redis-backed persistent memory |
24
- | `swarm` | Multi-agent hierarchical swarm |
25
- | `workflow` | DAG workflow with sequential agent nodes |
26
- | `api-server` | Express REST API with Cogitator backend |
27
- | `nextjs` | Next.js chat app with streaming UI |
30
+ | Template | Description |
31
+ | ------------ | ------------------------------------------------------------------------ |
32
+ | `basic` | Single agent with tools |
33
+ | `memory` | Agent with Redis-backed persistent memory (`@cogitator-ai/redis`) |
34
+ | `swarm` | Hierarchical swarm of researcher, writer and reviewer agents |
35
+ | `workflow` | DAG workflow (`@cogitator-ai/workflows`) with sequential agent nodes |
36
+ | `api-server` | Express REST API with `CogitatorServer` from `@cogitator-ai/express` |
37
+ | `nextjs` | Next.js App Router chat app with a streaming `/api/chat` route, Tailwind |
28
38
 
29
39
  ## CLI Flags
30
40
 
31
- | Flag | Shorthand | Description |
32
- | -------------------------- | --------- | -------------------------------------------------------- |
33
- | `--template <name>` | `-t` | Template to use |
34
- | `--provider <name>` | `-p` | LLM provider (`ollama`, `openai`, `anthropic`, `google`) |
35
- | `--pm <name>` | | Package manager (`pnpm`, `npm`, `yarn`, `bun`) |
36
- | `--docker` / `--no-docker` | | Include Docker Compose |
37
- | `--git` / `--no-git` | | Initialize git repository |
41
+ | Flag | Shorthand | Description |
42
+ | -------------------------- | --------- | --------------------------------------------------------- |
43
+ | `[name]` | | Project directory (its basename becomes the package name) |
44
+ | `--template <name>` | `-t` | Template to use |
45
+ | `--provider <name>` | `-p` | LLM provider (`ollama`, `openai`, `anthropic`, `google`) |
46
+ | `--pm <name>` | | Package manager (`pnpm`, `npm`, `yarn`, `bun`) |
47
+ | `--docker` / `--no-docker` | | Include Docker Compose (Redis, Postgres, plus Ollama) |
48
+ | `--git` / `--no-git` | | Initialize git repository |
49
+ | `--no-install` | | Write the files without running `<pm> install` |
50
+ | `--yes` | `-y` | Don't prompt; use the defaults for every missing value |
51
+
52
+ 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`.
38
53
 
39
54
  ## Providers
40
55
 
41
- | Provider | Default Model | Requires |
42
- | ----------- | ------------------- | ---------------------------------------------- |
43
- | `ollama` | `qwen3:8b` | [Ollama](https://ollama.com) installed locally |
44
- | `openai` | `gpt-6.1-sol` | `OPENAI_API_KEY` |
45
- | `anthropic` | `claude-sonnet-5-5` | `ANTHROPIC_API_KEY` |
46
- | `google` | `gemini-3.8-flash` | `GOOGLE_API_KEY` |
56
+ | Provider | Default Model | Requires |
57
+ | ----------- | ------------------- | ---------------------------------------------------------------------------------- |
58
+ | `ollama` | `qwen3:8b` | [Ollama](https://ollama.com) (`OLLAMA_BASE_URL`, default `http://localhost:11434`) |
59
+ | `openai` | `gpt-6.1-sol` | `OPENAI_API_KEY` |
60
+ | `anthropic` | `claude-sonnet-5-5` | `ANTHROPIC_API_KEY` |
61
+ | `google` | `gemini-3.8-flash` | `GOOGLE_API_KEY` |
62
+
63
+ ## Generated Project Structure
64
+
65
+ Every project gets these files (shown for the `basic` template):
66
+
67
+ ```
68
+ my-project/
69
+ ├── src/
70
+ │ ├── index.ts # Main entry point
71
+ │ └── tools.ts # Tool definitions
72
+ ├── package.json # dev / start / build / typecheck scripts
73
+ ├── tsconfig.json # not for nextjs, which ships its own
74
+ ├── cogitator.yml # provider and default model
75
+ ├── .env.example # the provider's key (and REDIS_URL for memory)
76
+ ├── .gitignore
77
+ ├── README.md
78
+ ├── pnpm-workspace.yaml # pnpm only
79
+ └── docker-compose.yml # with --docker
80
+ ```
81
+
82
+ Template-specific sources:
83
+
84
+ | Template | Files |
85
+ | ------------ | ----------------------------------------------------------------------------------------------------------- |
86
+ | `basic` | `src/index.ts`, `src/tools.ts` |
87
+ | `memory` | `src/index.ts`, `src/tools.ts` |
88
+ | `swarm` | `src/index.ts`, `src/tools.ts`, `src/agents/{researcher,writer,reviewer}.ts` |
89
+ | `workflow` | `src/index.ts`, `src/agents.ts` |
90
+ | `api-server` | `src/index.ts`, `src/agents.ts` |
91
+ | `nextjs` | `src/lib/agent.ts`, `src/app/api/{chat,health}/route.ts`, `src/app/{page,layout}.tsx`, Next/Tailwind config |
92
+
93
+ 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`).
47
94
 
48
95
  ## Programmatic API
49
96
 
50
97
  ```ts
51
- import { scaffold, parseArgs } from 'create-cogitator-app';
98
+ import { scaffold, parseArgs, collectOptions } from 'create-cogitator-app';
52
99
  import type { ProjectOptions } from 'create-cogitator-app';
53
100
 
54
101
  const options: ProjectOptions = {
@@ -59,25 +106,21 @@ const options: ProjectOptions = {
59
106
  packageManager: 'pnpm',
60
107
  docker: false,
61
108
  git: true,
109
+ install: false, // optional, default true
62
110
  };
63
111
 
64
- await scaffold(options);
112
+ const result = await scaffold(options);
113
+ // { files: ['package.json', 'src/index.ts', ...], install: { status: 'skipped' }, git: { status: 'done' } }
114
+ if (result.install.status === 'failed') console.error(result.install.error);
115
+
116
+ // or: parse CLI arguments and prompt for the rest
117
+ const fromCli = await collectOptions(parseArgs(process.argv.slice(2)));
118
+ await scaffold(fromCli);
65
119
  ```
66
120
 
67
- ## Generated Project Structure
121
+ `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.
68
122
 
69
- ```
70
- my-project/
71
- ├── src/
72
- │ ├── index.ts # Main entry point
73
- │ └── tools.ts # Tool definitions
74
- ├── package.json
75
- ├── tsconfig.json
76
- ├── cogitator.yml # Cogitator configuration
77
- ├── .env.example
78
- ├── .gitignore
79
- └── README.md
80
- ```
123
+ 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`.
81
124
 
82
125
  ## License
83
126