# make:fast-cli

Scaffold a POSIX shell wrapper (`bin/dowel`) and AOT-compiled dowel binary for a startup of about 0.2 s, against 0.4 to 2.7 s for `dart run`, which resolves and runs its build hooks on every cold start.

- [Basic Usage](#basic-usage)
- [Synopsis](#synopsis)
- [What It Does](#what-it-does)
- [Output](#output)
- [Re-running](#re-running)
- [Staleness Detection](#staleness-detection)
- [Performance](#performance)
- [Caveats](#caveats)
- [Related Documentation](#related-documentation)

---

## Basic Usage

```bash
dart run dowel make:fast-cli
```

Writes `bin/dowel` (POSIX shell wrapper, executable), `.dowel/cli-bundle/` (compiled binary + runtime libraries) and `.dowel/build.stamp` (staleness marker), and patches `.gitignore` to ignore that cache. Caches the build result so subsequent invocations are cached (about 0.2 s on a hit).

---

## Synopsis

```
make:fast-cli {--force : Overwrite bin/dowel even when it already exists}
```

| Option | Description |
|:---|:---|
| `--force` | Rewrite `bin/dowel` and recompile the binary, even if a cached version exists. |

---

## What It Does

1. **Validates the project structure.** Checks for `pubspec.yaml` and `bin/dispatcher.dart`; errors with actionable guidance if either is missing.

2. **Scaffolds the wrapper script.** Writes a POSIX `sh` script at `bin/dowel` that resolves symlinks via a portable `follow_links()` subshell and derives the project root at runtime.

3. **Computes a staleness key.** Captures the SHA256 hash of `pubspec.lock` and the Dart SDK version string, storing both in `.dowel/build.stamp` for later comparison.

4. **Compiles the binary.** Runs `dart build cli -t bin/dispatcher.dart -o .dowel/cli-bundle`, producing an AOT-native binary at `.dowel/cli-bundle/bundle/bin/dispatcher`.

5. **Patches `.gitignore`.** Appends the cache entries `.dowel/cli-bundle*`, `.dowel/build.stamp*` and `.dowel/.dowel.lock/` when they are missing, so the compiled cache is never tracked. The globs also cover the scratch paths of a build: `bin/dowel` compiles into `.dowel/cli-bundle.build.<pid>`, parks the old bundle at `.dowel/cli-bundle.old.<pid>` and stages the stamp at `.dowel/build.stamp.tmp`. The rest of `.dowel/` is source of truth and stays trackable: `plugins.json` is the registry `lib/app/_plugins.g.dart` is generated from, `installed/` holds the install records and `mcp.json` is the tool filter. A bare `.dowel/` line, which earlier versions wrote, is replaced by the three entries, because it also ignored `plugins.json`. Idempotent.

---

## Output

- **`bin/dowel`** (executable, ~50 LoC): shell wrapper that checks staleness, auto-recompiles if needed, then execs into the binary.
- **`.dowel/cli-bundle/bundle/bin/dispatcher`**: AOT-compiled native executable.
- **`.dowel/cli-bundle/bundle/lib/*.dylib`** (on macOS; `.so` on Linux): runtime libraries bundled with the binary.
- **`.dowel/build.stamp`**: one-line file with `<pubspec_lock_sha256>:<dart_sdk_version>`. Lets the wrapper detect when to rebuild.

---

## Re-running

Run `make:fast-cli` again without `--force`: the wrapper detects `bin/dowel` already exists and skips the override.

Run with `--force`: rewrites the wrapper and recompiles.

The wrapper script itself is the source of truth for staleness detection. When the user runs `./bin/dowel <cmd>` and the Dart SDK updates or `pubspec.lock` changes, the wrapper notices (inside the lock-acquire section) and transparently rebuilds. No manual re-run needed.

---

## Staleness Detection

The wrapper's `needs_build()` function triggers a rebuild when any of these conditions hold:

1. **Binary missing.** The compiled executable at `.dowel/cli-bundle/bundle/bin/dispatcher` does not exist.

2. **Stamp file missing or empty.** The `.dowel/build.stamp` file is absent or has zero size.

3. **Stamp file content mismatches.** The stored compile key (format: `<sha256-of-pubspec.lock>:<dart-sdk-version>`) differs from the current key, meaning either the lock or the SDK changed.

4. **`pubspec.yaml` modified since last build.** The mtime of `pubspec.yaml` is newer than the stamp file's mtime, detected via the `-nt` (newer than) operator.

5. **`lib/app/_plugins.g.dart` modified since last build.** The mtime of `lib/app/_plugins.g.dart` is newer than the stamp file's mtime. It invalidates the cache when `plugin:install` or `plugins:refresh` regenerates the file.

6. **`lib/app/commands/_index.g.dart` modified since last build.** The mtime of the commands index is newer than the stamp file's mtime. It catches a hand-edited index. `commands:refresh` and `make:command` also delete `.dowel/build.stamp` after writing the index, so the next `./bin/dowel` call rebuilds under condition 2 even in the same second; the compiled bundle stays until the rebuild replaces it.

Any match triggers a recompile inside the lock-acquire section. The re-check inside the lock prevents redundant builds when multiple invocations race.

### The build lock

`.dowel/.dowel.lock/` is a directory created with an atomic `mkdir` and holds the owner's pid. It is held only while building: the wrapper removes it and clears its trap before `exec`ing the binary, because `exec` replaces the shell and a trap would never run, which used to leave a long-lived `mcp:serve` holding the lock for its whole life. A dead owner's lock is reclaimed through a `kill -0` probe; a live owner is waited on for at most `DOWEL_LOCK_TIMEOUT` seconds (default 600), after which the call fails and names the pid. A build compiles into `.dowel/cli-bundle.build.<pid>` and is swapped in by rename, so a binary another process is running is never overwritten; leftovers from a killed build are removed by the next build.

---

## Performance

### Cache hit (wrapper runs existing binary)

```bash
time ./bin/dowel status
# real 0m0.170s
# user 0m0.010s
# sys  0m0.010s
```

About 0.2 s round-trip (0.17 to 0.35 s over six runs of `status` on the example app) on a modern machine (no `dart run`, no "Running build hooks..." overhead).

### Cache miss (first run or staleness detected)

```bash
time dart run dowel make:fast-cli
# Building dowel CLI (one-time, ~5s)...
# real 0m8.234s
```

~8 seconds (depends on machine and dependency size). The wrapper prints "Building dowel CLI..." so users know a compile is in progress and not to interrupt.

### Comparison with `dart run`

```bash
time dart run dowel status
# real 0m0.650s
# (warm; the first run after a dependency change took 1.7 s for `status` and 2.7 s for `list`)

time ./bin/dowel status
# real 0m0.170s
# (cached; about 4x faster than a warm `dart run`, about 10x faster than a first run)
```

---

## Caveats

**POSIX only (macOS and Linux).** Windows users use `dart run dowel <cmd>`; there is no `.cmd` variant.

**No cross-compilation.** The compiled binary targets the local machine architecture and OS. Distributing the binary to a different architecture or OS requires re-running `make:fast-cli` on that target.

---

## Related Documentation

- [make:command](https://anilcancakir.com/dowel/docs/v1.0/commands/index.md): scaffold a single `DowelCommand` subclass.
- [make:plugin](https://anilcancakir.com/dowel/docs/v1.0/commands/make-plugin.md): scaffold a full plugin package.
- [install](https://anilcancakir.com/dowel/docs/v1.0/commands/install.md): initialise a dowel consumer project structure.
