@mblua/agentscommander 0.32.0 → 0.34.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,8 +1,22 @@
1
1
  # AgentsCommander from npm
2
2
 
3
- For developers who deliberately choose the secondary npm route, this page defines the supported hosts, install command, verification signal, and configuration precaution.
3
+ ## Recommended npm installation: global
4
4
 
5
- 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.
5
+ When installing through npm, use `-g` so the `agentscommander` command is available from any directory:
6
+
7
+ ```bash
8
+ npm install -g @mblua/agentscommander@latest
9
+ ```
10
+
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
+
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
+
15
+ ## Choosing the npm route
16
+
17
+ For developers who install through npm, this page defines the supported hosts, install command, verification signal, and configuration precaution.
18
+
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.
6
20
 
7
21
  ## Platform boundary
8
22
 
@@ -11,11 +25,11 @@ Use this package only on these documented combinations:
11
25
  | Host | Native architecture | Status |
12
26
  |---|---|---|
13
27
  | Windows 10 version 1809 or newer, or Windows 11 | x86_64 / AMD64 | Fully supported |
14
- | Linux | x86_64 / AMD64 | Partial and in progress; continue only after acknowledging the limitation |
15
- | 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. |
16
30
  | Any other OS or architecture | Any | Unsupported; do not substitute an asset or use emulation |
17
31
 
18
- 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).
19
33
 
20
34
  ## Requirements
21
35
 
@@ -27,7 +41,7 @@ AgentsCommander does not install or authenticate Coding Agent CLIs for you.
27
41
 
28
42
  ## Resolve versions and preserve configuration
29
43
 
30
- 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.
31
45
 
