Skip to content

feat: add the drx command-line tool and create-druxt - #1

Closed
Decipher wants to merge 54 commits into
0.xfrom
feature/first-cut
Closed

Decipher wants to merge 54 commits into
0.xfrom
feature/first-cut

Conversation

@Decipher

Copy link
Copy Markdown
Member

What changed

The first cut of the Druxt command-line tool: two packages in an npm workspace.

  • @druxt/cli, with the drx binary.
    • drx init creates a site from a starter, guided in a terminal or by flags. It asks for the layout and for the engine that runs Drupal (local PHP with SQLite, DDEV, Lando, or a Drupal that already exists), checks that the engine's commands are on the machine, and records the choice in drx.config.json.
    • drx info reports the project's layout, its parts and the versions of their packages.
    • drx module list, search and info read the Druxt module registry, and in a project show which modules are installed and compatible.
    • drx add and drx remove install a module in the frontend, add it to the framework's config, and require and enable the Drupal modules it needs. --dry-run prints every step.
    • drx with no command opens a menu.
    • --no-interactive, DRX_NO_INTERACTIVE=1, CI and a missing terminal each turn every prompt off. --json gives each command's result as data.
  • create-druxt, so npm create druxt runs drx init.
  • A starter registry in starters/, in giget's registry format, with one entry for druxt/quickstart.
  • Linting, type checks, tests with a coverage floor, changesets, and pipelines for GitHub Actions and GitLab CI.

Why

Starting a Druxt site and adding a module to one are both a list of manual steps today, spread over a README. The tool turns them into commands that a person, a script or an agent can run.

How it was checked

  • npm run lint and npm run typecheck pass
  • npm test passes, and coverage did not drop
  • A changeset is included, if a published package changed
  • Nothing that resolves only on a private network reached a tracked file

Run by hand on the built binary: drx init against the real quickstart tarball, drx info, the module commands against the published registry, and drx add --dry-run in a created site.

Not covered yet

  • No real run of drx add or drx remove: every package manager, Composer and Drush call is replaced by a stand-in in the tests.
  • No engine's setup steps have been run. The steps init prints follow the quickstart's README.
  • No prompt has been driven in a real terminal. The tests answer them through an injected interface.
  • drx module configure, the drx patches commands, the split and workspace layouts, and sources other than npm answer "not available yet".
  • The default starter registry reads this repository's starters/ directory on main, so it falls back to the bundled copy until this is merged.

ESLint, Prettier, cspell, markdownlint, knip and commitlint, run by the
committed hooks. The private-host check and the attribution check come
from the Druxt module template.
An entry is giget's own format with a druxt object: the release line,
the layout, the parts, what the site requires, the date it was last
maintained and whether it is the default. Validation names the first
field that is wrong.
The registry is static JSON under starters/, in giget's format, with
one entry for druxt/quickstart and an index of names. The default
registry is the raw files of druxt/cli on GitHub. When its index cannot
be read the copy bundled with the package is used. A registry the user
names is never replaced.
…tion

A source says where the Druxt packages of a site come from. The public
code knows npm and the git:<url>#<ref> form. Any other name is looked
up in ~/.config/drx/config.json, or the file DRX_CONFIG names, which
may also name registries. Only the npm source installs in this version,
and the others say so.
A part has a role and a kind. What is specific to a kind sits behind
one interface: detect a directory, list the packages to report, and a
placeholder for adding a module. The commands look an adapter up by
kind, so another kind is another file.
The file sits at the project root and is found from any directory
below it. It holds the layout, the release line, the starter, the
source and the parts, each part a role, a kind and a path. It is read
with c12 and checked field by field.
runCli takes the arguments and returns an exit code, with the result
on stdout and everything else on stderr. --json turns the result, or a
failure, into JSON. An option the command does not define is an error.

drx info prints the CLI and Node versions. Inside a project it adds the
layout and, for each part, the packages its adapter reports.

The spell check reads British English as well, which the prose uses.
Creates a site from a starter in a registry: reads and checks the
entry, fetches the tarball with giget, writes drx.config.json and
prints what the site needs and what to run next, all from the entry.

Every prompt has a flag. With no terminal the defaults apply, and a
missing directory fails with a message saying what to pass. A directory
that is not empty is refused without --force. The split and workspace
layouts, and every source but npm, answer that they are not available
yet.
The binary runs runCli and sets the exit code. The package exports
runCli and the types of the registry, the project configuration, the
sources and the adapters.

