fix(build): set executable permissions on CLI bin files (#359)

TypeScript's tsc compiler does not preserve executable permissions on output files, requiring explicit chmod in build scripts.

Changes:
- Add chmod +x to build scripts for CLI packages (cli, device-profiler, mqtt-bridge)
- Set executable permissions on both ESM and CJS bin files
- Simplify mqtt-bridge prepublishOnly script (no longer needs separate chmod)
- Document CLI package requirements and shebang requirement in package-creation.md
- Add comprehensive CLI package section to NEW-PACKAGE.md

TypeScript does not support preserving executable permissions (see TypeScript issues #37583, #16257, #26060). The chmod approach in build scripts is the industry-standard solution.

Related: #360, #361

Author: groupsky

docs/NEW-PACKAGE.md

@@ -318,11 +318,52 @@ This pattern ensures the factory defaults are always valid according to the devi
 
 See `packages/driver-xymd1` for reference implementation.
 
+### CLI Package
+
+CLI packages expose executable commands via the npm `bin` field.
+
+**Required configuration**:
+
+```json
+{
+  "bin": {
+    "command-name": "./dist/esm/bin/command.js"
+  }
+}
+```
+
+**Required structure**:
+
+- `bin/` directory with executable TypeScript source files
+- Each bin file MUST start with shebang: `#!/usr/bin/env node`
+- TypeScript config MUST use `"rootDir": "."` to include both `src` and `bin`
+- Build script MUST set executable permissions after compilation
+
+**Example build script**:
+
+```json
+{
+  "scripts": {
+    "build": "npm run build:esm && npm run build:cjs && npm run build:package-json && chmod +x dist/esm/bin/*.js dist/cjs/bin/*.js"
+  }
+}
+```
+
+**Why chmod is required**: TypeScript's `tsc` compiler does not preserve executable permissions on output files. The build script must explicitly set permissions after compilation.
+
+**Reference implementations**:
+
+- `packages/cli` - Main CLI tool
+- `packages/device-profiler` - Profiling CLI
+- `packages/mqtt-bridge` - Bridge CLI
+
+See `docs/agents/package-creation.md` for technical details on CLI package structure.
+
 ### Utility Package
 
 Utility packages should use scoped naming: `@ya-modbus/<name>`
 
-Examples: `@ya-modbus/driver-types`, `@ya-modbus/cli`
+Examples: `@ya-modbus/driver-types`, `@ya-modbus/core`
 
 ## Getting Help
 

docs/agents/package-creation.md

@@ -48,10 +48,15 @@ ALL packages MUST use consistent tsconfig structure:
 - `types`: `"./dist/esm/src/index.d.ts"`
 - `exports["."]` points to `dist/{esm,cjs}/src/index.js`
 - `bin` (if present): `"./dist/esm/bin/<name>.js"`
+- Bin files MUST include shebang (`#!/usr/bin/env node` as first line)
+- Build script MUST set executable permissions on bin files (ESM and CJS)
 
 CRITICAL: Using `rootDir: "."` for all packages ensures consistent output structure and prevents configuration errors when adding bin executables.
 
+CRITICAL: TypeScript compilation does not preserve executable permissions. Add `chmod +x` to build script for all bin files.
+
 See: packages/cli for reference package with bin executable
+See: packages/cli/package.json (build script) for chmod pattern
 See: packages/driver-xymd1 for reference library package
 
 ### CommonJS Module Interop

packages/cli/package.json

@@ -47,7 +47,7 @@
   "license": "GPL-3.0-or-later",
   "author": "Geno Roupsky <185580+groupsky@users.noreply.github.com>",
   "scripts": {
-    "build": "npm run build:esm && npm run build:cjs && npm run build:package-json",
+    "build": "npm run build:esm && npm run build:cjs && npm run build:package-json && chmod +x dist/esm/bin/ya-modbus.js dist/cjs/bin/ya-modbus.js",
     "build:esm": "../../node_modules/.bin/tsc -p tsconfig.esm.json",
     "build:cjs": "../../node_modules/.bin/tsc -p tsconfig.cjs.json",
     "build:package-json": "echo '{\"type\":\"module\"}' > dist/esm/package.json && echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",

packages/device-profiler/package.json

@@ -34,7 +34,7 @@
   },
   "author": "Geno Roupsky <185580+groupsky@users.noreply.github.com>",
   "scripts": {
-    "build": "npm run build:esm && npm run build:cjs && npm run build:package-json",
+    "build": "npm run build:esm && npm run build:cjs && npm run build:package-json && chmod +x dist/esm/bin/profile.js dist/cjs/bin/profile.js",
     "clean": "rm -rf dist",
     "lint": "eslint .",
     "test": "jest",

packages/mqtt-bridge/package.json

@@ -37,11 +37,11 @@
     "access": "public"
   },
   "scripts": {
-    "build": "npm run build:esm && npm run build:cjs && npm run build:package-json",
+    "build": "npm run build:esm && npm run build:cjs && npm run build:package-json && chmod +x dist/esm/bin/ya-modbus-bridge.js dist/cjs/bin/ya-modbus-bridge.js",
     "clean": "rm -rf dist",
     "test": "jest",
     "lint": "eslint .",
-    "prepublishOnly": "npm run build && chmod +x dist/esm/bin/ya-modbus-bridge.js",
+    "prepublishOnly": "npm run build",
     "build:esm": "../../node_modules/.bin/tsc -p tsconfig.esm.json",
     "build:cjs": "../../node_modules/.bin/tsc -p tsconfig.cjs.json",
     "build:package-json": "echo '{\"type\":\"module\"}' > dist/esm/package.json && echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",