Fix Satis deploy docs: pin dev-main, separate install dir from executable path (#10)

Three real deploy bugs hit in the field:

1. `composer create-project composer/satis` unpinned resolves to satis
   1.0.0 (the only stable tag), which requires php ^5.6 || ^7.0 and
   fails on modern PHP. Pin composer/satis:dev-main.

2. deploy.md used $CRATE_SATIS_PATH as both the create-project target
   (a directory) and the value BuildSatis executes as the satis binary.
   These are two different paths: the executable lands at
   <install-dir>/bin/satis and Composer does not link a root package's
   bin into vendor/bin. Build Command and crate:install examples now
   use distinct install-dir / executable paths.

3. The config default (vendor/bin/satis) contradicts the "keep Satis
   isolated" rule — it only exists if Satis is required into the app
   vendor tree. All three docs now describe CRATE_SATIS_PATH as the
   isolated Satis executable path and state isolated deploys must set
   it explicitly; config gains a clarifying comment (default unchanged).

Co-authored-by: Ed Grosvenor <ed@artisan.build>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: 3 people

README.md

@@ -74,7 +74,7 @@ Crate-specific server config lives in `config/crate-server.php`:
 
 - `CRATE_URL`: the public registry URL used as Satis `homepage` and archive prefix.
 - `CRATE_ARCHIVE_DISK`: disk for Composer metadata and mirrored dist archives.
-- `CRATE_SATIS_PATH`: path to the isolated Satis binary.
+- `CRATE_SATIS_PATH`: path to the isolated Satis executable (`<install-dir>/bin/satis`), run directly by the build job. Install Satis with `composer create-project composer/satis:dev-main` (an unpinned install resolves to the ancient 1.0.0 stable and fails on modern PHP). The default (`vendor/bin/satis`) only applies if Satis is installed into the app's vendor directory, which is discouraged — isolated deploys must set this explicitly. See `docs/deploy.md`.
 - `CRATE_OUTPUT_DIR`: storage prefix for generated registry output.
 
 Do not hand-set Laravel Cloud managed resource credentials for database, queue, cache, or object storage. Let Cloud inject them.

docs/deploy.md

@@ -24,10 +24,22 @@ Install the app dependencies, then install Satis as an isolated tool with its ow
 
 ```bash
 composer install --no-dev --prefer-dist
-composer create-project composer/satis "$CRATE_SATIS_PATH" --no-dev
+composer create-project composer/satis:dev-main ../satis-tool --no-dev
 ```
 
-Do not `composer require` Satis into the Crate app. It must stay isolated because its dependency tree is separate from the Laravel app's dependency tree.
+Pin `dev-main` explicitly. Satis has no recent stable tag, so an unpinned `composer create-project composer/satis` resolves to satis 1.0.0 and fails on any modern runtime with:
+
+```
+Cannot use composer/satis's latest version 1.0.0 as it requires php ^5.6 || ^7.0 which is not satisfied by your platform.
+```
+
+Note the two distinct paths involved. The `create-project` target (`../satis-tool` above) is the install *directory*; the Satis *executable* lands inside it at `../satis-tool/bin/satis` (Composer does not link a root package's bin into `vendor/bin`). `CRATE_SATIS_PATH` must point at the executable, not the install directory — Crate's build job runs that path directly:
+
+```bash
+CRATE_SATIS_PATH=../satis-tool/bin/satis   # prefer an absolute path in real deploys
+```
+
+Do not `composer require` Satis into the Crate app. It must stay isolated because its dependency tree is separate from the Laravel app's dependency tree. Because Satis lives outside the app, the config default for `CRATE_SATIS_PATH` (`vendor/bin/satis`, which would only exist if Satis were required into the app) never applies — an isolated deploy must always set `CRATE_SATIS_PATH` explicitly.
 
 Ensure `git` is available anywhere Satis runs, including the build and queue runtimes. Satis uses it to read VCS repositories during registry builds.
 
@@ -40,18 +52,20 @@ Run the installer on the deployed environment. Run it interactively (it prompts
 php artisan crate:install
 
 # non-interactive (a bare crate:install with no TTY and no flags makes no changes)
+# --satis-path is the Satis EXECUTABLE inside the isolated install from the
+# Build Command step, not the install directory
 php artisan crate:install --no-interaction \
   --url="https://crate.example.com" \
   --archive-disk="crate-archive" \
-  --satis-path="$CRATE_SATIS_PATH" \
+  --satis-path="/path/to/satis-tool/bin/satis" \
   --credential-api=true
 ```
 
 The installer is idempotent and will not overwrite an existing value without confirmation (pass `--force` non-interactively). It configures only these app values:
 
 - `CRATE_URL`: the public Crate registry URL used as the Satis homepage and archive prefix.
 - `CRATE_ARCHIVE_DISK`: the object-storage filesystem disk name Crate should use for Satis output and mirrored archives.
-- `CRATE_SATIS_PATH`: the path to the isolated Satis binary or installation.
+- `CRATE_SATIS_PATH`: the path to the isolated Satis executable (`<install-dir>/bin/satis`), which the build job executes directly. The config default (`vendor/bin/satis`) only applies if Satis is installed into the app's own vendor directory — which the Build Command section advises against — so isolated deploys must set this explicitly.
 - `BUILT_FOR_CLOUD_CREDENTIAL_API_ENABLED`: whether built-for-cloud's admin-token credential API is enabled.
 
 Then run migrations:

packages/crate-server/README.md

@@ -76,7 +76,7 @@ Environment variables:
 
 - `CRATE_URL`: public registry URL used by Satis metadata and dist archive URLs.
 - `CRATE_ARCHIVE_DISK`: storage disk for generated metadata and mirrored archives. Defaults to `FILESYSTEM_DISK` then `local`.
-- `CRATE_SATIS_PATH`: isolated Satis binary path. Defaults to `vendor/bin/satis`.
+- `CRATE_SATIS_PATH`: path to the isolated Satis executable (`<install-dir>/bin/satis`), executed directly by `BuildSatis`. Defaults to `vendor/bin/satis`, which only applies if Satis is installed into the app's own vendor tree — isolated installs (recommended; install via `composer create-project composer/satis:dev-main`) must set it explicitly.
 - `CRATE_OUTPUT_DIR`: storage prefix for generated registry output. Defaults to `satis`.
 - `CRATE_DB_*`: optional separate database connection settings. If omitted, the app's default database connection is reused as `crate`.
 

packages/crate-server/config/crate-server.php

@@ -5,6 +5,10 @@
 return [
     'url' => env('CRATE_URL'),
     'archive_disk' => env('CRATE_ARCHIVE_DISK', env('FILESYSTEM_DISK', 'local')),
+    // The Satis EXECUTABLE (BuildSatis runs this path directly), not an install
+    // directory. The default only exists if Satis is required into the app
+    // vendor tree; isolated installs must set CRATE_SATIS_PATH to
+    // <install-dir>/bin/satis. See docs/deploy.md.
     'satis_path' => env('CRATE_SATIS_PATH', base_path('vendor/bin/satis')),
     'output_dir' => env('CRATE_OUTPUT_DIR', 'satis'),