@alvaroofernaandez/aval 0.0.0-stage → 0.1.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,68 @@
1
- # Temporary Holding Version
1
+ # aval
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Installer for [aval](https://github.com/alvaroofernaandez/aval), a personal agent harness. *Aval* is Spanish for a guarantee: nothing in it counts as done without evidence. It sets up Claude Code and OpenCode (instructions, skills, hooks, memory) plus a terminal environment (tmux, yazi, Ghostty, zsh) on macOS, Linux and Windows.
4
+
5
+ ## Use it
6
+
7
+ ```sh
8
+ npx @alvaroofernaandez/aval
9
+ ```
10
+
11
+ `npx` always resolves the latest published version, so this is the way to stay current: every push to `main` publishes a new build.
12
+
13
+ ## Or install it
14
+
15
+ ```sh
16
+ npm install -g @alvaroofernaandez/aval
17
+ aval
18
+ ```
19
+
20
+ A globally installed copy does **not** update itself — npm never pushes updates to a machine. The binary checks for a newer version when it starts and tells you when there is one:
21
+
22
+ ```sh
23
+ npm update -g @alvaroofernaandez/aval
24
+ ```
25
+
26
+ ## What it does
27
+
28
+ Opens a TUI that detects your platform and offers only what applies to it:
29
+
30
+ - **macOS / Linux** — everything, symlinked into `$HOME`.
31
+ - **Windows** — Claude Code, OpenCode and git natively; the terminal environment is shown greyed out with the reason, and installed in full if WSL is detected.
32
+
33
+ Existing files are never deleted. Anything in the way is moved to `~/.aval-backup/<timestamp>/` first, and re-running is a no-op for everything already linked.
34
+
35
+ ## Commands
36
+
37
+ `aval` looks for `install.manifest`: run it inside a clone of the repository or pass `--repo <path>`.
38
+
39
+ ```sh
40
+ aval # interactive TUI
41
+ aval --dry-run # show what would happen, change nothing
42
+ aval --yes # install everything applicable, no TUI
43
+ aval update # pull the repo and re-link what is new
44
+ aval doctor # check links, hooks, agents and settings (--fix, --json)
45
+ aval sync # merge repo-managed settings into ~/.claude/settings.json
46
+ aval restore # undo an install or sync from ~/.aval-backup
47
+ aval uninstall # remove aval's links and give back what they displaced
48
+ aval --version
49
+ ```
50
+
51
+ ## How the binary is delivered
52
+
53
+ Each platform's binary ships as a separate package, pulled in through `optionalDependencies` with `os`/`cpu` constraints — the esbuild pattern. npm downloads only the one that matches your machine.
54
+
55
+ There is **no postinstall script**. Nothing executes at install time, so this works under `npm ci --ignore-scripts` and in environments that forbid install scripts.
56
+
57
+ ## Without Node
58
+
59
+ ```sh
60
+ go install github.com/alvaroofernaandez/aval/cmd/aval@latest
61
+ ```
62
+
63
+ Or download the binary for your platform from the
64
+ [releases page](https://github.com/alvaroofernaandez/aval/releases) (checksums in `SHA256SUMS`).
65
+
66
+ ## License
67
+
68
+ MIT
package/bin/aval.js ADDED
@@ -0,0 +1,77 @@
1
+ #!/usr/bin/env node
2
+ // Launches the platform binary that npm installed alongside this package.
3
+ //
4
+ // The binaries ship as optionalDependencies with `os`/`cpu` constraints, so npm
5
+ // downloads only the one matching the machine — the esbuild pattern. That is
6
+ // deliberate: the alternative, a postinstall script that downloads a binary,
7
+ // breaks under `npm ci --ignore-scripts` and in any environment that forbids
8
+ // install scripts, which is most CI. Nothing here runs at install time.
9
+
10
+ import { spawn } from "node:child_process";
11
+ import { createRequire } from "node:module";
12
+ import { existsSync } from "node:fs";
13
+ import path from "node:path";
14
+
15
+ import { packageFor, binaryName, describeUnsupported, CLI_PACKAGE } from "../lib/resolve.js";
16
+
17
+ const require = createRequire(import.meta.url);
18
+
19
+ function resolveBinary() {
20
+ const pkg = packageFor(process.platform, process.arch);
21
+ if (!pkg) {
22
+ console.error(describeUnsupported(process.platform, process.arch));
23
+ process.exit(1);
24
+ }
25
+
26
+ const file = binaryName(process.platform);
27
+
28
+ // require.resolve on the package's own package.json, not on the binary: the
29
+ // binary is not a module and has no "exports" entry, so resolving it directly
30
+ // fails under modern Node resolution.
31
+ try {
32
+ const manifest = require.resolve(`${pkg}/package.json`);
33
+ const candidate = path.join(path.dirname(manifest), "bin", file);
34
+ if (existsSync(candidate)) return candidate;
35
+ } catch {
36
+ // Fall through to the shared error below.
37
+ }
38
+
39
+ console.error(
40
+ [
41
+ `aval: the binary for ${process.platform}/${process.arch} is missing.`,
42
+ ``,
43
+ `This usually means the optional dependency was skipped. Reinstall with:`,
44
+ ` npm install ${CLI_PACKAGE} --force`,
45
+ ``,
46
+ `If you installed with --no-optional, that flag is the cause.`,
47
+ ].join("\n"),
48
+ );
49
+ process.exit(1);
50
+ }
51
+
52
+ const binary = resolveBinary();
53
+
54
+ // stdio: "inherit" so the TUI owns the real terminal. Without it bubbletea sees
55
+ // a pipe rather than a tty, and renders nothing usable.
56
+ const child = spawn(binary, process.argv.slice(2), { stdio: "inherit" });
57
+
58
+ // Signals are forwarded rather than left to the shell: the child must get the
59
+ // chance to restore the terminal out of the alternate screen buffer, or the
60
+ // user is left with a corrupted prompt.
61
+ for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
62
+ process.on(signal, () => child.kill(signal));
63
+ }
64
+
65
+ child.on("error", (err) => {
66
+ console.error(`aval: could not run ${binary}: ${err.message}`);
67
+ process.exit(1);
68
+ });
69
+
70
+ child.on("close", (code, signal) => {
71
+ // A process killed by a signal reports code null. Exiting 0 there would tell
72
+ // a CI job that an interrupted install succeeded.
73
+ if (signal) {
74
+ process.exit(1);
75
+ }
76
+ process.exit(code ?? 0);
77
+ });
package/lib/resolve.js ADDED
@@ -0,0 +1,50 @@
1
+ // Maps the running platform to the npm package that carries its binary.
2
+ //
3
+ // npm and Go disagree on names — win32 vs windows, x64 vs amd64 — and getting
4
+ // the mapping wrong means npm installs nothing for that platform and the CLI
5
+ // fails at run time with no useful message. The table is therefore explicit
6
+ // rather than computed, and a test pins it against the CI build matrix.
7
+
8
+ export const SCOPE = "@alvaroofernaandez";
9
+ export const CLI_PACKAGE = `${SCOPE}/aval`;
10
+
11
+ /**
12
+ * Every platform we ship. `platform`/`arch` are Node's names (process.platform,
13
+ * process.arch); `goos`/`goarch` are Go's.
14
+ */
15
+ export const TARGETS = [
16
+ { platform: "darwin", arch: "arm64", goos: "darwin", goarch: "arm64" },
17
+ { platform: "darwin", arch: "x64", goos: "darwin", goarch: "amd64" },
18
+ { platform: "linux", arch: "arm64", goos: "linux", goarch: "arm64" },
19
+ { platform: "linux", arch: "x64", goos: "linux", goarch: "amd64" },
20
+ { platform: "win32", arch: "arm64", goos: "windows", goarch: "arm64" },
21
+ { platform: "win32", arch: "x64", goos: "windows", goarch: "amd64" },
22
+ ].map((t) => ({ ...t, pkg: `${CLI_PACKAGE}-${t.platform}-${t.arch}` }));
23
+
24
+ /** The package holding the binary for this platform, or null if unsupported. */
25
+ export function packageFor(platform, arch) {
26
+ const t = TARGETS.find((t) => t.platform === platform && t.arch === arch);
27
+ return t ? t.pkg : null;
28
+ }
29
+
30
+ /** The binary's filename on this platform. */
31
+ export function binaryName(platform) {
32
+ return platform === "win32" ? "aval.exe" : "aval";
33
+ }
34
+
35
+ /**
36
+ * The message shown on an unsupported platform. It names the platform and
37
+ * points at building from source, which needs nothing but Go — being on an
38
+ * odd architecture should not mean being stuck.
39
+ */
40
+ export function describeUnsupported(platform, arch) {
41
+ const supported = TARGETS.map((t) => `${t.platform}/${t.arch}`).join(", ");
42
+ return [
43
+ `aval has no prebuilt binary for ${platform}/${arch}.`,
44
+ ``,
45
+ `Supported: ${supported}`,
46
+ ``,
47
+ `Install from source instead:`,
48
+ ` go install github.com/alvaroofernaandez/aval/cmd/aval@latest`,
49
+ ].join("\n");
50
+ }
package/package.json CHANGED
@@ -1,6 +1,45 @@
1
1
  {
2
2
  "name": "@alvaroofernaandez/aval",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0-rc.1",
4
+ "license": "MIT",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "git+https://github.com/alvaroofernaandez/aval.git"
8
+ },
9
+ "homepage": "https://github.com/alvaroofernaandez/aval#readme",
10
+ "publishConfig": {
11
+ "access": "public"
12
+ },
13
+ "description": "aval — a personal agent harness: terminal, AI agents and evidence. macOS, Linux and Windows",
14
+ "keywords": [
15
+ "aval",
16
+ "harness",
17
+ "dotfiles",
18
+ "installer",
19
+ "tui",
20
+ "tmux",
21
+ "yazi",
22
+ "ghostty",
23
+ "claude-code"
24
+ ],
25
+ "type": "module",
26
+ "bin": {
27
+ "aval": "bin/aval.js"
28
+ },
29
+ "files": [
30
+ "bin",
31
+ "lib",
32
+ "README.md"
33
+ ],
34
+ "engines": {
35
+ "node": ">=18"
36
+ },
37
+ "optionalDependencies": {
38
+ "@alvaroofernaandez/aval-darwin-arm64": "0.1.0-rc.1",
39
+ "@alvaroofernaandez/aval-darwin-x64": "0.1.0-rc.1",
40
+ "@alvaroofernaandez/aval-linux-arm64": "0.1.0-rc.1",
41
+ "@alvaroofernaandez/aval-linux-x64": "0.1.0-rc.1",
42
+ "@alvaroofernaandez/aval-win32-arm64": "0.1.0-rc.1",
43
+ "@alvaroofernaandez/aval-win32-x64": "0.1.0-rc.1"
44
+ }
45
+ }