From 5738b60cf2ffa0df768d70f7dd80c329772fec28 Mon Sep 17 00:00:00 2001 From: Kit <344842+roodboi@users.noreply.github.com> Date: Fri, 13 Nov 2026 19:50:42 +0000 Subject: [PATCH 1/2] docs: add a short v5 start-here path (HACK-2195) --- AGENTS.md | 1 + docs/guides/native-candidate.md | 61 +++------ docs/versions/v5/getting-started.md | 87 +++++++++---- docs/versions/v5/guides/init-project.md | 9 +- docs/versions/v5/index.md | 9 +- docs/versions/v5/install.md | 129 ++++++++++--------- docs/versions/v5/native/start.md | 109 ++++++++++++++++ docs/versions/v5/troubleshooting.md | 51 ++++++++ docs/versions/v5/upgrade.md | 159 +++++++++++++----------- scripts/docs/prepare.ts | 5 +- scripts/docs/smoke.ts | 2 + scripts/docs/versions.json | 29 ++++- 12 files changed, 440 insertions(+), 211 deletions(-) create mode 100644 docs/versions/v5/native/start.md create mode 100644 docs/versions/v5/troubleshooting.md diff --git a/AGENTS.md b/AGENTS.md index 7115b035e..22c184dee 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -71,6 +71,7 @@ when testing Hack behavior. Keep host-native virtualization, routing/trust, and resource benchmarks on the host they qualify. Container checks do not replace them. For a behavior change, add or update the closest regression test and affected docs. +A PR that changes user-visible behavior updates the affected short page in the v5 start-here path in the same PR. Run focused checks first, then required CI gates. Documentation-only changes need link, generation, and contract checks rather than artificial unit tests. After applicable checks pass, broaden or repeat them only for a new change, failure, diff --git a/docs/guides/native-candidate.md b/docs/guides/native-candidate.md index 028d26d10..2e507b3f8 100644 --- a/docs/guides/native-candidate.md +++ b/docs/guides/native-candidate.md @@ -1,9 +1,9 @@ # Native backend reference This is the detailed reference for the native backend (beta). It is long and -precise. For a short introduction, read the [overview](../native/README.md), -[try it](../native/try-it.md) and -[what works and known limits](../native/limits.md). The +precise. For the first run, use [Try native on Apple Silicon](https://hack.foo/docs/v5/native/start). +The [overview](../native/README.md) and +[known limits](../native/limits.md) explain its scope. The [reference map](../native/reference.md) lists this page's sections by topic. The native backend is beta. `hack-native` is an opt-in Apple Silicon macOS executor installed alongside @@ -108,40 +108,15 @@ for this stable home; `channel` reports `installed-candidate`. State remains und child processes bind to its identity. Moving an executable is supported; moving an active home or adopting another installation's state is not. -Run the normal project CLI through the bundle's `hack-v5` entrypoint: - -```sh -export HACK_NATIVE_HOME=/absolute/private/candidate-home -/absolute/copied/hack-native-bundle/hack-v5 ps --path /absolute/project -``` - -Keep the bundle together and invoke this entrypoint by its full path (do not copy -or symlink only the script). With `HACK_RUNTIME_BACKEND` unset (or `native`) it -selects the native backend and the adjacent executor, even if an inherited -`HACK_NATIVE_BINARY` selects another binary. An explicit -`HACK_RUNTIME_BACKEND=compose` runs the same bundled CLI on the Compose backend -with your own Hack home and existing global routing services. It needs no -`HACK_NATIVE_HOME` and removes the native selectors. Other values refuse with exit -code 64. The [candidate installer guide](https://github.com/hack-dance/hack/blob/next/docs/guides/candidate-install.md#test-both-backends) -describes Compose testing and its shared-state limits: run stable `hack global up`, -then any stable `hack doctor` or `hack doctor --fix`, then stable `hack daemon stop`, -confirm `pgrep -fl "hack daemon start"` prints nothing, and run no stable `hack` -command while the candidate uses your Hack home. Stable `hack global up` (v4.2.0) -starts a stopped `hackd` again, and so does stable `hack doctor --fix` (it asks -first only in a terminal). If the check lists a process, the guide gives the -launchd remedy. The entrypoint turns off daemon autostart in newer builds, so the -candidate does not start the stable `hackd` on its own: a candidate -`hack doctor --fix` skips its `hackd` repair without asking and prints the -command to run yourself, which runs the stable CLI. Do not commit the -project's generated `.hack/.internal/` directory; newer generators rewrite files -such as `compose.override.yml`. The entrypoint preserves arguments, exit codes and -signals through `exec`, and never replaces the installed `hack`. Project-specific -native adaptation, dependency and routing selections remain explicit; this entrypoint -does not prepare a provider or migrate existing projects. An unversioned local -build reports the repository package version. A versioned prerelease build reports -its explicit candidate version and includes source provenance. The `hack-v5` -entrypoint alone does not identify a published release. Unsupported native workflows still -report their existing refusal rather than falling back to Docker. +For normal project commands, follow the short +[native start page](https://hack.foo/docs/v5/native/start). Manual bundle users +use the adjacent `hack-v5` entrypoint with an explicit `HACK_NATIVE_HOME`; +keep the bundle together. The [candidate installer guide](candidate-install.md#test-both-backends) +defines backend selectors, private versus shared homes, stable-daemon quiescence +and returning to Compose. Neither entrypoint prepares the provider, migrates a +project or falls back to Docker for an unsupported native command. An unversioned +local build reports its repository version; only a versioned bundle includes +candidate version provenance. The entrypoint alone does not identify a release. Native `up` accepts an explicit branch or the branch inferred from a linked Git worktree when its exact source root can be shared with a fresh or matching pool. @@ -934,15 +909,9 @@ compatibility. V4 and candidate homes remain separate; this procedure does not migrate V4 data into the candidate or replace the installed `hack`. DNS, trust and client configuration are outside this bundle-selection procedure. -Provider setup is separate and explicit. Prepare the native runtime with: - -```sh -./hack-native --candidate-root /absolute/private/candidate-home runtime setup -``` - -`runtime setup` lists the pinned SmolVM, Docker engine and four Alpine guest -packages with their exact compressed byte lengths, source hosts, SHA-256 hashes, private cache and -install destination, then asks once when preparation is needed. `--no-interactive` (or +For ordinary setup and consent, use the short +[native start page](https://hack.foo/docs/v5/native/start#prepare-the-runtime). +The remainder describes the setup and recovery contract. `--no-interactive` (or truthy `HACK_NO_INTERACTIVE` values `1`, `true`, `yes` or `on`, ignoring case and surrounding whitespace) refuses with `E_INTERACTIVE_REQUIRED` unless `--accept-downloads` explicitly consents. No provider download happens from `up`, diff --git a/docs/versions/v5/getting-started.md b/docs/versions/v5/getting-started.md index d95f9079e..fe2d3684d 100644 --- a/docs/versions/v5/getting-started.md +++ b/docs/versions/v5/getting-started.md @@ -1,47 +1,84 @@ -# Getting started +# First project on Compose -Complete [Install](install.md) first. These steps use the default Docker Compose -backend. For the native backend (beta), read -[Try the native backend](native/try-it.md) after this page. +Start here: [1. Install](install.md) → **2. First project** → +[3. Upgrade from v4](upgrade.md) or [4. Try native](native/start.md). -## Initialize one project +Use the terminal from Install: `hack` selects v5 and +`HACK_RUNTIME_BACKEND=compose` is exported. Docker must be running. +An existing v4 project should follow the upgrade page before these steps. -From a repository you own: +```mermaid +--- +title: First Compose run +--- +sequenceDiagram + autonumber + participant You + participant Hack + participant Compose + You->>Hack: init + Hack-->>You: Review .hack files + You->>Hack: up + Hack->>Compose: Start services + You->>Hack: open and logs + Hack-->>You: URL and output + You->>Hack: down + Hack->>Compose: Stop project +``` + +## Set up your repository + +From the repository you want to run: ```sh cd your-project hack init ``` -Review the generated `.hack/` files before starting anything. Keep configuration in -git and keep the secret key and local state out of it. For an existing Compose -project, custom domains or agent-assisted setup, follow -[Project setup](guides/init-project.md). +Follow the service and domain prompts. Discovery suggests services from the app's +packages; review the images and commands it proposes. To adopt an existing Compose +app, use `hack init --manual` for a scaffold, then put the needed service definitions +in `.hack/docker-compose.yml`. Adjust relative build and mount paths for that +file's location; keep the original Compose file until the app checks pass. +This is the Compose setup path; `hack config adopt` is a separate native configuration path. +If `.hack/` already exists, review that setup instead of replacing it. + +Check `.hack/docker-compose.yml`: its images, commands, ports and mounts should +match your app. Check the local URL in the service's routing labels. Commit shared +configuration, but never the project key `.hack.secret.key` or local env layers. +[Project setup](guides/init-project.md) explains discovery and custom domains. -## Start, inspect and stop +## Start and open ```sh hack up --detach -hack open hack ps -hack logs --no-follow --tail 50 +hack open ``` -Expected: the declared services start, `open` prints or opens the instance URL, -and `ps` shows service state. Visit the app and run its own health check. A URL or -a running container alone does not prove the app works. If startup fails, read the -error and run `hack doctor` before trying again. +Expect the declared services in `ps` and the app's local URL from `open`. +If a project has several URLs, choose the app's route. A worker-only project may +have no URL. Sign in or load a page that reads data to check the app itself. + +A failed startup prints a reason. Read it before retrying; use +[troubleshooting](troubleshooting.md) and `hack doctor` for setup problems. + +## Read logs and stop ```sh -hack down +hack logs --no-follow --tail 50 +hack logs --follow ``` -Stop releases project-owned runtime processes. It does not delete application -data or prune shared caches. [Run and inspect](guides/run-project.md) covers -selected services and log history. +The first command prints a snapshot. The second keeps watching. Ctrl-C stops +watching the logs; it does not stop the project. Logs may contain secret values. +Do not paste raw logs into a public issue. -## Next +```sh +hack down +``` -- [Core concepts](../core.md) explains projects, services and instances. -- [Work on another branch](guides/parallel-work.md) runs a second instance beside the first. -- [Agent handoff](agent-handoff.md) gives a coding agent the same documentation. +This stops the project. It does not delete its named volumes or stop shared +routing services. See [Run and inspect](guides/run-project.md) for service selection, +log history and restarts. When this Compose run works, try native only on a +[disposable project](native/start.md). diff --git a/docs/versions/v5/guides/init-project.md b/docs/versions/v5/guides/init-project.md index 427fdf5e2..05d71a273 100644 --- a/docs/versions/v5/guides/init-project.md +++ b/docs/versions/v5/guides/init-project.md @@ -11,12 +11,17 @@ cd your-project hack init ``` -`hack init` detects an existing `docker-compose.yml`, asks about services and -domains, and writes `.hack/`: the Compose file Hack manages, `hack.config.json`, +`hack init` discovers app packages, asks about services and domains, and writes +`.hack/`: the Compose file Hack manages, `hack.config.json`, the default env YAML and a `.gitignore` for machine-local state. Review the files and commit them. To hand setup to an agent instead, run `hack init --with claude` or `hack init --with codex`. +It does not automatically adopt an existing Compose file. Use `hack init --manual` +for a scaffold, then copy the needed service definitions into +`.hack/docker-compose.yml`. Review relative build and mount paths, env delivery +and Hack routing labels before starting; keep the old file until the app works. + For an existing project, `hack agent onboard` prints an onboarding prompt that describes the services, env and routing a Hack setup should cover. See [Explicit agent setup](agent-first-setup.md). diff --git a/docs/versions/v5/index.md b/docs/versions/v5/index.md index e979bcc6d..11e2ffa6b 100644 --- a/docs/versions/v5/index.md +++ b/docs/versions/v5/index.md @@ -11,7 +11,14 @@ macOS) is opt-in and ships only through the `hack-next` channel, not in the stab archives or the Homebrew formula. Read [Upgrade from v4](upgrade.md) for what changed and what was retired. -Start with [Install](install.md), then [Getting started](getting-started.md). +## Start here + +1. [Install v5](install.md): choose a channel and set up Compose routing. +2. [First project on Compose](getting-started.md): set up, start, open, read logs and stop. +3. [Upgrade from v4](upgrade.md): back up first, try one project and roll back. +4. [Try native on Apple Silicon](native/start.md): prepare, check, start and return to Compose. + +[Troubleshooting](troubleshooting.md) maps common Doctor findings to their fixes. [What's new in 5.0](../guides/v5-release-notes.md) summarizes the release. v5 prerelease bundles are Apple Silicon macOS only; see [Install](install.md#prerequisites) for platform support. diff --git a/docs/versions/v5/install.md b/docs/versions/v5/install.md index 1031f9d28..cd6b67bed 100644 --- a/docs/versions/v5/install.md +++ b/docs/versions/v5/install.md @@ -1,26 +1,30 @@ -# Install - -v5 is in prerelease. Stable Hack today is the v4 line, installed with Homebrew or -the release installer. v5 prereleases install beside it through a separate -channel, `hack-next`, so you can try v5 without touching your stable setup. When -5.0.0 ships, the Homebrew formula and release installer move to v5. - -## Prerequisites - -- A running Docker-compatible engine with Docker Compose for the default backend. - Check it with `docker info` and `docker compose version`. -- For the native backend (beta): an Apple Silicon Mac. See - [Native backend (beta)](native/overview.md). -- Local DNS and certificate trust are set up once per machine by `hack global - install` and can ask for native approval. - -v5 prerelease bundles are published for Apple Silicon macOS only. Other platforms -stay on stable v4 until 5.0.0. +# Install v5 + +Start here: **1. Install** → [2. First project](getting-started.md). +Already using v4? Read [3. Upgrade from v4](upgrade.md) before running v5 in a project. + +v5 is in prerelease. Stable is still v4. A stable install does **not** install v5. +The v5 prerelease bundle supports Apple Silicon macOS. Linux and Intel Macs stay +on stable v4; see [platform support](../guides/prereleases.md). +The [Linux host setup](../guides/linux-setup.md) and +[Linux certificate trust](../guides/linux-certificate-trust.md) guides cover host +configuration, not a Linux v5 candidate bundle. + +```mermaid +--- +title: Choose an install channel +--- +flowchart TD + Need{Which channel?} -->|Stable v4| Stable[Install hack] + Need -->|Try v5| Candidate[Install hack-next] + Candidate --> Compose[Select Compose] + Compose --> First[First project] + Stable --> V4[Follow v4 docs] +``` -## Install the current prerelease +## Install beside stable -Each prerelease has an immutable tag, `v5.0.0-next.N`. Download the bootstrap -from the release you want and run it: +Download the installer from an exact release. Review it before running it: ```sh curl --fail --location --proto '=https' --proto-redir '=https' --tlsv1.2 \ @@ -29,61 +33,68 @@ curl --fail --location --proto '=https' --proto-redir '=https' --tlsv1.2 \ less hack-next-install.sh sh hack-next-install.sh "$HOME/.hack-next/bin/hack-next" --version +"$HOME/.hack-next/bin/hack-next" --manager status ``` -The bootstrap pins its manager checksum and release version. It installs into -`~/.hack-next`, does not edit your PATH or shell profile, and leaves the stable -`hack` executable and `~/.hack` untouched. Installing does not migrate projects, -start a VM, or change DNS or trust. +Expect the version you chose and a selected bundle in the manager's report. +Newer releases are on [GitHub](https://github.com/hack-dance/hack/releases). +Check a release's notes before replacing the tag above. -Newer prereleases are listed on the [releases page](https://github.com/hack-dance/hack/releases). -Replace the tag in the URL to install a different one. The -[prerelease channel guide](../guides/prereleases.md) explains versioning, platform -support and the installer in detail. +| Channel | What it installs | Project state | +| --- | --- | --- | +| Stable `hack` | Homebrew's executable, or `~/.hack/bin/hack` with the release installer | Uses `~/.hack` | +| Prerelease `hack-next` | Launcher and versioned bundles under `~/.hack-next` | Native uses private homes per version; Compose shares `~/.hack` with stable | -## Choose a backend +The prerelease installer leaves stable alone. It does not edit PATH, start a VM, +or set up DNS or certificate trust. [Install details](../guides/candidate-install.md) +cover custom roots, checksums and version changes. -The `hack` CLI runs on Docker Compose unless you select native with -`HACK_RUNTIME_BACKEND=native`. The `hack-next` launcher is the exception: it -exists to test the native candidate, so it selects native by default and -version-private homes. To run the prerelease CLI on Compose against your -ordinary Hack home: +For stable v4 on macOS, use `brew install hack-dance/tap/hack`; the +[stable install instructions](https://github.com/hack-dance/hack/blob/main/README.md#install) +cover the release installer too. Check it with `command hack --version`. -```sh -export HACK_RUNTIME_BACKEND=compose -"$HOME/.hack-next/bin/hack-next" --version -``` - -The export applies to every later `hack-next` command in that shell. A one-off -`HACK_RUNTIME_BACKEND=compose` prefix selects Compose for that command only; the -next command without it runs native again. Unset the variable before native testing. +## Select v5 on Compose -On Compose, the prerelease shares project state with stable v4. Do not run both -against the same home at the same time, including their daemons. The -[prerelease install page](../guides/candidate-install.md#stop-stable-hackd-before-a-compose-run) gives -the exact order: stop the stable daemon first, then run the prerelease. +Have a running Docker-compatible engine and Docker Compose. Check with +`docker info` and `docker compose version`. -The rest of these docs write `hack` for the v5 CLI. During the prerelease, in the -shell where you exported the backend, run the examples through the launcher: +`hack-next` selects **native** unless you select Compose. In this terminal: ```sh +export HACK_RUNTIME_BACKEND=compose hack() { "$HOME/.hack-next/bin/hack-next" "$@"; } +hack --version ``` -This shell function lasts for the session and does not touch your PATH or the -stable `hack` executable in other shells. +The function makes `hack` mean the v5 candidate in this terminal only. It does not +replace the stable executable. Keep this terminal for the next page. A new +terminal needs these two setup lines again. -## Set up local routing +**Existing v4 users:** stop here and follow [the upgrade steps](upgrade.md). +Stable and the candidate must not run against the shared home at the same time. -Once per machine: +For a new machine, set up Compose routing once: ```sh hack global install ``` -This configures shared local routing, DNS and certificate trust. Read its prompts. -On Linux, see [Linux host setup](../guides/linux-setup.md) for DNS and daemon setup -and [Linux certificate trust](../guides/linux-certificate-trust.md) for distribution -and browser trust stores. These guides do not extend the prerelease bundle's -platform support described above. -Continue with [Getting started](getting-started.md). +Read the prompts for DNS and certificate trust. Host changes can require your +approval. Then continue to [First project on Compose](getting-started.md). + +## Stop using or remove an install + +Stop its projects with `hack down` first. For a login daemon, use that install's +`hack daemon stop` and `hack daemon uninstall` before removing its executable. + +- Homebrew: `brew uninstall hack-dance/tap/hack`. +- Release installer: remove only the executable `~/.hack/bin/hack`. Keep the rest + of `~/.hack` if you need its configuration or keys. +- Prerelease: stop every retained version's workloads, then run + `"$HOME/.hack-next/bin/hack-next" --manager stable` to deselect it. This keeps + the bundles and data. To remove the whole channel, save wanted data elsewhere + before removing `~/.hack-next`; that removes all its version-private homes too. + +Removing an executable does not undo host DNS/trust, project files or volumes. +For a candidate rollback or return to stable, use +[the full procedure](../guides/candidate-install.md#upgrade-roll-back-and-return-to-stable). diff --git a/docs/versions/v5/native/start.md b/docs/versions/v5/native/start.md new file mode 100644 index 000000000..e55b15653 --- /dev/null +++ b/docs/versions/v5/native/start.md @@ -0,0 +1,109 @@ +# Try native on Apple Silicon + +Start here: [1. Install](../install.md) · [2. First project](../getting-started.md) · +[3. Upgrade](../upgrade.md) · **4. Try native**. + +Use an Apple Silicon Mac and a disposable project with synthetic data. Native +runs services in Hack's Linux VM. It is beta; it does not move Compose volumes +or prove that every Compose feature works. Read [the limits](limits.md) first. + +```mermaid +--- +title: Native start and return +--- +stateDiagram-v2 + direction TB + [*] --> Unprepared + Unprepared --> Prepared: setup with consent + Prepared --> Review: preflight + Review --> Blocked: blockers or incomplete + Blocked --> Review: fix and rerun + Review --> Running: ready and up succeeds + Review --> Inspect: up fails + Running --> Stopped: down + Inspect --> Stopped: cleanup confirmed + Stopped --> [*]: choose Compose +``` + +## Prepare the runtime + +Keep the `hack-next` install from [Install](../install.md). Use the exact version +shown by `"$HOME/.hack-next/bin/hack-next" --manager status`: + +```sh +V=5.0.0-next.16 +NATIVE="$HOME/.hack-next/versions/$V/bundle/hack-native" +NATIVE_HOME="$HOME/.hack-next/versions/$V/native-home" +CANDIDATE="$HOME/.hack-next/bin/hack-next" +unset HACK_RUNTIME_BACKEND +``` + +Do not use the Compose shell function from page 1 for native commands. The full +launcher path below selects native and that version's private homes. + +Today's setup command is: + +```sh +"$NATIVE" --candidate-root "$NATIVE_HOME" runtime setup +``` + +A `hack` command for this step is coming (HACK-2193); only this setup line needs +to change when it lands. Setup shows file sizes, download hosts, hashes and +locations, then asks for consent. Read the list. `up` never downloads the runtime +for you. A matching install is checked and reused. For offline inputs or an +interrupted download, use [setup and recovery details](setup.md). + +## Check before starting + +```sh +"$CANDIDATE" doctor --native-preflight --path /absolute/project +``` + +Add the project's `--profile` selection if needed. Preflight reads the Compose +project and lists blockers with fixes. It starts no VM or service. Continue only +when there are no blockers **and** the runtime review completed with `ready: true`. +An exit of 0 alone is not enough: runtime review can be skipped or unavailable. + +If blocked, fix the named field and rerun. Do not remove a check or delete state +to force a start. Keep the project on Compose if it needs unsupported behavior. +See [Troubleshooting](../troubleshooting.md) and [the preflight reference](preflight.md). + +## Start, check and stop + +```sh +"$CANDIDATE" up --detach --path /absolute/project +"$CANDIDATE" ps --path /absolute/project +"$CANDIDATE" logs api --no-follow --tail 50 --path /absolute/project +``` + +Replace `api` with a service in your project. Start still checks images, source +sharing, credentials, ownership and readiness. Preflight does not prove these. +If writable source sharing asks for consent, review the exact source roots and +[sharing limits](full-reference.md#explicit-writable-development-source) before +opting in. Check the app and saved data yourself; a running VM is not acceptance. + +Stop with the **same version and native home**: + +```sh +"$CANDIDATE" down --path /absolute/project +``` + +If stop reports retained or unknown cleanup, follow its inspection instructions +before switching. Keep the home and receipts; use the +[cleanup reference](full-reference.md#manual-candidate-upgrade-and-rollback). + +## Back to Compose + +Once the native stop is confirmed, use the same candidate on Compose: + +```sh +HACK_RUNTIME_BACKEND=compose "$CANDIDATE" up --detach --path /absolute/project +``` + +This uses the shared stable Hack home. First follow the +[stable-daemon stop procedure](../../guides/candidate-install.md#stop-stable-hackd-before-a-compose-run) +if stable is installed. Native data stays in the native home; Compose data stays +in Compose volumes. This switch does not copy either database. + +[The command contract](authored-commands.md) and +[full reference](full-reference.md) cover advanced configuration and recovery. diff --git a/docs/versions/v5/troubleshooting.md b/docs/versions/v5/troubleshooting.md new file mode 100644 index 000000000..9305cb563 --- /dev/null +++ b/docs/versions/v5/troubleshooting.md @@ -0,0 +1,51 @@ +# Troubleshooting + +Run `hack doctor` using the **same CLI, backend and home** as the command that +failed. On the Compose path, use the terminal from [Install](install.md). On +native, use the full `hack-next` path from [Try native](native/start.md). +Read the named finding before using `--fix`; some problems need a decision or +an original key, not an automatic repair. + +The rows marked **next.17 source** describe merged code intended for next.17. +They do not change an installed next.16 bundle. See the +[release notes](../guides/v5-release-notes.md) for version boundaries. + +| Finding or message | Cause | What to do | +| --- | --- | --- | +| `proxy ports`: “port 443 on loopback is not reaching the Hack proxy” (**next.17 source**, #773) | A hostname resolves to loopback, but its published port does not reach Hack's proxy. Another listener, a VPN's serve feature or the container runtime's HTTPS setting may own the port. | Review visible listeners, `proxy.bind_address` and local DNS overrides. Change the conflicting setting deliberately, then rerun Doctor. Port 80 working does not prove 443 works. Doctor applies no automatic fix. [Routing details](guides/proxy-network-repair.md). | +| `secret integrity`: encrypted store has entries, but its key is missing or does not open it (**next.17 source**, #779) | An old global store remains, but the original key is unavailable. It is an error where the project reads it and a warning elsewhere. | Choose **restore the original key** or **retire the store** if the key is gone for good. Never create a replacement key to open old ciphertext. Retirement keeps the encrypted file and prints how to put it back. See the steps below. | +| `secret integrity`: env layer “could not be read or parsed” (**next.17 source**, #766) | The layer is unreadable, invalid, or outside an allowed path. | Fix its access, syntax or location, then rerun Doctor. Keep the file and original key. If encrypted entries cannot be opened, recover that key; a hidden value in `env list` is not proof of decryption. [Env and keys](../env.md#secret-key-handling). | +| `env-key-weak-permissions` | An old project key has group or other access. | Keep a private backup, then apply the reported `chmod 600` remedy to the named key. Do not move it to an unignored `.old` file in the checkout. The broader hygiene report (#764) is a separate change; check the installed release. | +| Native runtime/provider files are missing or setup is incomplete | The candidate is installed, but its per-version runtime is not prepared. | Run the explicit [native setup step](native/start.md#prepare-the-runtime) for that selected version and home. `up` does not download provider files. For `setup_existing_invalid`, keep existing state and follow [setup recovery](native/setup.md); do not delete the home. | +| Preflight has blockers or reports `runtime review: skipped` / `unavailable` | The Compose project uses an unsupported field, the wrong backend is selected, or the CLI/runtime pair cannot complete review. | Use the native launcher, fix the reported fields and rerun `doctor --native-preflight`. Check `ready` and the runtime review, not just the exit code. Stay on Compose when the feature is required. [Preflight details](native/preflight.md). | +| `E_LIFECYCLE_FAILED` | A project hook failed before startup could finish; its own credentials or command may need repair. | Read the hook's message, fix that project dependency, then retry. Do not bypass the hook just to get a green start. | +| next.16 `E_STARTUP_INCOMPLETE` after a fast one-shot service finished | next.16 can misread a service that exits successfully in under a second. | Inspect `ps` and logs. If this is that known case and the services are up, rerun `up --detach`. The fix is merged for a later prerelease. [Trial record](guides/upgrade-from-v4.md#known-problems-and-the-dogfood-record). | + +## A store whose key is lost + +Use a candidate containing #779; next.16 does not have `retire-store`. Doctor's +finding names the selected store and registered projects that read it. + +1. Prefer restoring the **same original key** from a private backup or another + machine, at the path Doctor names with mode 600. +2. If the key is gone for good, select the diagnosed project and retire the store: + + ```sh + hack secrets retire-store --path /absolute/project --allow-unchecked + ``` + + On the Compose path, `hack` must be the Compose-selected v5 CLI, as on page 1. + Pass `--allow-unchecked` only after confirming no shell for a project selecting + the store holds its key in `HACK_SECRETS_FILE_KEY`; Hack cannot inspect another + shell. The flag also acknowledges registered projects it could not check. + A store a configured key still opens is refused. Without a terminal, `--yes` + is also needed to confirm the move. + +Retirement moves the file to a timestamped directory beside it. It deletes no +entries, leaves the key file alone and prints the restore command. It does not +recover the values. Keep the moved file if you might recover the key later. +[Store details](https://github.com/hack-dance/hack/blob/91c311e4d9540ea3ca32113a61458a26db90c704/docs/env.md#compatibility-notes) +cover the refusal and recovery rules. + +If a report needs help, share the version, finding name and the action that failed. +Remove secret values and private paths from logs before sharing them. diff --git a/docs/versions/v5/upgrade.md b/docs/versions/v5/upgrade.md index f17566431..f29196933 100644 --- a/docs/versions/v5/upgrade.md +++ b/docs/versions/v5/upgrade.md @@ -1,78 +1,89 @@ # Upgrade from v4 -For the summary of the release, read [What's new in 5.0](../guides/v5-release-notes.md). - -v5 keeps the v4 project model and commands. Your `.hack/` folder, encrypted env -values, branch instances, lifecycle processes and sessions carry over. What changes -is the runtime layer underneath and the product boundary around it. - -## What stays the same - -- Docker Compose is still the ordinary CLI's default backend. The familiar - lifecycle commands remain, with env migration and parsing changes described - in the [machine upgrade checklist](guides/upgrade-from-v4.md). -- Project configuration stays in `.hack/`. Legacy env files may need migration; - use the [machine upgrade checklist](guides/upgrade-from-v4.md) before running it. -- Shared local routing, `.hack.local` names and certificate trust are unchanged. - -## What is new - -- **Native backend (beta).** On Apple Silicon macOS, through the `hack-next` - channel, `HACK_RUNTIME_BACKEND=native` runs explicitly prepared projects without - Docker Desktop or OrbStack. It supports a bounded command - subset and is qualified project by project. See - [Native backend (beta)](native/overview.md). -- **A config compiler.** `hack config validate`, `config plan`, `config import - --dry-run` and `config adopt --dry-run` inspect and preview native configuration - without starting workloads. See [Native config import](../reference/native-config-import.md). -- **A separate prerelease channel.** `hack-next` installs immutable `5.0.0-next.N` - builds beside stable Hack. See [Install](install.md). -- **Stricter command parsing.** Hack options go before the command tail. For - `exec`, `run` and `host exec`, everything after the service or `--` is passed - through unchanged, so a child's `--json` or `--help` is never read as a Hack flag. -- **Safer env handling.** `hack env hydrate` imports values from a file or stdin - so secrets never appear in command arguments. - -## What was retired - -These shipped in earlier major versions and are gone from v5. Use ordinary tools -in their place. - -| Retired | Use instead | -| --- | --- | -| Hosted accounts, organizations and teams | Nothing to replace; Hack is local-only | -| The web dashboard | `hack status`, `hack ps`, `hack tui` | -| Hack Tickets | The tracker your project already uses | -| Built-in GitHub and Linear integrations | `git`, `gh` and the tracker's own CLI | -| Automatic agent instruction injection (`hack setup sync`, primer hooks, injected rules) | The opt-in `hack` plugin and `hack agent onboard`; see [Agent integrations](../integrations.md) | - -Remote, gateway, node and dispatch commands and the macOS app remain in the -repository but are unsupported. They are hidden from `hack help` and warn when -invoked. - -## Upgrade path - -1. Keep stable v4 installed. Install the current prerelease with `hack-next` as - described in [Install](install.md). -2. Run one project on the prerelease using the Compose backend. Stop the stable - daemon first; v4 and the prerelease must not run against the same home at once. -3. Check the application itself: sign-in, data-backed pages, and anything written - before a restart that must still be there after it. -4. Only then try the native backend on a disposable project, following - [Try the native backend](native/try-it.md). - -When 5.0.0 ships, `brew upgrade hack` or the release installer moves the stable -executable to v5. Review legacy env migration before the Compose trial; the -[machine upgrade checklist](guides/upgrade-from-v4.md) records the steps and open checks. - -## The daemon after an upgrade - -Installing 5.0.0 over a running 4.x does not replace the daemon. On Linux the old -`hackd` keeps running: `hack daemon status` reports `incompatible` and exits 1, -while `hack status` and `hack projects --json` still work. Replace it yourself: - -```bash -hack daemon restart +Start here: [1. Install](install.md) · [2. First project](getting-started.md) · +**3. Upgrade** · [4. Try native](native/start.md). + +This is today's manual path. **To be replaced by the upgrade assistant** +(HACK-2189 and HACK-2191, in progress). Until it lands, keep stable v4 installed +and try v5 on one Compose project at a time. Native is a separate trial. +The published v5 candidate bundle requires an Apple Silicon Mac. + +```mermaid +--- +title: A reversible upgrade trial +--- +flowchart TD + Backup[Back up first] --> Stop[Stop stable daemon] + Stop --> Trial[Try v5 Compose] + Trial --> Check{App checks pass?} + Check -->|Yes| Keep[Keep backups] + Check -->|No| Restore[Stop and restore] ``` -This was checked on Linux x86_64. The macOS behavior has not been checked yet. +## Upgrade one project + +1. **Back up before running v5 on the project.** Keep a private copy outside the + checkout of `.hack/`, the root `.gitignore` and `.hack.secret.key`, and the + global Hack configuration and project registry. Record files that were absent. + Back up application data with the database's own tools; copying `.hack/` does + not back up volumes. Use the [complete backup steps](guides/upgrade-from-v4.md#2-before-you-start) + and confirm you can read the original key. If stable routing needs starting, + run stable `command hack global up` before the backup procedure stops its daemon + and copies the files. +2. **Confirm stable's daemon stays stopped.** In a terminal where + `hack` is the stable executable, run: + + ```sh + command hack daemon stop + command hack daemon uninstall + pgrep -fl "hack daemon start" + ``` + + The last command must print nothing before you continue. On macOS uninstall + removes the launchd service so it cannot restart the daemon during the trial. + Run no stable commands while the candidate uses the shared home. +3. **Install v5 beside stable**, following [Install](install.md). Use a fresh + terminal for the trial, select Compose, and check the chosen version: + + ```sh + export HACK_RUNTIME_BACKEND=compose + hack() { "$HOME/.hack-next/bin/hack-next" "$@"; } + hack --version + cd your-project + hack doctor + ``` + +4. **Review env migration before accepting it.** `up` can offer migration; + sessions and some env commands can migrate without a prompt. Keep backups + before any of them. If explicit migration is needed, use + `hack doctor --migrate-env-config` only after reading the + [migration and consent details](guides/upgrade-from-v4.md#4-what-changes-for-a-project). + On next.16 or earlier, cleanup can remove a project key a legacy store names: + never run that repair without the private readable key copy. The merged fix + intended for next.17 cannot recover an already deleted key. +5. **Run the project and check it**, using `hack up --detach`, `hack open`, + `hack logs --no-follow --tail 50` and `hack down`. Check sign-in, saved data, + hooks and a restart. Keep the backup until rollback and data recovery have + been checked. See [known problems](guides/upgrade-from-v4.md#known-problems-and-the-dogfood-record). + +v5 keeps Compose as the default for the ordinary CLI. Retired features include the hosted +account/team flows, dashboard and Hack Tickets; the +[release summary](../guides/v5-release-notes.md) covers retired features and +breaking command changes. Newer source changes are marked as intended for +next.17; an installed next.16 bundle keeps its original behavior. + +## Roll back + +Stop the candidate with `hack down` in its Compose terminal. Restore the project +and machine files, including the **original** project key, from the backup; +follow the [full restore procedure](guides/upgrade-from-v4.md#7-return-to-v4). +Restore project state after any migration. Selecting an older binary alone does +not undo migrated files, volumes or database schema changes. + +In a stable terminal, reinstall its login daemon with `command hack daemon install` +if you removed it. Then use stable `command hack up --detach` and check the app +and data again. A native trial's data never moves into Compose volumes by itself. + +If Doctor blocks the trial, use [Troubleshooting](troubleshooting.md). +The detailed [machine upgrade checklist](guides/upgrade-from-v4.md) keeps the +backup scripts, source evidence and checks still awaiting real-machine trials. diff --git a/scripts/docs/prepare.ts b/scripts/docs/prepare.ts index 18d7b67bf..2d52622c1 100644 --- a/scripts/docs/prepare.ts +++ b/scripts/docs/prepare.ts @@ -158,6 +158,7 @@ async function writeDocuments( /** Reading order of the v5 "Native backend (beta)" section. */ const nativeSectionOrder = [ + "start", "overview", "try-it", "preflight", @@ -458,8 +459,10 @@ async function stageVersion( "index", "install", "getting-started", - ...optional("release-notes"), "upgrade", + ...optional("native/start"), + ...optional("troubleshooting"), + ...optional("release-notes"), "core", "env", "lifecycle", diff --git a/scripts/docs/smoke.ts b/scripts/docs/smoke.ts index 018920548..84aa47841 100644 --- a/scripts/docs/smoke.ts +++ b/scripts/docs/smoke.ts @@ -210,6 +210,8 @@ const recipeEntryPoints = new Set([ "env", "reference/configuration-fields", "guides/upgrade-from-v4", + "native/start", + "troubleshooting", "native/setup", "native/log-follow", ]); diff --git a/scripts/docs/versions.json b/scripts/docs/versions.json index 88c4e324e..8926db6ba 100644 --- a/scripts/docs/versions.json +++ b/scripts/docs/versions.json @@ -4460,15 +4460,24 @@ }, { "slug": "install", - "title": "Install" + "title": "Install v5", + "sourceRevision": "6ab1acece79609bc102e23bd24263691aaf0d5ea", + "sourceLabel": "Current command audit (next 6ab1acec)", + "sourceFile": "docs/reference/cli.md" }, { "slug": "getting-started", - "title": "Getting started" + "title": "First project on Compose", + "sourceRevision": "6ab1acece79609bc102e23bd24263691aaf0d5ea", + "sourceLabel": "Current command audit (next 6ab1acec)", + "sourceFile": "docs/reference/cli.md" }, { "slug": "upgrade", - "title": "Upgrade from v4" + "title": "Upgrade from v4", + "sourceRevision": "6ab1acece79609bc102e23bd24263691aaf0d5ea", + "sourceLabel": "Current command audit (next 6ab1acec)", + "sourceFile": "docs/reference/cli.md" }, { "slug": "guides/upgrade-from-v4", @@ -4636,6 +4645,20 @@ "sourceRevision": "b21c3b189841c1a3cbb8af2b76414fa347dc7057", "sourceLabel": "v5.0.0-next.16 under verification", "sourceFile": "docs/reference/native-authored-commands.md" + }, + { + "slug": "native/start", + "title": "Try native on Apple Silicon", + "sourceRevision": "6ab1acece79609bc102e23bd24263691aaf0d5ea", + "sourceLabel": "Current command audit (next 6ab1acec)", + "sourceFile": "docs/guides/native-candidate.md" + }, + { + "slug": "troubleshooting", + "title": "Troubleshooting", + "sourceRevision": "6ab1acece79609bc102e23bd24263691aaf0d5ea", + "sourceLabel": "Current command audit (next 6ab1acec)", + "sourceFile": "docs/env.md" } ] } From a197580ee857e510478bb9aec06823cc4e1dff07 Mon Sep 17 00:00:00 2001 From: Kit <344842+roodboi@users.noreply.github.com> Date: Fri, 13 Nov 2026 19:56:55 +0000 Subject: [PATCH 2/2] docs: preserve entry-point anchors and clarify native preflight --- docs/guides/native-candidate.md | 4 ++++ docs/versions/v5/install.md | 2 ++ docs/versions/v5/native/start.md | 3 ++- docs/versions/v5/upgrade.md | 9 +++++++++ scripts/docs/smoke.ts | 4 ++++ 5 files changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/guides/native-candidate.md b/docs/guides/native-candidate.md index 2e507b3f8..ff1f43cae 100644 --- a/docs/guides/native-candidate.md +++ b/docs/guides/native-candidate.md @@ -117,6 +117,8 @@ and returning to Compose. Neither entrypoint prepares the provider, migrates a project or falls back to Docker for an unsupported native command. An unversioned local build reports its repository version; only a versioned bundle includes candidate version provenance. The entrypoint alone does not identify a release. +`hack-v5` passes arguments, exit codes and signals through `exec`; it never replaces +the installed stable executable. Native `up` accepts an explicit branch or the branch inferred from a linked Git worktree when its exact source root can be shared with a fresh or matching pool. @@ -917,6 +919,8 @@ surrounding whitespace) refuses with `E_INTERACTIVE_REQUIRED` unless `--accept-downloads` explicitly consents. No provider download happens from `up`, the installer, the probe or any other implicit path. The optional BuildKit client is still prepared separately below. +Setup lists the pinned SmolVM, Docker engine and four Alpine guest packages, +including exact compressed sizes, hosts, hashes, private cache and destinations. The executable embeds `provider-pins.json` and checks its hashes against the manual preparation pins. HTTPS redirects may use only the original host and the diff --git a/docs/versions/v5/install.md b/docs/versions/v5/install.md index cd6b67bed..256a86212 100644 --- a/docs/versions/v5/install.md +++ b/docs/versions/v5/install.md @@ -3,6 +3,8 @@ Start here: **1. Install** → [2. First project](getting-started.md). Already using v4? Read [3. Upgrade from v4](upgrade.md) before running v5 in a project. +## Prerequisites + v5 is in prerelease. Stable is still v4. A stable install does **not** install v5. The v5 prerelease bundle supports Apple Silicon macOS. Linux and Intel Macs stay on stable v4; see [platform support](../guides/prereleases.md). diff --git a/docs/versions/v5/native/start.md b/docs/versions/v5/native/start.md index e55b15653..6f2beae66 100644 --- a/docs/versions/v5/native/start.md +++ b/docs/versions/v5/native/start.md @@ -61,7 +61,8 @@ interrupted download, use [setup and recovery details](setup.md). Add the project's `--profile` selection if needed. Preflight reads the Compose project and lists blockers with fixes. It starts no VM or service. Continue only -when there are no blockers **and** the runtime review completed with `ready: true`. +when there are no blockers **and** the report says `Runtime review: completed`. +In JSON, this means `ready: true` and `runtime_review.status: "completed"`. An exit of 0 alone is not enough: runtime review can be skipped or unavailable. If blocked, fix the named field and rerun. Do not remove a check or delete state diff --git a/docs/versions/v5/upgrade.md b/docs/versions/v5/upgrade.md index f29196933..c03e0e145 100644 --- a/docs/versions/v5/upgrade.md +++ b/docs/versions/v5/upgrade.md @@ -87,3 +87,12 @@ and data again. A native trial's data never moves into Compose volumes by itself If Doctor blocks the trial, use [Troubleshooting](troubleshooting.md). The detailed [machine upgrade checklist](guides/upgrade-from-v4.md) keeps the backup scripts, source evidence and checks still awaiting real-machine trials. + +## The daemon after an upgrade + +Installing a CLI does not replace a running daemon. After choosing a durable v5 +install, use `hack daemon restart` for an unmanaged incompatible daemon. If a +login service still points at the old executable, use the chosen install's +`hack daemon install`. Keep this outside the shared-home candidate trial; +[daemon and service details](guides/upgrade-from-v4.md#daemon-old-lock-and-missing-checkouts) +explain the difference. diff --git a/scripts/docs/smoke.ts b/scripts/docs/smoke.ts index 84aa47841..239fcce7b 100644 --- a/scripts/docs/smoke.ts +++ b/scripts/docs/smoke.ts @@ -207,6 +207,10 @@ console.log( const recipeLinks = new Map(); const recipeEntryPoints = new Set([ "index", + "install", + "getting-started", + "upgrade", + "release-notes", "env", "reference/configuration-fields", "guides/upgrade-from-v4",