@dbx-tools/cli-service 0.9.38 → 0.9.40

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 (5) hide show
  1. package/README.md +119 -55
  2. package/index.ts +1 -1
  3. package/lib/index.d.ts +1 -1
  4. package/lib/index.js +2 -2
  5. package/package.json +2 -2
package/README.md CHANGED
@@ -1,27 +1,12 @@
1
1
  # @dbx-tools/cli-service
2
2
 
3
- Product-agnostic system-tray service lifecycle for Node and Bun CLIs. A
4
- consuming Commander program gets `service install`, `start`, `stop`, `restart`,
5
- `status`, and `uninstall` commands from one typed definition.
3
+ Add desktop-service installation, lifecycle commands, and a tray menu to a
4
+ Commander CLI. Users can keep your command running after their terminal closes
5
+ and manage it through the same `service` commands on macOS, Linux, and Windows.
6
6
 
7
- This is the shared owner for current-user CLI services. Product CLIs should
8
- provide a service definition and reuse this lifecycle instead of implementing
9
- their own installers, startup registration, tray host, runtime layout, or
10
- control channel.
11
-
12
- The resident `systray2` host can manage a foreground command and display a
13
- system tray icon. Its default menu contains:
14
-
15
- - `<program name> - <version>`
16
- - `Quit`
17
-
18
- Custom menu items can open an external URL, run a command, or add a separator.
19
-
20
- ## Usage
7
+ ## Add Service Commands
21
8
 
22
9
  ```ts
23
- import { fileURLToPath } from "node:url";
24
-
25
10
  import { buildServiceCommand } from "@dbx-tools/cli-service/cli";
26
11
  import { defineService } from "@dbx-tools/cli-service/definition";
27
12
  import { Command } from "commander";
@@ -30,44 +15,123 @@ const program = new Command("example");
30
15
  program.addCommand(
31
16
  buildServiceCommand(
32
17
  defineService(import.meta.url, {
33
- icon: fileURLToPath(new URL("../assets/icon.png", import.meta.url)),
34
- command: {
35
- arguments: ["serve"],
36
- },
37
- menu: [
38
- {
39
- type: "url",
40
- label: "Models",
41
- url: "http://127.0.0.1:4400/v1/models",
42
- },
43
- ],
18
+ command: { arguments: ["serve"] },
19
+ menu: [{ type: "url", label: "Open App", url: "http://127.0.0.1:4400" }],
44
20
  }),
45
21
  ),
46
22
  );
23
+ await program.parseAsync(process.argv);
24
+ ```
25
+
26
+ `defineService` uses the owning package's name, version, and default executable.
27
+ Use `command.binName` when the package has multiple executable entries. Set
28
+ `command.executable` to run an existing external program instead of compiling a
29
+ package entrypoint.
30
+
31
+ ## Install And Manage The Service
32
+
33
+ For the example program above:
34
+
35
+ ```sh
36
+ example service install
37
+ example service status
38
+ example service stop
39
+ example service start
40
+ example service restart
41
+ example service uninstall
42
+ ```
43
+
44
+ Installation starts the service by default. Pass `--no-start` to install without
45
+ launching it. `status` reports installation and process state as JSON.
46
+
47
+ The service belongs to the current user. Login startup uses a LaunchAgent on
48
+ macOS, an XDG autostart entry on Linux, and a Startup command on Windows. Package
49
+ entrypoints are compiled with Bun into `~/.dbx-tools/bin`.
50
+
51
+ `restart` stops and starts the installed executable; it does not rebuild it.
52
+ Re-run `install` after upgrading a consuming package to replace compiled
53
+ executables and update the saved configuration.
54
+
55
+ ## Customize The Tray Menu
56
+
57
+ The default tray menu shows the program name and version and offers `Quit`.
58
+ Add URL, command, or separator items through the service definition. Custom
59
+ command items can select a package binary or an external executable just like
60
+ the main service command.
61
+
62
+ Use this package when adding service support to another CLI so users get the
63
+ same installation, lifecycle commands, and tray behavior. The generated
64
+ reference uses `<cli>` as a placeholder for the consuming program's name.
65
+
66
+ <!-- cli-reference:start -->
67
+
68
+ ## Command Reference
69
+
70
+ ### `<cli> service`
71
+
72
+ ```text
73
+ Usage: <cli> service [command]
74
+
75
+ Install and manage the desktop service
76
+
77
+ Commands:
78
+ install [options] Install the service for the current user and start it
79
+ start Start the installed service
80
+ stop Stop the running service
81
+ restart Restart the installed service
82
+ status Print service installation and process state as JSON
83
+ uninstall Stop and remove the service for the current user
84
+ ```
85
+
86
+ ### `<cli> service install`
87
+
88
+ ```text
89
+ Usage: <cli> service install [options]
90
+
91
+ Install the service for the current user and start it
92
+
93
+ Options:
94
+ --no-start install without starting the service
95
+ ```
96
+
97
+ ### `<cli> service start`
98
+
99
+ ```text
100
+ Usage: <cli> service start
101
+
102
+ Start the installed service
103
+ ```
104
+
105
+ ### `<cli> service stop`
106
+
107
+ ```text
108
+ Usage: <cli> service stop
109
+
110
+ Stop the running service
111
+ ```
112
+
113
+ ### `<cli> service restart`
114
+
115
+ ```text
116
+ Usage: <cli> service restart
117
+
118
+ Restart the installed service
119
+ ```
120
+
121
+ ### `<cli> service status`
122
+
123
+ ```text
124
+ Usage: <cli> service status
125
+
126
+ Print service installation and process state as JSON
127
+ ```
128
+
129
+ ### `<cli> service uninstall`
130
+
131
+ ```text
132
+ Usage: <cli> service uninstall
133
+
134
+ Stop and remove the service for the current user
47
135
  ```