A test holds the adapter seam: the names of kinds appear in the sources
only inside adapters/, and are never a key in a registry file. The
end-to-end test creates a site from the real quickstart tarball and is
skipped unless DRX_E2E=1.
npm create druxt my-site is drx init my-site. The package does nothing
else: every other task is a drx command.
…e coverage floor

The floor in vitest.config.ts is measured from the tests as they are.
Both run the linters, the type check, the unit tests with a JUnit report
and the coverage floor, a pack-and-install check of both packages, and
the end-to-end test. The gitlab pipeline also lints the workflow and
scans for secrets with a detection canary. Neither publishes.
npm packs the readme and licence of the package directory, so the ones
at the repository root were not in either tarball.
npx reads a version or help flag as its own, so the check was reading
the version of npm.
…endor

drx info read composer.lock, so a site just created from a starter that
commits its lock file listed Drupal as installed before composer install
had run. It reads Composer's own record of what is installed.
A registry entry may name the commands its site needs in
`druxt.requires.commands`, as alternatives: the site can be set up when
every command of one inner list is found. Validation names the bad
field, and rejects a name with a path or a space in it.

`findOnPath` reads the directories of the path variable and runs
nothing. On Windows it reads the variable under either spelling and
tries each extension in the extensions variable.
When no alternative in `druxt.requires.commands` is complete, `init`
prints one warning that names the missing commands and the
alternatives. The site is still created. The JSON result gains a
`commands` object with what was found and what was missing, or null for
an entry without the field. The lookup is on the context, so a
test passes its own.
`php` and `composer`, or `ddev`. A test compares the copy of the
registry the build puts in the package with `starters/`, because the
other tests read that copy when it exists and a stale one would hide a
change here.
The first-release changeset mentions the warning. Under what is missing
the readme now lists a version check of those commands, and the same
check in `drx info`, which would need a second registry read.
`druxt` gives the range a part asks for and the version it has
installed, under either package name, including a copy another package
brought in. `package` gives the same for a package by name. Both are
undefined for a backend kind. `kindsWithRole` lists the kinds of a role.
`loadModules` reads a registry URL, checks it and keeps a copy. A copy
under an hour old is used with no request. When the registry cannot be
read, a copy of any age takes its place and the result says why. A
`schemaVersion` other than 1 is refused, and so is a field of the wrong
type, by name. Fields the CLI has no use for are ignored.

The backend modules of an entry are read from the key named after each
backend kind that has an adapter, so the reader does not name a kind.
The starter registry and this one share `fetchJson`.
`compatibility` takes the range a module states and the Druxt package a
part's adapter reports, and compares them with semver: the installed
version when there is one, the range the part asks for otherwise. A
module that states `unknown`, an invalid range or nothing is unknown,
and so is a part with no Druxt version.

The user configuration may name module registries under
`moduleRegistries`, for a `--module-registry` flag.
`list` prints the registry as a table and `search` the rows that match
a text. In a project both add, for each frontend part, what is
installed and whether the module's range admits the Druxt there, taken
from the part's adapter. `info` shows one module by its name or its
package name, with the backend modules it needs, and fails with the
closest names when it finds nothing.

`add`, `remove` and `configure` are registered and answer that they are
not available yet. The usage of a command inside a command is now
found, so `drx module list --help` works.
Skipped unless DRX_E2E=1, as the starter case is.
The first-release changeset lists the module commands. Under what is
missing the readme now names `add`, `remove` and `configure`.
`druxt.engines` lists the ways a starter's backend can be run: a name,
a label, the commands needed on the path, the databases on offer, the
steps, notes, the files the engine needs and the URL it serves at.
`druxt.backendUrl` says which file and variable the starter reads its
backend URL from. Validation names the bad field, and refuses a path
that is absolute or leaves the starter.

A backend part in `drx.config.json` may record `engine`, `database` and
`baseUrl`. A file without them still reads.
An engine adapter turns a tool and its arguments into the command line
for a backend part: `composer` and `vendor/bin/drush` on a machine with
its own PHP, `ddev composer` and `lando drush` through a container tool,
and an error for a backend that is not on this machine. No command
calls it yet.
`removeEngineFiles` deletes the paths of the engines that were not
chosen and keeps any path the chosen engine lists as well. Every path
is checked before the first is removed: one that is absolute, climbs
out of the site or reaches out of it through a link is refused.

