create-cogitator-app 0.4.0 → 0.5.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.
- package/README.md +110 -117
- package/dist/index.js +7664 -1652
- package/dist/index.js.map +1 -1
- package/dist/lib.d.ts +797 -85
- package/dist/lib.js +8443 -1602
- package/dist/lib.js.map +1 -1
- package/package.json +7 -9
package/README.md
CHANGED
|
@@ -1,158 +1,151 @@
|
|
|
1
1
|
# create-cogitator-app
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Scaffolder for [Cogitator](https://cogitator.app): a working TypeScript agent project in one command, from a preset or a stack you pick, with tests on a mocked model, a registry of agents, Cogitator Studio, coding-agent setup and a production Dockerfile.
|
|
4
4
|
|
|
5
5
|
Guide: [cogitator.app/docs/getting-started/scaffolding](https://cogitator.app/docs/getting-started/scaffolding)
|
|
6
6
|
|
|
7
7
|
## Usage
|
|
8
8
|
|
|
9
9
|
```bash
|
|
10
|
-
#
|
|
10
|
+
# Ask for everything
|
|
11
11
|
npx create-cogitator-app
|
|
12
12
|
|
|
13
|
-
#
|
|
14
|
-
npx create-cogitator-app my-
|
|
13
|
+
# A preset with a provider
|
|
14
|
+
npx create-cogitator-app my-bot --preset rag --provider openai
|
|
15
15
|
|
|
16
|
-
#
|
|
17
|
-
npx create-cogitator-app
|
|
16
|
+
# Pick the stack yourself, ask nothing
|
|
17
|
+
npx create-cogitator-app api --app server --server fastify --memory postgres --features rag,evals --yes
|
|
18
18
|
|
|
19
|
-
#
|
|
20
|
-
npx create-cogitator-app -
|
|
21
|
-
npx create-cogitator-app my-project -p openai --yes
|
|
19
|
+
# Look before writing anything
|
|
20
|
+
npx create-cogitator-app demo --preset nextjs --dry-run --json
|
|
22
21
|
|
|
23
|
-
#
|
|
24
|
-
npx create-cogitator-app
|
|
22
|
+
# Start from an example of the repository or from a GitHub template
|
|
23
|
+
npx create-cogitator-app tutor --example core/basic-agent
|
|
24
|
+
npx create-cogitator-app bot --template github:acme/agent-templates/support-bot#v2
|
|
25
25
|
```
|
|
26
26
|
|
|
27
|
-
|
|
27
|
+
Anything the flags leave out is asked for at a terminal. With `--yes`, `--json`, without a TTY or with `CI` set nothing is asked and the defaults fill the gaps: the `my-agents` directory, the `basic` preset, Ollama with `qwen3.5:9b`, the package manager that runs the scaffolder, Docker Compose on, git on. A typo in a flag or a value is an error with the closest valid name, never a silent default.
|
|
28
28
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
With Ollama the scaffolder checks whether the model is pulled. At the prompt it offers to pull it right away, otherwise the next steps it prints include `ollama pull <model>`. With a cloud provider they include `cp .env.example .env` and the key to set.
|
|
29
|
+
After writing the files the scaffolder installs the dependencies, formats the code with the project's Biome, writes `.cogitator/scaffold.json` (hashes of what it generated, for `cogitator add`) and commits everything to a new git repository, unless the project is inside one already. With Ollama it offers to pull a missing model, with a cloud provider it checks the key you pass with `--api-key` (written to `.env`, mode 600, never printed).
|
|
32
30
|
|
|
33
31
|
Requires Node.js 22.12+.
|
|
34
32
|
|
|
35
|
-
##
|
|
36
|
-
|
|
37
|
-
|
|
|
38
|
-
|
|
|
39
|
-
| `basic`
|
|
40
|
-
| `
|
|
41
|
-
| `
|
|
42
|
-
| `
|
|
43
|
-
| `
|
|
44
|
-
| `
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
|
49
|
-
|
|
|
50
|
-
| `
|
|
51
|
-
|
|
|
52
|
-
|
|
|
53
|
-
|
|
|
54
|
-
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
33
|
+
## Presets
|
|
34
|
+
|
|
35
|
+
| Preset | What you get |
|
|
36
|
+
| ------------------ | ----------------------------------------------------------------------- |
|
|
37
|
+
| `basic` | One agent with real tools in your terminal, the best place to start |
|
|
38
|
+
| `assistant` | Workspace files with approvals, long-term memory, a scheduler and evals |
|
|
39
|
+
| `memory` | Conversations that survive restarts, in SQLite |
|
|
40
|
+
| `api-server` | Express with Swagger UI, token auth and persistent threads |
|
|
41
|
+
| `hono` | Agents behind a small, fast HTTP API |
|
|
42
|
+
| `tetsu` | Bun-native controller with OpenAPI and WebSocket |
|
|
43
|
+
| `nextjs` | Streaming chat with tool calls, approvals and saved threads |
|
|
44
|
+
| `channels` | One assistant on Telegram, Discord, Slack or WebChat |
|
|
45
|
+
| `rag` | Answers grounded in the files of `docs/` |
|
|
46
|
+
| `mcp` | Tools from an MCP server, your agents served over MCP |
|
|
47
|
+
| `swarm` | A researcher and a writer under a reviewing supervisor |
|
|
48
|
+
| `workflow` | A multi-step pipeline of agents |
|
|
49
|
+
| `durable-workflow` | A saga with compensation, an approval step and crash recovery |
|
|
50
|
+
| `a2a` | An agent other frameworks call over the Agent-to-Agent protocol |
|
|
51
|
+
| `voice-realtime` | Speech in, speech out over WebSocket |
|
|
52
|
+
| `evals` | Measure an agent on a dataset and gate CI on the score |
|
|
53
|
+
|
|
54
|
+
`--list-templates` prints them, `--template <name>` is an alias of `--preset`. A preset is only a starting point: every flag below changes it.
|
|
55
|
+
|
|
56
|
+
## Flags
|
|
57
|
+
|
|
58
|
+
| Flag | What it does |
|
|
59
|
+
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
|
|
60
|
+
| `[directory]` | Where the project goes; its last segment becomes the package name |
|
|
61
|
+
| `-t, --preset <name>` | A preset from the table above |
|
|
62
|
+
| `--template <name\|repo>` | A preset, or `github:owner/repo[/path][#ref]` to copy a repository |
|
|
63
|
+
| `--example <name[#ref]>` | A runnable example of the Cogitator repository, see `--list-examples` |
|
|
64
|
+
| `--app <kind>` | `script`, `server`, `next`, `channels`, `worker` |
|
|
65
|
+
| `--server <framework>` | `hono`, `express`, `fastify`, `koa`, `tetsu` |
|
|
66
|
+
| `--channels <list>` | `telegram`, `discord`, `slack`, `webchat` |
|
|
67
|
+
| `--memory <kind>` | `none`, `memory`, `sqlite`, `postgres`, `redis`, `mongodb` |
|
|
68
|
+
| `--vector-store <store>` | For RAG: `memory`, `postgres`, `qdrant` |
|
|
69
|
+
| `--features <list>` | Add-ons: `harness`, `mcp`, `rag`, `workflows`, `durable`, `swarms`, `evals`, `otel`, `langfuse`, `voice`, `sandbox`, `a2a` |
|
|
70
|
+
| `--deploy <target>` | `none`, `docker`, `fly` |
|
|
71
|
+
| `--[no-]docker` | `docker-compose.yml` for the local services (default on) |
|
|
72
|
+
| `-p, --provider <name>` | `ollama`, `openai`, `anthropic`, `google` |
|
|
73
|
+
| `-m, --model <id>` | The model at the provider, the provider's default otherwise |
|
|
74
|
+
| `--api-key <key>` | Written to `.env` and checked against the provider |
|
|
75
|
+
| `--pm <name>` | `pnpm`, `npm`, `yarn`, `bun` (default: the one running the scaffolder) |
|
|
76
|
+
| `--agent <list>` | Coding-agent setup: `claude`, `cursor`, `codex`, `none` |
|
|
77
|
+
| `--[no-]git`, `--[no-]install` | Create the git repository, install the dependencies (both on by default) |
|
|
78
|
+
| `--no-telemetry` | Send no anonymous usage event, see [Telemetry](https://cogitator.app/docs/getting-started/telemetry) |
|
|
79
|
+
| `-y, --yes` | Ask nothing |
|
|
80
|
+
| `--dry-run` | Show the files, dependencies, services and variables without writing anything |
|
|
81
|
+
| `--json` | Machine-readable output, implies `--yes` |
|
|
82
|
+
| `--list-templates`, `--list-examples` | List the presets or the examples |
|
|
83
|
+
|
|
84
|
+
Combinations that cannot work are refused before anything is written, with how to fix them: a Tetsu server needs Bun, voice needs a provider with realtime speech, A2A needs a server or Next.js, and so on.
|
|
85
|
+
|
|
86
|
+
## What a project contains
|
|
87
|
+
|
|
88
|
+
Every project, whatever the stack:
|
|
89
|
+
|
|
90
|
+
- `src/cogitator.ts`, the registry: the runtime configured by `cogitator.yml` and every agent, workflow and swarm by name. The entry points, the tests, `cogitator dev` and `cogitator mcp` find them there.
|
|
91
|
+
- Three working tools in `src/tools/`: `fetch_url` with an SSRF guard, `current_time`, and a `calculator` that parses instead of evaluating.
|
|
92
|
+
- Tests that run offline on `mockCogitator`, a scripted model with tool calls, and a CI workflow running typecheck, lint and tests.
|
|
93
|
+
- `src/env.ts`, a Zod schema of every variable the project reads, matching `.env.example`.
|
|
94
|
+
- `AGENTS.md` with a managed block of rules for coding agents and `CLAUDE.md` pointing at it, and the Cogitator docs of the installed version in `node_modules/@cogitator-ai/core/docs/`.
|
|
95
|
+
- Scripts: `dev`, `build`, `start`, `test`, `typecheck`, `lint`, `format`, `doctor` and `dev:studio`.
|
|
96
|
+
- With `--deploy`, a production Dockerfile from `@cogitator-ai/deploy` (multi-stage, lockfile install, non-root user, only production dependencies) and `fly.toml` for Fly.io.
|
|
97
|
+
- With `--agent`, the `cogitator` MCP server and a skill for Claude Code (`.mcp.json`, `.claude/skills`), Cursor (`.cursor/mcp.json`, `.cursor/skills`) or Codex (`.codex/config.toml`, `.agents/skills`).
|
|
98
|
+
|
|
99
|
+
The `@cogitator-ai/*` packages are pinned with a caret to the versions released with the scaffolder, and `package.json` records the spec and the command that recreate the project under `cogitator`.
|
|
100
|
+
|
|
101
|
+
## Growing a project
|
|
102
|
+
|
|
103
|
+
`cogitator add` brings what the scaffolder generates into an existing project, with the same code a new project would get:
|
|
63
104
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
| `openai` | `gpt-6.1-sol` | `OPENAI_API_KEY` |
|
|
68
|
-
| `anthropic` | `claude-sonnet-5-5` | `ANTHROPIC_API_KEY` |
|
|
69
|
-
| `google` | `gemini-3.8-flash` | `GOOGLE_API_KEY` |
|
|
70
|
-
|
|
71
|
-
## Generated Project Structure
|
|
72
|
-
|
|
73
|
-
Every project gets these files (shown for the `basic` template):
|
|
74
|
-
|
|
75
|
-
```
|
|
76
|
-
my-project/
|
|
77
|
-
├── src/
|
|
78
|
-
│ ├── index.ts # Main entry point
|
|
79
|
-
│ └── tools.ts # Tool definitions
|
|
80
|
-
├── package.json # dev / start / build / typecheck scripts
|
|
81
|
-
├── tsconfig.json # not for nextjs, which ships its own
|
|
82
|
-
├── cogitator.yml # provider, model, memory and deploy settings
|
|
83
|
-
├── .env.example # the provider's key (REDIS_URL for memory, API_TOKEN for api-server)
|
|
84
|
-
├── .gitignore # also .env.* and, for nextjs, .next/ and next-env.d.ts
|
|
85
|
-
├── README.md
|
|
86
|
-
├── pnpm-workspace.yaml # pnpm only
|
|
87
|
-
└── docker-compose.yml # with --docker
|
|
105
|
+
```bash
|
|
106
|
+
npx cogitator add rag
|
|
107
|
+
npx cogitator add --memory postgres --dry-run
|
|
88
108
|
```
|
|
89
109
|
|
|
90
|
-
|
|
110
|
+
It merges into files you changed where it can (package.json, cogitator.yml, docker-compose.yml, the managed block of AGENTS.md, .gitignore), and refuses with a diff when it cannot. See the [CLI](https://www.npmjs.com/package/@cogitator-ai/cli).
|
|
91
111
|
|
|
92
|
-
|
|
93
|
-
| ------------ | ----------------------------------------------------------------------------------------------------------- |
|
|
94
|
-
| `basic` | `src/index.ts`, `src/tools.ts` |
|
|
95
|
-
| `memory` | `src/index.ts`, `src/tools.ts` |
|
|
96
|
-
| `swarm` | `src/index.ts`, `src/tools.ts`, `src/agents/{researcher,writer,reviewer}.ts` |
|
|
97
|
-
| `workflow` | `src/index.ts`, `src/agents.ts` |
|
|
98
|
-
| `api-server` | `src/index.ts`, `src/agents.ts` |
|
|
99
|
-
| `nextjs` | `src/lib/agent.ts`, `src/app/api/{chat,health}/route.ts`, `src/app/{page,layout}.tsx`, Next/Tailwind config |
|
|
112
|
+
## Examples and templates
|
|
100
113
|
|
|
101
|
-
|
|
114
|
+
`--example core/basic-agent` turns a runnable example of the repository into a project: the example and the files it imports are fetched at the tag of the scaffolder version (`#main` or any ref after the name picks another), with a package.json, tsconfig, `.env.example` and README around them. `--list-examples` lists them.
|
|
102
115
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
The `dev` and `start` scripts of the script templates run `tsx --env-file-if-exists=.env`, so the variables in `.env` reach the app (Next.js loads `.env*` itself). Copy `.env.example` to `.env`, fill it in, then run `pnpm dev` (or `npm run dev`, `yarn dev`, `bun dev`). Generated projects declare Node.js 22.12+ in `engines`.
|
|
106
|
-
|
|
107
|
-
### Dependency versions
|
|
108
|
-
|
|
109
|
-
The `@cogitator-ai/*` packages are pinned with a caret to the versions released together with the scaffolder (for example `^0.33.0`, never `latest`), so an older cached scaffolder keeps generating projects that compile. The ranges come from the scaffolder's own manifest, where `pnpm publish` writes the versions of the packages released alongside it.
|
|
110
|
-
|
|
111
|
-
### Runtime behavior
|
|
112
|
-
|
|
113
|
-
- The script templates (`basic`, `memory`, `swarm`, `workflow`) set a non-zero exit code when the run fails, and `workflow` also fails on an error in the workflow result. `memory` and `swarm` close their connections either way.
|
|
114
|
-
- `api-server` and `nextjs` keep conversations in in-process memory (`memory: { adapter: 'memory' }`), so a thread remembers earlier turns and the thread routes of `api-server` answer. Switch the adapter to Redis, Postgres or SQLite to keep them across restarts.
|
|
115
|
-
- `api-server` listens on `127.0.0.1` in development and on `0.0.0.0` with `NODE_ENV=production` (`HOST` overrides both). With `API_TOKEN` set, every route except `/api/health`, `/api/ready`, `/api/docs` and `/api/openapi.json` needs `Authorization: Bearer <token>`, and in production the server refuses to start without it. CORS stays off unless `CORS_ORIGIN` lists the allowed origins, comma-separated.
|
|
116
|
-
- `nextjs` shows run errors in the chat and offers Stop while a reply streams. Its scripts are `dev`, `build`, `start` and `typecheck`.
|
|
117
|
-
|
|
118
|
-
### cogitator.yml
|
|
119
|
-
|
|
120
|
-
`cogitator.yml` is read by `cogitator run` and `cogitator deploy`, not by the generated code, which configures `Cogitator` in `src/` itself, so keep the provider, model and memory in both places in sync. It holds `llm.defaultProvider` and `llm.defaultModel`, the `memory` adapter (`redis` for `memory`, `memory` for `api-server` and `nextjs`) and for the servers a `deploy` section: `health.path: /api/health`, so `cogitator deploy` produces a container that reports healthy, and for `api-server` `secrets` (the provider key and `API_TOKEN`), so deploy checks they are set.
|
|
121
|
-
|
|
122
|
-
### Docker Compose
|
|
123
|
-
|
|
124
|
-
`docker-compose.yml` runs Redis and Postgres, plus Ollama when it is the provider. A one-shot `ollama-pull` service pulls the project's model into the Ollama volume once the server is healthy, so the first run does not fail on a missing model.
|
|
116
|
+
`--template github:owner/repo/path#ref` copies a repository or a directory of one. Only regular files are extracted, `workspace:` ranges of `@cogitator-ai/*` become the released versions, and a template that depends on its own monorepo is refused before anything is installed. `GITHUB_TOKEN` reaches private repositories.
|
|
125
117
|
|
|
126
118
|
## Programmatic API
|
|
127
119
|
|
|
128
120
|
```ts
|
|
129
|
-
import {
|
|
130
|
-
import type { ProjectOptions } from 'create-cogitator-app';
|
|
121
|
+
import { planProject, scaffold, type ScaffoldLogger } from 'create-cogitator-app';
|
|
131
122
|
|
|
132
|
-
const
|
|
123
|
+
const spec = {
|
|
133
124
|
name: 'my-agent',
|
|
134
|
-
|
|
135
|
-
|
|
125
|
+
preset: 'basic',
|
|
126
|
+
app: 'script',
|
|
127
|
+
memory: 'sqlite',
|
|
136
128
|
provider: 'ollama',
|
|
137
|
-
model: 'qwen3.5:
|
|
129
|
+
model: 'qwen3.5:4b',
|
|
138
130
|
packageManager: 'pnpm',
|
|
139
|
-
|
|
140
|
-
git: true,
|
|
141
|
-
install: false, // optional, default true
|
|
142
|
-
};
|
|
131
|
+
} as const;
|
|
143
132
|
|
|
144
|
-
const
|
|
145
|
-
|
|
146
|
-
if (result.install.status === 'failed') console.error(result.install.error);
|
|
133
|
+
const plan = planProject(spec);
|
|
134
|
+
console.log(plan.files.length, plan.command);
|
|
147
135
|
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
136
|
+
const log: ScaffoldLogger = {
|
|
137
|
+
start: (message) => console.log(`... ${message}`),
|
|
138
|
+
done: (message) => console.log(`ok ${message}`),
|
|
139
|
+
fail: (message) => console.log(`!! ${message}`),
|
|
140
|
+
warn: (message) => console.log(`?? ${message}`),
|
|
141
|
+
};
|
|
142
|
+
const result = await scaffold(spec, { directory: './my-agent', install: true, git: true, log });
|
|
143
|
+
if (result.install.status === 'failed') console.error(result.install.error.message);
|
|
151
144
|
```
|
|
152
145
|
|
|
153
|
-
`
|
|
146
|
+
`planProject(spec)` is pure: it validates the spec, refuses combinations that cannot work (`IncompatibleSpecError` with the issues) and returns the files, dependencies, scripts, environment, services and the command that recreates the project. `scaffold(spec, options)` writes the plan, installs, formats, writes the lock and commits; the `log` option replaces the CLI's spinners, and a failed install, format or git step is reported in the result (`{ status: 'done' | 'skipped' | 'failed' }`) instead of thrown.
|
|
154
147
|
|
|
155
|
-
|
|
148
|
+
Also exported: `planAdd` and `addToProject` behind `cogitator add`, `createFromExample` and `createFromTemplate`, the catalogs (`PRESETS`, `FEATURE_CHOICES` and the rest), `compatibilityIssues`, `checkApiKey`, the Ollama helpers and the telemetry functions.
|
|
156
149
|
|
|
157
150
|
## License
|
|
158
151
|
|