ukacell 0.0.0-stage → 0.1.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.
Files changed (4) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +38 -2
  3. package/bin/cli.js +346 -0
  4. package/package.json +43 -4
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Ukacell contributors
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,3 +1,39 @@
1
- # Temporary Holding Version
1
+ # ukacell
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Prints a QR code for your local dev server so the **Ukacell** app can open
4
+ your Tauri v2 frontend on a phone, with 20 native plugins ready to call.
5
+
6
+ ```bash
7
+ npx ukacell # QR code for http://<your-lan-ip>:5173
8
+ npx ukacell 3000 # another port
9
+ npx ukacell --run # run `npm run dev -- --host` first, then show the QR code
10
+ ```
11
+
12
+ ## Options
13
+
14
+ | Option | Description |
15
+ | --- | --- |
16
+ | `[port]`, `-p, --port <port>` | Port of your dev server. Default `5173`. |
17
+ | `-r, --run` | Starts `npm run dev -- --host` in a child process, waits for the port to open, then prints the QR code. Ctrl+C stops both. |
18
+ | `--host <ip>` | Use this address instead of the detected LAN IPv4. |
19
+ | `-- <args>` | With `--run`, extra arguments for your dev script, for example `npx ukacell 3000 --run -- --port 3000`. |
20
+ | `-v, --version` | Print the version. |
21
+ | `-h, --help` | Show help. |
22
+
23
+ ## How the address is picked
24
+
25
+ ukacell lists every non-internal IPv4 interface and ranks them: private
26
+ ranges first (`192.168.x.x`, `10.x.x.x`, `172.16-31.x.x`, the ones the Ukacell
27
+ host trusts), physical Wi-Fi/Ethernet adapters above
28
+ virtual ones (WSL, Hyper-V, Docker, VirtualBox, VPNs). The best match goes in
29
+ the QR code and up to three alternatives are printed below it. If the wrong
30
+ one wins, pass `--host`.
31
+
32
+ ## Dev server checklist
33
+
34
+ - Listen on all interfaces, not just localhost: `vite --host`,
35
+ `next dev -H 0.0.0.0`, and so on. `--run` adds `--host` for you.
36
+ - Phone and computer on the same Wi-Fi.
37
+ - Allow the port through your computer's firewall.
38
+
39
+ Requires Node.js 18.18 or newer. MIT licensed.
package/bin/cli.js ADDED
@@ -0,0 +1,346 @@
1
+ #!/usr/bin/env node
2
+ // ukacell: print a QR code for your LAN dev server so the Ukacell host app
3
+ // on your phone can open it.
4
+ //
5
+ // npx ukacell # http://<lan-ip>:5173
6
+ // npx ukacell 3000 # custom port
7
+ // npx ukacell --port 3000
8
+ // npx ukacell --run # also runs `npm run dev -- --host`
9
+ // npx ukacell --run -- --mode staging # extra args for the dev script
10
+
11
+ import { spawn } from "node:child_process";
12
+ import { existsSync, readFileSync } from "node:fs";
13
+ import net from "node:net";
14
+ import os from "node:os";
15
+ import { join } from "node:path";
16
+ import process from "node:process";
17
+
18
+ import pc from "picocolors";
19
+ import qrcode from "qrcode-terminal";
20
+
21
+ const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
22
+
23
+ const DEFAULT_PORT = 5173;
24
+ const DEV_SERVER_WAIT_MS = 90_000;
25
+ const PORT_POLL_MS = 400;
26
+
27
+ // Interfaces that are almost never the phone-facing Wi-Fi/LAN adapter.
28
+ const VIRTUAL_INTERFACE =
29
+ /(vethernet|virtualbox|vmware|vbox|docker|podman|br-|veth|virbr|wsl|hyper-v|loopback|utun|tailscale|zerotier|wireguard|^wg\d|^tun|^tap|vpn|hamachi|awdl|llw|bridge)/i;
30
+ const PHYSICAL_INTERFACE = /^(wi-?fi|wlan|wlp|wl|en|eth|ethernet)/i;
31
+
32
+ class UsageError extends Error {}
33
+
34
+ /* Arguments ---------------------------------------------------------------- */
35
+
36
+ const HELP = `
37
+ ${pc.bold("ukacell")} ${pc.dim(`v${pkg.version}`)}: open your Tauri v2 frontend in the Ukacell app
38
+
39
+ ${pc.bold("Usage")}
40
+ npx ukacell [port] [options] [-- <dev script args>]
41
+
42
+ ${pc.bold("Options")}
43
+ -p, --port <port> Port of your dev server (default ${DEFAULT_PORT})
44
+ -r, --run Start the dev server with ${pc.cyan("npm run dev -- --host")}
45
+ --host <ip> Use this address instead of the detected LAN IPv4
46
+ -v, --version Print the version
47
+ -h, --help Show this help
48
+
49
+ ${pc.bold("Examples")}
50
+ npx ukacell QR code for http://<lan-ip>:5173
51
+ npx ukacell 3000 QR code for port 3000
52
+ npx ukacell --run run the dev server, then show the QR code
53
+ npx ukacell 3000 --run -- --port 3000
54
+ run the dev server on port 3000 (args after
55
+ -- go to the dev script; Vite syntax shown)
56
+ `;
57
+
58
+ function parsePort(value, flag) {
59
+ if (value === undefined || value === "") {
60
+ throw new UsageError(`${flag} needs a value, for example ${flag} 5173`);
61
+ }
62
+ if (!/^\d+$/.test(value)) {
63
+ throw new UsageError(`"${value}" is not a valid port number`);
64
+ }
65
+ const port = Number(value);
66
+ if (port < 1 || port > 65535) {
67
+ throw new UsageError(`Port ${port} is out of range (1-65535)`);
68
+ }
69
+ return port;
70
+ }
71
+
72
+ function requireValue(value, flag) {
73
+ if (value === undefined || value === "" || value.startsWith("-")) {
74
+ throw new UsageError(`${flag} needs a value`);
75
+ }
76
+ return value;
77
+ }
78
+
79
+ function parseArgs(argv) {
80
+ const options = {
81
+ port: DEFAULT_PORT,
82
+ run: false,
83
+ host: null,
84
+ help: false,
85
+ version: false,
86
+ devArgs: [],
87
+ };
88
+ let positionalPortSeen = false;
89
+
90
+ for (let i = 0; i < argv.length; i += 1) {
91
+ const arg = argv[i];
92
+ if (arg === "--") {
93
+ options.devArgs = argv.slice(i + 1);
94
+ break;
95
+ } else if (arg === "-h" || arg === "--help") {
96
+ options.help = true;
97
+ } else if (arg === "-v" || arg === "--version") {
98
+ options.version = true;
99
+ } else if (arg === "-r" || arg === "--run") {
100
+ options.run = true;
101
+ } else if (arg === "-p" || arg === "--port") {
102
+ options.port = parsePort(argv[i + 1], arg);
103
+ i += 1;
104
+ } else if (arg.startsWith("--port=")) {
105
+ options.port = parsePort(arg.slice("--port=".length), "--port");
106
+ } else if (arg === "--host") {
107
+ options.host = requireValue(argv[i + 1], arg);
108
+ i += 1;
109
+ } else if (arg.startsWith("--host=")) {
110
+ options.host = requireValue(arg.slice("--host=".length), "--host");
111
+ } else if (/^\d+$/.test(arg) && !positionalPortSeen) {
112
+ options.port = parsePort(arg, "port");
113
+ positionalPortSeen = true;
114
+ } else {
115
+ throw new UsageError(`Unknown argument: ${arg}`);
116
+ }
117
+ }
118
+ return options;
119
+ }
120
+
121
+ /* Network ------------------------------------------------------------------ */
122
+
123
+ function isPrivateIPv4(address) {
124
+ const [a, b] = address.split(".").map(Number);
125
+ return a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168);
126
+ }
127
+
128
+ // Mirrors `remote.urls` in apps/host/src-tauri/capabilities/remote-dev.json:
129
+ // every private IPv4 range (192.168/16, 10/8, 172.16/12).
130
+ function isTrustedByHost(address) {
131
+ return /^(?:192\.168|10\.\d{1,3}|172\.(?:1[6-9]|2\d|3[01]))\.\d{1,3}\.\d{1,3}$/.test(address);
132
+ }
133
+
134
+ function scoreInterface(name, address) {
135
+ let score = 0;
136
+ if (isPrivateIPv4(address)) score += 10;
137
+ if (isTrustedByHost(address)) score += 5;
138
+ if (address.startsWith("192.168.")) score += 1;
139
+ if (PHYSICAL_INTERFACE.test(name)) score += 3;
140
+ if (VIRTUAL_INTERFACE.test(name)) score -= 30;
141
+ return score;
142
+ }
143
+
144
+ function lanAddresses() {
145
+ const found = [];
146
+ for (const [name, entries] of Object.entries(os.networkInterfaces())) {
147
+ for (const entry of entries ?? []) {
148
+ // Node 18.0-18.3 reported `family` as the number 4.
149
+ const isIPv4 = entry.family === "IPv4" || entry.family === 4;
150
+ if (!isIPv4 || entry.internal || entry.address.startsWith("169.254.")) continue;
151
+ found.push({ name, address: entry.address, score: scoreInterface(name, entry.address) });
152
+ }
153
+ }
154
+ return found.sort((a, b) => b.score - a.score);
155
+ }
156
+
157
+ function canConnect(port, host, timeoutMs) {
158
+ return new Promise((resolve) => {
159
+ const socket = net.connect({ port, host });
160
+ const done = (result) => {
161
+ socket.destroy();
162
+ resolve(result);
163
+ };
164
+ socket.setTimeout(timeoutMs, () => done(false));
165
+ socket.once("connect", () => done(true));
166
+ socket.once("error", () => done(false));
167
+ });
168
+ }
169
+
170
+ async function isListening(port, lanHost) {
171
+ for (const host of [lanHost, "127.0.0.1", "::1"]) {
172
+ if (host && (await canConnect(port, host, 700))) return true;
173
+ }
174
+ return false;
175
+ }
176
+
177
+ async function waitForPort(port, lanHost, timeoutMs, shouldStop) {
178
+ const deadline = Date.now() + timeoutMs;
179
+ while (Date.now() < deadline) {
180
+ if (shouldStop()) return false;
181
+ if (await isListening(port, lanHost)) return true;
182
+ await new Promise((resolve) => setTimeout(resolve, PORT_POLL_MS));
183
+ }
184
+ return false;
185
+ }
186
+
187
+ /* Output ------------------------------------------------------------------- */
188
+
189
+ function renderQr(text) {
190
+ return new Promise((resolve) => {
191
+ qrcode.generate(text, { small: true }, (code) => resolve(code));
192
+ });
193
+ }
194
+
195
+ function indent(text, spaces = 2) {
196
+ const pad = " ".repeat(spaces);
197
+ return text
198
+ .split("\n")
199
+ .map((line) => (line ? pad + line : line))
200
+ .join("\n");
201
+ }
202
+
203
+ async function printBanner({ url, port, chosen, others, listening }) {
204
+ const lines = [
205
+ "",
206
+ ` ${pc.bgCyan(pc.black(pc.bold(" ukacell ")))} ${pc.dim(`v${pkg.version}`)}`,
207
+ "",
208
+ ` ${pc.dim("Local: ")} ${pc.cyan(`http://localhost:${port}`)}`,
209
+ ` ${pc.dim("Network:")} ${pc.bold(pc.cyan(url))}${chosen ? pc.dim(` (${chosen})`) : ""}`,
210
+ ];
211
+ for (const other of others) {
212
+ lines.push(` ${pc.dim(" ")} ${pc.dim(`http://${other.address}:${port} (${other.name})`)}`);
213
+ }
214
+ lines.push("", ` Scan with the ${pc.bold("Ukacell")} app:`, "");
215
+ console.log(lines.join("\n"));
216
+ console.log(indent(await renderQr(url)));
217
+
218
+ const notes = [` ${pc.dim("Phone and computer must be on the same Wi-Fi network.")}`];
219
+ if (!listening) {
220
+ notes.push(
221
+ ` ${pc.yellow("!")} Nothing is answering on port ${port} yet. Start your dev server with`,
222
+ ` ${pc.cyan("npm run dev -- --host")} or let ukacell do it: ${pc.cyan("npx ukacell --run")}`
223
+ );
224
+ }
225
+ const host = new URL(url).hostname;
226
+ if (host !== "localhost" && host !== "127.0.0.1" && !isTrustedByHost(host)) {
227
+ notes.push(
228
+ ` ${pc.yellow("!")} ${host} is not a private LAN address, which the Ukacell host requires.`,
229
+ " The page will load, but native plugin calls will be rejected."
230
+ );
231
+ }
232
+ console.log(notes.join("\n") + "\n");
233
+ }
234
+
235
+ /* Dev server --------------------------------------------------------------- */
236
+
237
+ function quoteForCmd(arg) {
238
+ return /[\s"&|<>^]/.test(arg) ? `"${arg.replace(/"/g, '\\"')}"` : arg;
239
+ }
240
+
241
+ function startDevServer(extraArgs) {
242
+ const packageJson = join(process.cwd(), "package.json");
243
+ if (!existsSync(packageJson)) {
244
+ throw new UsageError(`--run needs a package.json in ${process.cwd()}`);
245
+ }
246
+ const scripts = JSON.parse(readFileSync(packageJson, "utf8")).scripts ?? {};
247
+ if (!scripts.dev) {
248
+ throw new UsageError(`--run needs a "dev" script in ${packageJson}`);
249
+ }
250
+
251
+ const args = ["run", "dev", "--", "--host", ...extraArgs];
252
+ console.log(pc.dim(`\n > npm ${args.join(" ")}\n`));
253
+
254
+ // npm is a .cmd shim on Windows, which Node only runs through a shell.
255
+ return process.platform === "win32"
256
+ ? spawn(["npm", ...args].map(quoteForCmd).join(" "), { stdio: "inherit", shell: true })
257
+ : spawn("npm", args, { stdio: "inherit" });
258
+ }
259
+
260
+ /* Main --------------------------------------------------------------------- */
261
+
262
+ async function main() {
263
+ const options = parseArgs(process.argv.slice(2));
264
+
265
+ if (options.help) {
266
+ console.log(HELP);
267
+ return;
268
+ }
269
+ if (options.version) {
270
+ console.log(pkg.version);
271
+ return;
272
+ }
273
+
274
+ const candidates = lanAddresses();
275
+ let chosen;
276
+ if (options.host) {
277
+ chosen = { name: "--host", address: options.host };
278
+ } else if (candidates.length > 0) {
279
+ chosen = candidates[0];
280
+ } else {
281
+ console.error(
282
+ `\n ${pc.red("✖")} No LAN IPv4 address found. Connect this computer to Wi-Fi or Ethernet,` +
283
+ `\n or pass one explicitly: ${pc.cyan("npx ukacell --host 192.168.1.20")}\n`
284
+ );
285
+ process.exitCode = 1;
286
+ return;
287
+ }
288
+
289
+ const url = `http://${chosen.address}:${options.port}`;
290
+ const others = options.host ? [] : candidates.slice(1, 4);
291
+
292
+ if (!options.run) {
293
+ const listening = await isListening(options.port, chosen.address);
294
+ await printBanner({ url, port: options.port, chosen: chosen.name, others, listening });
295
+ return;
296
+ }
297
+
298
+ const child = startDevServer(options.devArgs);
299
+ let childExited = false;
300
+ let interrupted = false;
301
+
302
+ child.on("error", (error) => {
303
+ console.error(`\n ${pc.red("✖")} Could not start the dev server: ${error.message}\n`);
304
+ process.exit(1);
305
+ });
306
+ child.on("exit", (code, signal) => {
307
+ childExited = true;
308
+ process.exit(code ?? (signal ? 1 : 0));
309
+ });
310
+
311
+ // Ctrl+C (SIGINT) already reaches the dev server through the shared
312
+ // terminal, so just wait for it to shut down cleanly. SIGTERM is only sent
313
+ // to ukacell, so pass it on. A second signal forces ukacell out.
314
+ for (const signal of ["SIGINT", "SIGTERM"]) {
315
+ process.on(signal, () => {
316
+ if (interrupted) process.exit(130);
317
+ interrupted = true;
318
+ if (signal === "SIGTERM" && !childExited) child.kill(signal);
319
+ });
320
+ }
321
+
322
+ const ready = await waitForPort(
323
+ options.port,
324
+ chosen.address,
325
+ DEV_SERVER_WAIT_MS,
326
+ () => childExited || interrupted
327
+ );
328
+ if (childExited || interrupted) return;
329
+
330
+ if (!ready) {
331
+ console.log(
332
+ `\n ${pc.yellow("!")} The dev server did not open port ${options.port} within ` +
333
+ `${DEV_SERVER_WAIT_MS / 1000}s. If it picked another port, run ukacell with --port.`
334
+ );
335
+ }
336
+ await printBanner({ url, port: options.port, chosen: chosen.name, others, listening: ready });
337
+ }
338
+
339
+ main().catch((error) => {
340
+ if (error instanceof UsageError) {
341
+ console.error(`\n ${pc.red("✖")} ${error.message}\n Run ${pc.cyan("npx ukacell --help")} for usage.\n`);
342
+ } else {
343
+ console.error(error);
344
+ }
345
+ process.exit(1);
346
+ });
package/package.json CHANGED
@@ -1,6 +1,45 @@
1
1
  {
2
2
  "name": "ukacell",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Show a QR code for your local dev server so the Ukacell host app can open your Tauri v2 frontend on a phone.",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "bin": {
8
+ "ukacell": "bin/cli.js"
9
+ },
10
+ "files": [
11
+ "bin",
12
+ "README.md",
13
+ "LICENSE"
14
+ ],
15
+ "engines": {
16
+ "node": ">=18.18"
17
+ },
18
+ "keywords": [
19
+ "tauri",
20
+ "tauri-v2",
21
+ "mobile",
22
+ "android",
23
+ "ios",
24
+ "qr",
25
+ "dev-server",
26
+ "hot-reload"
27
+ ],
28
+ "homepage": "https://github.com/urukaa/ukacell/tree/main/packages/cli#readme",
29
+ "repository": {
30
+ "type": "git",
31
+ "url": "git+https://github.com/urukaa/ukacell.git",
32
+ "directory": "packages/cli"
33
+ },
34
+ "bugs": {
35
+ "url": "https://github.com/urukaa/ukacell/issues"
36
+ },
37
+ "scripts": {
38
+ "start": "node bin/cli.js",
39
+ "check": "node --check bin/cli.js && node bin/cli.js --help"
40
+ },
41
+ "dependencies": {
42
+ "picocolors": "^1.1.1",
43
+ "qrcode-terminal": "^0.12.0"
44
+ }
45
+ }