bc-pkg 1.0.0 → 1.0.2
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 +66 -134
- package/bin/bc-pkg.js +714 -422
- package/package.json +13 -13
package/README.md
CHANGED
|
@@ -1,163 +1,95 @@
|
|
|
1
1
|
# bc-pkg
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
3
|
+
`bc-pkg` creates or reuses a BigConfig CLI in the current directory, then
|
|
4
|
+
forwards your command to that CLI.
|
|
5
|
+
|
|
6
|
+
The npm package and the PyPI package expose the same behavior. The target
|
|
7
|
+
package can be implemented in Clojure, TypeScript, or Python; `bc-pkg` infers
|
|
8
|
+
that language from the pinned GitHub content.
|
|
7
9
|
|
|
8
10
|
## Usage
|
|
9
11
|
|
|
10
12
|
```sh
|
|
11
|
-
npx bc-pkg@
|
|
12
|
-
npx bc-pkg
|
|
13
|
-
npx bc-pkg@latest <owner>/<project> <args...> # bootstrap/validate bb.edn, then -> bb <args...>
|
|
13
|
+
npx bc-pkg <owner/repo@ref> package validate
|
|
14
|
+
npx bc-pkg package validate
|
|
14
15
|
```
|
|
15
16
|
|
|
16
|
-
|
|
17
|
-
other arguments (including flags) are passed through verbatim, and `bb` runs in
|
|
18
|
-
your current working directory, so it picks up the local `bb.edn`. If
|
|
19
|
-
the first argument has the shape `owner/project`, it is consumed as repo
|
|
20
|
-
identity and never forwarded to `bb`: it bootstraps a missing `bb.edn` or
|
|
21
|
-
validates the existing `bb.edn`'s top-level `:repo`.
|
|
22
|
-
|
|
23
|
-
## What happens on first run
|
|
24
|
-
|
|
25
|
-
1. The host OS/CPU are resolved to the matching babashka release asset and
|
|
26
|
-
Adoptium API parameters.
|
|
27
|
-
2. babashka is downloaded from its GitHub releases and cached.
|
|
28
|
-
3. A Temurin JDK is downloaded from the Adoptium API and cached.
|
|
29
|
-
4. On Linux, `git` is installed via the system package manager if it is not on
|
|
30
|
-
`PATH`.
|
|
31
|
-
5. If a `<owner>/<project>` slug is the first argument, it is consumed; it
|
|
32
|
-
bootstraps a missing `bb.edn` or validates an existing `bb.edn`'s `:repo`.
|
|
33
|
-
6. `bb` is launched with `JAVA_HOME` / `PATH` pointing at the cached JDK (and
|
|
34
|
-
the cached `bb`, so nested `bb` calls work) — the environment change applies
|
|
35
|
-
**only** to the `bb` subprocess.
|
|
36
|
-
|
|
37
|
-
Subsequent runs reuse the cache and start immediately.
|
|
38
|
-
|
|
39
|
-
## git (Linux only)
|
|
40
|
-
|
|
41
|
-
On Linux, if `git` is not on `PATH`, it is installed via the system package
|
|
42
|
-
manager (`apt-get`, `dnf`, `yum`, `zypper`, `pacman`, or `apk`), using `sudo`
|
|
43
|
-
when not running as root. This is **skipped** when git is already present, and
|
|
44
|
-
is a **no-op on macOS/Windows**. Unlike babashka/JDK, this modifies the system
|
|
45
|
-
and may prompt for a sudo password; in non-interactive environments without
|
|
46
|
-
passwordless sudo it will fail with an actionable message — pre-install git to
|
|
47
|
-
avoid this entirely.
|
|
48
|
-
|
|
49
|
-
## bb.edn bootstrap (optional)
|
|
50
|
-
|
|
51
|
-
If the current directory has **no `bb.edn`** and the first argument has the
|
|
52
|
-
shape `owner/project`, that repo's `bb.edn` is downloaded (pinned to its
|
|
53
|
-
default branch's latest commit), top-level `:repo "owner/project"` is ensured,
|
|
54
|
-
and the repo itself is added to `:deps` as
|
|
55
|
-
`io.github.<owner>/<project> {:git/sha "<sha>"}`. The edit is done with
|
|
56
|
-
`borkdude/rewrite-edn`, so existing comments and formatting are preserved.
|
|
57
|
-
The slug is consumed; remaining arguments are forwarded to `bb`.
|
|
58
|
-
|
|
59
|
-
If a `bb.edn` already exists, the same slug is still consumed and compared
|
|
60
|
-
exactly with top-level `:repo`. The slug may be omitted when `bb.edn` exists.
|
|
61
|
-
|
|
62
|
-
Any dependency using `:local/root` (in `:deps` or a task's `:extra-deps`) is
|
|
63
|
-
removed first, since those paths don't exist once the file is downloaded.
|
|
64
|
-
Valid Maven/git deps are kept.
|
|
65
|
-
|
|
66
|
-
- Skipped if no slug is given and no `bb.edn` needs to be created.
|
|
67
|
-
- Fatal error, when a slug is supplied, if an existing `bb.edn` is invalid,
|
|
68
|
-
lacks `:repo`, or has a different `:repo`.
|
|
69
|
-
- Fatal error if the repo is missing/inaccessible, has no `bb.edn`, or its
|
|
70
|
-
`bb.edn` declares a different `:repo`.
|
|
71
|
-
- Set `GITHUB_TOKEN` for private repos or to avoid GitHub's unauthenticated
|
|
72
|
-
API rate limit.
|
|
17
|
+
`ref` can be a branch name or a full 40-character commit SHA:
|
|
73
18
|
|
|
74
19
|
```sh
|
|
75
|
-
npx bc-pkg
|
|
20
|
+
npx bc-pkg bigconfig-ai/once@typescript package validate
|
|
21
|
+
npx bc-pkg bigconfig-ai/once@2f4e8c0d0b4c4b8f0c3a9f6e2a1b5c7d8e9f0123 package validate
|
|
76
22
|
```
|
|
77
23
|
|
|
78
|
-
|
|
24
|
+
On the first run, `bc-pkg` resolves the ref to a full SHA and pins it. Later
|
|
25
|
+
runs omit `<owner/repo@ref>` and keep using the pinned SHA.
|
|
79
26
|
|
|
80
|
-
|
|
27
|
+
## Local repositories
|
|
81
28
|
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
| Windows | `%LOCALAPPDATA%` → `bc-pkg/` |
|
|
29
|
+
For live local development you can point `bc-pkg` at a local checkout of a
|
|
30
|
+
target package instead of a GitHub spec. The first argument is treated as a
|
|
31
|
+
local path when it starts with `/`, `./`, `../`, `~`, or is `.`/`..`:
|
|
86
32
|
|
|
87
|
-
|
|
33
|
+
```sh
|
|
34
|
+
npx bc-pkg ../once/typescript package build
|
|
35
|
+
npx bc-pkg /abs/path/to/once/clojure package build
|
|
36
|
+
```
|
|
88
37
|
|
|
89
|
-
|
|
38
|
+
Local targets are wired up **live** — your uncommitted edits in the local
|
|
39
|
+
package are picked up on the next run, with no SHA pinning and no push:
|
|
90
40
|
|
|
91
|
-
|
|
|
92
|
-
|
|
|
93
|
-
|
|
|
94
|
-
|
|
|
95
|
-
|
|
|
96
|
-
| `REWRITE_EDN_VERSION` | `0.5.9` | `borkdude/rewrite-edn` version used to edit the `bb.edn` |
|
|
41
|
+
| Target language | Local dependency |
|
|
42
|
+
| --- | --- |
|
|
43
|
+
| Clojure | `deps.edn` / `bb.edn` use `:local/root` |
|
|
44
|
+
| TypeScript | `package.json` uses a `file:` dependency |
|
|
45
|
+
| Python | `pyproject.toml` uses an editable `[tool.uv.sources]` path |
|
|
97
46
|
|
|
98
|
-
|
|
47
|
+
The `run` file is symlinked (not copied) so run-file edits are also live. Run
|
|
48
|
+
`bc-pkg` from a **separate** directory; pointing it at the current directory is
|
|
49
|
+
refused so it never overwrites the package's own manifest. Switching an
|
|
50
|
+
initialized directory between local and GitHub (or to a different local path) is
|
|
51
|
+
a hard error, just like a repo/ref/SHA mismatch.
|
|
99
52
|
|
|
100
|
-
|
|
53
|
+
Notes: TypeScript local dev requires the local package to be built (its
|
|
54
|
+
`dist/`); Python local dev installs the package editable and exposes its
|
|
55
|
+
`resources/` from the source tree.
|
|
101
56
|
|
|
102
|
-
|
|
57
|
+
## What is created
|
|
103
58
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
and musl.
|
|
107
|
-
- Extraction uses the system `tar` (present on macOS, Linux, and Windows
|
|
108
|
-
10+); Windows falls back to PowerShell `Expand-Archive` for `.zip` if `tar`
|
|
109
|
-
is unavailable.
|
|
59
|
+
The launcher copies the target package's root `run` file into the current
|
|
60
|
+
directory and writes language-native metadata:
|
|
110
61
|
|
|
111
|
-
|
|
62
|
+
| Target language | Manifest | Runtime command |
|
|
63
|
+
| --- | --- | --- |
|
|
64
|
+
| Clojure | `deps.edn` | `bb run ...` |
|
|
65
|
+
| TypeScript | `package.json` | `node run ...` |
|
|
66
|
+
| Python | `pyproject.toml` | `uv run python run ...` |
|
|
112
67
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
`bb.edn`. The image is based on Ubuntu 24.04 and installs Node.js, the pi
|
|
116
|
-
coding agent, Claude, `ripgrep`, `fd`, and `sudo`. Requires Docker. Commands
|
|
117
|
-
below assume `bb` is on `PATH`; use `node bin/bc-pkg.js <task>` to exercise the
|
|
118
|
-
local launcher instead.
|
|
68
|
+
For Clojure targets, a small `bb.edn` runtime dependency file is also written so
|
|
69
|
+
Babashka can load the pinned Git dependency.
|
|
119
70
|
|
|
120
|
-
If
|
|
121
|
-
|
|
122
|
-
downloaded into that directory from the same pinned GitHub SHA as the
|
|
123
|
-
bootstrapped `bb.edn`:
|
|
71
|
+
If the directory is already initialized for a different repo/ref/SHA, `bc-pkg`
|
|
72
|
+
exits with an error instead of updating it implicitly.
|
|
124
73
|
|
|
125
|
-
|
|
126
|
-
mkdir empty && cd empty
|
|
127
|
-
npx bc-pkg@latest bigconfig-ai/bc-pkg shell
|
|
128
|
-
```
|
|
74
|
+
## Requirements
|
|
129
75
|
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
bb shell --skip-build # reuse the existing image
|
|
136
|
-
```
|
|
76
|
+
- npm launcher: Node.js >= 18.
|
|
77
|
+
- TypeScript target packages: Node.js and npm must already be installed.
|
|
78
|
+
- Python target packages: Python and `uv` must already be installed.
|
|
79
|
+
- Clojure target packages: `bc-pkg` downloads pinned Babashka and Temurin JDK
|
|
80
|
+
versions into a shared user cache and checks/installs `git` on Linux.
|
|
137
81
|
|
|
138
|
-
|
|
139
|
-
mounts it at `/home/developer` in the container. Before starting Docker it
|
|
140
|
-
copies `~/.pi/agent/auth.json` and `~/.pi/agent/settings.json` into that
|
|
141
|
-
generated home when those files exist; missing files are skipped. Use
|
|
142
|
-
`--project-subdir PATH` to mount a specific host directory instead, and
|
|
143
|
-
`bb homes` / `bb clean --all` to list or remove generated homes.
|
|
144
|
-
|
|
145
|
-
Common options are available as flags or environment variables:
|
|
146
|
-
|
|
147
|
-
| Option / env | Default | Effect |
|
|
148
|
-
| ------------ | ------- | ------ |
|
|
149
|
-
| `--image` / `IMAGE` | `bc-pkg` | Docker image name |
|
|
150
|
-
| `--tag` / `TAG` | `dev` | Docker image tag |
|
|
151
|
-
| `--node-major` / `NODE_MAJOR` | `24` | Node.js major version build arg |
|
|
152
|
-
| `--no-cache` | `false` | Pass `--no-cache` to `docker build` |
|
|
153
|
-
| `--workdir` / `WORKDIR` | `/home/developer` | Container working directory |
|
|
154
|
-
| `--name` / `DOCKER_STYLE_RANDOM_NAME` | random | Container hostname and generated home name |
|
|
155
|
-
| `--project-subdir` / `PROJECT_SUBDIR` | `homes/<name>` | Host directory mounted into the container |
|
|
156
|
-
| `--docker-run-arg ARG` | _(none)_ | Extra `docker run` argument; repeat as needed |
|
|
157
|
-
| `--dry-run` | `false` | Print commands without executing them |
|
|
158
|
-
|
|
159
|
-
Run `bb options` for the full option list.
|
|
82
|
+
## Environment
|
|
160
83
|
|
|
161
|
-
|
|
84
|
+
| Variable | Effect |
|
|
85
|
+
| --- | --- |
|
|
86
|
+
| `GITHUB_TOKEN` | Used for private GitHub repos or higher API rate limits. |
|
|
87
|
+
| `BB_VERSION` | Override the Babashka version for Clojure targets. |
|
|
88
|
+
| `JDK_VERSION` | Override the Temurin JDK feature version for Clojure targets. |
|
|
89
|
+
|
|
90
|
+
## Cache
|
|
91
|
+
|
|
92
|
+
Babashka and JDK downloads are shared across projects under:
|
|
162
93
|
|
|
163
|
-
|
|
94
|
+
- macOS/Linux: `$XDG_CACHE_HOME/bc-pkg` or `~/.cache/bc-pkg`
|
|
95
|
+
- Windows: `%LOCALAPPDATA%/bc-pkg`
|