@dryvcode/cli 0.0.1 → 0.1.0

package/README.md

@@ -1,253 +1,69 @@
 # Dryv CLI
 
-The Dryv CLI is the filesystem-owning TypeScript client for Dryv. It reads local Dryv bootstrap inputs and resources, communicates with the Dryv API, displays validation/planning/generation results, previews generated diffs, and applies approved artifact changes back to the project.
-
-The API, engine, and template plugins do not receive ambient authority to access the user's real filesystem or Git credentials.
+`dryv` turns software you describe once (schemas, operations, events) into real code, through reusable packs. It shows you a plan and a diff first, and only writes files when you approve.
 
 ## Install
 
-The published package runs on **Node.js 22+** or **Bun 1.3+**, and installs with any package manager:
-
 ```bash
-npm install --global @dryvcode/cli
-pnpm add --global @dryvcode/cli
-yarn global add @dryvcode/cli
-bun add --global @dryvcode/cli
-```
-
-Or run it without installing: `npx @dryvcode/cli --help`, or `bunx @dryvcode/cli --help`.
-
-The package ships one bundled file, `dist/dryv.js` (a `node` shebang, no runtime dependencies), built from the TypeScript source by `bun run build`. Process, `which` and sleep helpers live in `src/platform/process.ts` and behave the same on both runtimes.
-
-## Development
-
-Repository development uses Bun. `bin/dryv.ts` runs the TypeScript source directly.
-
-Install dependencies:
-
-```text
-cd apps/cli
-bun install
-```
-
-`bun install` creates/updates `bun.lock`; commit that lockfile for reproducible installs. CI or other frozen environments should use:
-
-```text
-bun install --frozen-lockfile
+npm install --global @dryvcode/cli     # or pnpm / yarn / bun add --global
+dryv --help
 ```
 
-Run the CLI from the repository:
-
-```text
-bun run start -- --help
-```
-
-or directly:
-
-```text
-bun ./bin/dryv.ts --help
-```
-
-Run all checks:
-
-```text
-bun run check
-```
-
-This performs the TypeScript type-check through Bun and then runs the Bun test runner.
-
-`bun run check` also builds `dist/dryv.js` and smoke-tests it with Node.
-
-## Commands
-
-```text
-dryv capabilities
-dryv info
-dryv build
-dryv ir build
-dryv validate
-dryv plan
-dryv generate
-```
-
-The API defaults to `http://127.0.0.1:8750`. Override it with either:
-
-```text
-dryv validate --api https://dryv.example.com
-```
-
-or `DRYV_API_URL`.
-
-### `dryv capabilities`
-
-Inspects the local environment only. It reports whether this client can read/write the workspace and whether native local/Git pack resolvers are available. A capability means the mechanism is available; it does not claim every referenced resource is accessible.
-
-Native Git resolution uses the user's existing Git environment such as SSH agents and credential helpers. Dryv does not store Git credentials. Git subprocesses are launched through `Bun.spawn()` and inherit the user's environment.
-
-### `dryv info`
-
-Reads `GET /` and displays the Dryv API and engine capabilities.
-
-### `dryv build`
-
-Compiles an authored source into canonical Runtime IR through the selected author/compiler provider and Runtime ingestion pipeline. The completed build is validated by the Runtime but is not written to disk.
-
-### `dryv ir build`
-
-Compiles authored source and writes a portable canonical Runtime IR artifact. By default it writes:
-
-```text
-.dryv/ir/dryv.ir.yaml
-```
-
-Available formats:
-
-```text
-dryv ir build --format yaml
-dryv ir build --format json
-dryv ir build --format jsonl
-dryv ir build --all
-```
-
-This command does not require a generation pack. An author-only usage document may use `packs: {}`.
-
-### `dryv validate`
+Needs Node.js 22+ or Bun 1.3+. Try without installing: `npx @dryvcode/cli --help`.
 
