T8 project commands

.github/workflows/main.yml

@@ -21,13 +21,16 @@ env:
   LANGUAGE: en_US.UTF-8
   LC_ALL: en_US.UTF-8
 
-  # PHP extensions required by Composer and the suite. No Phalcon extension:
-  # this workflow runs the v6 variant, where Phalcon arrives as the
-  # phalcon/phalcon composer dev dependency. When ext-phalcon 5.18 ships, the
-  # v5 variant is added by extending the matrix and installing the extension
-  # through setup-php's `extensions` input.
+  # PHP extensions required by Composer and the suite. The Phalcon extension is
+  # not here: the unit-tests job installs it for the v5 variant only. The v6
+  # variant, and the other jobs, get Phalcon from the phalcon/phalcon composer
+  # dev dependency.
   EXTENSIONS: mbstring, zip
 
+  # The cphalcon constraint for the v5 variant. 5.18 is the first release with
+  # Phalcon\ADR.
+  PHALCON_CONSTRAINT: "^5.18"
+
 permissions: { }
 
 concurrency:
@@ -64,6 +67,9 @@ jobs:
         env:
           COMPOSER_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: "Validate composer"
+        run: composer validate --no-check-all --no-check-publish
+
       # No --ignore-platform-reqs: composer.json pins config.platform.php to
       # 8.1.0, so the lock resolves against the floor and installs cleanly on
       # every matrix cell.
@@ -78,8 +84,11 @@ jobs:
       - name: "PHPStan"
         run: composer analyze
 
+      - name: "PHP CS Fixer (dry-run)"
+        run: composer cs-fixer
+
   unit-tests:
-    name: "Unit tests"
+    name: "Unit tests (PHP ${{ matrix.php }}, Phalcon ${{ matrix.variant }})"
 
     permissions:
       contents: read
@@ -100,6 +109,10 @@ jobs:
           - '8.3'
           - '8.4'
           - '8.5'
+        variant:
+          # v5 = cphalcon C extension; v6 = phalcon/phalcon composer package
+          - 'v5'
+          - 'v6'
 
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -117,6 +130,20 @@ jobs:
         env:
           COMPOSER_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+      # v5 only, with the same PIE install as resources/docker/Dockerfile.
+      # PIE writes to the extension directory, so it needs sudo. sudo resets
+      # PATH, so "$(which php)" names the PHP that setup-php installed.
+      # phalcon/phalcon stays in vendor/, as in the v5 dev container. The
+      # extension classes load first, so the package does not replace them.
+      - name: "Install the Phalcon extension"
+        if: matrix.variant == 'v5'
+        env:
+          PIE_VERSION: '1.5.0'
+        run: |
+          curl -fsSL "https://github.com/php/pie/releases/download/${PIE_VERSION}/pie.phar" -o "${RUNNER_TEMP}/pie.phar"
+          sudo "$(which php)" "${RUNNER_TEMP}/pie.phar" install --no-interaction "phalcon/cphalcon:${PHALCON_CONSTRAINT}"
+          php -m | grep -i phalcon
+
       # No --ignore-platform-reqs: composer.json pins config.platform.php to
       # 8.1.0, so the lock resolves against the floor and installs cleanly on
       # every matrix cell.
@@ -177,7 +204,10 @@ jobs:
       - name: "Tests with coverage"
         run: composer test-coverage
 
+      # Push only: a pull request from a fork gets no SONAR_TOKEN. SonarQube
+      # runs before octocov, so a failed octocov gate cannot skip the upload.
       - name: "SonarQube Scan"
+        if: github.event_name == 'push'
         uses: SonarSource/sonarqube-scan-action@ba9859eae8dd6bd29e412f25ddbbef3d032000f4 # v8.2.2
         env:
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

CHANGELOG.md