48
136
 
49
- `defineService()` accepts an owning module's `import.meta.url` or a package name.
50
- It derives package name, version, service ID, display name, and a single default
51
- bin from the package manifest. Package names resolve from installed packages
52
- first and then from current monorepo workspace manifests. Override `version`,
53
- `id`, `name`, or `command.binName` only when those defaults are not appropriate.
54
-
55
- `service install` uses the package's Bun dependency to compile the tray host and
56
- each package bin or explicit command entrypoint. Standalone executables are
57
- installed under `~/.dbx-tools/bin` through `@dbx-tools/core/bin`. Direct
58
- third-party package dependencies are derived from the owner manifest and
59
- installed under `~/.dbx-tools/node_modules`; callers do not maintain an external
60
- package list. systray2's native helper is installed under
61
- `~/.dbx-tools/bin/traybin`. Startup therefore does not require a globally
62
- installed Node or Bun runtime. Set `command.executable` only for an already-built
63
- external program that should not be compiled.
64
-
65
- macOS installs a per-user LaunchAgent, Linux installs an XDG autostart desktop
66
- entry, and Windows installs a current-user Startup command. Start, stop, and
67
- status use a local socket or named pipe rather than process-name matching.
68
-
69
- ## Publication
70
-
71
- This package is public because generated package output is compiled with `tsc`,
72
- not bundled into consuming CLIs. A private workspace package would leave a
73
- published CLI with an unavailable runtime dependency.
137
+ <!-- cli-reference:end -->
package/index.ts CHANGED
@@ -3,7 +3,7 @@
3
3
  // Hand edits are overwritten on the next watch; this file is read-only.
4
4
 
5
5
  export const PACKAGE_IDENTIFIER = "@dbx-tools/cli-service";
6
- export const PACKAGE_VERSION = "0.9.38";
6
+ export const PACKAGE_VERSION = "0.9.40";
7
7
  export * as cli from "./src/cli.ts";
8
8
  export * as definition from "./src/definition.ts";
9
9
  export * as icon from "./src/icon.ts";
package/lib/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  export declare const PACKAGE_IDENTIFIER = "@dbx-tools/cli-service";
2
- export declare const PACKAGE_VERSION = "0.9.38";
2
+ export declare const PACKAGE_VERSION = "0.9.40";
3
3
  export * as cli from "./src/cli.ts";
4
4
  export * as definition from "./src/definition.ts";
5
5
  export * as icon from "./src/icon.ts";
package/lib/index.js CHANGED
@@ -2,11 +2,11 @@
2
2
  // Regenerated from the exporting modules in ./src.
3
3
  // Hand edits are overwritten on the next watch; this file is read-only.
4
4
  export const PACKAGE_IDENTIFIER = "@dbx-tools/cli-service";
5
- export const PACKAGE_VERSION = "0.9.38";
5
+ export const PACKAGE_VERSION = "0.9.40";
6
6
  export * as cli from "./src/cli.js";
7
7
  export * as definition from "./src/definition.js";
8
8
  export * as icon from "./src/icon.js";
9
9
  export * as service from "./src/service.js";
10
10
  export { CliServiceCommandSchema, CliServiceMenuItemSchema, CliServiceDefinitionSchema } from "./src/definition.js";
11
11
  export { CliService } from "./src/service.js";
