# install

Scaffold the canonical Flutter consumer project structure and install the fast-CLI wrapper in a single step. Running `install` produces `bin/dispatcher.dart`, the two generated barrels, and `bin/dowel`, then injects `dowel` into `pubspec.yaml` so every future `plugin:install` and `make:command` invocation resolves cleanly.

- [Prerequisites](#prerequisites)
- [Basic Usage](#basic-usage)
- [Synopsis](#synopsis)
- [What It Writes](#what-it-writes)
- [Pubspec Injection](#pubspec-injection)
- [Idempotency](#idempotency)
- [Fast-CLI Auto-Chain](#fast-cli-auto-chain)
- [Examples](#examples)
- [Related Documentation](#related-documentation)

---

## Prerequisites

Add `dowel` to the project before invoking `install`. The package needs to resolve from `pubspec.yaml` so the substrate CLI is discoverable via `dart run`:

```bash
dart pub add dowel
```

`install` checks the dependency at scaffold time and adds it only when the pubspec has no `dowel` entry (see [Pubspec Injection](#pubspec-injection)), so the pub-add step never conflicts with the scaffold's own pubspec writes.

A project that still carries files generated by `fluttersdk_artisan` is a migration, not a fresh install: see [Migrating from fluttersdk_artisan](https://anilcancakir.com/dowel/docs/v1.0/getting-started/migrating-from-fluttersdk-artisan.md).

---

## Basic Usage

```bash
dart run dowel install
```

Run once in a new Flutter project root. The command reads the project name from `pubspec.yaml`, writes the artefacts listed below, and prints a summary. After this completes, use the consumer wrapper alias:

```bash
dart run dowel <cmd>
```

or, after the fast-CLI build finishes:

```bash
./bin/dowel <cmd>
```

---

## Synopsis

Full signature as declared in `lib/src/commands/install_command.dart`:

```
install
  {--force : Overwrite files even when they already exist}
```

| Flag | Effect |
|:---|:---|
| `--force` | Overwrite `bin/dispatcher.dart`, the two generated barrels, and `bin/dowel` even when they are already present, and skip the stop on a file generated by `fluttersdk_artisan`. Does not re-inject already-present pubspec entries. |

Exit code `0` on success, `1` when `pubspec.yaml` has no `name:` or when a generated file still comes from `fluttersdk_artisan` (see below), otherwise the exit code of the chained `make:fast-cli`.

### Stops on files from fluttersdk_artisan

When `bin/dispatcher.dart`, `lib/app/_plugins.g.dart` or `lib/app/commands/_index.g.dart` still imports `package:fluttersdk_artisan/`, or names a class the old package exported (`ArtisanCommand`, `ArtisanServiceProvider` and the rest dowel renamed) or `runArtisan`, `install` writes nothing and exits `1`. It prints every leftover it found and the migration steps, because each of those files would otherwise be skipped as already present and the build that follows would fail on its imports. `install` runs from the substrate itself, never through the project's `bin/dispatcher.dart`, so the old dispatcher cannot intercept it. The real message is quoted in [Migrating from fluttersdk_artisan](https://anilcancakir.com/dowel/docs/v1.0/getting-started/migrating-from-fluttersdk-artisan.md#what-dowel-detects).

---

## What It Writes

`install` produces these artefacts in this order:

### 1. `bin/dispatcher.dart`

A generated CLI entry point that wires the consumer's own commands and plugin providers into the dowel runtime. The file is written from the `dispatcher.dart.stub` template with `{{ name }}` substituted to the `pubspec.yaml` project name. Header comment: ``GENERATED by the `install` command. DO NOT EDIT.``

Structure:
- imports `package:<name>/app/commands/_index.g.dart as consumer_commands`
- imports `package:<name>/app/_plugins.g.dart as plugins`
- defines `_ConsumerCommandsProvider extends DowelServiceProvider` registering the consumer barrel
- `main(List<String> args)` calls `runDowel(args, baseProviders: [_ConsumerCommandsProvider(), ...plugins.autoDiscoveredProviders()], delegateToConsumer: false, collectMcpTools: args.isNotEmpty && args.first == 'mcp:serve')`

The `collectMcpTools` parameter is conditionally enabled only when the command is `mcp:serve`, so plugin providers' MCP tools register for the server without overhead on non-MCP CLI invocations.

### 2. `lib/app/_plugins.g.dart`

The plugins codegen barrel. Written as an empty-but-valid barrel on first install. `plugin:install` and `plugins:refresh` regenerate this file when plugins are added or removed. Never edit by hand: the source of truth is `.dowel/plugins.json`.

### 3. `lib/app/commands/_index.g.dart`

The commands codegen barrel. Written as an empty-but-valid barrel on first install. `make:command` and `commands:refresh` regenerate this file as new command files appear under `lib/app/commands/`. Never edit by hand.

### 4. `bin/dowel` (via Fast-CLI Auto-Chain)

A POSIX shell wrapper written by the `make:fast-cli` sub-command, which `install` calls in-process at the end of the scaffold phase. See [Fast-CLI Auto-Chain](#fast-cli-auto-chain) for details.

---

## Pubspec Injection

`install` injects a `dowel` dependency into `pubspec.yaml` after writing the artefacts, unless `dependencies` or `dev_dependencies` already declares `dowel`: an existing entry keeps its constraint, whatever it is. Two injection modes when there is none:

**Path-dep mode (monorepo)**

When `.dart_tool/package_config.json` lists `dowel` with a *relative* `rootUri` (sibling-package monorepo workflow), `install` resolves the path against the consumer root and writes a `path:` dependency:

```yaml
dependencies:
  dowel:
    path: ../dowel
```

A `file://` absolute URI or any other absolute `rootUri` (the shape pub-cache produces) skips this branch and falls through to pub.dev mode.

**Pub.dev mode**

When no local relative-rootUri entry resolves, `install` injects a caret constraint on the dowel version that is running (`dowel: ^<running version>`), so the next `dart pub get` (or `flutter pub get`) resolves the same release.

The injection is idempotent: if `pubspec.yaml` already contains a `dowel:` key under `dependencies:` or `dev_dependencies:`, neither form is written again (regardless of `--force`). A plugin's `pubspec` section follows the same rule for its own dependencies, and `plugin:uninstall` leaves a dependency the project already declared in place.

---

## Idempotency

Re-running `install` without `--force` is a no-op when the artefacts already exist. Each file goes through a `_shouldWrite(path, force)` guard: if the file exists and `force` is false, the write is skipped and a `[skip]` line is printed for that artefact. The pubspec injection is always idempotent (key presence check, independent of `--force`).

Pass `--force` to overwrite all the artefacts unconditionally. Useful after renaming the project or updating the stub template to a newer version:

```bash
dart run dowel install --force
```

`--force` is forwarded to the `make:fast-cli` auto-chain as well, so `bin/dowel` is rewritten and the AOT binary is recompiled from scratch.

---

## Fast-CLI Auto-Chain

At the end of `scaffoldInto`, `install` calls `MakeFastCliCommand.scaffoldInto(root, force, ctx)` in-process. This produces `bin/dowel`, compiles the AOT binary under `.dowel/cli-bundle/`, and patches `.gitignore` with the cache entries only (`.dowel/cli-bundle*`, `.dowel/build.stamp*` and `.dowel/.dowel.lock/`; a bare `.dowel/` line is replaced by them, so `.dowel/plugins.json` and `.dowel/installed/` stay trackable). The call happens only after all scaffold writes and pubspec injection succeed, so a partial failure in the scaffold phase does not leave a compiled binary that references a missing dispatcher.

The fast-CLI step is not separately gated: if `dart build cli` fails (e.g. the toolchain is missing or the build itself errors), `make:fast-cli` returns a non-zero exit code and `install` propagates that failure. The scaffold artefacts written before the failure remain on disk so the project is still usable via `dart run dowel <cmd>` (the slower fallback). Re-running `install --force` after fixing the underlying issue recompiles `bin/dowel` and the AOT cache.

See [make:fast-cli](https://anilcancakir.com/dowel/docs/v1.0/commands/make-fast-cli.md) for the full performance profile, cache-hit behaviour, and POSIX-only caveat.

---

## Examples

### 1. Fresh install in a new Flutter project

```bash
flutter create my_app
cd my_app
dart pub add dowel
dart run dowel install
```

Output (colour codes omitted):
```
✓ Created: /path/to/my_app/bin/dispatcher.dart
✓ Created: /path/to/my_app/lib/app/_plugins.g.dart
✓ Created: /path/to/my_app/lib/app/commands/_index.g.dart
 ℹ Install scaffold complete (3 written, 0 skipped). Chaining make:fast-cli for bin/dowel setup.
✓ Created: /path/to/my_app/bin/dowel
Compiling dispatcher...
Generating snapshot for dispatcher...
Generated: /path/to/my_app/.dowel/cli-bundle/bundle/bin/dispatcher

✓ dowel: ready. Run ./bin/dowel <cmd> for a startup of about 0.2 s.
```

### 2. Force-overwrite after project rename

```bash
dart run dowel install --force
```

Regenerates `bin/dispatcher.dart` with the updated project name and recompiles `bin/dowel`.

### 3. Monorepo path-dep install

In a monorepo where `dowel` lives at `../dowel`, run `flutter pub get` once to populate `.dart_tool/package_config.json`, then:

```bash
dart run dowel install
```

The path-dep form is detected automatically and written to `pubspec.yaml`. No flag needed.

---

## Related Documentation

- [make:command](https://anilcancakir.com/dowel/docs/v1.0/commands/index.md): scaffold a single `DowelCommand` subclass under `lib/app/commands/` and regenerate `_index.g.dart`.
- [plugin:install](https://anilcancakir.com/dowel/docs/v1.0/commands/plugin-install.md): register a third-party plugin after `flutter pub add`; requires the `lib/app/_plugins.g.dart` barrel that `install` writes.
- [make:fast-cli](https://anilcancakir.com/dowel/docs/v1.0/commands/make-fast-cli.md): the sub-command auto-chained by `install`; run it standalone to rebuild `bin/dowel` without touching the scaffold artefacts.
- [Getting Started: Installation](https://anilcancakir.com/dowel/docs/v1.0/getting-started/installation.md): step-by-step walkthrough from `dart pub add` to first `./bin/dowel status` for both vanilla Flutter and magic-stack projects.
- [Migrating from fluttersdk_artisan](https://anilcancakir.com/dowel/docs/v1.0/getting-started/migrating-from-fluttersdk-artisan.md): what `install` stops on and the steps it prints.