@@ -26,6 +26,11 @@ All notable changes are documented here. The format is based on [Keep a Changelo
 - Added `Crest\Command\ProjectCommand::writer()`, assembling the stub writer once instead of repeating the same three-argument construction in five `make:*` commands. [#5](https://github.com/phalcon/crest/issues/5)
 - Added `methodFor()` to `Crest\ADR\ActionResolver`, so the HTTP method an Action answers is asked of the framework rather than derived from the class name. [#1](https://github.com/phalcon/crest/issues/1)
 - Added `Crest\Console\Registry::descriptions()` and `Crest\Console\Output::commandTable()`, so a bare `crest` and `crest list` render the command listing through one path instead of two copies kept in agreement by hand.
+- Added `new`, creating an ADR project from stubs: front controller, web entry point, `crest.php`, an action for `GET /`, `composer.json` and docker files. It runs nothing - no composer, no docker, no network. `--namespace`, `--php` and `--phalcon` set the root namespace, the PHP version and the Phalcon variant. The project requires `phalcon/crest` as a dev dependency: the commands that work on the project need its autoloader and its Phalcon, so they run as `vendor/bin/crest`, not with the crest that created the project. The generated `crest.php` states `paths.action`, so a later crest default does not move the actions. `new` renders every file before it writes the first one, so a published stub that does not render leaves no files. [#8](https://github.com/phalcon/crest/issues/8)
+- Added `up`, `down` and `install`, running `docker compose up -d`, `docker compose down` and `composer install` in the `app` container of a project that `new` created. `--directory` names the project. [#8](https://github.com/phalcon/crest/issues/8)
+- Added `Crest\Process\Runner`, the seam through which commands run external programs, with `ShellRunner` as the default. A missing program or working directory is reported as a crest error. [#8](https://github.com/phalcon/crest/issues/8)
+- Added `Crest\Generator\ClassName::namespace()`, validating a namespace with the same identifier rule as a class name. [#8](https://github.com/phalcon/crest/issues/8)
+- Added `Crest\Command\Make\NamedArtifactCommand`, the base of `make:command`, `make:middleware`, `make:provider` and `make:responder`. The four commands repeated the same `handle()` and `define()`; each now gives only its key, its suffix, its description, an example name and the instructions it prints after the file is written. The base declares the `name` argument and the `--force` option, because `handle()` reads both, so a new generator cannot leave them out.
 
 ### Changed
 
@@ -40,6 +45,8 @@ All notable changes are documented here. The format is based on [Keep a Changelo
 - `route:list` and `make:action` now accept an `ActionResolver`, defaulted so the kernel still constructs them with no arguments. This is what lets a test prove the routing answers come from the framework rather than from crest. [#5](https://github.com/phalcon/crest/issues/5)
 - `event:list` now reads every listener in a single `getListenerMap()` call instead of one call per event type. [#1](https://github.com/phalcon/crest/issues/1)
 - `phalcon/talon` moved from `^0.8` to `^0.9`.
+- `stub:publish` with no name leaves out the `project-*` stubs that `new` renders. They have an effect only in the directory that `new` puts the project into; publish one by name. A `project-*` name goes where `new` reads it - the working directory, or `--directory` - with the `adr` flavor, and needs no `crest.php`. [#8](https://github.com/phalcon/crest/issues/8)
+- Rendering a stub now fails when a placeholder has no value, and the error names the stub file. A published copy that kept a placeholder crest no longer sends put the raw `{{ name }}` into the generated file. [#8](https://github.com/phalcon/crest/issues/8)
 
 ### Fixed
 

README.md

@@ -20,25 +20,40 @@ Command line application for Phalcon - generators, introspection and project too
 ## Requirements
 
 - PHP `^8.1`
-- Phalcon, either the `ext-phalcon` C extension (`^5`) or the `phalcon/phalcon` PHP
+- Phalcon, either the `ext-phalcon` C extension (`^5.18`) or the `phalcon/phalcon` PHP
   implementation (`^6`) - crest itself needs neither to run
 
 ## Install
 
+In a project:
+
     composer require --dev phalcon/crest
 
+To create projects, also install crest globally. The global composer `vendor/bin`
+directory must be in your `PATH`:
+
+    composer global require phalcon/crest
+
 ## Usage
 
+In a project, use the crest in `vendor/`. The commands that work on the project need
+the project autoloader and its Phalcon:
+
     vendor/bin/crest                      list available commands
     vendor/bin/crest about                environment and version report
     vendor/bin/crest make:action GET /company/all
 
+To create a project, use the global crest. The new project requires `phalcon/crest`, so
+after `composer install` it has its own `vendor/bin/crest`:
+
+    crest new my-app                      create an ADR project
+
 ## Global options
 
 | Option | Purpose |
 |---|---|
 | `--config=<file>` | explicit path to `crest.php` |
-| `--directory=<dir>` | project root override |
+| `--directory=<dir>` | project root override; for `new`, the directory the project is created in |
 | `--trace` | full exception trace |
 | `--help`, `-h` | usage for the current command |
 | `--quiet`, `-q` | suppress non-essential output |
@@ -93,6 +108,9 @@ filesystem and keeps working on a project that does not currently run.
 Copy a stub into `resources/stubs/<flavor>/` in your project and crest uses yours instead
 of the packaged one.
 
+The `project-*` stubs that `new` renders are published by name only. See
+[docs/index.md](docs/index.md#creating-a-project).
+
 ## Development
 
     docker compose up -d

composer.json

@@ -9,7 +9,6 @@
     },
     "require-dev": {
         "friendsofphp/php-cs-fixer": "^3",
-        "infection/infection": "^0.29",
         "pds/composer-script-names": "^1",
         "pds/skeleton": "^1",
         "phalcon/phalcon": "v6.0.x-dev",