Skip to content

Add dft init for dbt-native repo bootstrap

Problem

Implement a first-class dft project bootstrap command for existing repos, especially dbt repos that will store dashboards under /faces. The command should detect dbt_project.yml, create or validate faces/ and optional dataface.yml, scaffold starter dashboards or partials, and avoid manual setup steps currently described only in docs. It should support the analytics repo as an internal example-customer path for future M2 dashboard authoring.

Context

  • Dataface already assumes a dbt-native repo layout with faces/ as the canonical dashboard directory.
  • The docs describe a manual workflow rather than a first-class bootstrap command:
  • docs/docs/guides/installation.md
  • docs/docs/guides/cli-reference.md
  • The CLI currently has validate, compile, serve, render, inspect, agent, and mcp commands, but no repo/project bootstrap command:
  • dataface/cli/main.py
  • Existing runtime behavior already auto-detects dbt project markers and repo structure in several places:
  • apps/playground/routes.py
  • apps/playground/file_watcher.py
  • IDE detection paths under apps/ide/vscode-extension/
  • The expected near-term analyst workflow is to add Dataface to an existing dbt repo, especially the internal analytics repo at /Users/dave.fowler/Fivetran/analytics, and start authoring dashboards in /faces.
  • Today that requires users to know multiple undocumented or weakly-enforced conventions:
  • create faces/
  • optionally add dataface.yml
  • understand where starter dashboards/partials should go
  • understand how Dataface discovers the dbt project root
  • For M1 analyst work, this needs to become a predictable, low-friction command rather than a docs-only setup ritual.

Possible Solutions

Option 1: Improve docs only

  • Expand installation and getting-started docs with an "existing dbt repo" recipe.
  • Pros:
  • Lowest engineering effort
  • No CLI surface expansion
  • Cons:
  • Does not reduce analyst setup friction
  • Easy to get slightly wrong in real repos
  • Hard to enforce conventions consistently

Option 2: Add a minimal dft init that only creates missing files

  • Add a CLI command that detects a dbt repo and creates faces/, faces/partials/, and optional dataface.yml.
  • Pros:
  • Solves the main bootstrap problem
  • Small surface area
  • Cons:
  • May still leave users without a useful starter workflow
  • Risks becoming a thin wrapper around mkdir
  • Add a first-class bootstrap command that:
  • detects dbt repo/project root
  • confirms whether Dataface is already initialized
  • creates faces/, faces/partials/, and optional dataface.yml
  • scaffolds starter files
  • supports safe re-runs without clobbering existing work
  • prints next-step guidance tailored to the detected repo
  • Pros:
  • Matches the actual intended product workflow
  • Gives analysts a single obvious command
  • Establishes one canonical repo shape for future docs, IDE, and CI support
  • Cons:
  • More implementation work
  • Requires decisions on template defaults and overwrite behavior

Plan

  1. Define the desired bootstrap contract for existing dbt repos.
  2. Inputs: current working directory or explicit --project-dir
  3. Detection: dbt_project.yml, existing faces/, existing dataface.yml
  4. Outputs: initialized repo layout plus clear terminal guidance
  5. Add a new CLI command surface, likely dft init, in the main CLI.
  6. Implement project-root discovery and idempotent filesystem setup.
  7. Add starter templates.
  8. Minimum viable set:
    • faces/hello.yml or equivalent starter face
    • faces/partials/_header.yml if helpful
    • optional dataface.yml
  9. Decide and implement safe overwrite policy.
  10. Create missing files by default
  11. Refuse to overwrite existing files unless an explicit force flag exists
  12. Add tests for:
  13. dbt repo detection
  14. non-dbt directory behavior
  15. re-running dft init
  16. project-dir override
  17. Update docs to make dft init the primary path, not a manual sequence.
  18. Validate the command against the internal analytics repo workflow captured by the companion task.

Implementation Progress

  • Initial planning notes:
  • Confirmed there is currently no dft init repo bootstrap command in dataface/cli/main.py.
  • Confirmed docs already describe the target conventions (faces/, optional dataface.yml, dbt repo auto-detection), so this task is mainly about productizing that convention.
  • Confirmed this should land before analyst-facing onboarding, not as a later polish item.
  • This task should complete before the analytics repo bootstrap task (create-analytics-repo-dataface-branch-and-bootstrap-workflow.md). That task is the first real-world test case for dft init — run it in ~/Fivetran/analytics/dbt_ft_prod/, validate that faces/ is created as a sibling of models/, and feed any pain points back here.
  • faces/ placement: must be at the same level as models/ inside the dbt project dir. dft init detects dbt_project.yml and puts faces/ alongside models/, macros/, tests/, etc.

QA Exploration

  • QA exploration completed (or N/A for non-UI tasks)

N/A for browser QA. Verification should focus on CLI behavior in temporary repos and in the internal analytics repo.

Review Feedback

  • Review cleared