@baldaworks/acprun 0.1.1 → 0.1.3

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.
Files changed (3) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +76 -37
  3. package/package.json +10 -8
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Alexey Samoylov
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,5 +1,14 @@
1
1
  # acprun
2
2
 
3
+ [![Test](https://github.com/baldaworks/acprun/actions/workflows/test.yml/badge.svg)](https://github.com/baldaworks/acprun/actions/workflows/test.yml)
4
+ [![Lint](https://github.com/baldaworks/acprun/actions/workflows/lint.yml/badge.svg)](https://github.com/baldaworks/acprun/actions/workflows/lint.yml)
5
+ [![Security](https://github.com/baldaworks/acprun/actions/workflows/security.yml/badge.svg)](https://github.com/baldaworks/acprun/actions/workflows/security.yml)
6
+ [![Latest release](https://img.shields.io/github/v/release/baldaworks/acprun)](https://github.com/baldaworks/acprun/releases/latest)
7
+ [![npm version](https://img.shields.io/npm/v/%40baldaworks%2Facprun)](https://www.npmjs.com/package/@baldaworks/acprun)
8
+ [![License: MIT](https://img.shields.io/github/license/baldaworks/acprun)](LICENSE)
9
+
10
+ ## Universal agent runner and registry client for the Agent Client Protocol (ACP)
11
+
3
12
  `acprun` is a CLI tool, runner, and Go library for discovering, resolving, and running agents published in the [Agent Client Protocol (ACP) Registry](https://agentclientprotocol.com).
4
13
 
5
14
  It transparently handles distribution resolution across:
@@ -10,21 +19,32 @@ It transparently handles distribution resolution across:
10
19
 
11
20
  ---
12
21
 
13
- ## Installation
22
+ ## Installation and quick start
23
+
24
+ ### npm package (recommended)
25
+
26
+ For repeated direct shell use, install the npm launcher globally:
14
27
 
15
- ### Via Go
16
28
  ```bash
17
- go install github.com/baldaworks/acprun/cmd/acprun@latest
29
+ npm install --global @baldaworks/acprun@latest
30
+ acprun --version
18
31
  ```
19
32
 
20
- ### Via NPX (Omnidist)
33
+ For one-shot execution without global installation, run the complete `npx` command:
34
+
21
35
  ```bash
22
- npx -y @baldaworks/acprun list
36
+ npx --yes @baldaworks/acprun@latest list
37
+ ```
38
+
39
+ ### Go binary
40
+
41
+ ```bash
42
+ go install github.com/baldaworks/acprun/cmd/acprun@latest
23
43
  ```
24
44
 
25
45
  ---
26
46
 
27
- ## Quick Start & One-Shot Mode
47
+ ## One-shot agent execution
28
48
 
29
49
  `acprun` supports **one-shot execution** directly without needing explicit subcommands (similar to `npx` or `uvx`):
30
50
 
@@ -44,20 +64,9 @@ acprun amp-acp --verbose
44
64
 
45
65
  ---
46
66
 
47
- ## CLI Reference
67
+ ## Agent discovery and inspection
48
68
 
49
- ### Global Flags
50
- ```text
51
- -r, --registry string ACP Registry URL (default: official CDN, env: ACP_REGISTRY_URL)
52
- --cache-dir string Custom cache directory (default: $USER_CACHE_DIR/acprun, env: ACP_CACHE_DIR)
53
- --offline Offline mode: use cached manifests and binaries only
54
- -v, --verbose Enable verbose output
55
- -h, --help Help for acprun
56
- ```
57
-
58
- ### Commands
59
-
60
- #### `acprun list`
69
+ ### `acprun list`
61
70
  List all agents available in the ACP registry.
62
71
  ```bash
63
72
  # Formatted table
@@ -70,22 +79,26 @@ acprun list --distribution binary
70
79
  acprun list --format json
71
80
  ```
72
81
 
73
- #### `acprun info <agent-id>` (alias: `show`)
82
+ ### `acprun info <agent-id>` (alias: `show`)
74
83
  Display detailed agent metadata, license, authors, repository, and platform distribution specs.
75
84
  ```bash
76
85
  acprun info devin
77
86
  acprun info gemini --json
78
87
  ```
79
88
 
80
- #### `acprun resolve <agent-id>`
89
+ ### `acprun resolve <agent-id>`
81
90
  Dry-run resolution: downloads and extracts binary archives to local cache if needed, and prints the resolved command vector without running the process.
82
91
  ```bash
83
92
  acprun resolve antigravity-acp --json
84
93
  acprun resolve goose --platform linux-x86_64
85
94
  ```
86
95
 
87
- #### `acprun run <agent-id> [-- extra-args...]` (aliases: `serve`, `exec`, `start`)
88
- Explicit execution form to run any agent without potential name collision (e.g. running an agent named `list` or `cache`).
96
+ ---
97
+
98
+ ## Explicit runner subcommands
99
+
100
+ Use explicit runner subcommands (`run`, `serve`, `exec`, `start`) when you want to avoid any potential ambiguity with management subcommands (e.g. running an agent whose ID is `list` or `cache`):
101
+
89
102
  ```bash
90
103
  # Explicit run
91
104
  acprun run cursor -- acp
@@ -97,8 +110,10 @@ acprun serve devin
97
110
  acprun run fast-agent -e FAST_AGENT_MODEL=custom -- -x
98
111
  ```
99
112
 
100
- #### `acprun cache`
101
- Manage local ACP cache directory.
113
+ ---
114
+
115
+ ## Cache management
116
+
102
117
  ```bash
103
118
  # Print cache directory path
104
119
  acprun cache path
@@ -108,22 +123,40 @@ acprun cache clean --all
108
123
  acprun cache clean --manifests-only
109
124
  ```
110
125
 
111
- #### `acprun version`
112
- Print version and build information.
113
- ```bash
114
- acprun version
126
+ ---
127
+
128
+ ## CLI reference
129
+
130
+ ### Global Flags
131
+ ```text
132
+ -r, --registry string ACP Registry URL (default: official CDN, env: ACP_REGISTRY_URL)
133
+ --cache-dir string Custom cache directory (default: $USER_CACHE_DIR/acprun, env: ACP_CACHE_DIR)
134
+ --offline Offline mode: use cached manifests and binaries only
135
+ -v, --verbose Enable verbose output
136
+ -h, --help Help for acprun
115
137
  ```
116
138
 
139
+ ### Subcommands Table
140
+ | Command | Description | Aliases |
141
+ | --- | --- | --- |
142
+ | `acprun <agent-id> [args...]` | One-shot agent resolution and execution | — |
143
+ | `acprun run <agent-id>` | Explicit agent process runner | `serve`, `exec`, `start` |
144
+ | `acprun list` | List available registry agents | `ls` |
145
+ | `acprun info <agent-id>` | Display detailed agent metadata and distributions | `show` |
146
+ | `acprun resolve <agent-id>` | Dry-run resolution to command vector | — |
147
+ | `acprun cache [path\|clean]` | Inspect or clean local ACP cache | — |
148
+ | `acprun version` | Print version and build metadata | — |
149
+
117
150
  ---
118
151
 
119
- ## Architecture & Security
152
+ ## Architecture and security
120
153
 
121
- - **Targeted Internal Package Layout**:
122
- - `cmd/acprun/`: Binary entrypoint.
123
- - `internal/cli/`: Cobra CLI commands with one-shot dispatch.
124
- - `internal/registry/`: ACP v1 models, HTTP client, and manifest caching.
125
- - `internal/resolver/`: Host platform detection, safe archive extraction (`.zip`, `.tar.gz`, `.tar.bz2`), and Binary/NPX/UVX distribution resolvers.
126
- - `internal/runner/`: Process execution, stdio binding, and signal forwarding (`SIGINT`, `SIGTERM`).
154
+ - **Targeted Package Layout**:
155
+ - [`cmd/acprun/`](cmd/acprun/): Binary entrypoint.
156
+ - [`internal/cli/`](internal/cli/): Cobra CLI commands with one-shot dispatch.
157
+ - [`internal/registry/`](internal/registry/): ACP v1 models, HTTP client, and manifest caching.
158
+ - [`internal/resolver/`](internal/resolver/): Host platform detection, safe archive extraction (`.zip`, `.tar.gz`, `.tar.bz2`), and Binary/NPX/UVX distribution resolvers.
159
+ - [`internal/runner/`](internal/runner/): Process execution, stdio binding, and signal forwarding (`SIGINT`, `SIGTERM`).
127
160
  - **Security & Integrity**:
128
161
  - **Zip Slip Prevention**: Validates all archive entry paths stay within the target destination directory before extraction.
129
162
  - **SHA256 Verification**: Verifies SHA256 integrity checksums against registry manifests.
@@ -131,6 +164,12 @@ acprun version
131
164
 
132
165
  ---
133
166
 
167
+ ## Distribution
168
+
169
+ The npm distribution uses CGO-disabled native executables for macOS and Linux on AMD64/ARM64 and Windows AMD64/ARM64 behind the [`@baldaworks/acprun`](https://www.npmjs.com/package/@baldaworks/acprun) launcher.
170
+
171
+ ---
172
+
134
173
  ## License
135
174
 
136
- Apache-2.0 / MIT
175
+ `acprun` is released under the [MIT License](LICENSE).
package/package.json CHANGED
@@ -8,16 +8,18 @@
8
8
  },
9
9
  "files": [
10
10
  "acprun.js",
11
- "README.md"
11
+ "README.md",
12
+ "LICENSE"
12
13
  ],
14
+ "license": "SEE LICENSE IN LICENSE",
13
15
  "name": "@baldaworks/acprun",
14
16
  "optionalDependencies": {
15
- "@baldaworks/acprun-darwin-arm64": "0.1.1",
16
- "@baldaworks/acprun-darwin-x64": "0.1.1",
17
- "@baldaworks/acprun-linux-arm64": "0.1.1",
18
- "@baldaworks/acprun-linux-x64": "0.1.1",
19
- "@baldaworks/acprun-win32-arm64": "0.1.1",
20
- "@baldaworks/acprun-win32-x64": "0.1.1"
17
+ "@baldaworks/acprun-darwin-arm64": "0.1.3",
18
+ "@baldaworks/acprun-darwin-x64": "0.1.3",
19
+ "@baldaworks/acprun-linux-arm64": "0.1.3",
20
+ "@baldaworks/acprun-linux-x64": "0.1.3",
21
+ "@baldaworks/acprun-win32-arm64": "0.1.3",
22
+ "@baldaworks/acprun-win32-x64": "0.1.3"
21
23
  },
22
- "version": "0.1.1"
24
+ "version": "0.1.3"
23
25
  }