@mblua/agentscommander 0.34.0 → 0.36.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
@@ -53,15 +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.34.0`
56
+ ### npm `0.36.0`
57
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).
58
+ `0.36.0` is the release described by this package. Its installer downloads the `v0.36.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.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.
60
+ The `v0.36.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.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.
62
+ **Version `0.36.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.36.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
63
 
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.
64
+ **Version `0.36.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.
65
65
 
66
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.
67
67
 
@@ -90,6 +90,12 @@ Both commands must exit 0. Confirm that `npm list` and the installed `package.js
90
90
 
91
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
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
+
93
99
  ### macOS Launchpad and Spotlight
94
100
 
95
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.
@@ -106,7 +112,7 @@ Identify, back up, and verify the version-selected configuration as described ab
106
112
  npm uninstall -g @mblua/agentscommander
107
113
  ```
108
114
 
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.
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.
110
116
 
111
117
  On Windows:
112
118
 
@@ -114,6 +120,12 @@ On Windows:
114
120
  Remove-Item "$env:APPDATA\Microsoft\Windows\Start Menu\Programs\AgentsCommander.lnk"
115
121
  ```
116
122
 
123
+ On Linux:
124
+
125
+ ```bash
126
+ rm "${XDG_DATA_HOME:-$HOME/.local/share}/applications/agentscommander.desktop"
127
+ ```
128
+
117
129
  On macOS:
118
130
 
119
131
  ```bash
package/icon.png ADDED
Binary file
package/install.js CHANGED
@@ -7,8 +7,9 @@ const { execSync } = require('child_process');
7
7
  const { assertExecutable } = require('./resolve-bin');
8
8
  const { createStartMenuShortcut } = require('./windows-shortcut');
9
9
  const { createLaunchpadAlias } = require('./macos-alias');
10
+ const { createDesktopEntry } = require('./linux-desktop-entry');
10
11
 
11
- const VERSION = "0.34.0"; // Must match package.json
12
+ const VERSION = "0.36.0"; // Must match package.json
12
13
  const OWNER = 'mblua';
13
14
  const REPO = 'AgentsCommander';
14
15
 
@@ -161,6 +162,14 @@ async function main() {
161
162
  console.warn(`Warning: Start Menu shortcut not created: ${err.message}`);
162
163
  }
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
+ }
164
173
  }
165
174
 
166
175
  fs.unlinkSync(shasumTmpPath);
@@ -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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mblua/agentscommander",
3
- "version": "0.34.0",
3
+ "version": "0.36.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": {
@@ -14,7 +14,9 @@
14
14
  "install.js",
15
15
  "resolve-bin.js",
16
16
  "macos-alias.js",
17
- "windows-shortcut.js"
17
+ "windows-shortcut.js",
18
+ "linux-desktop-entry.js",
19
+ "icon.png"
18
20
  ],
19
21
  "engines": {
20
22
  "node": ">=18.0.0"