feat(cli): drt init --template <connector> + README quickstart rewrite (closes #545)#564
Merged
Conversation
closes #545) Eighth slice of the Tech Foundation Hardening epic (#538). Closes the last UX gap on the v0.7.5 Wave 1 list. The README's old 5-step quickstart had users (1) install (2) run the interactive wizard (3) seed sample DuckDB data (4) hand-author a sync YAML (5) run. Steps 2 and 4 were the friction — every newcomer typed something different and roughly half mistyped. Replaces the path with a single command: $ drt init --template duckdb_to_rest Three curated templates ship in this PR (per #545's scoping): - duckdb_to_rest — DuckDB → REST API POST (httpbin.org, no accounts) - postgres_to_slack — PostgreSQL → Slack webhook (operational alerts) - duckdb_to_hubspot — DuckDB → HubSpot contacts upsert Each template is a static, self-contained sync YAML living under ``drt/cli/templates/syncs/``. ``drt init --template list`` enumerates them; ``drt init --template <name>`` writes ``syncs/<name>.yml`` plus a minimal ``drt_project.yml`` + ``.drt/.gitignore`` shell and prints per-template next-steps text (env vars to set, sample tables to seed). Design notes ------------ - **Static files, not Jinja-rendered.** The on-disk template is what the user gets — no per-invocation substitution. Edits are then the user's domain. Keeps the scaffolding step boring and predictable. - **Project shell is created if missing, never overwritten.** Running ``--template <name>`` in a directory with an existing ``drt_project.yml`` appends only the new sync file; the project metadata stays put. - **Registry lives at ``drt/cli/_init_templates.py``.** Each ``TemplateInfo`` carries name + description + next-steps tuple, so the CLI handler can render both ``--template list`` and the post- scaffold guidance from one source of truth. README quickstart ----------------- Rewritten end-to-end: - New quickstart fits in one ``bash`` block: install + ``init --template`` + seed + run. Three commands, copy-paste friendly. - "Other starter templates" subsection lists the other two and points at ``--template list`` for the live set. - "Customizing your sync" subsection demotes the interactive wizard to advanced usage — it still exists, just not the default path. - Links added to ``docs/connectors/`` and to the new ``drt sources --detailed`` / ``drt destinations --detailed`` flags from #543, both as a discovery hint above the Connectors table and in the new "Customizing" subsection. Tests ----- ``tests/unit/test_cli_init_templates.py`` — 9 tests: - ``--template list`` exits 0 and surfaces every registered template - Per-template (parameterized × 3): scaffolds the expected project shell, sync file lands under ``syncs/``, next-steps text prints - ``--template`` does not overwrite an existing ``drt_project.yml`` - ``--template invalid_name`` exits 1 with a pointer to ``list`` - **Validation parity (parameterized × 3)**: each shipped template YAML parses as a ``SyncConfig`` via Pydantic. Fails fast if a template is shipped that ``drt validate`` would reject — i.e. the "ready to run" bar the issue calls for. Local verification ------------------ pytest tests/ → 1185 passed, 1 skipped, 7 deselected ruff check drt tests → All checks passed mypy drt → Success: no issues in 96 files Out of scope (follow-ups) ------------------------- - Quickstart GIF / asciinema (#282) lives in v0.8. This PR rewrites the text that the GIF will eventually record. - README.ja.md updated in a follow-up commit so the i18n-sync marker hash can reference this commit. Refs: #538 (epic), #545 (this issue), #543 (companion UX work — ``--detailed`` flags discovered from the new Connectors note), #282 (future GIF), #297 (v0.9 plugin system — third-party connectors can register templates the same way). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Mirrors the README.md changes from the previous commit: - Quickstart collapsed to a three-command block using ``drt init --template duckdb_to_rest`` - "Other starter templates" subsection - "Customizing your sync" subsection demoting the interactive wizard - ``docs/connectors/`` discovery hint above the Connectors table Updates the i18n-sync marker hash to the previous commit so ``make check-i18n`` returns to clean. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #545. Eighth slice of the Tech Foundation Hardening epic #538. Closes the last UX gap on the v0.7.5 Wave 1 list.
Why
The README's old 5-step quickstart had users (1) install (2) run the interactive wizard (3) seed sample DuckDB data (4) hand-author a sync YAML (5) run. Steps 2 and 4 were the friction — every newcomer typed something different and roughly half mistyped. This PR collapses the path to a single command:
```bash
$ drt init --template duckdb_to_rest
```
Three curated starter templates
Each is a static, self-contained sync YAML under `drt/cli/templates/syncs/`. `drt init --template list` enumerates them; `drt init --template ` writes `syncs/.yml` plus a minimal `drt_project.yml` + `.drt/.gitignore` shell and prints per-template next-steps text (env vars, sample tables).
Design notes
README rewrite
README.ja.md mirrored in a second commit with the i18n-sync marker updated.
Tests
`tests/unit/test_cli_init_templates.py` — 9 tests:
Files
Local verification
```
$ pytest tests/ → 1185 passed, 1 skipped, 7 deselected
$ ruff check drt tests → All checks passed!
$ mypy drt → Success: no issues in 96 files
$ make check-i18n → OK
```
Out of scope (follow-ups)
Coordination
drt sources --detailed/drt destinations --detailed#543 (`--detailed` flags) — the new "Customizing" subsection points at themTest plan
🤖 Generated with Claude Code