12
- //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxNQUFNLENBQUMsTUFBTSxrQkFBa0IsR0FBRyx3QkFBd0IsQ0FBQztBQUMzRCxNQUFNLENBQUMsTUFBTSxlQUFlLEdBQUcsUUFBUSxDQUFDO0FBQ3hDLE9BQU8sS0FBSyxHQUFHLE1BQU0sY0FBYyxDQUFDO0FBQ3BDLE9BQU8sS0FBSyxVQUFVLE1BQU0scUJBQXFCLENBQUM7QUFDbEQsT0FBTyxLQUFLLElBQUksTUFBTSxlQUFlLENBQUM7QUFDdEMsT0FBTyxLQUFLLE9BQU8sTUFBTSxrQkFBa0IsQ0FBQztBQUU1QyxPQUFPLEVBQUUsdUJBQXVCLEVBQUUsd0JBQXdCLEVBQUUsMEJBQTBCLEVBQUUsTUFBTSxxQkFBcUIsQ0FBQztBQUVwSCxPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0sa0JBQWtCLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBHRU5FUkFURUQgYnkgcHJvamVuIHdhdGNoIC0gRE8gTk9UIEVESVQuXG4vLyBSZWdlbmVyYXRlZCBmcm9tIHRoZSBleHBvcnRpbmcgbW9kdWxlcyBpbiAuL3NyYy5cbi8vIEhhbmQgZWRpdHMgYXJlIG92ZXJ3cml0dGVuIG9uIHRoZSBuZXh0IHdhdGNoOyB0aGlzIGZpbGUgaXMgcmVhZC1vbmx5LlxuXG5leHBvcnQgY29uc3QgUEFDS0FHRV9JREVOVElGSUVSID0gXCJAZGJ4LXRvb2xzL2NsaS1zZXJ2aWNlXCI7XG5leHBvcnQgY29uc3QgUEFDS0FHRV9WRVJTSU9OID0gXCIwLjkuMzhcIjtcbmV4cG9ydCAqIGFzIGNsaSBmcm9tIFwiLi9zcmMvY2xpLnRzXCI7XG5leHBvcnQgKiBhcyBkZWZpbml0aW9uIGZyb20gXCIuL3NyYy9kZWZpbml0aW9uLnRzXCI7XG5leHBvcnQgKiBhcyBpY29uIGZyb20gXCIuL3NyYy9pY29uLnRzXCI7XG5leHBvcnQgKiBhcyBzZXJ2aWNlIGZyb20gXCIuL3NyYy9zZXJ2aWNlLnRzXCI7XG5leHBvcnQgdHlwZSB7IENsaVNlcnZpY2VEZWZpbml0aW9uU291cmNlLCBDbGlTZXJ2aWNlQ2xpRGVwZW5kZW5jaWVzIH0gZnJvbSBcIi4vc3JjL2NsaS50c1wiO1xuZXhwb3J0IHsgQ2xpU2VydmljZUNvbW1hbmRTY2hlbWEsIENsaVNlcnZpY2VNZW51SXRlbVNjaGVtYSwgQ2xpU2VydmljZURlZmluaXRpb25TY2hlbWEgfSBmcm9tIFwiLi9zcmMvZGVmaW5pdGlvbi50c1wiO1xuZXhwb3J0IHR5cGUgeyBDbGlTZXJ2aWNlQ29tbWFuZCwgQ2xpU2VydmljZU1lbnVJdGVtLCBDbGlTZXJ2aWNlRGVmaW5pdGlvbiwgQ2xpU2VydmljZURlZmluaXRpb25PcHRpb25zIH0gZnJvbSBcIi4vc3JjL2RlZmluaXRpb24udHNcIjtcbmV4cG9ydCB7IENsaVNlcnZpY2UgfSBmcm9tIFwiLi9zcmMvc2VydmljZS50c1wiO1xuZXhwb3J0IHR5cGUgeyBDbGlTZXJ2aWNlQ29tcGlsZXIsIENsaVNlcnZpY2VSdW50aW1lSW5zdGFsbGVyLCBDbGlTZXJ2aWNlUnVudGltZU9wdGlvbnMsIENsaVNlcnZpY2VJbnN0YWxsT3B0aW9ucywgQ2xpU2VydmljZVN0YXR1cywgQ2xpU2VydmljZUxpZmVjeWNsZSB9IGZyb20gXCIuL3NyYy9zZXJ2aWNlLnRzXCI7XG4iXX0=
12
+ //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxNQUFNLENBQUMsTUFBTSxrQkFBa0IsR0FBRyx3QkFBd0IsQ0FBQztBQUMzRCxNQUFNLENBQUMsTUFBTSxlQUFlLEdBQUcsUUFBUSxDQUFDO0FBQ3hDLE9BQU8sS0FBSyxHQUFHLE1BQU0sY0FBYyxDQUFDO0FBQ3BDLE9BQU8sS0FBSyxVQUFVLE1BQU0scUJBQXFCLENBQUM7QUFDbEQsT0FBTyxLQUFLLElBQUksTUFBTSxlQUFlLENBQUM7QUFDdEMsT0FBTyxLQUFLLE9BQU8sTUFBTSxrQkFBa0IsQ0FBQztBQUU1QyxPQUFPLEVBQUUsdUJBQXVCLEVBQUUsd0JBQXdCLEVBQUUsMEJBQTBCLEVBQUUsTUFBTSxxQkFBcUIsQ0FBQztBQUVwSCxPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0sa0JBQWtCLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBHRU5FUkFURUQgYnkgcHJvamVuIHdhdGNoIC0gRE8gTk9UIEVESVQuXG4vLyBSZWdlbmVyYXRlZCBmcm9tIHRoZSBleHBvcnRpbmcgbW9kdWxlcyBpbiAuL3NyYy5cbi8vIEhhbmQgZWRpdHMgYXJlIG92ZXJ3cml0dGVuIG9uIHRoZSBuZXh0IHdhdGNoOyB0aGlzIGZpbGUgaXMgcmVhZC1vbmx5LlxuXG5leHBvcnQgY29uc3QgUEFDS0FHRV9JREVOVElGSUVSID0gXCJAZGJ4LXRvb2xzL2NsaS1zZXJ2aWNlXCI7XG5leHBvcnQgY29uc3QgUEFDS0FHRV9WRVJTSU9OID0gXCIwLjkuNDBcIjtcbmV4cG9ydCAqIGFzIGNsaSBmcm9tIFwiLi9zcmMvY2xpLnRzXCI7XG5leHBvcnQgKiBhcyBkZWZpbml0aW9uIGZyb20gXCIuL3NyYy9kZWZpbml0aW9uLnRzXCI7XG5leHBvcnQgKiBhcyBpY29uIGZyb20gXCIuL3NyYy9pY29uLnRzXCI7XG5leHBvcnQgKiBhcyBzZXJ2aWNlIGZyb20gXCIuL3NyYy9zZXJ2aWNlLnRzXCI7XG5leHBvcnQgdHlwZSB7IENsaVNlcnZpY2VEZWZpbml0aW9uU291cmNlLCBDbGlTZXJ2aWNlQ2xpRGVwZW5kZW5jaWVzIH0gZnJvbSBcIi4vc3JjL2NsaS50c1wiO1xuZXhwb3J0IHsgQ2xpU2VydmljZUNvbW1hbmRTY2hlbWEsIENsaVNlcnZpY2VNZW51SXRlbVNjaGVtYSwgQ2xpU2VydmljZURlZmluaXRpb25TY2hlbWEgfSBmcm9tIFwiLi9zcmMvZGVmaW5pdGlvbi50c1wiO1xuZXhwb3J0IHR5cGUgeyBDbGlTZXJ2aWNlQ29tbWFuZCwgQ2xpU2VydmljZU1lbnVJdGVtLCBDbGlTZXJ2aWNlRGVmaW5pdGlvbiwgQ2xpU2VydmljZURlZmluaXRpb25PcHRpb25zIH0gZnJvbSBcIi4vc3JjL2RlZmluaXRpb24udHNcIjtcbmV4cG9ydCB7IENsaVNlcnZpY2UgfSBmcm9tIFwiLi9zcmMvc2VydmljZS50c1wiO1xuZXhwb3J0IHR5cGUgeyBDbGlTZXJ2aWNlQ29tcGlsZXIsIENsaVNlcnZpY2VSdW50aW1lSW5zdGFsbGVyLCBDbGlTZXJ2aWNlUnVudGltZU9wdGlvbnMsIENsaVNlcnZpY2VJbnN0YWxsT3B0aW9ucywgQ2xpU2VydmljZVN0YXR1cywgQ2xpU2VydmljZUxpZmVjeWNsZSB9IGZyb20gXCIuL3NyYy9zZXJ2aWNlLnRzXCI7XG4iXX0=
package/package.json CHANGED
@@ -23,7 +23,7 @@
23
23
  "typescript": "^5.9.3"
24
24
  },
25
25
  "dependencies": {
26
- "@dbx-tools/core": "^0.9.38",
26
+ "@dbx-tools/core": "^0.9.40",
27
27
  "bun": "1.3.14",
28
28
  "commander": "^15.0.0",
29
29
  "systray2": "^2.1.4",
@@ -59,7 +59,7 @@
59
59
  "./package.json": "./package.json"
60
60
  }
61
61
  },
62
- "version": "0.9.38",
62
+ "version": "0.9.40",
63
63
  "types": "./lib/index.d.ts",
64
64
  "dbxToolsConfig": {
65
65
  "tags": [