`writeBackendUrl` sets one variable in the file a starter reads its
backend URL from, starting from the starter's template.
c12 loads a JSON file through Node's require, which keeps the first
read for the life of the process. A caller that ran two commands in one
process, as the tests do, read the first project configuration again.
The cached copy is now dropped before each load.
`--engine` picks one of the starter's engines, or `none` for a backend
that exists already, which takes `--base-url`. `--database` picks among
the engine's databases. In a terminal each is asked for when the
starter gives a choice, with the engines whose commands are present
listed first. With `--yes` or no terminal, the first engine whose
commands are present is used, or the first the starter lists.

`init` removes the files of the engines not chosen unless
`--keep-engines` is given, writes the backend URL where the starter
reads it, and records the engine, the database and the URL on the
backend part. The warning about missing commands, what the site needs
and the next steps all come from the chosen engine. `drx info` prints
what was recorded. `--setup` is registered and is not available yet.

A test fails when the name of an engine appears in the sources outside
`engines/`.
Local PHP with SQLite, DDEV and Lando, each with its commands, its
steps as the starter's readme gives them, and its files. Lando runs the
install scripts under `drupal/.ddev/commands`, so it lists that path as
well and the path stays when either engine is chosen. `backendUrl` says
the starter reads `BASE_URL` from `.env`.

The end-to-end run checks every path the entry names against the real
tarball.
`requires.commands` is marked as superseded. Under what is missing the
readme now lists `--setup` and setting up another database.
… chosen

The quickstart's own scripts, such as its provision and drush commands,
run the tooling in drupal/.devtools, so removing it for another engine left
them pointing at nothing.
It decides the colour depth of a stream from `NO_COLOR`, `FORCE_COLOR`,
`CI`, `--json` and whether the stream is a terminal. It draws four
marks of different shapes, colours a part by its role, blue for a
backend and green for a frontend, and draws the wordmark with a
gradient from one to the other. Terminals with 16 colours get plain
blue and green, and one that cannot draw Unicode gets ASCII marks and
the name in letters.

The art is the quickstart starter's, character for character. The
escape codes are written by hand, so there is no new dependency.
In a terminal each line on stderr carries one of the four marks, a step
that finished gets a line of its own, and a command can print a small
header or the wordmark. Without a terminal, and with `--json`, stderr
is the same plain sentences as before.

`repeatCommand` writes a `drx` command line with each argument quoted
for a POSIX shell. The user configuration may set `banner` to false.
When values are missing and somebody is there to answer, `init` opens
with the wordmark and asks for the directory, the starter, the layout,
the engine with its database or URL, and whether to install. It then
lists what it will do and asks before it writes. Saying no, or
cancelling any prompt, exits with one line and leaves the disk as it
was. The run ends with the command that repeats it, each choice a flag.

The registry read, the download and the install each get a line when
they finish. `--json` no longer asks anything, and `--no-banner` or
`"banner": false` in the user configuration replaces the wordmark with
the small header. A starter entry may carry a `description` for the
prompt that lists it, and a layout that is not built is shown and
cannot be picked.
In a terminal, `drx` with no command draws the wordmark, says which
project it is in and lists what can be done there. Each entry runs the
command it stands for, and the commands that are not built are listed
and cannot be picked. `drx module` with no command is a list to narrow
by typing, and shows the module picked. Both end with the command that
repeats the choice.

`drx info` and the module commands start with a small header in a
terminal, and a part is printed in the colour of its role.

`--no-interactive`, `DRX_NO_INTERACTIVE` and `CI` each turn every
prompt, the menu and the wordmark off, as having no terminal does.
Bare `drx` then prints its usage.
One table of every command and subcommand, run with the flag, with the
variable, under `CI` and with no terminal, against a prompter that
fails the test when it is called.
The prompt that lists starters shows it beside the name.
The installed binary creates a site with `--yes --no-interactive
--json`, as a pipeline would, in both pipelines.
… runs

The readme gains a section on the menu and the guided `init`, with how
to turn the wordmark and colour off, and a section for CI and scripts
with a complete unattended `init` and the exit codes.
In a terminal both lines had the mark of a step that is still running.
A backend module in a registry entry may name the Composer package that
provides it. It may also list the steps left to do once it is enabled
and the patches it needs. Each field is optional, so the published
registry reads as before.
The adapter returns the steps and runs nothing: the install with the
package manager of the part's lock file, then an edit of the `modules`
array in the Nuxt config, made with magicast so the rest of the file
stays as written. On the quickstart's own config the edit is two lines.
A config that is a function, or whose list is not written out in the
file, is left alone and the line to add is returned for the user.
For each backend module a Druxt module needs, the adapter plans a
`composer require` of the package the registry names, or of
`drupal/<name>`, and one `drush en` for them all. A core module is only
enabled. Patches go into `extra.patches` of `composer.json`, with the
composer-patches plugin required and allowed when the site lacks it. A
patch is skipped when the installed package has the fix, or when the
site already carries it. The steps left to do by hand are returned to
print.

