@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 +67 -2
- package/bin/aval.js +77 -0
- package/lib/resolve.js +50 -0
- package/package.json +43 -4
package/README.md
CHANGED
|
@@ -1,3 +1,68 @@
|
|
|
1
|
-
#
|
|
1
|
+
# aval
|
|
2
2
|
|
|
3
|
-
|
|
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.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
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
|
+
}
|