create-cogitator-app 0.3.1 → 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.
Files changed (7) hide show
  1. package/README.md +113 -88
  2. package/dist/index.js +7764 -1370
  3. package/dist/index.js.map +1 -1
  4. package/dist/lib.d.ts +808 -58
  5. package/dist/lib.js +8441 -1309
  6. package/dist/lib.js.map +1 -1
  7. package/package.json +7 -2
package/README.md CHANGED
@@ -1,126 +1,151 @@
1
1
  # create-cogitator-app
2
2
 
3
- Interactive scaffolder for [Cogitator](https://cogitator.app) — creates a ready-to-run TypeScript AI agent project from one of six templates.
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
- # Interactive mode
10
+ # Ask for everything
11
11
  npx create-cogitator-app
12
12
 
13
- # With arguments
14
- npx create-cogitator-app my-project --template basic --provider openai
13
+ # A preset with a provider
14
+ npx create-cogitator-app my-bot --preset rag --provider openai
15
15
 
16
- # Skip every prompt with flags
17
- npx create-cogitator-app my-project -t swarm -p ollama --pm pnpm --docker --no-git
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
- # Accept the defaults for everything not given
20
- npx create-cogitator-app -y
21
- npx create-cogitator-app my-project -p openai --yes
22
- ```
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
-
28
- ## Templates
29
-
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 |
38
-
39
- ## CLI Flags
40
-
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 |
19
+ # Look before writing anything
20
+ npx create-cogitator-app demo --preset nextjs --dry-run --json
51
21
 
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`.
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
+ ```
53
26
 
54
- ## Providers
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.
55
28
 
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` |
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).
62
30
 
63
- ## Generated Project Structure
31
+ Requires Node.js 22.12+.
64
32
 
65
- Every project gets these files (shown for the `basic` template):
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:
66
104
 
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
105
+ ```bash
106
+ npx cogitator add rag
107
+ npx cogitator add --memory postgres --dry-run
80
108
  ```
81
109
 
82
- Template-specific sources:
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).
83
111
 
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 |
112
+ ## Examples and templates
92
113
 
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`).
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.
115
+
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.
94
117
 
95
118
  ## Programmatic API
96
119
 
97
120
  ```ts
98
- import { scaffold, parseArgs, collectOptions } from 'create-cogitator-app';
99
- import type { ProjectOptions } from 'create-cogitator-app';
121
+ import { planProject, scaffold, type ScaffoldLogger } from 'create-cogitator-app';
100
122
 
101
- const options: ProjectOptions = {
123
+ const spec = {
102
124
  name: 'my-agent',
103
- path: '/path/to/my-agent',
104
- template: 'basic',
125
+ preset: 'basic',
126
+ app: 'script',
127
+ memory: 'sqlite',
105
128
  provider: 'ollama',
129
+ model: 'qwen3.5:4b',
106
130
  packageManager: 'pnpm',
107
- docker: false,
108
- git: true,
109
- install: false, // optional, default true
110
- };
131
+ } as const;
111
132
 
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);
133
+ const plan = planProject(spec);
134
+ console.log(plan.files.length, plan.command);
115
135
 
116
- // or: parse CLI arguments and prompt for the rest
117
- const fromCli = await collectOptions(parseArgs(process.argv.slice(2)));
118
- await scaffold(fromCli);
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);
119
144
  ```
120
145
 
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.
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.
122
147
 
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`.
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.
124
149
 
125
150
  ## License
126
151