Repository navigation
Conversation
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.
… request templates
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.
|
Important Review skippedToo 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.
|
Member
Author
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 join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
What changed
The first cut of the Druxt command-line tool: two packages in an npm workspace.
@druxt/cli, with thedrxbinary.drx initcreates 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 indrx.config.json.drx inforeports the project's layout, its parts and the versions of their packages.drx module list,searchandinforead the Druxt module registry, and in a project show which modules are installed and compatible.drx addanddrx removeinstall a module in the frontend, add it to the framework's config, and require and enable the Drupal modules it needs.--dry-runprints every step.drxwith no command opens a menu.--no-interactive,DRX_NO_INTERACTIVE=1,CIand a missing terminal each turn every prompt off.--jsongives each command's result as data.create-druxt, sonpm create druxtrunsdrx init.starters/, in giget's registry format, with one entry fordruxt/quickstart.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 lintandnpm run typecheckpassnpm testpasses, and coverage did not dropRun by hand on the built binary:
drx initagainst the real quickstart tarball,drx info, the module commands against the published registry, anddrx add --dry-runin a created site.Not covered yet
drx addordrx remove: every package manager, Composer and Drush call is replaced by a stand-in in the tests.initprints follow the quickstart's README.drx module configure, thedrx patchescommands, the split and workspace layouts, and sources other than npm answer "not available yet".starters/directory onmain, so it falls back to the bundled copy until this is merged.