# init-config

`dev-cockpit init-config` writes a starter `cockpit.yaml` at the current working directory. Two modes:

```
dev-cockpit init-config [--with-docker] [-f|--force]      # static template
dev-cockpit init-config -i [-f|--force]                    # interactive wizard
```

## Flags

| Flag                 | Default | Effect                                                                                        |
|----------------------|---------|-----------------------------------------------------------------------------------------------|
| `-i, --interactive`  | off     | Walk through prompts to populate the file. Skips the static template.                         |
| `--with-docker`      | off     | Uncomments the `docker:` block in the static template (ignored in `--interactive` mode).      |
| `-f, --force`        | off     | Overwrites an existing `cockpit.yaml` instead of refusing.                                    |

## Static template

`version: 2` and `appName` are required and uncommented. Everything else (processes, repos, docker, highlights, health, actions, help, notifications, mounts) ships as a commented example. Best when you already know what you want — fastest path from scratch to "edit me".

## Interactive wizard

The recommended path the first time you set the cockpit up on a project. Eight steps, with project sniffing pre-populating sensible defaults so you usually just press enter:

| Step | Section | What it asks + auto-detects |
|------|---------|------------------------------|
| 1 | **App name** | Defaults to `package.json` `name`, then the cwd basename. |
| 2 | **Docker** | Detects `compose.yaml` / `docker-compose.yml` and parses its services. Offers them as a multi-select. Skip entirely for non-compose projects. |
| 3 | **Processes** | Surfaces `package.json` scripts (`dev`, `watch`, `start`, `serve`) as pre-checked candidates. Anything that runs forever and writes to stdout — `vite`, `tsc --watch`, `php artisan serve`, `tail -f storage/logs/laravel.log` — fits here. |
| 4 | **Targets** | Detects npm/yarn/pnpm workspaces; falls back to a single `.` entry. Each becomes a row in the Targets pane. The way to attach keystrokes to a repo is the Actions step (step 7), with `scope: repos:<id>` + `key:`. |
| 5 | **Highlights** | Regex patterns that re-colour matching Output lines. `error`-severity matches additionally feed the Recent Errors strip + OS notifications. Patterns now apply to process stdout/stderr too — not just docker logs. |
| 6 | **Health** | Test-and-fix pairs. Pick one of the five built-in types (`container-running`, `port-open`, `http-ok`, `file-exists`, `exec-zero`), supply the type-specific arg(s), then bind a single-keystroke remediation. Add as many checks as you like — same type repeats freely. `container-running` is hidden when no docker block was declared. |
| 7 | **Actions** | One-shot shell commands surfaced through the `:` palette and/or bound to a single keypress. Auto-seeds from `package.json` scripts (`test`, `build`, `lint`, `format`, `typecheck`) with sensible default keys (`t`, `b`, `l`, `f`). Custom actions can be added inline. Distinct from processes (long-running) and health (state-checked). |
| 8 | **Notifications** | Toggle native OS notifications on state transitions. |

After writing the file, the wizard offers to run `dev-cockpit doctor` immediately so you get instant feedback that the config parses + each declared health check has a baseline state.

The wizard scaffolds a *working* config. Anything more advanced (custom triggers, `expectStatus`, exec args, mounts, profile namespaces) is a hand-edit on the generated file.

## Profile-contributed steps

Profiles can append their own wizard steps via `Profile.wizardSteps?: WizardStep[]`. Each step runs after step 8 (Notifications) and before the final summary. Step output (YAML lines, returned from `run(ctx)`) lands under `profile.<appName>:` in the generated cockpit.yaml — the namespace defined by [ADR 0005](../adr/0005-strict-profile-namespace.md).

```ts
import type { Profile, WizardStep } from 'dev-cockpit';

const gitlabStep: WizardStep = {
  id: 'gitlab-config',
  title: 'GitLab integration',
  description: 'Where does this project live in your gitlab?',
  async run(ctx) {
    const host = await ctx.prompts.input({ message: 'GitLab host', default: 'gitlab.com' });
    return ['gitlab:', `  host: ${host}`];
  },
};

export const myProfile: Profile = {
  appName: 'myapp',
  wizardSteps: [gitlabStep],
};
```

Step context (`ctx`) exposes the lazy-loaded `prompts` (inquirer subset), `hints` (sniffed project metadata), `workspaceRoot`, and a read-only snapshot of the core-step answers via `result`.

## Profile-driven defaults

When a profile is active (e.g. `<profile-bin> init-config -i`), the wizard defaults `appName` to the profile's `appName`. Profile bundles can also register their own `init-config` via `setupCli(program)` if they want a domain-specific template — the generic command is skipped when the profile claims the slot.

## Schema reference

The full schema definition lives at [config-reference.md](./config-reference.md).
