@n-dream/builders-cli 0.2.4 → 1.0.0-next.0

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,89 +1,41 @@
1
1
  # @n-dream/builders-cli
2
2
 
3
- The command line helper of Builders for coding agent sessions.
4
-
5
- ## Dev preview tunnel
6
-
7
- The tunnel makes the dev server of a coding session visible at the app's
8
- dev preview address (`https://d--<app>.<company>.builders.n-dream.com`).
9
- Only the person who opened the app sees it.
10
-
11
- ```
12
- BUILDERS_TUNNEL_TOKEN_FILE=<file> BUILDERS_TUNNEL_URL=<url> npx -y @n-dream/builders-cli tunnel --port 3000
13
- ```
14
-
15
- The Builders MCP tool `open_app` writes the token file and gives the URL
16
- and the full command. The token is short-lived and is for one app and one
17
- person. Do not share it. The command reads the file again before each
18
- connection, so a new token from `open_app` takes effect without a restart.
19
- `BUILDERS_TUNNEL_TOKEN` (the token itself) also works, but never put the
20
- token in an argument: other processes can read arguments.
21
-
22
- Options:
23
-
24
- - `--port <port>`: the port of the local dev server (required).
25
- - `--url <url>`: the tunnel URL, if `BUILDERS_TUNNEL_URL` is not set.
26
- - `--token-file <file>`: the token file, if `BUILDERS_TUNNEL_TOKEN_FILE` is
27
- not set.
28
- - `--transport auto|ws|poll`: `auto` (default) uses a WebSocket and falls
29
- back to HTTPS polling when a proxy does not let WebSockets through.
30
-
31
- The command writes one line per change of state, for example:
32
-
33
- ```
34
- builders-cli: connected: dev preview at https://d--todo.internal.builders.n-dream.com (local port 3000)
3
+ The Builders command line (design 4.4). Claude runs it with `npx` in a
4
+ Claude Code session; the person never runs it.
5
+
6
+ | Command | What it does |
7
+ |---|---|
8
+ | `login --portal <https://PORTAL_HOST> --code <code>` | Swaps the one-time code from the MCP tool `open_app` for a CLI token (one app, one work branch, 24 hours). Keeps it in `~/.config/builders/credentials.json` (mode 600). |
9
+ | `git-credential --app <appId> --work <workId> get` | git's credential helper for the Builders git address. `open_app` sets it in the repo's git config. |
10
+ | `preview` | Builds (`npm run build`), checks the file rules, scans the source and the output for keys (gitleaks), uploads the files that the app does not have (8 at a time, with retries) and overwrites the app's preview. Prints `Preview: <address>`. |
11
+ | `save --title '<title>'` | The same as a new numbered version, from a clean work tree whose `HEAD` is pushed to the work branch. Prints `Version <n> (<state>): <address>`. |
12
+ | `status` | The app, the preview, the live version and the newest versions. |
13
+ | `doctor` | Checks Node.js, git, the proxy, the network, the CLI version, the token and `build.json`. One line per problem, with the fix. |
14
+
15
+ The secret scan uses gitleaks at the version that core pins
16
+ (`packages/core/src/gitleaks.json`). The CLI downloads it once from
17
+ `https://<PORTAL_HOST>/tools/gitleaks/<version>/<os>-<arch>` (the one
18
+ domain a session reaches), checks its SHA-256 against the pin, and keeps
19
+ it in `~/.cache/builders` (`BUILDERS_CACHE_DIR`). Only the sure rules
20
+ count; `generic-api-key` is dropped (L6). `.gitleaksignore` and
21
+ `gitleaks:allow` have no effect. A finding names the file, the line and
22
+ the rule, never the value.
23
+
24
+ `scripts/fetch-gitleaks.ts` gets the pinned release from GitHub, checks
25
+ both hashes and writes the gzipped binaries (the api image runs it).
26
+
27
+ The CLI uses `HTTPS_PROXY` and `NO_PROXY`. It asks the API for the lowest
28
+ version that it accepts, and an older CLI stops with the command to run.
29
+ It starts no process that runs after the command ends.
30
+
31
+ `BUILDERS_CONFIG_DIR` changes the config folder (tests).
32
+ `BUILDERS_CACHE_DIR` changes the cache folder of the scanner.
33
+
34
+ ## Build
35
+
36
+ ```sh
37
+ pnpm --filter @n-dream/builders-cli build # dist/builders-cli.cjs, all dependencies bundled
35
38
  ```
36
39
 
37
- When `HTTPS_PROXY` (or `https_proxy`) is set, as in claude.ai/code
38
- sessions, the command connects through that proxy. `NO_PROXY` hosts go
39
- direct. The connection to the local dev server never uses the proxy.
40
-
41
- It connects again by itself when the connection breaks. It stops when the
42
- token is not valid, or when a newer tunnel for the same work takes over.
43
-
44
- ## Dev server and test data (`--dev`)
45
-
46
- With `--dev`, the command also runs the app's dev server
47
- (`pnpm dev --port <port>`) in the current folder, and starts it again
48
- when it stops. It also runs the Firebase emulators (Firestore and
49
- Storage) for the app's test data:
50
-
51
- - They need Java 21 or later. Without it, the command tells you what to
52
- install, and the app shows the same message.
53
- - The first start installs firebase-tools in `~/.builders/firebase-tools/`
54
- and takes about 30 seconds. The package has a lock file for it: every
55
- package has a fixed version and checksum, and no install script runs.
56
- Later starts take about 15 seconds.
57
- - The data is in `.builders-dev/emulators/` in the app folder. Git does
58
- not see it. The command saves it every 30 seconds and when it stops,
59
- and loads it at the next start. If the machine stops hard, the changes
60
- of the last 30 seconds can be lost. If the emulators cannot load the
61
- saved data (3 failed starts, a start without it works, and one more
62
- start with it fails), they start empty, and the old data stays in
63
- `.builders-dev/emulators/export-bad-<time>/`.
64
- - The emulator files (about 180 MB) download once per machine, before
65
- the first start.
66
- - The dev server gets `FIRESTORE_EMULATOR_HOST`,
67
- `FIREBASE_STORAGE_EMULATOR_HOST`, `STORAGE_EMULATOR_HOST`,
68
- `GOOGLE_CLOUD_PROJECT` (`demo-builders`, no Google credentials needed)
69
- and, with the storage add-on, `STORAGE_BUCKET`.
70
- - Emulators that an earlier run left behind are stopped at the next
71
- start, after their data is saved.
72
- - When an emulator does not answer two checks in a row (30 seconds
73
- apart), the command starts the emulators again.
74
-
75
- ## Keep the preview awake
76
-
77
- ```
78
- npx -y @n-dream/builders-cli awake --token-file <file> [--again] [--idle-minutes 15] [--max-minutes 25]
79
- ```
80
-
81
- A cloud session of a coding agent pauses after a few minutes without
82
- activity, and the dev preview stops with it. The agent runs this command
83
- in the background at the end of each answer (`open_app` gives it as
84
- `keepAwake`). It waits until nobody used the preview or wrote for 15
85
- minutes, and then ends with `idle`. After 25 minutes it ends with `in use`,
86
- and the agent starts it again with `--again` (not a new message). Only one
87
- runs per preview.
88
-
89
- Node.js 20.18.1 or later. No runtime dependencies (all are bundled).
40
+ The owner publishes it with the npm dist-tag `next` (Q29). Nothing here
41
+ publishes.