32
46
  ```bash
33
47
  npm list -g @mblua/agentscommander --depth=0
@@ -39,13 +53,15 @@ npm view @mblua/agentscommander@latest version
39
53
 
40
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.
41
55
 
42
- ### npm `0.32.0`
56
+ ### npm `0.34.0`
57
+
58
+ `0.34.0` is the release described by this package. Its installer downloads the `v0.34.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) and [macOS Launchpad and Spotlight](#macos-launchpad-and-spotlight).
43
59
 
44
- `0.32.0` is the release described by this package. Its installer downloads the `v0.32.0` native release asset, verifies it against `SHASUMS256.txt`, and renames it to the unsuffixed executable in the package's `bin/` directory. The launcher spawns that binary and injects no configuration override.
60
+ The `v0.34.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.
45
61
 
46
- The `v0.32.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 retain their separate instance-location rules.
62
+ **Version `0.34.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`, `0.33.0` or `0.34.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 `0.34.0` keeps it removed.
47
63
 
48
- **This changes the default location from npm `0.31.0` and `0.30.5`.** Those versions normally selected `.agentscommander` beside the native executable under `@mblua/agentscommander/bin/` when that location was writable, with their documented home fallback and refusal rules. Version `0.32.0` does not discover, copy, move or migrate any old configuration automatically. Before updating, 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.
64
+ **Version `0.34.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.
49
65
 
50
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.
51
67
 
@@ -56,10 +72,10 @@ Copy the complete persistent configuration directory to a user-controlled backup
56
72
  ## Install and validate
57
73
 
58
74
  ```bash
59
- npm install -g @mblua/agentscommander@<version>
75
+ npm install -g @mblua/agentscommander@latest
60
76
  ```
61
77
 
62
- 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.
63
79
 
64
80
  Validate the installed command:
65
81
 
@@ -68,7 +84,19 @@ npm list -g @mblua/agentscommander --depth=0
68
84
  agentscommander --help
69
85
  ```
70
86
 
71
- 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
+ ### macOS Launchpad and Spotlight
94
+
95
+ 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.
96
+
97
+ 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.
98
+
99
+ 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.
72
100
 
73
101
  ## Uninstall
74
102
 
@@ -78,6 +106,20 @@ Identify, back up, and verify the version-selected configuration as described ab
78
106
  npm uninstall -g @mblua/agentscommander
79
107
  ```
80
108
 
81
- Success exits 0. Restore a previous version or remove the saved configuration only as a separate, deliberate action.
109
+ Success exits 0. npm does not run uninstall scripts, so the Start Menu shortcut and the `~/Applications` symlink survive the uninstall and must be deleted by hand.
110
+
111
+ On Windows:
112
+
113
+ ```powershell
114
+ Remove-Item "$env:APPDATA\Microsoft\Windows\Start Menu\Programs\AgentsCommander.lnk"
115
+ ```
116
+
117
+ On macOS:
118
+
119
+ ```bash
120
+ rm ~/Applications/AgentsCommander.app
121
+ ```
122
+
123
+ `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.
82
124
 
83
125
  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/install.js CHANGED
@@ -4,8 +4,11 @@ const https = require('https');
4
4
  const crypto = require('crypto');
5
5
  const os = require('os');
6
6
  const { execSync } = require('child_process');
7
+ const { assertExecutable } = require('./resolve-bin');
8
+ const { createStartMenuShortcut } = require('./windows-shortcut');
9
+ const { createLaunchpadAlias } = require('./macos-alias');
7
10
 
8
- const VERSION = "0.32.0"; // Must match package.json
11
+ const VERSION = "0.34.0"; // Must match package.json
9
12
  const OWNER = 'mblua';
10
13
  const REPO = 'AgentsCommander';
11
14
 
@@ -132,14 +135,34 @@ async function main() {
132
135
  if (fs.existsSync(extractTmpDir)) fs.rmSync(extractTmpDir, { recursive: true, force: true });
133
136
  }
134
137
  fs.unlinkSync(tmpPath);
138
+ const macBinPath = assertExecutable('darwin', binDir);
139
+ // <bundle>.app/Contents/MacOS/<exe> -> <bundle>.app
140
+ const bundlePath = path.dirname(path.dirname(path.dirname(macBinPath)));
141
+ try {
142
+ const alias = createLaunchpadAlias(bundlePath, { platform });
143
+ if (alias.created) {
144
+ console.log(`Launchpad alias created: ${alias.path}`);
145
+ 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');
146
+ }
147
+ } catch (err) {
148
+ console.warn(`Warning: Launchpad alias not created: ${err.message}`);
149
+ }
135
150
  } else {
136
151
  const finalBinPath = path.join(binDir, platform === 'win32' ? 'agentscommander.exe' : 'agentscommander');
137
152
  if (platform !== 'win32') {
138
153
  fs.chmodSync(tmpPath, 0o755);
139
154
  }
140
155
  fs.renameSync(tmpPath, finalBinPath);
156
+ if (platform === 'win32') {
157
+ try {
158
+ const shortcut = createStartMenuShortcut(finalBinPath);
159
+ if (shortcut.created) console.log(`Start Menu shortcut created: ${shortcut.path}`);
160
+ } catch (err) {
161
+ console.warn(`Warning: Start Menu shortcut not created: ${err.message}`);
162
+ }
163
+ }
141
164
  }
142
-
165
+
143
166
  fs.unlinkSync(shasumTmpPath);
144
167
  console.log('Installation completed successfully.');
145
168
  } catch (err) {
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.32.0",
3
+ "version": "0.34.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": {
@@ -11,7 +11,10 @@
11
11
  },
12
12
  "files": [
13
13
  "run.js",
14
- "install.js"
14
+ "install.js",
15
+ "resolve-bin.js",
16
+ "macos-alias.js",
17
+ "windows-shortcut.js"
15
18
  ],
16
19
  "engines": {
17
20
  "node": ">=18.0.0"
package/resolve-bin.js ADDED
@@ -0,0 +1,67 @@
1
+ // Shared, platform-aware locator for the AgentsCommander executable inside the
2
+ // installed package. run.js (launch) and install.js (post-extraction validation)
3
+ // both use it so the two files agree on one on-disk contract. Issue #2016.
4
+ const fs = require('node:fs');
5
+ const path = require('node:path');
6
+
7
+ // A Tauri Info.plist states CFBundleExecutable as a single <key>/<string> pair.
8
+ // A bounded regex reads it without adding a plist parser to the published package.
9
+ const CFBUNDLE_EXECUTABLE_RE = /<key>\s*CFBundleExecutable\s*<\/key>\s*<string>([^<]*)<\/string>/;
10
+
11
+ function resolveBinPath(platform, binDir) {
12
+ if (platform !== 'darwin') {
13
+ return path.join(binDir, platform === 'win32' ? 'agentscommander.exe' : 'agentscommander');
14
+ }
15
+
16
+ let entries;
17
+ try {
18
+ entries = fs.readdirSync(binDir, { withFileTypes: true });
19
+ } catch (err) {
20
+ throw new Error(`macOS app bundle not found: cannot read ${binDir} (${err.code})`);
21
+ }
22
+
23
+ const bundles = entries.filter((entry) => entry.isDirectory() && entry.name.endsWith('.app'));
24
+ if (bundles.length !== 1) {
25
+ const found = bundles.length === 0 ? 'none' : `${bundles.length}: ${bundles.map((b) => b.name).join(', ')}`;
26
+ throw new Error(`macOS app bundle not found in ${binDir}: expected exactly one *.app directory, found ${found}`);
27
+ }
28
+
29
+ const appDir = path.join(binDir, bundles[0].name);
30
+ const plistPath = path.join(appDir, 'Contents', 'Info.plist');
31
+ let plist;
32
+ try {
33
+ plist = fs.readFileSync(plistPath, 'utf8');
34
+ } catch (err) {
35
+ throw new Error(`macOS app bundle is incomplete: cannot read ${plistPath} (${err.code})`);
36
+ }
37
+
38
+ const match = CFBUNDLE_EXECUTABLE_RE.exec(plist);
39
+ const executable = match ? match[1].trim() : '';
40
+ if (
41
+ !executable ||
42
+ executable === '.' ||
43
+ executable === '..' ||
44
+ executable.includes('/') ||
45
+ executable.includes('\\')
46
+ ) {
47
+ throw new Error(`macOS app bundle is incomplete: valid CFBundleExecutable not found in ${plistPath}`);
48
+ }
49
+
50
+ return path.join(appDir, 'Contents', 'MacOS', executable);
51
+ }
52
+
53
+ function assertExecutable(platform, binDir) {
54
+ const binPath = resolveBinPath(platform, binDir);
55
+ let stat;
56
+ try {
57
+ stat = fs.statSync(binPath);
58
+ } catch (err) {
59
+ throw new Error(`macOS app bundle is incomplete: executable missing at ${binPath} (${err.code})`);
60
+ }
61
+ if (!stat.isFile()) {
62
+ throw new Error(`macOS app bundle is incomplete: not a regular file at ${binPath}`);
63
+ }
64
+ return binPath;
65
+ }
66
+
67
+ module.exports = { resolveBinPath, assertExecutable };
package/run.js CHANGED
@@ -3,13 +3,27 @@ const { spawn } = require('child_process');
3
3
  const path = require('path');
4
4
  const os = require('os');
5
5
  const fs = require('fs');
6
+ const { resolveBinPath } = require('./resolve-bin');
6
7
 
7
- const binName = os.platform() === 'win32' ? 'agentscommander.exe' : 'agentscommander';
8
- const binPath = path.join(__dirname, 'bin', binName);
8
+ const binDir = path.join(__dirname, 'bin');
9
+
10
+ const IGNORE_SCRIPTS_HINT =
11
+ 'Hint: if npm install ran with --ignore-scripts, reinstall without that flag, or run: npm rebuild -g @mblua/agentscommander';
12
+
13
+ let binPath;
14
+ try {
15
+ binPath = resolveBinPath(os.platform(), binDir);
16
+ } catch (err) {
17
+ console.error(`Error: ${err.message}`);
18
+ console.error('Please ensure the package was installed correctly.');
19
+ console.error(IGNORE_SCRIPTS_HINT);
20
+ process.exit(1);
21
+ }
9
22
 
10
23
  if (!fs.existsSync(binPath)) {
11
24
  console.error(`Error: Cannot find AgentsCommander executable at ${binPath}`);
12
25
  console.error('Please ensure the package was installed correctly.');
26
+ console.error(IGNORE_SCRIPTS_HINT);
13
27
  process.exit(1);
14
28
  }
15
29
 
@@ -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 };