@dryvcode/cli 0.0.1

package/README.md

@@ -0,0 +1,253 @@
+# 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.
+
+## 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
+```
+
+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`
+
+The current API compatibility flow still loads the local workspace as typed `VirtualFile` values and sends an `EngineRequest` to `POST /v1/validate`.
+
+### `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:
+
+```text
+.git/
+node_modules/
+.dryv/.cache/
+.dryv/contracts/
+```
+
+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.
+
+## Typed boundary rule
+
+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
+```
+
+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.
+
+## Filesystem safety
+
+Before a generated artifact is written or deleted, the CLI verifies that:
+
+- 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.
+
+Generated files are classified as `CREATE`, `MODIFY`, `DELETE`, or `UNCHANGED`. Only the CLI applies those operations to disk.