A registry that marks core modules is believed. With one that does not,
a module is core when the installed core has it, a package when the
site requires it, and otherwise the adapter refuses and says to install
the backend first. There is no list of core modules in the CLI.

The removal undoes what the record says an add did, and nothing else.
A tool runner on the context, which keeps a tool's output to show when
it fails and which a test replaces. An engine adapter says whether its
backend is on this machine. `drx.config.json` may hold a record of the
modules that were added, and the prompter gains a list to pick several
entries from.
`drx add <module...>`, also `drx module add`, plans each module with
the adapters of the project's parts and then carries the plan out. The
frontend part gets the package and a line in its config. A backend part
gets its steps as command lines of the part's engine. A backend that is
not run from this machine gets none: its commands are printed as what
is left to do.

A module that is archived, or whose range does not admit the Druxt in
the part, is refused unless `--force` is given, and one with no package
is always refused. Refusals are found before the first step. A tool
that fails stops the run with its output, what was done and what was
not. What was added is recorded in `drx.config.json`.

`drx remove` takes the package and the config line out. With
`--backend` it also undoes what the record says an add did, keeping any
backend module another installed module needs. `--dry-run` on either
prints every step and changes nothing. In a terminal with no name, both
offer a list to pick from and ask before they change anything. The
menu runs them.
The readme covers the steps for each part, what is refused, patches,
the record in `drx.config.json` and how a core module is told from a
contributed one against a registry that does not say. Under what is
missing it now lists `configure`, the patches commands and running a
module's setup steps.
@coderabbitai

coderabbitai Bot commented Nov 18, 2026

Copy link
Copy Markdown

Important

Review skipped

Too many files!

This PR contains 140 files, which is 40 over the limit of 100.

To get a review, reduce the PR to 100 files or fewer by splitting it into smaller PRs or changing its base branch.

Upgrade to a paid plan to raise the limit.

This review couldn't start because sufficient usage credits or metered capacity aren't available. Add credits or update usage-based reviews in the billing tab, then retry.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 38d32a01-e2fe-47e8-b842-470c5af03928
Commits

Reviewing files that changed from the base of the PR and between 2ba5d25 and 89601ed.

Files ignored due to path filters: 1

  • package-lock.json is excluded by !**/package-lock.json