-The current API compatibility flow still loads the local workspace as typed `VirtualFile` values and sends an `EngineRequest` to `POST /v1/validate`.
+## Five-minute start
 
-### `dryv plan`
-
-The current API compatibility flow uploads the same virtual workspace to `POST /v1/plan` and displays planned artifact paths and trace references without changing local files.
-
-### `dryv generate`
-
-Uses Bun's built-in WebSocket client to connect to `WS /v1/generate`, reconstruct streamed generated artifacts, compare those artifacts with the real workspace, and print unified diffs before any mutation.
-
-By default an interactive terminal asks before applying changes.
-
-```text
-dryv generate --dry-run   # diff only; never write
-dryv generate --check     # diff only; exit 1 when output differs
-dryv generate --yes       # apply without prompting
-```
-
-A non-interactive invocation never writes unless `--yes` is supplied.
-
-## Bootstrap loading
-
-The environment-request protocol is moving Dryv away from whole-workspace upload. The bootstrap loader reads only:
-
-```text
-dryv.yaml
-dryv.lock.yaml   # optional
-```
-
-`dryv.yaml` remains the required entrypoint. `dryv.lock.yaml` is supplied when present so the engine can decide what additional resources are required.
-
-The older broad workspace loader remains temporarily for the existing API endpoints until the new operation protocol is connected.
-
-## Local pack capabilities
-
-The CLI can resolve explicit local pack resources without interpreting `dryv.yaml` itself. A future API/engine environment request supplies the typed pack source; the CLI fulfills it.
-
-Local pack resolution:
-
-- remains inside the project root;
-- rejects symbolic links and non-regular files;
-- has file-count, per-file-size, and total-size limits;
-- includes text and binary resources;
-- requires a UTF-8 `dryv.pack.yaml`;
-- sorts files deterministically;
-- computes SHA-256 file and resource digests.
-
-## Native Git pack capability
-
-The native Git resolver uses the installed `git` executable through Bun's process API and the user's normal Git authentication environment. It does not create a Dryv credential store.
-
-Resolved Git packs record:
-
-- requested repository;
-- requested revision;
-- concrete resolved commit;
-- optional pack subpath;
-- deterministic pack content digest;
-- resolver provenance (`client.git-native`).
-
-Git cache state is stored under `.dryv/.cache/git`. `.dryv/.cache` is reserved for disposable Dryv-owned operational state such as resolved resources, plans, sessions and digests. Repository URLs are not installed as persistent remotes in the cache, and HTTP(S) repository URLs containing embedded credentials are rejected.
-
-## Resource bundles
-
-Resolved packs can be converted into a self-describing ZIP transport bundle with media type:
-
-```text
-application/vnd.dryv.resource-bundle+zip
-```
-
-The archive contains:
-
-```text
-dryv.bundle.json
-files/
-  dryv.pack.yaml
-  templates/...
-  resources/...
-```
-
-`dryv.bundle.json` uses `dryv.resource-bundle/v1alpha1` and records the resource request ID, pack identity, content digest, every file's path/kind/SHA-256/size/archive path, and normalized provenance.
-
-ZIP is only a transport optimization. The semantic identity remains the typed resource manifest and content hashes; engine behavior must not depend on ZIP metadata or compression implementation.
-
-Bundle file paths are canonical project-relative paths and are namespaced below `files/`, so resource entries cannot collide with the bundle manifest.
-
-## Workspace loading compatibility path
-
-Inside a Git repository the older workspace loader uses:
-
-```text
-git ls-files -z --cached --others --exclude-standard
-```
-
-This naturally honors Git's normal ignored-file rules. Outside Git, the CLI performs a deterministic recursive filesystem walk.
-
-In both modes it also honors `.dryvignore` plus repeatable `--exclude <pattern>` options.
-
-Default exclusions include:
+```bash
+cd my-project
+npm install -D @dryvcode/author @dryvcode/compiler   # or: uv add --dev dryv-author dryv-compiler
+dryv init --author typescript --author-path dryv/contracts/index.ts --yes
+dryv pack search nestjs
+dryv pack add inject/backend/nestjs --activation server --destination src/server --yes
+dryv plan                 # what would be generated? (writes nothing)
+dryv generate --dry-run   # the exact diff (writes nothing)
+dryv generate             # asks, then writes
+```
+
+`dryv init` also writes `dryv/README.md` and a Dryv block in `AGENTS.md`, so people and AI agents opening the project know how it works.
+
+## Everyday commands
+
+| Command | Use it to |
+| --- | --- |
+| `dryv validate` / `plan` | Check your definitions and preview the files |
+| `dryv generate [--dry-run \| --check]` | Write files, preview them, or fail CI when stale |
+| `dryv status` | See drift between generated files and your definitions |
+| `dryv why <path>` | Learn why a generated file exists |
+| `dryv explain change` | Learn what caused the latest change |
+| `dryv undo` | Revert the last apply |
+| `dryv pack search / describe / explain / add / remove / update` | Find, read about and manage packs from the registry |
+| `dryv doctor` | Diagnose project, engine and pack problems |
+| `dryv docs [topic]` | Read built-in guides: workflow, dryv-yaml, pack-yaml, authoring, errors, agents |
+
+## Built-in help for people and agents
 
