@nimblebrain/mpak 0.0.1-beta.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/.env.example +13 -0
- package/CLAUDE.md +117 -0
- package/LICENSE +201 -0
- package/README.md +206 -0
- package/dist/commands/packages/pull.d.ts +11 -0
- package/dist/commands/packages/pull.d.ts.map +1 -0
- package/dist/commands/packages/pull.js +72 -0
- package/dist/commands/packages/pull.js.map +1 -0
- package/dist/commands/packages/search.d.ts +12 -0
- package/dist/commands/packages/search.d.ts.map +1 -0
- package/dist/commands/packages/search.js +63 -0
- package/dist/commands/packages/search.js.map +1 -0
- package/dist/commands/packages/show.d.ts +8 -0
- package/dist/commands/packages/show.d.ts.map +1 -0
- package/dist/commands/packages/show.js +121 -0
- package/dist/commands/packages/show.js.map +1 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +12 -0
- package/dist/index.js.map +1 -0
- package/dist/lib/api/registry-client.d.ts +63 -0
- package/dist/lib/api/registry-client.d.ts.map +1 -0
- package/dist/lib/api/registry-client.js +167 -0
- package/dist/lib/api/registry-client.js.map +1 -0
- package/dist/program.d.ts +8 -0
- package/dist/program.d.ts.map +1 -0
- package/dist/program.js +69 -0
- package/dist/program.js.map +1 -0
- package/dist/utils/config-manager.d.ts +23 -0
- package/dist/utils/config-manager.d.ts.map +1 -0
- package/dist/utils/config-manager.js +65 -0
- package/dist/utils/config-manager.js.map +1 -0
- package/dist/utils/errors.d.ts +12 -0
- package/dist/utils/errors.d.ts.map +1 -0
- package/dist/utils/errors.js +27 -0
- package/dist/utils/errors.js.map +1 -0
- package/dist/utils/version.d.ts +5 -0
- package/dist/utils/version.d.ts.map +1 -0
- package/dist/utils/version.js +19 -0
- package/dist/utils/version.js.map +1 -0
- package/eslint.config.js +63 -0
- package/package.json +48 -0
- package/src/commands/packages/pull.ts +96 -0
- package/src/commands/packages/search.ts +83 -0
- package/src/commands/packages/show.ts +138 -0
- package/src/index.ts +15 -0
- package/src/lib/api/registry-client.ts +223 -0
- package/src/lib/api/schema.d.ts +548 -0
- package/src/program.test.ts +24 -0
- package/src/program.ts +76 -0
- package/src/utils/config-manager.test.ts +60 -0
- package/src/utils/config-manager.ts +81 -0
- package/src/utils/errors.test.ts +25 -0
- package/src/utils/errors.ts +33 -0
- package/src/utils/version.test.ts +16 -0
- package/src/utils/version.ts +18 -0
- package/tsconfig.json +25 -0
- package/vitest.config.ts +13 -0
package/.env.example
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# Clerk OAuth Configuration
|
|
2
|
+
# Get these from your Clerk dashboard: https://dashboard.clerk.com
|
|
3
|
+
CLERK_OAUTH_CLIENT_ID=96WRYcxabFktp9wn
|
|
4
|
+
# Domain without protocol (https:// will be added automatically)
|
|
5
|
+
# Example: select-shiner-31.clerk.accounts.dev
|
|
6
|
+
CLERK_OAUTH_DOMAIN=clerk.nimblebrain.ai
|
|
7
|
+
|
|
8
|
+
# OAuth Callback Server Configuration
|
|
9
|
+
# Port for the local OAuth callback server
|
|
10
|
+
MPAK_DEFAULT_PORT=41248
|
|
11
|
+
|
|
12
|
+
# OAuth timeout in milliseconds (default: 5 minutes)
|
|
13
|
+
MPAK_OAUTH_TIMEOUT=300000
|
package/CLAUDE.md
ADDED
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
# mpak CLI
|
|
2
|
+
|
|
3
|
+
CLI for discovering and downloading MCPB bundles from the mpak registry.
|
|
4
|
+
|
|
5
|
+
## Architecture
|
|
6
|
+
|
|
7
|
+
This is a standalone CLI that uses only the public v1 API. It has no dependencies on the server or client packages and generates its TypeScript types from the server's OpenAPI spec.
|
|
8
|
+
|
|
9
|
+
### Key Files
|
|
10
|
+
|
|
11
|
+
| File | Purpose |
|
|
12
|
+
|------|---------|
|
|
13
|
+
| `src/program.ts` | Commander program setup with all commands |
|
|
14
|
+
| `src/lib/api/registry-client.ts` | API client for v1 endpoints |
|
|
15
|
+
| `src/lib/api/schema.d.ts` | Generated types from OpenAPI spec |
|
|
16
|
+
| `src/commands/packages/search.ts` | Search command implementation |
|
|
17
|
+
| `src/commands/packages/show.ts` | Show/info command implementation |
|
|
18
|
+
| `src/commands/packages/pull.ts` | Pull/install command implementation |
|
|
19
|
+
| `src/utils/config-manager.ts` | Config file handling (~/.mpak/config.json) |
|
|
20
|
+
|
|
21
|
+
### Type Generation
|
|
22
|
+
|
|
23
|
+
Types are generated from the server's OpenAPI spec using `openapi-typescript`:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
# Requires server running locally on port 3200
|
|
27
|
+
npm run generate:types
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
This generates `src/lib/api/schema.d.ts` from `http://localhost:3200/documentation/json`.
|
|
31
|
+
|
|
32
|
+
The `registry-client.ts` uses helper types to extract response types:
|
|
33
|
+
|
|
34
|
+
```typescript
|
|
35
|
+
import type { paths } from './schema.js';
|
|
36
|
+
|
|
37
|
+
type ResponseOf<T> = T extends { responses: { 200: { content: { 'application/json': infer R } } } } ? R : never;
|
|
38
|
+
|
|
39
|
+
export type BundleSearchResponse = ResponseOf<paths['/v1/bundles/search']['get']>;
|
|
40
|
+
export type Bundle = BundleSearchResponse['bundles'][number];
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## v1 API Endpoints
|
|
44
|
+
|
|
45
|
+
The CLI uses these public endpoints:
|
|
46
|
+
|
|
47
|
+
| Endpoint | Description |
|
|
48
|
+
|----------|-------------|
|
|
49
|
+
| `GET /v1/bundles/search` | Search bundles by query, type, sort |
|
|
50
|
+
| `GET /v1/bundles/@{scope}/{package}` | Get bundle details (metadata, readme) |
|
|
51
|
+
| `GET /v1/bundles/@{scope}/{package}/versions` | List versions with platform availability |
|
|
52
|
+
| `GET /v1/bundles/@{scope}/{package}/versions/{version}/download` | Get download URL for specific version/platform |
|
|
53
|
+
| `GET /v1/bundles/@{scope}/{package}/versions/latest/download` | Get download URL for latest version |
|
|
54
|
+
|
|
55
|
+
### Platform Selection
|
|
56
|
+
|
|
57
|
+
Download endpoints accept `os` and `arch` query parameters:
|
|
58
|
+
- `os`: darwin, linux, win32, any
|
|
59
|
+
- `arch`: x64, arm64, any
|
|
60
|
+
|
|
61
|
+
The server returns the best matching artifact using this priority:
|
|
62
|
+
1. Exact match (requested os + arch)
|
|
63
|
+
2. OS match with `any` arch
|
|
64
|
+
3. `any` OS with exact arch
|
|
65
|
+
4. Universal (`any` + `any`)
|
|
66
|
+
|
|
67
|
+
## Local Development
|
|
68
|
+
|
|
69
|
+
### Setup
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
npm install
|
|
73
|
+
npm run build
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
### Testing with Local Server
|
|
77
|
+
|
|
78
|
+
The CLI defaults to `https://api.mpak.dev`. For local development:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
# Start the server (from ../server)
|
|
82
|
+
cd ../server && npm run dev
|
|
83
|
+
|
|
84
|
+
# Run CLI commands with local registry
|
|
85
|
+
MPAK_REGISTRY_URL=http://localhost:3200 npm run dev -- search echo
|
|
86
|
+
MPAK_REGISTRY_URL=http://localhost:3200 node dist/index.js pull @nimblebraininc/echo
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
### Verification
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
npm run build
|
|
93
|
+
npm run typecheck
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## Commands (MVP)
|
|
97
|
+
|
|
98
|
+
| Command | Description |
|
|
99
|
+
|---------|-------------|
|
|
100
|
+
| `search <query>` | Search public bundles |
|
|
101
|
+
| `show <package>` | Show bundle details with platforms |
|
|
102
|
+
| `info <package>` | Alias for show |
|
|
103
|
+
| `pull <package>` | Download a bundle |
|
|
104
|
+
| `install <package>` | Alias for pull |
|
|
105
|
+
|
|
106
|
+
## Design Decisions
|
|
107
|
+
|
|
108
|
+
1. **Standalone**: No shared dependencies with server/client. Types generated from OpenAPI.
|
|
109
|
+
2. **Public API only**: MVP uses only v1 API. Publishing requires separate tooling.
|
|
110
|
+
3. **Platform detection**: Auto-detects OS/arch, allows explicit override for cross-platform downloads.
|
|
111
|
+
4. **Config file**: Stores registry URL in `~/.mpak/config.json`, overridable via `MPAK_REGISTRY_URL`.
|
|
112
|
+
|
|
113
|
+
## Future Considerations
|
|
114
|
+
|
|
115
|
+
- The CLI will be broken out into a completely standalone repository
|
|
116
|
+
- Authentication commands (login, publish) may be added when needed
|
|
117
|
+
- Consider adding `npx` support for zero-install usage
|
package/LICENSE
ADDED
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
|
+
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
25
|
+
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
29
|
+
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
34
|
+
|
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
36
|
+
Object form, made available under the License, as indicated by a
|
|
37
|
+
copyright notice that is included in or attached to the work
|
|
38
|
+
(an example is provided in the Appendix below).
|
|
39
|
+
|
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
46
|
+
the Work and Derivative Works thereof.
|
|
47
|
+
|
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
|
49
|
+
the original version of the Work and any modifications or additions
|
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
51
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
61
|
+
|
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
63
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
64
|
+
subsequently incorporated within the Work.
|
|
65
|
+
|
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
|
72
|
+
|
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
78
|
+
where such license applies only to those patent claims licensable
|
|
79
|
+
by such Contributor that are necessarily infringed by their
|
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
82
|
+
institute patent litigation against any entity (including a
|
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
85
|
+
or contributory patent infringement, then any patent licenses
|
|
86
|
+
granted to You under this License for that Work shall terminate
|
|
87
|
+
as of the date such litigation is filed.
|
|
88
|
+
|
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
91
|
+
modifications, and in Source or Object form, provided that You
|
|
92
|
+
meet the following conditions:
|
|
93
|
+
|
|
94
|
+
(a) You must give any other recipients of the Work or
|
|
95
|
+
Derivative Works a copy of this License; and
|
|
96
|
+
|
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
|
98
|
+
stating that You changed the files; and
|
|
99
|
+
|
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
|
102
|
+
attribution notices from the Source form of the Work,
|
|
103
|
+
excluding those notices that do not pertain to any part of
|
|
104
|
+
the Derivative Works; and
|
|
105
|
+
|
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
|
108
|
+
include a readable copy of the attribution notices contained
|
|
109
|
+
within such NOTICE file, excluding those notices that do not
|
|
110
|
+
pertain to any part of the Derivative Works, in at least one
|
|
111
|
+
of the following places: within a NOTICE text file distributed
|
|
112
|
+
as part of the Derivative Works; within the Source form or
|
|
113
|
+
documentation, if provided along with the Derivative Works; or,
|
|
114
|
+
within a display generated by the Derivative Works, if and
|
|
115
|
+
wherever such third-party notices normally appear. The contents
|
|
116
|
+
of the NOTICE file are for informational purposes only and
|
|
117
|
+
do not modify the License. You may add Your own attribution
|
|
118
|
+
notices within Derivative Works that You distribute, alongside
|
|
119
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
120
|
+
that such additional attribution notices cannot be construed
|
|
121
|
+
as modifying the License.
|
|
122
|
+
|
|
123
|
+
You may add Your own copyright statement to Your modifications and
|
|
124
|
+
may provide additional or different license terms and conditions
|
|
125
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
126
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
127
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
128
|
+
the conditions stated in this License.
|
|
129
|
+
|
|
130
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
131
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
132
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
133
|
+
this License, without any additional terms or conditions.
|
|
134
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
135
|
+
the terms of any separate license agreement you may have executed
|
|
136
|
+
with Licensor regarding such Contributions.
|
|
137
|
+
|
|
138
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
139
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
140
|
+
except as required for reasonable and customary use in describing the
|
|
141
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
142
|
+
|
|
143
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
144
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
145
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
146
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
147
|
+
implied, including, without limitation, any warranties or conditions
|
|
148
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
149
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
150
|
+
appropriateness of using or redistributing the Work and assume any
|
|
151
|
+
risks associated with Your exercise of permissions under this License.
|
|
152
|
+
|
|
153
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
154
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
155
|
+
unless required by applicable law (such as deliberate and grossly
|
|
156
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
157
|
+
liable to You for damages, including any direct, indirect, special,
|
|
158
|
+
incidental, or consequential damages of any character arising as a
|
|
159
|
+
result of this License or out of the use or inability to use the
|
|
160
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
161
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
162
|
+
other commercial damages or losses), even if such Contributor
|
|
163
|
+
has been advised of the possibility of such damages.
|
|
164
|
+
|
|
165
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
166
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
167
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
168
|
+
or other liability obligations and/or rights consistent with this
|
|
169
|
+
License. However, in accepting such obligations, You may act only
|
|
170
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
171
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
172
|
+
defend, and hold each Contributor harmless for any liability
|
|
173
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
174
|
+
of your accepting any such warranty or additional liability.
|
|
175
|
+
|
|
176
|
+
END OF TERMS AND CONDITIONS
|
|
177
|
+
|
|
178
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
179
|
+
|
|
180
|
+
To apply the Apache License to your work, attach the following
|
|
181
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
182
|
+
replaced with your own identifying information. (Don't include
|
|
183
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
184
|
+
comment syntax for the file format. We also recommend that a
|
|
185
|
+
file or class name and description of purpose be included on the
|
|
186
|
+
same "printed page" as the copyright notice for easier
|
|
187
|
+
identification within third-party archives.
|
|
188
|
+
|
|
189
|
+
Copyright 2025 NimbleBrain, Inc.
|
|
190
|
+
|
|
191
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
192
|
+
you may not use this file except in compliance with the License.
|
|
193
|
+
You may obtain a copy of the License at
|
|
194
|
+
|
|
195
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
196
|
+
|
|
197
|
+
Unless required by applicable law or agreed to in writing, software
|
|
198
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
199
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
200
|
+
See the License for the specific language governing permissions and
|
|
201
|
+
limitations under the License.
|
package/README.md
ADDED
|
@@ -0,0 +1,206 @@
|
|
|
1
|
+
# mpak CLI
|
|
2
|
+
|
|
3
|
+
CLI for discovering and downloading MCPB bundles from the mpak registry.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install -g @nimblebrain/mpak
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Quick Start
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
# Search for bundles
|
|
15
|
+
mpak search postgres
|
|
16
|
+
|
|
17
|
+
# Show bundle details
|
|
18
|
+
mpak show @owner/my-server
|
|
19
|
+
|
|
20
|
+
# Download a bundle
|
|
21
|
+
mpak pull @owner/my-server
|
|
22
|
+
mpak pull @owner/my-server@1.0.0 # specific version
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## Commands
|
|
26
|
+
|
|
27
|
+
| Command | Description |
|
|
28
|
+
|---------|-------------|
|
|
29
|
+
| `search <query>` | Search public bundles |
|
|
30
|
+
| `show <package>` | Show bundle details with platforms |
|
|
31
|
+
| `info <package>` | Alias for show |
|
|
32
|
+
| `pull <package>` | Download a bundle |
|
|
33
|
+
| `install <package>` | Alias for pull |
|
|
34
|
+
|
|
35
|
+
### search
|
|
36
|
+
|
|
37
|
+
Search for bundles in the registry.
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
mpak search echo
|
|
41
|
+
mpak search --type python echo
|
|
42
|
+
mpak search --sort downloads --limit 10 mcp
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Options:
|
|
46
|
+
- `--type <type>` - Filter by server type (node, python, binary)
|
|
47
|
+
- `--sort <field>` - Sort by: downloads, recent, name (default: downloads)
|
|
48
|
+
- `--limit <n>` - Limit results (default: 20)
|
|
49
|
+
- `--offset <n>` - Pagination offset
|
|
50
|
+
- `--json` - Output as JSON
|
|
51
|
+
|
|
52
|
+
### show / info
|
|
53
|
+
|
|
54
|
+
Display detailed information about a bundle.
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
mpak show @nimblebraininc/echo
|
|
58
|
+
mpak show @nimblebraininc/echo --json
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Shows:
|
|
62
|
+
- Bundle metadata (name, author, type, license)
|
|
63
|
+
- Provenance info (if published via GitHub Actions OIDC)
|
|
64
|
+
- Download stats
|
|
65
|
+
- Available versions with platforms
|
|
66
|
+
- Install instructions
|
|
67
|
+
|
|
68
|
+
Options:
|
|
69
|
+
- `--json` - Output as JSON
|
|
70
|
+
|
|
71
|
+
### pull / install
|
|
72
|
+
|
|
73
|
+
Download a bundle from the registry.
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
# Download latest version for current platform
|
|
77
|
+
mpak pull @nimblebraininc/echo
|
|
78
|
+
|
|
79
|
+
# Download specific version
|
|
80
|
+
mpak pull @nimblebraininc/echo@1.0.0
|
|
81
|
+
|
|
82
|
+
# Download for different platform (cross-compile use case)
|
|
83
|
+
mpak pull @nimblebraininc/echo --os linux --arch arm64
|
|
84
|
+
|
|
85
|
+
# Custom output path
|
|
86
|
+
mpak pull @nimblebraininc/echo -o ./bundles/echo.mcpb
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Options:
|
|
90
|
+
- `-o, --output <path>` - Output file path
|
|
91
|
+
- `--os <os>` - Target OS: darwin, linux, win32
|
|
92
|
+
- `--arch <arch>` - Target architecture: x64, arm64
|
|
93
|
+
- `--json` - Output download info as JSON (doesn't download)
|
|
94
|
+
|
|
95
|
+
## Configuration
|
|
96
|
+
|
|
97
|
+
Configuration is stored in `~/.mpak/config.json`:
|
|
98
|
+
|
|
99
|
+
```json
|
|
100
|
+
{
|
|
101
|
+
"version": "1.0.0",
|
|
102
|
+
"lastUpdated": "2025-12-30T...",
|
|
103
|
+
"registryUrl": "https://api.mpak.dev"
|
|
104
|
+
}
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
### Environment Variables
|
|
108
|
+
|
|
109
|
+
| Variable | Description | Default |
|
|
110
|
+
|----------|-------------|---------|
|
|
111
|
+
| `MPAK_REGISTRY_URL` | Registry API URL | `https://api.mpak.dev` |
|
|
112
|
+
|
|
113
|
+
## API
|
|
114
|
+
|
|
115
|
+
The CLI uses the public v1 API:
|
|
116
|
+
|
|
117
|
+
| Endpoint | Description |
|
|
118
|
+
|----------|-------------|
|
|
119
|
+
| `GET /v1/bundles/search` | Search bundles |
|
|
120
|
+
| `GET /v1/bundles/@{scope}/{pkg}` | Get bundle details |
|
|
121
|
+
| `GET /v1/bundles/@{scope}/{pkg}/versions` | List versions with platforms |
|
|
122
|
+
| `GET /v1/bundles/@{scope}/{pkg}/versions/{version}/download` | Get download URL |
|
|
123
|
+
|
|
124
|
+
## Development
|
|
125
|
+
|
|
126
|
+
### Setup
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
cd apps/mpak/cli
|
|
130
|
+
npm install
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### Scripts
|
|
134
|
+
|
|
135
|
+
| Script | Description |
|
|
136
|
+
|--------|-------------|
|
|
137
|
+
| `npm run build` | Build TypeScript to JavaScript |
|
|
138
|
+
| `npm run dev` | Run CLI in development mode |
|
|
139
|
+
| `npm run typecheck` | Type check without building |
|
|
140
|
+
| `npm run generate:types` | Generate types from OpenAPI spec |
|
|
141
|
+
| `npm test` | Run tests |
|
|
142
|
+
| `npm run lint` | Lint source code |
|
|
143
|
+
|
|
144
|
+
### Publishing
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
# Stable release
|
|
148
|
+
npm publish
|
|
149
|
+
|
|
150
|
+
# Beta/prerelease (required for versions like 0.0.1-beta.1)
|
|
151
|
+
npm publish --tag beta
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
### Local Testing
|
|
155
|
+
|
|
156
|
+
1. Start the server locally:
|
|
157
|
+
```bash
|
|
158
|
+
cd ../server
|
|
159
|
+
npm run dev
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
2. Run CLI with local registry:
|
|
163
|
+
```bash
|
|
164
|
+
MPAK_REGISTRY_URL=http://localhost:3200 npm run dev -- search echo
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
3. Or build and test:
|
|
168
|
+
```bash
|
|
169
|
+
npm run build
|
|
170
|
+
MPAK_REGISTRY_URL=http://localhost:3200 node dist/index.js search echo
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
### Type Generation
|
|
174
|
+
|
|
175
|
+
Types are generated from the server's OpenAPI spec:
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
# Requires server running locally
|
|
179
|
+
npm run generate:types
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
This generates `src/lib/api/schema.d.ts` from `http://localhost:3200/documentation/json`.
|
|
183
|
+
|
|
184
|
+
### Project Structure
|
|
185
|
+
|
|
186
|
+
```
|
|
187
|
+
src/
|
|
188
|
+
├── index.ts # Entry point
|
|
189
|
+
├── program.ts # Commander program setup
|
|
190
|
+
├── commands/
|
|
191
|
+
│ └── packages/
|
|
192
|
+
│ ├── search.ts # Search command
|
|
193
|
+
│ ├── show.ts # Show/info command
|
|
194
|
+
│ └── pull.ts # Pull/install command
|
|
195
|
+
├── lib/
|
|
196
|
+
│ └── api/
|
|
197
|
+
│ ├── registry-client.ts # API client
|
|
198
|
+
│ └── schema.d.ts # Generated OpenAPI types
|
|
199
|
+
└── utils/
|
|
200
|
+
├── config-manager.ts # Config file handling
|
|
201
|
+
└── version.ts # Version helper
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
## License
|
|
205
|
+
|
|
206
|
+
[Apache 2.0](LICENSE)
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
export interface PullOptions {
|
|
2
|
+
output?: string;
|
|
3
|
+
json?: boolean;
|
|
4
|
+
os?: string;
|
|
5
|
+
arch?: string;
|
|
6
|
+
}
|
|
7
|
+
/**
|
|
8
|
+
* Pull (download) a package from the registry
|
|
9
|
+
*/
|
|
10
|
+
export declare function handlePull(packageSpec: string, options?: PullOptions): Promise<void>;
|
|
11
|
+
//# sourceMappingURL=pull.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"pull.d.ts","sourceRoot":"","sources":["../../../src/commands/packages/pull.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AA8BD;;GAEG;AACH,wBAAsB,UAAU,CAC9B,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CAmDf"}
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
import { resolve } from 'path';
|
|
2
|
+
import { RegistryClient } from '../../lib/api/registry-client.js';
|
|
3
|
+
/**
|
|
4
|
+
* Parse package specification into name and version
|
|
5
|
+
* Examples:
|
|
6
|
+
* @scope/name -> { name: '@scope/name', version: undefined }
|
|
7
|
+
* @scope/name@1.0.0 -> { name: '@scope/name', version: '1.0.0' }
|
|
8
|
+
*/
|
|
9
|
+
function parsePackageSpec(spec) {
|
|
10
|
+
// Find the last @ which separates version from package name
|
|
11
|
+
// Package names start with @, so we need to find the second @
|
|
12
|
+
const lastAtIndex = spec.lastIndexOf('@');
|
|
13
|
+
if (lastAtIndex <= 0) {
|
|
14
|
+
// No version specified or invalid format
|
|
15
|
+
return { name: spec };
|
|
16
|
+
}
|
|
17
|
+
const name = spec.substring(0, lastAtIndex);
|
|
18
|
+
const version = spec.substring(lastAtIndex + 1);
|
|
19
|
+
// Validate that the name still starts with @
|
|
20
|
+
if (!name.startsWith('@')) {
|
|
21
|
+
// This means the @ was part of the package name, not a version separator
|
|
22
|
+
return { name: spec };
|
|
23
|
+
}
|
|
24
|
+
return { name, version };
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* Pull (download) a package from the registry
|
|
28
|
+
*/
|
|
29
|
+
export async function handlePull(packageSpec, options = {}) {
|
|
30
|
+
try {
|
|
31
|
+
const { name, version } = parsePackageSpec(packageSpec);
|
|
32
|
+
const client = new RegistryClient();
|
|
33
|
+
// Detect platform (or use explicit overrides)
|
|
34
|
+
const detectedPlatform = RegistryClient.detectPlatform();
|
|
35
|
+
const platform = {
|
|
36
|
+
os: options.os || detectedPlatform.os,
|
|
37
|
+
arch: options.arch || detectedPlatform.arch,
|
|
38
|
+
};
|
|
39
|
+
console.log(`=> Fetching ${version ? `${name}@${version}` : `${name} (latest)`}...`);
|
|
40
|
+
console.log(` Platform: ${platform.os}-${platform.arch}`);
|
|
41
|
+
// Get download info with platform
|
|
42
|
+
const downloadInfo = await client.getDownloadInfo(name, version, platform);
|
|
43
|
+
if (options.json) {
|
|
44
|
+
console.log(JSON.stringify(downloadInfo, null, 2));
|
|
45
|
+
return;
|
|
46
|
+
}
|
|
47
|
+
const bundle = downloadInfo.bundle;
|
|
48
|
+
console.log(` Version: ${bundle.version}`);
|
|
49
|
+
console.log(` Artifact: ${bundle.platform.os}-${bundle.platform.arch}`);
|
|
50
|
+
console.log(` Size: ${(bundle.size / (1024 * 1024)).toFixed(2)} MB`);
|
|
51
|
+
// Determine output filename (include platform in name)
|
|
52
|
+
const platformSuffix = `${bundle.platform.os}-${bundle.platform.arch}`;
|
|
53
|
+
const defaultFilename = `${name.replace('@', '').replace('/', '-')}-${bundle.version}-${platformSuffix}.mcpb`;
|
|
54
|
+
const outputPath = options.output
|
|
55
|
+
? resolve(options.output)
|
|
56
|
+
: resolve(defaultFilename);
|
|
57
|
+
console.log(`\n=> Downloading to ${outputPath}...`);
|
|
58
|
+
// Download the bundle
|
|
59
|
+
await client.downloadBundle(downloadInfo.url, outputPath);
|
|
60
|
+
console.log(`\n=> Bundle downloaded successfully!`);
|
|
61
|
+
console.log(` File: ${outputPath}`);
|
|
62
|
+
console.log(` SHA256: ${bundle.sha256.substring(0, 16)}...`);
|
|
63
|
+
}
|
|
64
|
+
catch (error) {
|
|
65
|
+
console.error('\n=> Failed to pull bundle');
|
|
66
|
+
if (error instanceof Error) {
|
|
67
|
+
console.error(` ${error.message}`);
|
|
68
|
+
}
|
|
69
|
+
process.exit(1);
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
//# sourceMappingURL=pull.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"pull.js","sourceRoot":"","sources":["../../../src/commands/packages/pull.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
export interface SearchOptions {
|
|
2
|
+
type?: string;
|
|
3
|
+
sort?: 'downloads' | 'recent' | 'name';
|
|
4
|
+
limit?: number;
|
|
5
|
+
offset?: number;
|
|
6
|
+
json?: boolean;
|
|
7
|
+
}
|
|
8
|
+
/**
|
|
9
|
+
* Search bundles (v1 API)
|
|
10
|
+
*/
|
|
11
|
+
export declare function handleSearch(query: string, options?: SearchOptions): Promise<void>;
|
|
12
|
+
//# sourceMappingURL=search.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../src/commands/packages/search.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAkEf"}
|