vde-open 0.1.0 → 0.1.2

package/README.md

@@ -11,21 +11,47 @@ A local document viewer for agents and people who work from the same material. O
 
 ## Install
 
-Node.js 24 or later is required (this repository pins 24.21.0 in `mise.toml`).
+Node.js 24 or later is required.
 
 ```bash
-pnpm install --frozen-lockfile
-pnpm build
-pnpm test:pack                              # builds artifacts/vde-open-0.1.0.tgz and verifies an install in a separate directory
-bun add -g ./artifacts/vde-open-0.1.0.tgz   # recommended: user-level install into ~/.bun/bin
+bun add -g vde-open      # recommended: user-level install into ~/.bun/bin
+npm install -g vde-open  # also works
 ```
 
 - We recommend installing it once per user with Bun. `~/.bun/bin` does not depend on which Node.js version is active, so switching Node.js versions (with mise and similar tools) does not remove `vo`. Bun is only used to install; the commands run on Node.js (`#!/usr/bin/env node`), so Node.js 24 or later must be on your `PATH`. Running it on the Bun runtime (`bun --bun`) is not tested.
-- `npm install -g ./artifacts/vde-open-0.1.0.tgz` also works, but it installs into the prefix of the active Node.js version.
+- `npm install -g` installs into the prefix of the active Node.js version.
 - Installing it per project is not recommended. There is one daemon per user, so different versions in different projects would talk to the same daemon.
-- Always start the path with `./`. Without it, the path is treated as a GitHub repository name.
 
-Installing does not change shell files such as `.zshrc`, and runs no build or install scripts (the tarball bundles every dependency). The package is not published to npm.
+Installing does not change shell files such as `.zshrc`, and runs no build or install scripts (the package bundles every dependency). Releases are published from GitHub Actions with provenance (see "Releasing").
+
+To install from a clone of this repository (pins Node.js 24.21.0 in `mise.toml`):
+
+```bash
+pnpm install --frozen-lockfile
+pnpm build
+pnpm test:pack                              # builds artifacts/vde-open-<version>.tgz and verifies an install in a separate directory
+bun add -g "$PWD/artifacts/vde-open-0.1.2.tgz"   # use an absolute path: bun add -g resolves relative paths from its global install directory, not the current one
+```
+
+## Developing with a linked CLI
+
+From the repository root, build once and link the CLI package globally:
+
+```bash
+pnpm install --frozen-lockfile
+pnpm build
+cd apps/cli
+bun link
+bun link -g vde-open
+cd ../..
+pnpm build:watch
+```
+
+`build:watch` builds immediately, then watches the CLI, UI, shared sources, build configuration, and packaged files. Saves are coalesced and builds run one at a time. Both apps and the package files are prepared in a temporary directory before replacing the distribution; a failed build leaves the last successful output in place. The next linked CLI invocation uses the updated build.
+
+The watcher does not start or restart your daemon. After a successful build, run `vo daemon restart`, then `vo ui` to open the updated UI. Restarting preserves registered documents and saved answers, but changes the UI address and invalidates earlier browser sessions and interactive HTML permissions. Stop the watcher with Ctrl+C; it stops an active build and removes its temporary output.
+
+For frequent UI changes, use `pnpm dev` instead. It runs the source daemon with a separate `.dev-home` and serves the UI through Vite HMR. It does not rebuild the linked CLI or automatically restart the backend when its source changes. CLI commands for that environment need the same absolute `VDE_OPEN_HOME` (for example, `VDE_OPEN_HOME="$PWD/.dev-home" vo list` from the repository root).
 
 ## `vde-open` and `vo`
 
@@ -36,7 +62,7 @@ The same CLI is installed under two names. Both use the same state and daemon.
 
 If you already have a different `vo` (another tool's command, an alias, and so on), installing never overwrites or deletes it.
 
-- If the install target's bin directory (for `npm install -g`, npm's global bin) already has another `vo` file, npm stops with `EEXIST`. Do not use `--force`; it replaces the existing `vo`. Install with Bun instead, or into another prefix (for example `npm install -g --prefix ~/.local/vde-open ./artifacts/vde-open-0.1.0.tgz`) and use `vde-open` from that bin directory.
+- If the install target's bin directory (for `npm install -g`, npm's global bin) already has another `vo` file, npm stops with `EEXIST`. Do not use `--force`; it replaces the existing `vo`. Install with Bun instead, or into another prefix (for example `npm install -g --prefix ~/.local/vde-open ./artifacts/vde-open-0.1.2.tgz`) and use `vde-open` from that bin directory.
 - For a `vo` or alias elsewhere, whichever comes first on `PATH` runs. In that case, use `vde-open`. If you want a short name, define an alias in your shell (for example `alias vdo=vde-open`).
 
 ## Basic usage