Files selected for processing: 140

  • .changeset/README.md
  • .changeset/config.json
  • .changeset/first-release-cli.md
  • .changeset/first-release-create-druxt.md
  • .cspell-project-words.txt
  • .cspell.json
  • .devcontainer/devcontainer.json
  • .githooks/commit-msg
  • .githooks/pre-commit
  • .github/ISSUE_TEMPLATE/bug_report.md
  • .github/ISSUE_TEMPLATE/feature_request.md
  • .github/PULL_REQUEST_TEMPLATE.md
  • .github/workflows/ci.yml
  • .gitlab-ci.yml
  • .gitlab/issue_templates/Default.md
  • .gitlab/merge_request_templates/Default.md
  • .gitlab/scripts/check-attribution.sh
  • .gitlab/scripts/install-vale.sh
  • .gitlab/scripts/lint-prose.sh
  • .markdownlint-cli2.jsonc
  • .prettierignore
  • .prettierrc.json
  • .vale.ini
  • .yamllint
  • AGENTS.md
  • CHANGELOG.md
  • CLAUDE.md
  • CONTRIBUTING.md
  • README.md
  • commitlint.config.mjs
  • eslint.config.mjs
  • knip.jsonc
  • package.json
  • packages/cli/LICENSE
  • packages/cli/README.md
  • packages/cli/package.json
  • packages/cli/src/adapters/adapter.ts
  • packages/cli/src/adapters/drupal-modules.ts
  • packages/cli/src/adapters/drupal.ts
  • packages/cli/src/adapters/index.ts
  • packages/cli/src/adapters/nuxt-config.ts
  • packages/cli/src/adapters/nuxt.ts
  • packages/cli/src/adapters/read-json.ts
  • packages/cli/src/args.ts
  • packages/cli/src/bin.ts
  • packages/cli/src/cli.ts
  • packages/cli/src/commands-on-path.ts
  • packages/cli/src/commands/change.ts
  • packages/cli/src/commands/info.ts
  • packages/cli/src/commands/init.ts
  • packages/cli/src/commands/menu.ts
  • packages/cli/src/commands/module.ts
  • packages/cli/src/context.ts
  • packages/cli/src/engines/backend-url.ts
  • packages/cli/src/engines/choose.ts
  • packages/cli/src/engines/ddev.ts
  • packages/cli/src/engines/engine.ts
  • packages/cli/src/engines/files.ts
  • packages/cli/src/engines/index.ts
  • packages/cli/src/engines/lando.ts
  • packages/cli/src/engines/none.ts
  • packages/cli/src/engines/php.ts
  • packages/cli/src/errors.ts
  • packages/cli/src/exec.ts
  • packages/cli/src/fetch-json.ts
  • packages/cli/src/index.ts
  • packages/cli/src/install.ts
  • packages/cli/src/layouts.ts
  • packages/cli/src/modules/change.ts
  • packages/cli/src/modules/compatibility.ts
  • packages/cli/src/modules/entry.ts
  • packages/cli/src/modules/project.ts
  • packages/cli/src/modules/registry.ts
  • packages/cli/src/output.ts
  • packages/cli/src/package-root.ts
  • packages/cli/src/parts.ts
  • packages/cli/src/presentation.ts
  • packages/cli/src/project.ts
  • packages/cli/src/prompts.ts
  • packages/cli/src/registry/entry.ts
  • packages/cli/src/registry/registry.ts
  • packages/cli/src/repeat.ts
  • packages/cli/src/sources.ts
  • packages/cli/src/user-config.ts
  • packages/cli/src/validate.ts
  • packages/cli/test/adapters/adapters.test.ts
  • packages/cli/test/adapters/drupal-modules.test.ts
  • packages/cli/test/adapters/nuxt-modules.test.ts
  • packages/cli/test/cli.test.ts
  • packages/cli/test/commands-on-path.test.ts
  • packages/cli/test/commands/add.test.ts
  • packages/cli/test/commands/info.test.ts
  • packages/cli/test/commands/init-engines.test.ts
  • packages/cli/test/commands/init-guided.test.ts
  • packages/cli/test/commands/init.test.ts
  • packages/cli/test/commands/menu.test.ts
  • packages/cli/test/commands/module.test.ts
  • packages/cli/test/e2e/modules.test.ts
  • packages/cli/test/e2e/quickstart.test.ts
  • packages/cli/test/engines/engines.test.ts
  • packages/cli/test/engines/files.test.ts
  • packages/cli/test/exec.test.ts
  • packages/cli/test/fixtures/quickstart-nuxt.config.js
  • packages/cli/test/helpers/engines.ts
  • packages/cli/test/helpers/entry.ts
  • packages/cli/test/helpers/modules.ts
  • packages/cli/test/helpers/prompter.ts
  • packages/cli/test/helpers/run.ts
  • packages/cli/test/helpers/server.ts
  • packages/cli/test/helpers/starter.ts
  • packages/cli/test/helpers/tmp.ts
  • packages/cli/test/install.test.ts
  • packages/cli/test/modules/compatibility.test.ts
  • packages/cli/test/modules/entry.test.ts
  • packages/cli/test/modules/registry.test.ts
  • packages/cli/test/non-interactive.test.ts
  • packages/cli/test/output.test.ts
  • packages/cli/test/presentation.test.ts
  • packages/cli/test/project.test.ts
  • packages/cli/test/prompts.test.ts
  • packages/cli/test/registry/entry.test.ts
  • packages/cli/test/registry/registry.test.ts
  • packages/cli/test/repeat.test.ts
  • packages/cli/test/seams.test.ts
  • packages/cli/test/sources.test.ts
  • packages/cli/test/user-config.test.ts
  • packages/create-druxt/LICENSE
  • packages/create-druxt/README.md
  • packages/create-druxt/package.json
  • packages/create-druxt/src/bin.ts
  • packages/create-druxt/src/index.ts
  • packages/create-druxt/test/create.test.ts
  • renovate.json
  • scripts/copy-starters.mjs
  • scripts/lint-private-refs.mjs
  • scripts/postinstall.mjs
  • starters/index.json
  • starters/quickstart.json
  • test/private-refs.test.ts
  • vitest.config.ts

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@Decipher

Copy link
Copy Markdown
Member Author

Replaced by a stack of six smaller pull requests, #3 to #8, with the tooling and CI first. The code is the same.

@Decipher Decipher closed this Nov 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant