The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
Make mage easier to browse: grouped task list, ls filter, cwd-aware alias (#83616)
bryan2b17f4d88772
diff --git a/bb.edn b/bb.ednindex 8be54cbaa91..6b3efd56564 100644--- a/bb.edn+++ b/bb.edn@@ -15,6 +15,8 @@table/table {:mvn/version "0.5.0"} ;; table printing};; No :pods key on purpose: tasks lazily load only what they need.+ ;; Every public task needs a :group naming its section in the `./bin/mage` listing. Use one of the+ ;; names in `mage.util/task-groups`, or add a new name there; that vector sets the section order.:tasks{:requires [[mage.cli :as cli][mage.color :as c]]@@ -26,7 +28,8 @@(cons 'do body))))alias- {:doc "Installs 'mage' alias and autocomplete"+ {:group "Mage"+ :doc "Installs 'mage' alias and autocomplete":examples [["./bin/mage alias" "Prints instructions to install the 'mage' alias and autocomplete"]["./bin/mage alias install fish" "Installs mage alias for fish shell"]["./bin/mage alias print zsh" "Prints shell script to put into .zshrc for zsh users"]]@@ -38,7 +41,8 @@:task (task! (alias/instructions parsed))}cljfmt-staged- {:doc "Runs cljfmt on staged files"+ {:group "Format & lint"+ :doc "Runs cljfmt on staged files":requires [[mage.format :as format]]:examples [["./bin/mage cljfmt-staged" "Format staged files"]["./bin/mage cljfmt-staged -c" "Check staged files"]]@@ -46,7 +50,8 @@:task (task! (format/staged parsed))}cljfmt-files- {:doc "Runs cljfmt on the given files/directories"+ {:group "Format & lint"+ :doc "Runs cljfmt on the given files/directories":requires [[mage.format :as format]]:examples [["./bin/mage cljfmt-files src/metabase/events.clj" "Format events.clj"]["./bin/mage cljfmt-files src" "Format all files in src"]@@ -57,14 +62,16 @@:task (task! (format/files parsed))}cljfmt-all- {:doc "Runs cljfmt on all (clojure) files"+ {:group "Format & lint"+ :doc "Runs cljfmt on all (clojure) files":requires [[mage.format :as format]]:examples [["./bin/mage cljfmt-all" "Format all files"]]:options [["-c" "--force-check" "Check staged files"]]:task (task! (format/all parsed))}cljfmt-updated- {:doc "Runs cljfmt on all (Clojure) files relative to a git ref (default HEAD)"+ {:group "Format & lint"+ :doc "Runs cljfmt on all (Clojure) files relative to a git ref (default HEAD)":requires [[mage.format :as format]]:examples [["./bin/mage cljfmt-updated" "Format updated files relative to HEAD"]["./bin/mage cljfmt-updated master" "Format updated files relative to master"]]@@ -73,7 +80,8 @@:task (task! (format/updated parsed))}kondo- {:doc "Runs Kondo against a file, directory, or everything we usually lint"+ {:group "Format & lint"+ :doc "Runs Kondo against a file, directory, or everything we usually lint":examples [["./bin/mage kondo" "run Kondo against everything we usually lint"]["./bin/mage kondo src/metabase/db.clj" "run Kondo against a file"]["./bin/mage kondo src/metabase/db.clj src/metabase/config.clj" "run Kondo against 2 files"]@@ -82,14 +90,16 @@:task (task! (kondo/kondo (:arguments parsed)))}kondo-updated- {:doc "Runs kondo against files changed compared to a git ref"+ {:group "Format & lint"+ :doc "Runs kondo against files changed compared to a git ref":examples [["./bin/mage kondo-updated" "run Kondo on files with changes relative to HEAD"]["./bin/mage kondo-updated master" "run Kondo on files with changes relative to master"]]:requires [[mage.kondo :as kondo]]:task (task! (kondo/kondo-updated (:arguments parsed)))}fix-unused-requires- {:doc "Removes unused requires flagged by clj-kondo"+ {:group "Format & lint"+ :doc "Removes unused requires flagged by clj-kondo":examples [["./bin/mage fix-unused-requires src/metabase/utils/validate.cljc" "Fix unused requires in a specific file"]["./bin/mage fix-unused-requires src" "Fix unused requires in all files in src"]]:requires [[mage.fix-unused-requires :as fix]]@@ -98,32 +108,37 @@:task (task! (fix/fix-files parsed))}load-namespaces- {:doc "Checks that every shipped namespace loads without :dev dependencies (and finds circular dependencies)"+ {:group "Tests & checks"+ :doc "Checks that every shipped namespace loads without :dev dependencies (and finds circular dependencies)":examples [["./bin/mage load-namespaces"]]:requires [[mage.load-namespaces]]:arg-schema [:tuple]:task (task! (mage.load-namespaces/load-namespaces))}codespell- {:doc "Check for misspellings in the source code."+ {:group "Format & lint"+ :doc "Check for misspellings in the source code.":examples [["./bin/mage codespell"]]:requires [[mage.codespell]]:task (task! (mage.codespell/codespell (:arguments parsed)))}codespell-interactive- {:doc "Check for misspellings in the source code, and interactively prompt to fix them."+ {:group "Format & lint"+ :doc "Check for misspellings in the source code, and interactively prompt to fix them.":examples [["./bin/mage codespell-interactive"]]:requires [[mage.codespell]]:task (task! (mage.codespell/codespell-interactive (:arguments parsed)))}start-maildev- {:doc "Start Maildev"+ {:group "Local dev"+ :doc "Start Maildev":examples [["./bin/mage start-maildev -h" "print help for start-maildev"]]:requires [[mage.start-maildev :as start-maildev]]:task (task! (start-maildev/start-maildev!))}docs-preview- {:doc "Preview the docs of a Metabase repo in your metabase-dot-com checkout, at http://localhost:4000/docs/latest/"+ {:group "Local dev"+ :doc "Preview the docs of a Metabase repo in your metabase-dot-com checkout, at http://localhost:4000/docs/latest/":examples [["./bin/mage docs-preview" "Preview the docs of this repo"]["./bin/mage docs-preview .claude/worktrees/my-feature" "Preview the docs of a worktree (a relative path starts at this repo)"]["./bin/mage docs-preview ~/code/other-metabase" "Preview the docs of another checkout"]@@ -136,19 +151,22 @@:task (task! (docs-preview/docs-preview! parsed))}tail-d- {:doc "Tail the #d debug log in real time (see dev.debug). Asks the running REPL for the exact path; falls back to DEV_DEBUG_LOG or /tmp/<dir>_debug.log."+ {:group "Local dev"+ :doc "Tail the #d debug log in real time (see dev.debug). Asks the running REPL for the exact path; falls back to DEV_DEBUG_LOG or /tmp/<dir>_debug.log.":examples [["./bin/mage tail-d" "tail the #d log, with bat syntax highlighting if available"]]:requires [[mage.tail-d :as tail-d]]:task (task! (tail-d/tail-d! parsed))}start-python-runner- {:doc "Start python-runner container with internal Moto S3 server for Python transforms"+ {:group "Local dev"+ :doc "Start python-runner container with internal Moto S3 server for Python transforms":examples [["./bin/mage start-python-runner" "start python-runner with internal S3"]]:requires [[mage.start-python-runner :as start-python-runner]]:task (task! (start-python-runner/start-python-runner!))}start-db- {:doc "Start a db on a default port in docker"+ {:group "Local dev"+ :doc "Start a db on a default port in docker":examples [["./bin/mage start-db postgres latest" "start the latest postgres db we support"]["./bin/mage start-db mysql oldest" "start the oldest mysql db we support"]["./bin/mage start-db postgres latest --port 5555" "start postgres on a custom port"]]@@ -172,7 +190,8 @@(start-db/start-db (-> (current-task) :db-info db) db version (:options parsed))))}nrepl- {:doc "Starts the babashka nrepl: helpful for mage development"+ {:group "Mage"+ :doc "Starts the babashka nrepl: helpful for mage development":requires [[babashka.nrepl.server :as nrepl.server][mage.color :as c]]:examples [["./bin/mage nrepl" "Starts the nrepl server"]@@ -186,7 +205,8 @@(deref (promise))))}lint-migrations- {:doc "Lint migrations files"+ {:group "Migrations"+ :doc "Lint migrations files":requires [[lint-migrations-file][babashka.process :as p]]:examples [["./bin/mage lint-migrations" "Lint all migrations and print report"]]@@ -195,7 +215,8 @@(lint-migrations-file/-main))}new-migration- {:doc "Create a new version-less migration file in the current year's directory"+ {:group "Migrations"+ :doc "Create a new version-less migration file in the current year's directory":requires [[mage.new-migration :as new-migration]]:examples [["./bin/mage new-migration mq_indexes" "Create resources/migrations/2026/20261012_mq_indexes.yaml with a random changeset id"]]:arg-schema [:tuple@@ -203,7 +224,8 @@:task (task! (new-migration/new-migration parsed))}jar-download- {:doc "Download (and optionally run) jar for a metabase version or branch"+ {:group "Local dev"+ :doc "Download (and optionally run) jar for a metabase version or branch":examples [["./bin/mage jar-download 50" "Download the latest enterprise version of release 50 to ~/path/to/my/metabase/jars"]["./bin/mage jar-download 1.45.2 -r" "Download and run metabase_1.45.2.jar"]["./bin/mage jar-download 1.45.2 -d ~/path/to/my/jars" "Download metabase_1.45.2.jar to ~/path/to/my/jars, deleting if it exists"]@@ -229,13 +251,15 @@:task (task! (jar-download/jar-download parsed))}setup-stats-repl- {:doc "Connect to the stats repl"+ {:group "Local dev"+ :doc "Connect to the stats repl":examples [["./bin/mage connect-stats-repl" "Connects to the stats repl"]]:requires [[mage.stats-repl :as stats-repl]]:task (stats-repl/connect (cli/parse! (current-task)))}notify- {:doc "Send notification for a comment (that already exists)"+ {:group "CI"+ :doc "Send notification for a comment (that already exists)":requires [[mage.be-dev :refer [nrepl-eval]]]:options [["-c" "--comment-id ID" "Notify about this comment id"]["-p" "--port PORT" "Port to use for the task, defaults to value in .nrepl-port"]]@@ -249,7 +273,8 @@(nrepl-eval "metabase.comments.core" code)))}run-tests- {:doc "Quickly run tests locally. Pass dirs, files, namespaces, or single tests as arguments."+ {:group "Tests & checks"+ :doc "Quickly run tests locally. Pass dirs, files, namespaces, or single tests as arguments.":examples [["./bin/mage run-tests" "launch interactive test picker"]["./bin/mage run-tests test/metabase/db" "run tests in test/metabase/db"]["./bin/mage run-tests test/metabase/logger test/metabase/api_keys" "run tests in test/metabase/logger and test/metabase/api_keys"]@@ -267,7 +292,8 @@:task (task! (qtr/go parsed))}openapi-diff- {:doc "Semantic diff of two OpenAPI specs, classified breaking-first, for the API changelog"+ {:group "Tests & checks"+ :doc "Semantic diff of two OpenAPI specs, classified breaking-first, for the API changelog":examples [["./bin/mage openapi-diff old.json new.json" "Full diff, breaking changes first"]["./bin/mage openapi-diff old.json new.json --severity breaking" "Only what needs a changelog entry"]["./bin/mage openapi-diff --refs release-x.63.x release-x.64.x --severity breaking" "Generate both specs from source, then diff"]@@ -301,14 +327,16 @@:task (task! (mage.openapi-diff/cli-diff parsed))}openapi-staleness- {:doc "Is the committed OpenAPI spec current relative to the API source? (a stale spec under-reports)"+ {:group "Tests & checks"+ :doc "Is the committed OpenAPI spec current relative to the API source? (a stale spec under-reports)":examples [["./bin/mage openapi-staleness"]]:arg-schema [:tuple]:requires [[mage.openapi-diff]]:task (task! (mage.openapi-diff/cli-staleness parsed))}affected-modules- {:doc "Which backend modules have changes?"+ {:group "Modules"+ :doc "Which backend modules have changes?":examples [["./bin/mage affected-modules master" "prints changes compared to `master`"]["./bin/mage affected-modules"]]:arg-schema [:or [:tuple] [:tuple [:string {:name "git-ref"}]]]@@ -316,7 +344,8 @@:task (task! (mage.modules/cli-print-affected-modules (:arguments parsed)))}update-codeowners- {:doc "Rewrite the module-ownership block in .github/CODEOWNERS from the modules that set :codeowners"+ {:group "Modules"+ :doc "Rewrite the module-ownership block in .github/CODEOWNERS from the modules that set :codeowners":examples [["./bin/mage update-codeowners" "Rewrite the generated block in .github/CODEOWNERS"]["./bin/mage update-codeowners --check" "Exit non-zero if the block is out of date (for CI)"]]:options [[nil "--check" "Exit non-zero if CODEOWNERS is out of date instead of rewriting it"]]@@ -324,7 +353,8 @@:task (task! (mage.modules/cli-update-codeowners parsed))}modules-tree- {:doc "Print the module hierarchy, nesting enterprise extensions under their OSS module"+ {:group "Modules"+ :doc "Print the module hierarchy, nesting enterprise extensions under their OSS module":examples [["./bin/mage modules-tree" "Print the full tree; * marks a custom :ns-prefix"]["./bin/mage modules-tree --nested-only" "Print only roots with nested modules"]["./bin/mage modules-tree --prefixes" "Show custom prefixes instead of *"]@@ -338,14 +368,16 @@:task (task! (mage.modules/cli-print-module-tree parsed))}can-skip-driver-tests- {:doc "Can we skip driver tests for this branch?"+ {:group "Tests & checks"+ :doc "Can we skip driver tests for this branch?":examples [["./bin/mage can-skip-driver-tests master" "Returns zero (success) if we can skip driver tests based on changes related to `master`"]["./bin/mage can-skip-driver-tests" "Returns zero (success) if we can skip driver tests based on changes? (defaults to master)"]]:requires [[mage.modules]]:task (task! (mage.modules/cli-can-skip-driver-tests (:arguments parsed)))}module-history- {:doc "Update the CSV files that track how the backend module graph changed on master, and optionally publish them. Measures only commits it has not measured before."+ {:group "Modules"+ :doc "Update the CSV files that track how the backend module graph changed on master, and optionally publish them. Measures only commits it has not measured before.":examples [["./bin/mage module-history --dir ~/module-history" "Fetch master, measure its new commits, and write the CSV files and history.json"]["./bin/mage module-history --dir ~/module-history --publish ~/module-history/publish.edn" "Then fill pages, replace Metabase uploads, refresh cards and update shares, as the EDN file says"]["./bin/mage module-history --dir ~/module-history-ahead --ref origin/my-stack-tip" "Write the history as it would be with a branch merged: master up to where the branch left it, then the branch's commits"]@@ -361,7 +393,8 @@:task (task! (mage.module-history/cli-update parsed))}fix-modules-config- {:doc "Regenerate .clj-kondo/config/modules/config.edn so it passes metabase.core.modules-test."+ {:group "Modules"+ :doc "Regenerate .clj-kondo/config/modules/config.edn so it passes metabase.core.modules-test.":examples [["./bin/mage fix-modules-config" "Fix the modules config (uses the running dev REPL if available, else a JVM)"]["./bin/mage fix-modules-config --port 59498" "Use the dev REPL on a specific nREPL port"]];; Cold-JVM fallback invokes `clojure -X:dev dev.modules-config/fix-config!`.@@ -370,7 +403,8 @@:task (task! (mage.modules/cli-fix-config (cli/parse! (current-task))))}project-tests- {:doc "Run project-level checks."+ {:group "Tests & checks"+ :doc "Run project-level checks.":examples [["./bin/mage project-tests" "Run every suite"]["./bin/mage project-tests backend" "Run backend checks"]["./bin/mage project-tests migrations" "Run migration checks"]@@ -389,13 +423,15 @@(project-tests/run!)))}kondo-ratchets- {:doc "Validate the kondo and module ratchet files against the source tree (about half a minute, most of it a kondo run over the files with a discouraged-var or discouraged-namespace ignore)."+ {:group "Ratchets"+ :doc "Validate the kondo and module ratchet files against the source tree (about half a minute, most of it a kondo run over the files with a discouraged-var or discouraged-namespace ignore).":examples [["./bin/mage kondo-ratchets" "Fail on an invalid ratchets file, an over-budget suppression, or a missing justification comment"]]:requires [[dev.kondo-ratchet] [mage.kondo-ratchet]]:task (task! (dev.kondo-ratchet/check {:attribute mage.kondo-ratchet/attribute-occurrences!}))}kondo-ratchets-shrink- {:doc "Lower kondo and module budgets to match the source tree. This is the only Mage task that writes the ratchet files."+ {:group "Ratchets"+ :doc "Lower kondo and module budgets to match the source tree. This is the only Mage task that writes the ratchet files.":examples [["./bin/mage kondo-ratchets-shrink" "Lower budgets to current counts without raising over-budget entries"]["./bin/mage kondo-ratchets-shrink --seed :some-linter" "Set :some-linter's budget to its current count when introducing the linter"]["./bin/mage kondo-ratchets-shrink --seed :discouraged-var/clojure.core/println" "Set one discouraged symbol's budget to its current count"]@@ -405,7 +441,8 @@:task (task! (dev.kondo-ratchet/fix! (assoc (:options parsed) :attribute mage.kondo-ratchet/attribute-occurrences!)))}kondo-ratchets-history- {:doc "Report which commits and pull requests shrank, grew and introduced ratchet budgets."+ {:group "Ratchets"+ :doc "Report which commits and pull requests shrank, grew and introduced ratchet budgets.":examples [["./bin/mage kondo-ratchets-history" "Summarize the last 7 days"]["./bin/mage kondo-ratchets-history --days 30" "Summarize the last 30 days"]["./bin/mage kondo-ratchets-history --all" "Summarize every change since the first ratchet"]@@ -426,7 +463,8 @@:task (task! (mage.kondo-ratchets-history/history parsed))}kondo-redundant-ignores- {:doc "Report inline kondo ignores that are no longer necessary (slow: full kondo run)."+ {:group "Ratchets"+ :doc "Report inline kondo ignores that are no longer necessary (slow: full kondo run).":examples [["./bin/mage kondo-redundant-ignores" "Scan the backend tree for removable ignores"]["./bin/mage kondo-redundant-ignores --fix" "Also remove them from source (restores + marks [kondo-keep] any that re-trigger)"]["./bin/mage kondo-redundant-ignores --fix --audit" "Recheck [kondo-keep] sites too, unmarking any now truly redundant"]]@@ -436,7 +474,8 @@:task (task! (mage.kondo-ratchet/redundant-ignores parsed))}kondo-insert-ignores- {:doc "Insert inline ignores at every site a linter flags -- for landing a new linter without a big-bang fix."+ {:group "Ratchets"+ :doc "Insert inline ignores at every site a linter flags -- for landing a new linter without a big-bang fix.":examples [["./bin/mage kondo-insert-ignores :metabase/new-linter" "Insert ignores everywhere the linter fires, then seed its budget"]["./bin/mage kondo-insert-ignores :equals-true test/metabase/pulse" "Only under the given paths"]]:arg-schema [:sequential [:string {:name "linter-then-paths"}]]@@ -444,13 +483,17 @@:task (task! (mage.kondo-ratchet/insert-ignores (:arguments parsed)))}ls- {:doc "List all mage public and private tasks"- :examples [["./bin/mage ls" "List all tasks"]]+ {:group "Mage"+ :doc "List all mage public and private tasks"+ :examples [["./bin/mage ls" "List all tasks"]+ ["./bin/mage ls kondo" "List tasks whose name contains 'kondo'"]]+ :arg-schema [:or [:tuple] [:tuple [:string {:name "pattern" :description "Only list tasks whose name contains this"}]]]:requires [[mage.util :as u]]:task (task! (u/print-tasks parsed))}generate-cursive-resolve-as- {:doc "Generate XML configuration for Cursive's symbol resolution based on the current clj-kondo lint-as configuration."+ {:group "Local dev"+ :doc "Generate XML configuration for Cursive's symbol resolution based on the current clj-kondo lint-as configuration.":examples [["./bin/mage generate-cursive-resolve-as" "Generate resolve-as XML configuration"]["./bin/mage generate-cursive-resolve-as > /Users/bgrabow/Library/Application\\ Support/JetBrains/IntelliJIdea2025.3/options/ClojureResolveSettings.xml""Generate resolve-as XML configuration and install it in your global editor configuration"]]@@ -458,7 +501,8 @@:task (task! (cursive-resolve-as/do-it))}docs-generate- {:doc "Regenerate the docs that are built from source. The backend suite runs every Clojure generator in one JVM."+ {:group "Local dev"+ :doc "Regenerate the docs that are built from source. The backend suite runs every Clojure generator in one JVM.":examples [["./bin/mage docs-generate" "Regenerate every generated doc"]["./bin/mage docs-generate backend" "Environment variables, config template, API, AI providers, MCP tools, and CLI commands"]["./bin/mage docs-generate usage-analytics" "Usage analytics reference"]@@ -476,13 +520,15 @@:task (task! (docs-generate/run! (first (:arguments parsed)) (:options parsed)))}analytics:setup- {:doc "Set up usage analytics development mode"+ {:group "Analytics"+ :doc "Set up usage analytics development mode":examples [["./bin/mage analytics:setup" "Enable usage analytics dev mode and import content"]]:requires [[mage.analytics :as analytics]]:task (task! (analytics/setup!))}analytics:export- {:doc "Export usage analytics content to YAML files"+ {:group "Analytics"+ :doc "Export usage analytics content to YAML files":examples [["./bin/mage analytics:export" "Export to default location (resources/instance_analytics)"]["./bin/mage analytics:export my-custom-dir" "Export to custom directory"]]:arg-schema [:or@@ -494,13 +540,15 @@(analytics/export!)))}analytics:teardown- {:doc "Tear down usage analytics development mode"+ {:group "Analytics"+ :doc "Tear down usage analytics development mode":examples [["./bin/mage analytics:teardown" "Remove usage analytics dev database and disable dev mode"]]:requires [[mage.analytics :as analytics]]:task (task! (analytics/teardown!))}analytics:finalize- {:doc "Export usage analytics content and tear down development mode"+ {:group "Analytics"+ :doc "Export usage analytics content and tear down development mode":examples [["./bin/mage analytics:finalize" "Export to default location and tear down"]]:requires [[mage.analytics :as analytics]]:task (task! (do@@ -508,13 +556,15 @@(analytics/teardown!)))}doctor- {:doc "Check your development environment for issues"+ {:group "Tests & checks"+ :doc "Check your development environment for issues":examples [["./bin/mage doctor" "Run all health checks"]]:requires [[mage.doctor :as doctor]]:task (task! (doctor/doctor!))}ci-report- {:doc "Generate a CI failure report for a PR, branch, or commit"+ {:group "CI"+ :doc "Generate a CI failure report for a PR, branch, or commit":examples [["./bin/mage ci-report" "Check current branch (PR or branch CI)"]["./bin/mage ci-report 68292" "Generate report for PR #68292"]["./bin/mage ci-report source-replacement" "Report for a branch by name"]diff --git a/bin/mage.bb b/bin/mage.bbindex e6628369fc5..81dabf886b8 100755--- a/bin/mage.bb+++ b/bin/mage.bb@@ -8,6 +8,7 @@[babashka.tasks :as bt][bling.banner :refer [banner]][bling.fonts.ansi-shadow :as ansi-shadow]+ [clojure.edn :as edn][clojure.string :as str][mage.color :as c][mage.util :as u]))@@ -44,7 +45,10 @@(flush)(println (c/bold " ✨ Metabase Automation Genius Engine ✨"))(println "")- (println (u/sh (str u/project-root-directory "/bin/bb tasks")))+ (println "The following tasks are available:\n")+ (println (u/grouped-tasks-help (:tasks (edn/read-string (slurp (str u/project-root-directory "/bb.edn"))))+ (u/terminal-width)))+ (println "")(println (tip-o-day)))(defn- summarize-exception [^Exception e]diff --git a/docs/developers-guide/mage.md b/docs/developers-guide/mage.mdindex ddbefa0d684..6aba73d3f8a 100644--- a/docs/developers-guide/mage.md+++ b/docs/developers-guide/mage.md@@ -16,11 +16,17 @@ $ ./bin/mageThe following tasks are available:-cljfmt-staged Runs cljfmt on staged files-kondo Runs Kondo against a file, directory, or everything we usually lint-...-start-db Start a db on a default port in docker-jar-download Given a version, downloads a metabase jar+Format & lint+ cljfmt-staged Runs cljfmt on staged files+ kondo Runs Kondo against a file, directory, or everything we usually lint+ ...++Local dev+ jar-download Download (and optionally run) jar for a metabase version or branch+ start-db Start a db on a default port in docker+ ...+$ ./bin/mage ls kondo+<lists only tasks whose name contains "kondo", including private ones>$ ./bin/mage kondo -h<prints help for easily running kondo>```@@ -28,3 +34,22 @@ $ ./bin/mage kondo -h### mage AutocompleteRun `./bin/mage setup-autocomplete` and follow the instructions to set up autocomplete in your terminal.++### Adding a task++Add the task to the `:tasks` map in `bb.edn`. A public task (name not starting with `-`) needs:++- `:group`: the section it appears under in `./bin/mage`. Use one of the names in `mage.util/task-groups`. If none fits, add a new name to that vector; its position sets the section order. `mage.core-test/public-task-has-group-test` fails if a public task has no `:group` or one that isn't in the vector.+- `:doc`: put the useful part in the first sentence. The listing shows only the first sentence, cut to the terminal width. `-h` shows the full text.+- `:examples`: `mage.core-test/bb-task-has-example-test` checks that `-h` prints them.++```clojure+ my-task+ {:group "Local dev"+ :doc "Does the thing. More detail that only `-h` shows."+ :examples [["./bin/mage my-task" "Does the thing"]]+ :requires [[mage.my-task :as my-task]]+ :task (task! (my-task/run! parsed))}+```++Private tasks (names starting with `-`) don't need a `:group`. They are hidden from `./bin/mage` and appear in `./bin/mage ls`.diff --git a/mage/resources/bash_alias.sh b/mage/resources/bash_alias.shindex b1cacffe228..588844513a1 100644--- a/mage/resources/bash_alias.sh+++ b/mage/resources/bash_alias.sh@@ -1,10 +1,16 @@export MB_DIR="{{mb-dir}}"+# the checkout you're in, else $MB_DIR:+_mage_root() {+ local root+ root=$(git rev-parse --show-toplevel 2>/dev/null)+ if [ -x "$root/bin/mage" ]; then echo "$root"; else echo "$MB_DIR"; fi+}# alias:mage() {- cd $MB_DIR && ./bin/mage "$@"+ "$(_mage_root)/bin/mage" "$@"}# autocomplete:_bb_tasks() {- COMPREPLY=( $(compgen -W "$(bb tasks |tail -n +3 |cut -f1 -d ' ')" -- ${COMP_WORDS[COMP_CWORD]}) );+ COMPREPLY=( $(compgen -W "$(bb --config "$(_mage_root)/bb.edn" tasks |tail -n +3 |cut -f1 -d ' ')" -- ${COMP_WORDS[COMP_CWORD]}) );}complete -f -F _bb_tasks magediff --git a/mage/resources/fish_completions.fish b/mage/resources/fish_completions.fishindex 6e34d9551f2..a456930a933 100644--- a/mage/resources/fish_completions.fish+++ b/mage/resources/fish_completions.fish@@ -1,8 +1,6 @@function __mage_complete_tasksif not test "$__mage_tasks"- if test -n "$MB_DIR"- set -g __mage_tasks (cd $MB_DIR && bb tasks 2>/dev/null |tail -n +3 |cut -f1 -d ' ')- end+ set -g __mage_tasks (bb --config (__mage_root)/bb.edn tasks 2>/dev/null |tail -n +3 |cut -f1 -d ' ')endprintf "%s\n" $__mage_tasksdiff --git a/mage/resources/fish_function.fish b/mage/resources/fish_function.fishindex b79c45f8275..69896c71fb2 100644--- a/mage/resources/fish_function.fish+++ b/mage/resources/fish_function.fish@@ -1,4 +1,14 @@set -x MB_DIR {{mb-dir}}+# the checkout you're in, else $MB_DIR:+function __mage_root+ set -l root (git rev-parse --show-toplevel 2>/dev/null)+ if test -x "$root/bin/mage"+ echo $root+ else+ echo $MB_DIR+ end+endfunction mage --description 'Metabase Automation Genius Engine'- cd $MB_DIR && ./bin/mage $argv+ set -l mage_bin (__mage_root)/bin/mage+ $mage_bin $argvenddiff --git a/mage/resources/zsh_alias.sh b/mage/resources/zsh_alias.shindex 84a3c1181bb..6c9f6ec7fce 100644--- a/mage/resources/zsh_alias.sh+++ b/mage/resources/zsh_alias.sh@@ -1,12 +1,18 @@export MB_DIR="{{mb-dir}}"+# the checkout you're in, else $MB_DIR:+_mage_root() {+ local root+ root=$(git rev-parse --show-toplevel 2>/dev/null)+ if [ -x "$root/bin/mage" ]; then echo "$root"; else echo "$MB_DIR"; fi+}# alias:mage() {- cd $MB_DIR && ./bin/mage "$@"+ "$(_mage_root)/bin/mage" "$@"}# autocomplete:_bb_tasks() {- local matches=(`bb tasks |tail -n +3 |cut -f1 -d ' '`)+ local matches=(`bb --config "$(_mage_root)/bb.edn" tasks |tail -n +3 |cut -f1 -d ' '`)compadd -a matches_files # autocomplete filenames as well}diff --git a/mage/src/mage/util.clj b/mage/src/mage/util.cljindex e6176060692..537862020f5 100644--- a/mage/src/mage/util.clj+++ b/mage/src/mage/util.clj@@ -173,13 +173,51 @@[& xs](doseq [x xs] (puget/cprint x {:width 10e30})))-(defn print-tasks [& _]+(def task-groups+ "Display order for the `:group` of public tasks in bb.edn."+ ["Format & lint" "Tests & checks" "Modules" "Ratchets" "Migrations" "Local dev" "CI" "Analytics" "Mage"])++(defn- one-line+ "First sentence of `doc`, cut to `width` chars."+ [doc width]+ (let [s (first (str/split (str doc) #"(?<=\.)\s"))]+ (if (> (count s) width)+ (str (subs s 0 (max 0 (dec width))) "…")+ s)))++(defn grouped-tasks-help+ "Public tasks in `tasks` (the bb.edn :tasks map) as one section per `:group`, with one-line descriptions+ fitted to `width` columns."+ [tasks width]+ (let [public (for [[task {:keys [group doc]}] tasks+ :when (and (symbol? task) (not (str/starts-with? (name task) "-")))]+ {:task (name task) :group group :doc doc})+ name-w (apply max (map (comp count :task) public))+ by-grp (group-by :group public)]+ (str/join+ "\n\n"+ (for [group (concat task-groups (remove (set task-groups) (keys by-grp)))+ :let [ts (sort-by :task (by-grp group))]+ :when (seq ts)]+ (str/join "\n"+ (cons (c/bold (or group "Other"))+ (for [{:keys [task doc]} ts]+ (str " " (format (str "%-" name-w "s") task) " "+ (one-line doc (- width name-w 4))))))))))++(defn terminal-width+ "Columns in the terminal, or 100 if `tput` can't tell."+ []+ (or (try (parse-long (sh "tput cols")) (catch Exception _ nil)) 100))++(defn print-tasks [& [{[pattern] :arguments}]](let [task+descriptions (->> "bb.edn"(str project-root-directory "/")slurpedn/read-string:tasks- (filter (fn [[task _v]] (symbol? task)))+ (filter (fn [[task _v]] (and (symbol? task)+ (str/includes? (name task) (or pattern "")))))(sort-by (fn [[task _task-data]](let [task-name (name task)](if (str/starts-with? task-name "-")diff --git a/mage/test/mage/core_test.clj b/mage/test/mage/core_test.cljindex ffc61201b38..cabb42a194b 100644--- a/mage/test/mage/core_test.clj+++ b/mage/test/mage/core_test.clj@@ -68,6 +68,17 @@(let [out (u/sh cmd)](is (str/includes? out "The following tasks are available:"))))))+(deftest public-task-has-group-test+ (doseq [[task {:keys [group]}] (:tasks (edn/read-string (slurp (str u/project-root-directory "/bb.edn"))))+ :when (and (symbol? task) (not (str/starts-with? (name task) "-")))]+ (testing (str task " has a :group listed in mage.util/task-groups, so `./bin/mage` shows it in a section")+ (is (some #{group} u/task-groups)+ (str "Task `" task "` in bb.edn has "+ (if group (str ":group " (pr-str group) ", which is not in mage.util/task-groups.") "no :group.")+ "\n\nTo fix, set :group to one of " (str/join ", " (map pr-str u/task-groups)) ":\n\n"+ " " task "\n {:group " (pr-str (first u/task-groups)) "\n :doc ...}\n\n"+ "If none fits, add a new name to mage.util/task-groups. Its position there sets the section order.")))))+(deftest bb-task-has-example-test(doseq [task-name (u/public-bb-tasks-list)cmd [(str "./bin/mage " task-name " -h")