cloudflare-tunnel-kit 0.1.0 → 0.1.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 +128 -67
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,84 +1,78 @@
|
|
|
1
1
|
# cloudflare-tunnel-kit
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
An open-source toolkit for creating and integrating Cloudflare Tunnels through two simple interfaces: a command-line wizard and a local live UI. It replaces scattered shell scripts and Makefile targets with a validated, reviewable, and confirmation-based workflow.
|
|
4
4
|
|
|
5
5
|
## Current version
|
|
6
6
|
|
|
7
|
-
`0.1.0`
|
|
7
|
+
`0.1.0` is the current MVP and includes:
|
|
8
8
|
|
|
9
|
-
-
|
|
10
|
-
-
|
|
11
|
-
-
|
|
12
|
-
- Quick
|
|
13
|
-
-
|
|
14
|
-
- Dry-run, structured errors
|
|
15
|
-
- UI
|
|
9
|
+
- A reusable TypeScript API for validation, plan generation, execution, and redaction.
|
|
10
|
+
- The `cf-tunnel` CLI with `init`, `create`, `quick`, `start`, `stop`, `status`, `doctor`, and `ui` commands.
|
|
11
|
+
- `custom` and `laravel` project profiles.
|
|
12
|
+
- Quick Tunnel and named-tunnel command generation.
|
|
13
|
+
- URL, hostname, tunnel-name, and project-path validation.
|
|
14
|
+
- Dry-run mode, structured errors, remediation guidance, and copyable AI help prompts.
|
|
15
|
+
- A lightweight localhost UI with live plan preview and confirmation-token protection.
|
|
16
|
+
- Laravel detection and `APP_URL` proposal/diff with explicit confirmation.
|
|
16
17
|
|
|
17
|
-
Laravel `.env`
|
|
18
|
+
Laravel `.env` changes are never written silently. The current MVP presents the proposed diff and requires confirmation; automatic file mutation is intentionally not enabled yet.
|
|
18
19
|
|
|
19
|
-
##
|
|
20
|
+
## Design principles
|
|
20
21
|
|
|
21
|
-
|
|
22
|
+
The workflow is always:
|
|
22
23
|
|
|
23
|
-
|
|
24
|
+
```text
|
|
25
|
+
input -> detect -> validate -> preview plan -> confirm -> execute -> summary
|
|
26
|
+
```
|
|
24
27
|
|
|
25
|
-
|
|
28
|
+
The toolkit does not concatenate user input into shell commands, print secrets to logs, overwrite configuration silently, or send diagnostics to an external service.
|
|
26
29
|
|
|
27
|
-
|
|
28
|
-
- `cloudflared` trong `PATH` nếu muốn chạy tunnel thật.
|
|
29
|
-
- Quyền Cloudflare phù hợp với loại named tunnel.
|
|
30
|
+
## Requirements
|
|
30
31
|
|
|
31
|
-
|
|
32
|
+
- Node.js 20 or newer.
|
|
33
|
+
- `cloudflared` available in `PATH` when starting a real tunnel.
|
|
34
|
+
- Appropriate Cloudflare permissions for named tunnels.
|
|
32
35
|
|
|
33
|
-
|
|
36
|
+
## Installation
|
|
37
|
+
|
|
38
|
+
Install the package after it is published:
|
|
34
39
|
|
|
35
40
|
```bash
|
|
36
41
|
npm install --save-dev cloudflare-tunnel-kit
|
|
37
42
|
```
|
|
38
43
|
|
|
39
|
-
|
|
44
|
+
For a source checkout:
|
|
40
45
|
|
|
41
46
|
```bash
|
|
42
47
|
npm install
|
|
43
48
|
npm run build
|
|
44
|
-
node dist/cli/main.js --help
|
|
49
|
+
node ./dist/cli/main.js --help
|
|
45
50
|
```
|
|
46
51
|
|
|
47
|
-
##
|
|
52
|
+
## CLI usage
|
|
48
53
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
```bash
|
|
52
|
-
make setup
|
|
53
|
-
make help
|
|
54
|
-
make init
|
|
55
|
-
make ui
|
|
56
|
-
make quick URL=http://127.0.0.1:8000
|
|
57
|
-
make create NAME=law-firm URL=http://127.0.0.1:8000
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
`make quick` và `make create` mặc định chỉ preview (`--dry-run`). Sau khi review, dùng CLI trực tiếp để execute và xác nhận rõ ràng.
|
|
61
|
-
|
|
62
|
-
## CLI text-only
|
|
63
|
-
|
|
64
|
-
Kiểm tra môi trường:
|
|
54
|
+
Check the local environment:
|
|
65
55
|
|
|
66
56
|
```bash
|
|
67
57
|
cf-tunnel doctor
|
|
68
58
|
```
|
|
69
59
|
|
|
70
|
-
|
|
60
|
+
Run `cf-tunnel` or `cf-tunnel init` without options to start the interactive text-only wizard. It asks for each value, validates before execution, prints a command preview, and asks for confirmation.
|
|
71
61
|
|
|
72
|
-
Quick
|
|
62
|
+
Preview a Quick Tunnel without starting `cloudflared`:
|
|
73
63
|
|
|
74
64
|
```bash
|
|
75
65
|
cf-tunnel quick --url http://127.0.0.1:8000 --dry-run
|
|
76
66
|
```
|
|
77
67
|
|
|
78
|
-
|
|
68
|
+
Preview a named tunnel:
|
|
79
69
|
|
|
80
70
|
```bash
|
|
81
|
-
cf-tunnel create
|
|
71
|
+
cf-tunnel create \
|
|
72
|
+
--url http://127.0.0.1:8000 \
|
|
73
|
+
--name my-project \
|
|
74
|
+
--hostname tunnel.example.com \
|
|
75
|
+
--dry-run
|
|
82
76
|
```
|
|
83
77
|
|
|
84
78
|
Lifecycle commands:
|
|
@@ -87,22 +81,42 @@ Lifecycle commands:
|
|
|
87
81
|
cf-tunnel start --name my-project
|
|
88
82
|
cf-tunnel stop --name my-project
|
|
89
83
|
cf-tunnel status --name my-project
|
|
90
|
-
cf-tunnel init --profile custom --url http://127.0.0.1:8000 --dry-run
|
|
91
84
|
```
|
|
92
85
|
|
|
93
|
-
`--yes`
|
|
86
|
+
`--yes` does not bypass validation or Laravel `.env` confirmation.
|
|
87
|
+
|
|
88
|
+
## Makefile shortcuts
|
|
89
|
+
|
|
90
|
+
The repository includes a small Makefile for discoverable commands:
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
make setup
|
|
94
|
+
make help
|
|
95
|
+
make init
|
|
96
|
+
make ui
|
|
97
|
+
make quick URL=http://127.0.0.1:8000
|
|
98
|
+
make create NAME=law-firm URL=http://127.0.0.1:8000
|
|
99
|
+
make doctor
|
|
100
|
+
make test
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
`make quick` and `make create` use `--dry-run` by default. Review the plan, then use the CLI to execute and confirm the operation explicitly.
|
|
94
104
|
|
|
95
105
|
## Live UI
|
|
96
106
|
|
|
107
|
+
Start the local UI:
|
|
108
|
+
|
|
97
109
|
```bash
|
|
98
110
|
cf-tunnel ui
|
|
99
111
|
```
|
|
100
112
|
|
|
101
|
-
|
|
113
|
+
Open the URL printed in the terminal, usually `http://127.0.0.1:<port>`. The wizard includes profile selection, local URL input, tunnel name, validation, plan preview, confirmation, execution, and a button to copy a redacted AI-help prompt.
|
|
114
|
+
|
|
115
|
+
The UI binds to loopback by default and does not send the copied prompt anywhere.
|
|
102
116
|
|
|
103
117
|
## Custom profile
|
|
104
118
|
|
|
105
|
-
|
|
119
|
+
The custom profile makes no framework assumptions:
|
|
106
120
|
|
|
107
121
|
```bash
|
|
108
122
|
cf-tunnel quick --profile custom --url http://127.0.0.1:3000 --dry-run
|
|
@@ -111,57 +125,104 @@ cf-tunnel create --profile custom --url http://127.0.0.1:8000 --name billing --d
|
|
|
111
125
|
|
|
112
126
|
## Laravel profile
|
|
113
127
|
|
|
114
|
-
Laravel adapter
|
|
128
|
+
The Laravel adapter checks for `artisan` and Laravel evidence in `composer.json`. It can propose mappings such as `APP_URL`, `ASSET_URL`, and optional Reverb URLs.
|
|
129
|
+
|
|
130
|
+
Every mapping is shown as a diff and requires explicit confirmation. If `.env` is missing or ambiguous, the adapter stops with a remediation message instead of guessing.
|
|
115
131
|
|
|
116
132
|
```bash
|
|
117
|
-
cf-tunnel create
|
|
133
|
+
cf-tunnel create \
|
|
134
|
+
--profile laravel \
|
|
135
|
+
--url http://127.0.0.1:8000 \
|
|
136
|
+
--name law-firm \
|
|
137
|
+
--dry-run
|
|
118
138
|
```
|
|
119
139
|
|
|
120
140
|
## API
|
|
121
141
|
|
|
122
142
|
```ts
|
|
123
|
-
import {
|
|
143
|
+
import {
|
|
144
|
+
validateTunnelConfig,
|
|
145
|
+
createTunnelPlan,
|
|
146
|
+
executeTunnelPlan,
|
|
147
|
+
} from 'cloudflare-tunnel-kit';
|
|
148
|
+
|
|
149
|
+
const config = {
|
|
150
|
+
profile: 'custom',
|
|
151
|
+
operation: 'quick',
|
|
152
|
+
localUrl: 'http://127.0.0.1:8000',
|
|
153
|
+
};
|
|
124
154
|
|
|
125
|
-
const config = { profile: 'custom', operation: 'quick', localUrl: 'http://127.0.0.1:8000' };
|
|
126
155
|
const validation = validateTunnelConfig(config);
|
|
127
|
-
if (!validation.ok)
|
|
156
|
+
if (!validation.ok) {
|
|
157
|
+
for (const error of validation.issues) {
|
|
158
|
+
console.error(error.code, error.reason, error.fix);
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
|
|
128
162
|
const plan = createTunnelPlan(config);
|
|
129
163
|
const result = await executeTunnelPlan(plan, { dryRun: true });
|
|
130
164
|
console.log(result);
|
|
131
165
|
```
|
|
132
166
|
|
|
133
|
-
|
|
167
|
+
Plans are serializable and can be displayed inside another system. Execute only validated plans and provide the required confirmation groups.
|
|
134
168
|
|
|
135
169
|
## Error model
|
|
136
170
|
|
|
137
|
-
|
|
171
|
+
Every error includes a stable `code`, optional `field`, `reason`, and `fix`. Common codes include:
|
|
172
|
+
|
|
173
|
+
- `INPUT_INVALID_URL`: the local URL is not HTTP/HTTPS.
|
|
174
|
+
- `INPUT_INVALID_HOSTNAME`: the hostname is not valid.
|
|
175
|
+
- `INPUT_INVALID_TUNNEL_NAME`: the tunnel name is unsafe.
|
|
176
|
+
- `PATH_OUTSIDE_PROJECT`: the config path escapes the project root.
|
|
177
|
+
- `CONFIRMATION_REQUIRED`: a mutation has not been confirmed.
|
|
178
|
+
- `PROCESS_FAILED`: `cloudflared` failed or could not be started.
|
|
138
179
|
|
|
139
|
-
|
|
180
|
+
Review the redacted prompt before pasting it into an external AI service.
|
|
140
181
|
|
|
141
182
|
## Security model
|
|
142
183
|
|
|
143
|
-
- UI
|
|
144
|
-
-
|
|
145
|
-
- Secret-looking
|
|
146
|
-
- File
|
|
147
|
-
- Dry-run
|
|
148
|
-
-
|
|
149
|
-
-
|
|
184
|
+
- The UI binds to `127.0.0.1` by default.
|
|
185
|
+
- Child processes use argv arrays with shell execution disabled.
|
|
186
|
+
- Secret-looking keys/values, bearer tokens, and credential paths are redacted.
|
|
187
|
+
- File paths are checked against the project root.
|
|
188
|
+
- Dry-run does not start `cloudflared`.
|
|
189
|
+
- Configuration overwrite and Laravel `.env` changes require a visible plan and confirmation.
|
|
190
|
+
- No telemetry or diagnostics are sent externally.
|
|
191
|
+
|
|
192
|
+
This toolkit does not replace review of Cloudflare account permissions, DNS, access policies, or organizational secret management.
|
|
193
|
+
|
|
194
|
+
## Publishing to npm
|
|
195
|
+
|
|
196
|
+
After logging in to npm and completing any required 2FA verification:
|
|
150
197
|
|
|
151
|
-
|
|
198
|
+
```bash
|
|
199
|
+
npm install
|
|
200
|
+
npm run build
|
|
201
|
+
npm test
|
|
202
|
+
npm pack --dry-run
|
|
203
|
+
npm publish
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
Increase the version before publishing a new release:
|
|
152
207
|
|
|
153
|
-
|
|
208
|
+
```bash
|
|
209
|
+
npm version patch
|
|
210
|
+
npm publish
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
An already-published `name@version` cannot be published again. See the [npm publish documentation](https://docs.npmjs.com/cli/commands/npm-publish/).
|
|
214
|
+
|
|
215
|
+
## Development
|
|
154
216
|
|
|
155
217
|
```bash
|
|
218
|
+
npm install
|
|
156
219
|
npm test
|
|
157
220
|
npm run build
|
|
158
221
|
git diff --check
|
|
159
222
|
```
|
|
160
223
|
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
Test dùng Node built-ins và temporary fixtures; không cần Cloudflare account. Khi đóng góp, thêm test trước cho behavior mới và không đưa secret thật vào fixture.
|
|
224
|
+
Tests use Node built-ins and temporary fixtures; no Cloudflare account is required. Add tests before introducing new behavior, do not place real secrets in fixtures, and keep remediation messages actionable.
|
|
164
225
|
|
|
165
226
|
## License
|
|
166
227
|
|
|
167
|
-
MIT.
|
|
228
|
+
MIT. See [LICENSE](LICENSE).
|