-```text
-.git/
-node_modules/
-.dryv/.cache/
-.dryv/contracts/
+```bash
+dryv docs               # list guides
+dryv docs dryv-yaml     # how to write dryv.yaml
+dryv docs errors        # every error code and its fix
+dryv docs --write       # (re)write dryv/README.md and the AGENTS.md block
 ```
 
-Local packs under `.dryv/packs/` are included by the compatibility workspace upload because the current plan/generate API path still resolves pack manifests and templates from the uploaded virtual workspace.
-
-This broad upload behavior is transitional and will be removed from the normal engine workflow once environment requests are connected.
+For scripts and agents add `--json --no-input`: output is one JSON document with a stable `status` and `code`. `dryv generate --check` exits 2 when output is out of date.
 
-## Typed boundary rule
+## Engine and sign-in
 
-The CLI mirrors the Dryv typed-contract rule used by the Python API:
-
-```text
-untrusted JSON
-    ↓
-API protocol parser
-    ↓
-typed TypeScript contract classes
-    ↓
-CLI/application logic
-```
+The CLI uses the hosted engine at `https://dryv-engine.alidantech.org`. Use your own with `--api <url>` or `DRYV_API_URL`, for example `docker run -p 8750:8750 ghcr.io/dryvcode/dryv-engine:latest`.
 
-Raw `unknown` JSON is confined to network/archive parsing boundaries. Outbound wire objects exist only inside encoders. Commands, workspace code, resolvers, and the API client use known TypeScript contract types.
+Store an API key in your OS credential store with `dryv login` (remove it with `dryv logout`), or set `DRYV_API_KEY` in CI. Keys are only sent in headers and never in URLs.
 
-## Filesystem safety
+## Safety
 
-Before a generated artifact is written or deleted, the CLI verifies that:
+- Only compiled Runtime IR leaves your machine; the CLI alone writes files.
+- Running your author compiler or pack actions needs trust: `dryv trust`. CI never auto-trusts.
+- If you edited a generated file and the definition changed too, Dryv stops. Choose `--conflicts keep` or `overwrite`.
+- `dryv clean` removes plans, journals and caches stored outside your project.
 
-- its path is project-relative and portable;
-- it cannot traverse outside the project root;
-- it does not pass through a symbolic link;
-- an existing output target is a regular file;
-- a generation stream has not emitted the same output path twice.
+## Learn more
 
-Generated files are classified as `CREATE`, `MODIFY`, `DELETE`, or `UNCHANGED`. Only the CLI applies those operations to disk.
+Full docs: https://dryv.alidantech.org/docs · CLI reference: https://dryv.alidantech.org/docs/usage/cli