@@ -59,8 +85,11 @@ How agents should use it is described in [docs/agent-usage.md](docs/agent-usage.
 [`skills/vde-open/SKILL.md`](skills/vde-open/SKILL.md) is a skill that teaches an agent (Claude Code, Codex, and others that read `SKILL.md`) when and how to use `vo`. It is also included in the package. To use it, link or copy the directory into your agent's skill directory:
 
 ```bash
-ln -s "$PWD/skills/vde-open" ~/.claude/skills/vde-open   # Claude Code
-ln -s "$PWD/skills/vde-open" ~/.codex/skills/vde-open    # Codex
+# Installed with Bun: the skill is in the global package directory.
+ln -s ~/.bun/install/global/node_modules/vde-open/skills/vde-open ~/.claude/skills/vde-open   # Claude Code
+ln -s ~/.bun/install/global/node_modules/vde-open/skills/vde-open ~/.codex/skills/vde-open    # Codex
+# Installed with npm: use "$(npm root -g)/vde-open/skills/vde-open" instead.
+# From a clone of this repository: use "$PWD/skills/vde-open".
 ```
 
 ## Search scope

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { C as decodeStateFile, D as daemonEntryPath, E as resolveStateRoot, O as referencedBlobs, S as renameWithRetry, T as resolveRuntimeLocation, a as DAEMON_LOCK_NAME, b as proofMatches, c as readIpcKey, d as inspectOwner, f as readCurrentLock, g as encodeFrame, h as FrameDecoder, i as requirePrivateDirectoryIfExists, k as version, l as readPointer, m as systemProcessProbe, n as ensurePrivateDirectory, o as POINTER_FILE, p as releaseLock, r as inspectPrivateDirectory, s as START_LOCK_NAME, t as startDaemon, u as acquireLock, v as computeProof, w as currentPathEnvironment, x as removeWithRetry, y as createNonce } from "./main-lxBamyBU.js";
-import { A as successEnvelope, C as VdeError, D as ExitCode, E as isVdeError, O as envelopeSchema, T as isErrorCode, Y as LIMITS, k as errorEnvelope, w as exitCodeForError } from "./search-index-C0szMSlZ.js";
+import { C as decodeStateFile, D as daemonEntryPath, E as resolveStateRoot, O as referencedBlobs, S as renameWithRetry, T as resolveRuntimeLocation, a as DAEMON_LOCK_NAME, b as proofMatches, c as readIpcKey, d as inspectOwner, f as readCurrentLock, g as encodeFrame, h as FrameDecoder, i as requirePrivateDirectoryIfExists, k as version, l as readPointer, m as systemProcessProbe, n as ensurePrivateDirectory, o as POINTER_FILE, p as releaseLock, r as inspectPrivateDirectory, s as START_LOCK_NAME, t as startDaemon, u as acquireLock, v as computeProof, w as currentPathEnvironment, x as removeWithRetry, y as createNonce } from "./main-CqENdUsw.js";
+import { A as successEnvelope, C as VdeError, D as ExitCode, E as isVdeError, O as envelopeSchema, T as isErrorCode, Y as LIMITS, k as errorEnvelope, w as exitCodeForError } from "./search-index-__laOomT.js";
 import fs, { fstatSync } from "node:fs";
 import { lstat, readFile, readdir, stat as stat$1, writeFile } from "node:fs/promises";
 import path, { join, resolve } from "node:path";

package/dist/daemon.js

@@ -1,5 +1,5 @@
-import { k as version, t as startDaemon, w as currentPathEnvironment } from "./main-lxBamyBU.js";
-import { E as isVdeError } from "./search-index-C0szMSlZ.js";
+import { k as version, t as startDaemon, w as currentPathEnvironment } from "./main-CqENdUsw.js";
+import { E as isVdeError } from "./search-index-__laOomT.js";
 //#region src/daemon.ts
 function notifyParent(message) {
 	if (!process.send) return;

package/dist/{heap-Dev_gSQn.js → heap-C3qHm7SE.js}

@@ -1,12 +1,17 @@
 import { getHeapStatistics, setFlagsFromString } from "node:v8";
 import { runInNewContext } from "node:vm";
 //#region src/diagnostics/heap.ts
-function measureHeap(collectGarbage) {
-	if (collectGarbage) {
+let gc = null;
+function collectGarbage() {
+	if (gc === null) {
 		setFlagsFromString("--expose-gc");
-		runInNewContext("gc")();
+		gc = runInNewContext("gc");
 	}
+	gc();
+}
+function measureHeap(collect) {
+	if (collect) collectGarbage();
 	return getHeapStatistics().used_heap_size;
 }
 //#endregion
-export { measureHeap as t };
+export { measureHeap as n, collectGarbage as t };