@mblua/agentscommander 0.33.0 → 0.35.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
@@ -5,18 +5,18 @@
5
5
  When installing through npm, use `-g` so the `agentscommander` command is available from any directory:
6
6
 
7
7
  ```bash
8
- npm install -g @mblua/agentscommander@<version>
8
+ npm install -g @mblua/agentscommander@latest
9
9
  ```
10
10
 
11
- Replace `<version>` with the exact version selected using [Resolve versions and preserve configuration](#resolve-versions-and-preserve-configuration), then follow [Install and validate](#install-and-validate). Check the supported platforms and requirements below before installing.
11
+ This installs the current `latest` release. Before installing, follow [Resolve versions and preserve configuration](#resolve-versions-and-preserve-configuration), then [Install and validate](#install-and-validate). Check the supported platforms and requirements below before installing.
12
12
 
13
13
  The npm website's **Install** sidebar shows the generic local-install command. For the recommended global npm installation, include `-g` as shown above.
14
14
 
15
15
  ## Choosing the npm route
16
16
 
17
- For developers who deliberately choose the secondary npm route, this page defines the supported hosts, install command, verification signal, and configuration precaution.
17
+ For developers who install through npm, this page defines the supported hosts, install command, verification signal, and configuration precaution.
18
18
 
19
- npm is not the recommended first install. Start with the reviewable [Coding Agent installation contract](https://github.com/mblua/AgentsCommander/blob/main/docs/install-with-agent.md), which detects the host, selects an approved stable-release asset, verifies its checksum, and waits for approval.
19
+ On Windows and Linux, npm is not the recommended first install: start with the reviewable [Coding Agent installation contract](https://github.com/mblua/AgentsCommander/blob/main/docs/install-with-agent.md), which detects the host, selects an approved stable-release asset, verifies its checksum, and waits for approval. On macOS, npm is the only supported route.
20
20
 
21
21
  ## Platform boundary
22
22
 
@@ -25,11 +25,11 @@ Use this package only on these documented combinations:
25
25
  | Host | Native architecture | Status |
26
26
  |---|---|---|
27
27
  | Windows 10 version 1809 or newer, or Windows 11 | x86_64 / AMD64 | Fully supported |
28
- | Linux | x86_64 / AMD64 | Partial and in progress; continue only after acknowledging the limitation |
29
- | macOS | Any | Not supported; do not install through npm |
28
+ | Linux | x86_64 / AMD64 | Supported with medium test coverage; some turbulence is expected. Continue after acknowledging the limitation. |
29
+ | macOS | Any | Supported via npm only, with very low test coverage; errors are expected. |
30
30
  | Any other OS or architecture | Any | Unsupported; do not substitute an asset or use emulation |
31
31
 
32
- The current npm installer does not enforce this complete allowlist: its asset mapping treats architectures other than `arm64` as `x86_64`. An asset selection or download is not a support promise. Follow the canonical [platform gates](https://github.com/mblua/AgentsCommander/blob/main/docs/install-with-agent.md#support-gates).
32
+ The current npm installer does not enforce this complete allowlist: its asset mapping treats architectures other than `arm64` as `x86_64`, so an x64 Node on an arm64 Mac installs the x86_64 bundle. An asset selection or download is not a support promise. Follow the canonical [platform gates](https://github.com/mblua/AgentsCommander/blob/main/docs/install-with-agent.md#support-gates).
33
33
 
34
34
  ## Requirements
35
35
 
@@ -41,7 +41,7 @@ AgentsCommander does not install or authenticate Coding Agent CLIs for you.
41
41
 
42
42
  ## Resolve versions and preserve configuration
43
43
 
44
- Before an install, update, or uninstall, resolve and report the exact existing package and binary versions, then the exact registry release selected for comparison. For an install or update, that selected release must also be the version you install; for an uninstall, report that no replacement will be installed.
44
+ Before an install, update, or uninstall, resolve and report the exact existing package and binary versions, then the current `latest` registry release. For an install or update, that `latest` release is the version you install; for an uninstall, report that no replacement will be installed.
45
45
 
46
46
  ```bash
47
47
  npm list -g @mblua/agentscommander --depth=0
@@ -53,13 +53,15 @@ npm view @mblua/agentscommander@latest version
53
53
 
54
54
  The existing binary's exact resolver determines what must be preserved. The selected package's exact release tag determines post-install behavior. Verify both against the corresponding `v<version>` source tag; do not use `main` as evidence for a published npm package.
55
55
 
56
- ### npm `0.33.0`
56
+ ### npm `0.35.0`
57
57
 
58
- `0.33.0` is the release described by this package. Its installer downloads the `v0.33.0` native release asset and verifies it against `SHASUMS256.txt`. On Windows and Linux it renames the asset to the unsuffixed executable in the package's `bin/` directory. On macOS it downloads the `agentscommander-mac-<arch>.app.tar.gz` bundle, extracts the single `.app` directory into `bin/`, and validates the executable named by the bundle's `CFBundleExecutable`. The launcher spawns that executable and injects no configuration override.
58
+ `0.35.0` is the release described by this package. Its installer downloads the `v0.35.0` native release asset and verifies it against `SHASUMS256.txt`. On Windows and Linux it renames the asset to the unsuffixed executable in the package's `bin/` directory. On macOS it downloads the `agentscommander-mac-<arch>.app.tar.gz` bundle, extracts the single `.app` directory into `bin/`, and validates the executable named by the bundle's `CFBundleExecutable`. The launcher spawns that executable and injects no configuration override. A global install also creates the desktop entry points described in [Windows Start Menu shortcut](#windows-start-menu-shortcut), [macOS Launchpad and Spotlight](#macos-launchpad-and-spotlight), and [Linux application menu](#linux-application-menu).
59
59
 
60
- The `v0.33.0` native resolver selects a non-blank `AGENTSCOMMANDER_CONFIG_DIR` value verbatim when present. Otherwise, the normal unsuffixed npm executable selects the user's home directory plus `.agentscommander`, independently of its install location and build profile. It does not inspect an adjacent `portable.txt` marker or probe an adjacent configuration directory on this route. Suffixed executables use their adjacent `.agentscommander_<suffix>` directory and refuse to start when it is not writable.
60
+ The `v0.35.0` native resolver selects a non-blank `AGENTSCOMMANDER_CONFIG_DIR` value verbatim when present. Otherwise, the normal unsuffixed npm executable selects the user's home directory plus `.agentscommander`, independently of its install location and build profile. It does not probe an adjacent configuration directory on this route. Suffixed executables use their adjacent `.agentscommander_<suffix>` directory and refuse to start when it is not writable.
61
61
 
62
- **Version `0.33.0` keeps the `0.32.0` default location.** Versions `0.31.0` and `0.30.5` normally selected `.agentscommander` beside the native executable under `@mblua/agentscommander/bin/` when that location was writable, with their documented home fallback and refusal rules. Neither `0.32.0` nor `0.33.0` discovers, copies, moves or migrates any old configuration automatically. Before updating from `0.31.0` or older, identify and back up the old version's active configuration. If you intend to keep using that directory, set `AGENTSCOMMANDER_CONFIG_DIR` to its verified path; otherwise arrange the intended configuration at the new home location separately. Version `0.33.0` also drops the legacy pre-v2 `codingAgentProfiles` settings migration.
62
+ **Version `0.35.0` keeps the `0.32.0` default location.** Versions `0.31.0` and `0.30.5` normally selected `.agentscommander` beside the native executable under `@mblua/agentscommander/bin/` when that location was writable, with their documented home fallback and refusal rules. None of `0.32.0` through `0.35.0` discovers, copies, moves or migrates any old configuration automatically. Before updating from `0.31.0` or older, identify and back up the old version's active configuration. If you intend to keep using that directory, set `AGENTSCOMMANDER_CONFIG_DIR` to its verified path; otherwise arrange the intended configuration at the new home location separately. Version `0.33.0` dropped the legacy pre-v2 `codingAgentProfiles` settings migration, and later versions keep it removed.
63
+
64
+ **Version `0.35.0` keeps bounded backups of `settings.json`.** Every successful save archives the bytes it replaced into `settings.backup.1.json` through `settings.backup.5.json` in the same configuration directory, newest in slot 1. These files live beside `settings.json`, so preserve them with it when you move or back up a configuration directory.
63
65
 
64
66
  The older npm `0.30.3` resolver immediately selected an executable-adjacent directory when the parent and stem were available and did not support the configuration override or portable-marker/write-probe rules. npm never published `0.30.4`; that number exists only as a GitHub release. For other versions, inspect `src-tauri/src/config/mod.rs`, `src-tauri/src/config/profile.rs`, `npm/run.js`, and `npm/install.js` at the exact `v<version>` tag.
65
67
 
@@ -70,10 +72,10 @@ Copy the complete persistent configuration directory to a user-controlled backup
70
72
  ## Install and validate
71
73
 
72
74
  ```bash
73
- npm install -g @mblua/agentscommander@<version>
75
+ npm install -g @mblua/agentscommander@latest
74
76
  ```
75
77
 
76
- Replace `<version>` with the exact version already inspected and approved; do not leave the install unpinned after resolving `latest`. The command exits 0 on success. The package's install script downloads that package version's raw asset and `SHASUMS256.txt` from `mblua/AgentsCommander`, computes SHA-256, and fails the install on a missing record or mismatch. This does not protect against compromise of the publisher or repository account because the asset and checksum share that trust boundary.
78
+ The command installs the current `latest` release and exits 0 on success. The package's install script downloads that package version's raw asset and `SHASUMS256.txt` from `mblua/AgentsCommander`, computes SHA-256, and fails the install on a missing record or mismatch. This does not protect against compromise of the publisher or repository account because the asset and checksum share that trust boundary.
77
79
 
78
80
  Validate the installed command:
79
81
 
@@ -82,7 +84,25 @@ npm list -g @mblua/agentscommander --depth=0
82
84
  agentscommander --help
83
85
  ```
84
86
 
85
- Both commands must exit 0. Confirm that `npm list` and the installed `package.json` report the approved package version; re-check the installed scripts, native path, and checksum correlation described above. `--help` must print the AgentsCommander command help, and on `0.31.0` or newer `agentscommander --version` must print the same version `npm list` reports. The npm package is `@mblua/agentscommander`; the installed command is `agentscommander`.
87
+ Both commands must exit 0. Confirm that `npm list` and the installed `package.json` report the `latest` version that `npm view @mblua/agentscommander@latest version` returned; re-check the installed scripts, native path, and checksum correlation described above. `--help` must print the AgentsCommander command help, and on `0.31.0` or newer `agentscommander --version` must print the same version `npm list` reports. The npm package is `@mblua/agentscommander`; the installed command is `agentscommander`.
88
+
89
+ ### Windows Start Menu shortcut
90
+
91
+ On Windows, a global install also creates a per-user Start Menu shortcut named **AgentsCommander**, with the app icon, at `%APPDATA%\Microsoft\Windows\Start Menu\Programs\AgentsCommander.lnk`. It opens the installed `bin\agentscommander.exe`. A local install (without `-g`) creates no shortcut. To skip it, set `AGENTSCOMMANDER_NO_SHORTCUT=1` before installing. If the shortcut cannot be created, the install prints a warning and still succeeds. Installing again replaces the same shortcut.
92
+
93
+ ### Linux application menu
94
+
95
+ On Linux, a global install also writes a per-user desktop entry at `~/.local/share/applications/agentscommander.desktop`, or under `$XDG_DATA_HOME/applications` when `XDG_DATA_HOME` is set and not empty. It launches the installed `bin/agentscommander` and uses the `icon.png` shipped in the package, so AgentsCommander appears in the application menu and overview search and can be pinned to the dock. It needs no root; `/usr/share/applications` is not used.
96
+
97
+ When `update-desktop-database` exists at `/usr/bin` or `/bin`, the installer runs it on that directory; when it is missing, nothing is reported, because most desktop environments pick the entry up without it. A local install (without `-g`) creates nothing. To skip the entry, set `AGENTSCOMMANDER_NO_SHORTCUT=1` before installing. If the entry cannot be written, the install prints a warning and still succeeds. Installing again overwrites the same file.
98
+
99
+ ### macOS Launchpad and Spotlight
100
+
101
+ On macOS, a global install also creates a symlink named **AgentsCommander.app** at `~/Applications/AgentsCommander.app`, pointing at the `.app` bundle that the installer extracted into the package's `bin/` directory. `~/Applications` is user-owned, so this needs no administrator password and no `sudo`; `/Applications` is not used because writing there needs elevation. Launchpad and Spotlight index `~/Applications`, so after the install the app is searchable, launchable, and can be pinned to the Dock with its own icon.
102
+
103
+ A local install (without `-g`) creates nothing. To skip the symlink, set `AGENTSCOMMANDER_NO_SHORTCUT=1` before installing, the same opt-out Windows uses. If the symlink cannot be created, the install prints a warning and still succeeds. Installing again replaces the same symlink, so there is never more than one entry; if a real application already occupies that name, the installer leaves it alone and warns.
104
+
105
+ The bundle is **not signed**. macOS Gatekeeper may block the first launch even though the icon is visible. The installer does not strip the quarantine attribute and does not call `xattr`, `spctl`, or `codesign`, and you should not either: report the block at the [issue tracker](https://github.com/mblua/AgentsCommander/issues) instead of bypassing Gatekeeper.
86
106
 
87
107
  ## Uninstall
88
108
 
@@ -92,6 +112,26 @@ Identify, back up, and verify the version-selected configuration as described ab
92
112
  npm uninstall -g @mblua/agentscommander
93
113
  ```
94
114
 
95
- Success exits 0. Restore a previous version or remove the saved configuration only as a separate, deliberate action.
115
+ Success exits 0. npm does not run uninstall scripts, so the Start Menu shortcut, the Linux desktop entry, and the `~/Applications` symlink survive the uninstall and must be deleted by hand.
116
+
117
+ On Windows:
118
+
119
+ ```powershell
120
+ Remove-Item "$env:APPDATA\Microsoft\Windows\Start Menu\Programs\AgentsCommander.lnk"
121
+ ```
122
+
123
+ On Linux:
124
+
125
+ ```bash
126
+ rm "${XDG_DATA_HOME:-$HOME/.local/share}/applications/agentscommander.desktop"
127
+ ```
128
+
129
+ On macOS:
130
+
131
+ ```bash
132
+ rm ~/Applications/AgentsCommander.app
133
+ ```
134
+
135
+ `rm` without `-r` is deliberate: the entry is a symlink, so this removes the link and never the bundle it points at. If `rm` reports that it is a directory, stop: something other than the installer's symlink is at that path. Restore a previous version or remove the saved configuration only as a separate, deliberate action.
96
136
 
97
137
  For stable-release downloads and rollback rules, use the [manual alternatives](https://github.com/mblua/AgentsCommander/blob/main/docs/install-with-agent.md#manual-alternatives).
package/icon.png ADDED
Binary file
package/install.js CHANGED
@@ -5,8 +5,11 @@ const crypto = require('crypto');
5
5
  const os = require('os');
6
6
  const { execSync } = require('child_process');
7
7
  const { assertExecutable } = require('./resolve-bin');
8
+ const { createStartMenuShortcut } = require('./windows-shortcut');
9
+ const { createLaunchpadAlias } = require('./macos-alias');
10
+ const { createDesktopEntry } = require('./linux-desktop-entry');
8
11
 
9
- const VERSION = "0.33.0"; // Must match package.json
12
+ const VERSION = "0.35.0"; // Must match package.json
10
13
  const OWNER = 'mblua';
11
14
  const REPO = 'AgentsCommander';
12
15
 
@@ -133,15 +136,42 @@ async function main() {
133
136
  if (fs.existsSync(extractTmpDir)) fs.rmSync(extractTmpDir, { recursive: true, force: true });
134
137
  }
135
138
  fs.unlinkSync(tmpPath);
136
- assertExecutable('darwin', binDir);
139
+ const macBinPath = assertExecutable('darwin', binDir);
140
+ // <bundle>.app/Contents/MacOS/<exe> -> <bundle>.app
141
+ const bundlePath = path.dirname(path.dirname(path.dirname(macBinPath)));
142
+ try {
143
+ const alias = createLaunchpadAlias(bundlePath, { platform });
144
+ if (alias.created) {
145
+ console.log(`Launchpad alias created: ${alias.path}`);
146
+ console.log('The app bundle is not signed, so macOS may block the first launch. Do not bypass Gatekeeper: report the block at https://github.com/mblua/AgentsCommander/issues');
147
+ }
148
+ } catch (err) {
149
+ console.warn(`Warning: Launchpad alias not created: ${err.message}`);
150
+ }
137
151
  } else {
138
152
  const finalBinPath = path.join(binDir, platform === 'win32' ? 'agentscommander.exe' : 'agentscommander');
139
153
  if (platform !== 'win32') {
140
154
  fs.chmodSync(tmpPath, 0o755);
141
155
  }
142
156
  fs.renameSync(tmpPath, finalBinPath);
157
+ if (platform === 'win32') {
158
+ try {
159
+ const shortcut = createStartMenuShortcut(finalBinPath);
160
+ if (shortcut.created) console.log(`Start Menu shortcut created: ${shortcut.path}`);
161
+ } catch (err) {
162
+ console.warn(`Warning: Start Menu shortcut not created: ${err.message}`);
163
+ }
164
+ }
165
+ if (platform === 'linux') {
166
+ try {
167
+ const entry = createDesktopEntry(finalBinPath, { platform });
168
+ if (entry.created) console.log(`Application menu entry created: ${entry.path}`);
169
+ } catch (err) {
170
+ console.warn(`Warning: application menu entry not created: ${err.message}`);
171
+ }
172
+ }
143
173
  }
144
-
174
+
145
175
  fs.unlinkSync(shasumTmpPath);
146
176
  console.log('Installation completed successfully.');
147
177
  } catch (err) {
@@ -0,0 +1,102 @@
1
+ // Creates the per-user application menu entry for a global npm install on Linux.
2
+ // install.js calls it after the executable is in place; a failure only warns.
3
+ // Issue #2066.
4
+ //
5
+ // The entry is written under $XDG_DATA_HOME/applications (default
6
+ // ~/.local/share/applications). /usr/share/applications needs root and is out of
7
+ // scope. The icon is the icon.png shipped inside this package: the Linux release
8
+ // asset is a bare binary with no icon of its own.
9
+ const fs = require('node:fs');
10
+ const path = require('node:path');
11
+ const { spawnSync } = require('node:child_process');
12
+
13
+ const ENTRY_NAME = 'agentscommander.desktop';
14
+ const ICON_PATH = path.join(__dirname, 'icon.png');
15
+
16
+ // Fixed, OS-owned locations: never resolved through PATH.
17
+ const UPDATE_DB_CANDIDATES = ['/usr/bin/update-desktop-database', '/bin/update-desktop-database'];
18
+
19
+ // Returns the reason the entry is skipped, or null when it should be created.
20
+ function skipReason(platform, env) {
21
+ if (platform !== 'linux') return 'not Linux';
22
+ if (env.npm_config_global !== 'true') return 'not a global install';
23
+ if (env.AGENTSCOMMANDER_NO_SHORTCUT === '1') return 'AGENTSCOMMANDER_NO_SHORTCUT=1';
24
+ if (!env.XDG_DATA_HOME && !env.HOME) return 'neither XDG_DATA_HOME nor HOME is set';
25
+ return null;
26
+ }
27
+
28
+ function applicationsDir(env) {
29
+ const dataHome = env.XDG_DATA_HOME ? env.XDG_DATA_HOME : path.join(env.HOME, '.local', 'share');
30
+ return path.join(dataHome, 'applications');
31
+ }
32
+
33
+ function entryPath(env) {
34
+ return path.join(applicationsDir(env), ENTRY_NAME);
35
+ }
36
+
37
+ // Desktop Entry Specification: a string value escapes backslash, and an Exec
38
+ // argument is double-quoted with ", `, $ and \ backslash-escaped, % doubled.
39
+ // The quoting layer is applied first, then the string-value layer.
40
+ function quoteExecArg(arg) {
41
+ const quoted = '"' + arg.replace(/[\\"`$]/g, (c) => '\\' + c).replace(/%/g, '%%') + '"';
42
+ return quoted.replace(/\\/g, '\\\\');
43
+ }
44
+
45
+ function assertSingleLine(value, label) {
46
+ if (/[\r\n]/.test(value)) throw new Error(`${label} contains a line break: ${JSON.stringify(value)}`);
47
+ }
48
+
49
+ function entryText(targetPath, iconPath = ICON_PATH) {
50
+ assertSingleLine(targetPath, 'executable path');
51
+ assertSingleLine(iconPath, 'icon path');
52
+ return [
53
+ '[Desktop Entry]',
54
+ 'Type=Application',
55
+ 'Version=1.0',
56
+ 'Name=AgentsCommander',
57
+ 'Comment=Terminal session manager for AI coding agent teams',
58
+ `Exec=${quoteExecArg(targetPath)}`,
59
+ `TryExec=${targetPath.replace(/\\/g, '\\\\')}`,
60
+ `Icon=${iconPath.replace(/\\/g, '\\\\')}`,
61
+ 'Terminal=false',
62
+ 'Categories=Development;Utility;',
63
+ '',
64
+ ].join('\n');
65
+ }
66
+
67
+ // Optional: most desktop environments pick the file up without it, so its
68
+ // absence or failure is silent.
69
+ function refreshDesktopDatabase(dir, candidates = UPDATE_DB_CANDIDATES) {
70
+ const cmd = candidates.find((candidate) => fs.existsSync(candidate));
71
+ if (!cmd) return false;
72
+ const r = spawnSync(cmd, [dir], { stdio: 'ignore', timeout: 15000 });
73
+ return !r.error && r.status === 0;
74
+ }
75
+
76
+ function createDesktopEntry(targetPath, options = {}) {
77
+ const platform = options.platform || process.platform;
78
+ const env = options.env || process.env;
79
+ const reason = skipReason(platform, env);
80
+ if (reason) return { created: false, reason };
81
+
82
+ const iconPath = options.iconPath || ICON_PATH;
83
+ if (!fs.existsSync(iconPath)) throw new Error(`icon not found at ${iconPath}`);
84
+ const text = entryText(targetPath, iconPath);
85
+ const file = entryPath(env);
86
+ fs.mkdirSync(path.dirname(file), { recursive: true });
87
+ fs.writeFileSync(file, text, { mode: 0o644 });
88
+ if (fs.readFileSync(file, 'utf8') !== text) throw new Error(`desktop entry was not written at ${file}`);
89
+ const refreshed = refreshDesktopDatabase(path.dirname(file), options.updateDbCandidates);
90
+ return { created: true, path: file, refreshed };
91
+ }
92
+
93
+ module.exports = {
94
+ createDesktopEntry,
95
+ skipReason,
96
+ applicationsDir,
97
+ entryPath,
98
+ entryText,
99
+ quoteExecArg,
100
+ ENTRY_NAME,
101
+ ICON_PATH,
102
+ };
package/macos-alias.js ADDED
@@ -0,0 +1,74 @@
1
+ // Creates the per-user ~/Applications alias for a global npm install on macOS.
2
+ // install.js calls it after the bundle is extracted and validated; a failure
3
+ // only warns. Issue #2065.
4
+ //
5
+ // The bundle stays where npm put it, inside the package's bin/ directory. Only a
6
+ // symlink is added, so Launchpad and Spotlight can index the app and the user can
7
+ // pin it to the Dock. ~/Applications is user-owned: no sudo, no elevation.
8
+ // /Applications is deliberately out of scope because it needs elevation.
9
+ //
10
+ // This module never touches Gatekeeper: no `xattr`, no `spctl`, no quarantine
11
+ // attribute is read or cleared. The bundle is unsigned, so the first launch may
12
+ // still be blocked; that is a condition to report, never to bypass.
13
+ const fs = require('node:fs');
14
+ const path = require('node:path');
15
+
16
+ const ALIAS_NAME = 'AgentsCommander.app';
17
+
18
+ // Returns the reason the alias is skipped, or null when it should be created.
19
+ function skipReason(platform, env) {
20
+ if (platform !== 'darwin') return 'not macOS';
21
+ if (env.npm_config_global !== 'true') return 'not a global install';
22
+ if (env.AGENTSCOMMANDER_NO_SHORTCUT === '1') return 'AGENTSCOMMANDER_NO_SHORTCUT=1';
23
+ if (!env.HOME) return 'HOME is not set';
24
+ return null;
25
+ }
26
+
27
+ function aliasPath(env) {
28
+ return path.join(env.HOME, 'Applications', ALIAS_NAME);
29
+ }
30
+
31
+ // Replaces our own symlink and nothing else: a real directory or file already at
32
+ // the alias path belongs to someone else and is left untouched.
33
+ function removeExistingAlias(alias) {
34
+ let stat;
35
+ try {
36
+ stat = fs.lstatSync(alias);
37
+ } catch (err) {
38
+ if (err.code === 'ENOENT') return;
39
+ throw err;
40
+ }
41
+ if (!stat.isSymbolicLink()) {
42
+ throw new Error(`${alias} already exists and is not a symlink; leaving it alone`);
43
+ }
44
+ fs.unlinkSync(alias);
45
+ }
46
+
47
+ function createLaunchpadAlias(bundlePath, options = {}) {
48
+ const platform = options.platform || process.platform;
49
+ const env = options.env || process.env;
50
+ const reason = skipReason(platform, env);
51
+ if (reason) return { created: false, reason };
52
+
53
+ let bundleStat;
54
+ try {
55
+ bundleStat = fs.statSync(bundlePath);
56
+ } catch (err) {
57
+ throw new Error(`app bundle not found at ${bundlePath} (${err.code})`);
58
+ }
59
+ if (!bundleStat.isDirectory() || !bundlePath.endsWith('.app')) {
60
+ throw new Error(`not an app bundle: ${bundlePath}`);
61
+ }
62
+
63
+ const alias = aliasPath(env);
64
+ fs.mkdirSync(path.dirname(alias), { recursive: true });
65
+ removeExistingAlias(alias);
66
+ fs.symlinkSync(bundlePath, alias, 'dir');
67
+
68
+ const written = fs.lstatSync(alias);
69
+ if (!written.isSymbolicLink()) throw new Error(`alias was not written as a symlink at ${alias}`);
70
+ if (fs.readlinkSync(alias) !== bundlePath) throw new Error(`alias at ${alias} does not point at ${bundlePath}`);
71
+ return { created: true, path: alias, target: bundlePath };
72
+ }
73
+
74
+ module.exports = { createLaunchpadAlias, skipReason, aliasPath, ALIAS_NAME };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mblua/agentscommander",
3
- "version": "0.33.0",
3
+ "version": "0.35.0",
4
4
  "description": "Install and run AgentsCommander, the local terminal session manager for AI coding agent teams with Claude Code, Codex, Hermes, Cursor CLI, OpenCode, and more to come.",
5
5
  "license": "MIT",
6
6
  "bin": {
@@ -12,7 +12,11 @@
12
12
  "files": [
13
13
  "run.js",
14
14
  "install.js",
15
- "resolve-bin.js"
15
+ "resolve-bin.js",
16
+ "macos-alias.js",
17
+ "windows-shortcut.js",
18
+ "linux-desktop-entry.js",
19
+ "icon.png"
16
20
  ],
17
21
  "engines": {
18
22
  "node": ">=18.0.0"
@@ -0,0 +1,68 @@
1
+ // Creates the per-user Start Menu shortcut for a global npm install on Windows.
2
+ // install.js calls it after the executable is in place; a failure only warns.
3
+ const fs = require('node:fs');
4
+ const path = require('node:path');
5
+ const { spawnSync } = require('node:child_process');
6
+
7
+ const SHORTCUT_NAME = 'AgentsCommander.lnk';
8
+
9
+ // Paths reach PowerShell through environment variables, never through the
10
+ // script text, so a quote or `$` in a user path cannot change the script.
11
+ const PS_SCRIPT = [
12
+ '$ErrorActionPreference = "Stop"',
13
+ '$s = (New-Object -ComObject WScript.Shell).CreateShortcut($env:AC_SHORTCUT_PATH)',
14
+ '$s.TargetPath = $env:AC_SHORTCUT_TARGET',
15
+ '$s.WorkingDirectory = $env:AC_SHORTCUT_WORKDIR',
16
+ '$s.IconLocation = $env:AC_SHORTCUT_TARGET + ",0"',
17
+ '$s.Description = "AgentsCommander"',
18
+ '$s.Save()',
19
+ ].join('; ');
20
+
21
+ // Returns the reason the shortcut is skipped, or null when it should be created.
22
+ function skipReason(platform, env) {
23
+ if (platform !== 'win32') return 'not Windows';
24
+ if (env.npm_config_global !== 'true') return 'not a global install';
25
+ if (env.AGENTSCOMMANDER_NO_SHORTCUT === '1') return 'AGENTSCOMMANDER_NO_SHORTCUT=1';
26
+ if (!env.APPDATA) return 'APPDATA is not set';
27
+ return null;
28
+ }
29
+
30
+ function shortcutPath(env) {
31
+ return path.join(env.APPDATA, 'Microsoft', 'Windows', 'Start Menu', 'Programs', SHORTCUT_NAME);
32
+ }
33
+
34
+ // Fixed, OS-owned PowerShell location: never resolved through PATH.
35
+ function powershellPath(env) {
36
+ const systemRoot = env.SystemRoot || env.SYSTEMROOT || String.raw`C:\Windows`;
37
+ return path.join(systemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
38
+ }
39
+
40
+ function createStartMenuShortcut(targetPath, options = {}) {
41
+ const platform = options.platform || process.platform;
42
+ const env = options.env || process.env;
43
+ const reason = skipReason(platform, env);
44
+ if (reason) return { created: false, reason };
45
+
46
+ const lnk = shortcutPath(env);
47
+ fs.mkdirSync(path.dirname(lnk), { recursive: true });
48
+ const r = spawnSync(
49
+ powershellPath(env),
50
+ ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', PS_SCRIPT],
51
+ {
52
+ env: {
53
+ ...env,
54
+ AC_SHORTCUT_PATH: lnk,
55
+ AC_SHORTCUT_TARGET: targetPath,
56
+ AC_SHORTCUT_WORKDIR: env.USERPROFILE || path.dirname(targetPath),
57
+ },
58
+ encoding: 'utf8',
59
+ windowsHide: true,
60
+ },
61
+ );
62
+ if (r.error) throw new Error(`could not run PowerShell: ${r.error.message}`);
63
+ if (r.status !== 0) throw new Error(`PowerShell exited ${r.status}: ${(r.stderr || '').trim()}`);
64
+ if (!fs.existsSync(lnk)) throw new Error(`shortcut was not written at ${lnk}`);
65
+ return { created: true, path: lnk };
66
+ }
67
+
68
+ module.exports = { createStartMenuShortcut, skipReason, shortcutPath, SHORTCUT_NAME };