Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
node_modules/
*.tgz
.test-artifacts/
/release-work/

23 changes: 23 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,27 @@
# Changelog

## 1.0.4 — 2026-10-13

**Users on version 1.0.x can update normally. No configuration changes or migration are required. This also applies to 1.0.0-beta.1.**

### ⚠️ Upgrading from a version before 1.0.0

**Only these older versions require migration. Back up your Homebridge config.json before updating, then follow the [migration guide](https://github.com/pponce/homebridge-script2/blob/master/MIGRATION.md).** Legacy Script2 accessory mode and old platform configuration formats are no longer supported.

### Successful commands with stderr

- Treat ON/OFF and stateless trigger commands that exit `0` as successful when they write stderr, including switches using a state file (issue #125).
- Log a warning when stderr is present and show bounded, escaped stderr text in Homebridge debug logs. Ordinary logs continue to omit script output.
- Preserve action failures for nonzero exits and execution errors, and keep the configurable nonzero state-script policy from issue #29.

Debug stderr may include sensitive script output. Remove secrets before sharing logs.

### Update

Select **1.0.4** / **latest** in Homebridge UI and restart the instance or child bridge running Script2.

[Full 1.0.4 release notes](releases/v1.0.4.md)

## 1.0.3 — 2026-09-11

# ⚠️ **BREAKING CHANGE — BACK UP YOUR CONFIGURATION BEFORE UPDATING.**
Expand Down Expand Up @@ -86,3 +108,4 @@ Select **1.0.3** / **latest** in Homebridge UI and restart the instance or child

- Added optional early HomeKit acknowledgement for long-running commands, serialized and coalesced SET requests, deferred state reads, and custom UI saving fixes.
- See [published release notes](https://github.com/pponce/homebridge-script2/releases/tag/v0.4.6) for the original release history.

21 changes: 15 additions & 6 deletions DEVELOPMENT.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Script2 development and release

1.0.4 accepts exit-zero ON/OFF and stateless trigger commands that write stderr, warns in normal logs, and exposes bounded stderr text in Homebridge debug logs. The configurable nonzero state-script behavior is preserved. No configuration migration is needed from stable 1.0.x releases.

1.0.2 includes Dependabot PR #123: the development-only fast-uri lockfile entry moves to 3.1.7. The 1.0.1 schema fix remains in place; runtime behavior and dependencies are unchanged.

1.0.1 fixes configuration-schema metadata while preserving existing configurations. Runtime code and dependencies are unchanged from 1.0.0. Ajv is a pinned development dependency used to validate the schema against JSON Schema rules; it is not installed as a runtime dependency of the plugin. Publication does not imply Homebridge verification.
Expand All @@ -12,23 +14,29 @@ Run `python3 scripts/check-publisher.py beta` and `python3 scripts/check-publish

Production versions are pinned in package-lock.json. npm ci validates the locked versions in GitHub Actions. The lock's integrity metadata can be refreshed with npm on a connected host. Live Homebridge behavior still depends on the maintainer's configured scripts and service environment.

## Publish 1.0.2 from SSH
## Publish 1.0.4 from SSH

The local checkout is `~/devProjects/homebridge-script2`. The stable publisher requires `master` to match `origin/master`. GitHub account: `pponce`; npm account: `klidec`.

Copy the complete contents of [scripts/update-and-publish-stable.txt](scripts/update-and-publish-stable.txt) into the SSH shell. It uses one outer brace block, a child Bash process, `set -e`, and beginning/end output markers. A failure stops the child process while leaving SSH open. Review the reported status before continuing.
Use the complete bootstrap block supplied in the maintainer conversation to fetch the prepared tools and [update wrapper](scripts/update-and-publish-stable.txt) over SSH into `release-work/bootstrap/`. It uses one outer brace block, a child Bash process, `set -e`, and beginning/end output markers. A failure stops the child process while leaving SSH open. Review the reported status before continuing.

The complete release block supplied in the maintainer conversation fetches the prepared source over SSH, loads the release tools and update wrapper from that commit, waits for PR #126 checks, and merges the prepared head before publishing.

The helper refuses dirty/unexpected checkouts and existing versions/tags. It validates matching package/lockfile versions, a versioned changelog entry and release notes, packs a source snapshot, installs and tests the exact archive, then publishes `homebridge-script2@1.0.4` to npm `latest`. It creates a normal GitHub release marked latest from the exact source commit, using [releases/v1.0.4.md](releases/v1.0.4.md), with the archive and both final PNG icons attached. The publisher checks the official release body against the notes file and verifies npm's latest tag.

The helper refuses dirty/unexpected checkouts and existing versions/tags. It validates and packs a source snapshot, installs and tests the exact archive, then publishes `homebridge-script2@1.0.2` to npm `latest`. It creates a normal GitHub release marked latest from the exact source commit, using [releases/v1.0.2.md](releases/v1.0.2.md), with the archive and both final PNG icons attached.
Git fetch/pull/tag operations use the repository's SSH remote. Creating the official GitHub release still requires GitHub API authentication: the publisher tests actual API access and starts the browser/device-code login when necessary, instead of relying only on `gh auth status`. Environment token overrides are cleared in the child shell; `GH_BROWSER=echo` displays the browser URL for manual opening.

Interactive commands reconnect to the controlling SSH terminal even though the outer wrapper reads commands from a heredoc. npm uses `--browser=false`: open the displayed authentication URL in your local browser and leave SSH running while npm waits. An existing npm login does not eliminate publish-time authentication. A failed attempt's URL should not be reused.
All release work is contained in `~/devProjects/homebridge-script2/release-work/`, which is ignored by Git. The tools helper downloads the official GitHub CLI 2.102.0 Linux archive into `release-work/tools/`, verifies its published SHA-256 digest, and selects that binary for this release process. Build snapshots, package archives, and test installs are under `release-work/1.0.4/`; npm's cache and subprocess temporary files are under `release-work/npm-cache/` and `release-work/tmp/`. Authentication uses the standard GitHub/npm credential settings.

Interactive commands reconnect to the controlling SSH terminal even though the outer wrapper reads commands from a heredoc. npm uses `--browser=false` for login and publish: open the displayed authentication URL in your local browser and leave SSH running while npm waits. An existing npm login does not eliminate publish-time authentication. A failed attempt's URL should not be reused.

If npm succeeds but GitHub fails, inspect for a partial release and use the printed GitHub-only recovery command if the release is absent. Never publish the same npm version again. The helper does not install the plugin into the running Homebridge instance.

## Release warnings

The release notes and changelog use a large Markdown heading with a warning symbol and bold backup instruction. Homebridge's Release Notes tab obtains the published GitHub release body; its separate Changelog tab may obtain the tagged or installed CHANGELOG.md. Updating a branch file alone does not rewrite either an existing GitHub release body or an already-published npm archive.
The current release notes and changelog first state that 1.0.x users can update without configuration changes or migration. A separate warning explicitly applies only to upgrades from versions before 1.0.0; retain the backup instruction and migration link in that section. The same normal-upgrade guidance applies to 1.0.0-beta.1. Homebridge's Release Notes tab obtains the published GitHub release body; its separate Changelog tab may obtain the tagged or installed CHANGELOG.md. Updating a branch file alone does not rewrite either an existing GitHub release body or an already-published npm archive.

The 1.0.1 archive includes the enlarged changelog warning. Keep it prominent in future 1.0 release notes while users are migrating from pre-1.0 configurations.
Historical 1.0.1–1.0.3 notes used an enlarged general warning. From 1.0.4 onward, make the affected upgrade path explicit instead of presenting that warning to every user.

## Future beta releases

Expand All @@ -42,3 +50,4 @@ The older [beta publisher](scripts/publish-beta.sh) and [SSH wrapper](scripts/up
- For early acknowledgement, verify a long-running success and late failure without duplicate commands.
- Confirm shutdown/restart and room/scene/automation assignments.
- Inspect the warning in Homebridge's Release Notes and Changelog tabs.

19 changes: 12 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,15 @@

Run your own scripts from Apple Home and Siri using Homebridge.

# ⚠️ **BREAKING CHANGE — BACK UP YOUR CONFIGURATION BEFORE UPDATING.**
**Users on version 1.0.x can update normally. No configuration changes or migration are required. This also applies to 1.0.0-beta.1.**

**Version 1.0.0 removes legacy Script2 accessory mode and old platform configuration formats. Review and save a copy of your current Homebridge config.json before installing, then follow the [migration guide](https://github.com/pponce/homebridge-script2/blob/master/MIGRATION.md). Legacy configurations will no longer run.**
## ⚠️ Upgrading from a version before 1.0.0

**Stable release: 1.0.2.** Install the `latest` channel. Homebridge verification is pending; this release does not claim certification.
**Only these older versions require migration. Back up your Homebridge config.json before updating, then follow the [migration guide](https://github.com/pponce/homebridge-script2/blob/master/MIGRATION.md).** Legacy Script2 accessory mode and old platform configuration formats are no longer supported.

**Updating from 1.0.0 or 1.0.1?** Version 1.0.2 includes the schema fix and development dependency maintenance. No configuration changes are required.
**Stable release: 1.0.4.** Install the `latest` channel. Homebridge verification is pending; this release does not claim certification.

**Updating from a stable 1.0.x release?** Version 1.0.4 accepts successful commands that write stderr and adds debug stderr details. No configuration changes are required.

[Quick start](#quick-start) · [Migration](#migration) · [Minimal configuration](#minimal-configuration) · [Settings reference](#settings-reference) · [Full example](#full-configuration-example) · [Advanced behavior](#advanced-behavior) · [FAQ](#troubleshooting-faq) · [Changelog](CHANGELOG.md)

Expand All @@ -30,7 +32,7 @@ See [advanced behavior](#advanced-behavior) for execution details and [the featu

1. Save a Homebridge backup and your full config.json.
2. Follow [Migration](#migration) if you use an older configuration.
3. In Homebridge UI, install Script2 and select **1.0.2** / **latest** using the plugin version selector.
3. In Homebridge UI, install Script2 and select **1.0.4** / **latest** using the plugin version selector.
4. For a new setup, open Settings and add an **On/Off switch** or a **Stateless switch**. Enter your commands; On/Off switches also need a state command or state file. For an existing valid setup, keep your current entries.
5. Review Advanced settings if needed, use Homebridge Save, then restart the instance or child bridge running Script2. Opening or saving settings never runs commands.

Expand Down Expand Up @@ -216,9 +218,11 @@ A state-read result uses this format:
GetState <name>: ON/OFF (path: <request origin>, source: <state source>)
```

The request origin is `homekit-get` or `polling`; the state source is `state-script`, `ttl-cache`, `in-flight-coalesced`, or `file-state`. Errors identify the accessory and action. Raw commands, stdout, and stderr are omitted from plugin diagnostics because scripts may contain credentials.
The request origin is `homekit-get` or `polling`; the state source is `state-script`, `ttl-cache`, `in-flight-coalesced`, or `file-state`. Errors identify the accessory and action. Raw commands and stdout are omitted from plugin diagnostics. When a command writes nonblank stderr, Script2 logs a warning without its contents; enable Homebridge debug logging to see the stderr text, limited to 4,096 characters with control characters escaped. Debug stderr may contain credentials or other sensitive script output; remove secrets before sharing logs.

ON/OFF and trigger commands succeed when they exit `0`, even if they write stderr. Nonzero exits, timeouts, termination, and other execution errors still fail. This applies to both command-based and file-based state; changing a state file does not override an action command failure.

Timeouts, terminated state commands, and output overflow are failures even if partial output was printed. For an ordinary nonzero state-command exit, `fail_on_state_exit_code` determines whether otherwise usable stdout can still determine state. ON/OFF and trigger commands retain their stderr-as-failure policy.
Timeouts, terminated state commands, and output overflow are failures even if partial output was printed. For an ordinary nonzero state-command exit, `fail_on_state_exit_code` determines whether otherwise usable stdout can still determine state. Its default is `false`: log the nonzero exit and use usable stdout; enable it to return the state-read error to HomeKit. This setting applies only to the state command, and stderr alone does not cause a state-read failure.

### Storage and shutdown

Expand Down Expand Up @@ -374,3 +378,4 @@ sudo -u homebridge /home/homebridge/scripts/light_off.sh
---

Originally based on [homebridge-script](https://github.com/xxcombat/homebridge-script).

23 changes: 17 additions & 6 deletions index.js
Original file line number Diff line number Diff line change
Expand Up @@ -209,6 +209,17 @@ Script2DeviceLogic.prototype.formatCommandDiagnostics = function (action, comman
return `${this.name}: ${action} command ${error?.killed ? "timed out or was terminated" : "failed"} (exit code: ${code}). Check the script as the Homebridge service user. Command text and output are omitted.`;
};

Script2DeviceLogic.prototype.logCommandStderr = function (action, stderr) {
const output = String(stderr ?? "").trim();
if (!output) return;
this.log.warn(`${this.name}: ${action} command wrote to stderr (enable Homebridge debug logging for details).`);
// Keep diagnostic output bounded and escape control characters so script output
// cannot insert terminal sequences or impersonate another log entry.
const limit = 4096;
const preview = JSON.stringify(output.slice(0, limit));
this.log.debug(`${this.name}: ${action} command stderr: ${preview}${output.length > limit ? " [truncated]" : ""}`);
};

Script2DeviceLogic.prototype.executeCommand = function (command, options, callback) {
if (this.stopped) return;
let child;
Expand Down Expand Up @@ -424,13 +435,13 @@ Script2DeviceLogic.prototype.startSetCommand = function (setRequest) {

let callbackError = null;

if (error || stderr) {
this.logCommandStderr(action, stderr);
if (error) {
const diagnostics = this.formatCommandDiagnostics(action, command, error, stdout, stderr);
const errMessage = `Set State returned an error. ${diagnostics}`;
this.log.error(`Set State returned an error: ${errMessage}`);
callbackError = new Error(errMessage);
} else {
const commandOutput = stdout.trim().toLowerCase();
this.log.debug(`${this.name}: set command completed.`);

this.currentState = powerOn;
Expand Down Expand Up @@ -627,9 +638,7 @@ Script2DeviceLogic.prototype.getState = function (
const cleanCommandOutput = stdout.trim().toLowerCase();
this.log.debug(`${this.name}: state command returned output.`);

if (stderr && stderr.trim().length > 0) {
this.log.warn(`${this.name}: state command wrote to stderr (output omitted).`);
}
this.logCommandStderr("state", stderr);

if (!cleanCommandOutput) {
const diagnostics = this.formatCommandDiagnostics("state", command, error, stdout, stderr);
Expand Down Expand Up @@ -684,7 +693,8 @@ Script2DeviceLogic.prototype.setStatelessTrigger = function (powerOn, callback)
this.commandExecutor(this.triggerCommand, { timeout: this.commandTimeout }, (error, stdout, stderr) => {
this.triggerInFlight = false;
const callbacks = this.triggerCallbacks.splice(0);
const failure = error || stderr ? new Error(this.formatCommandDiagnostics("trigger", this.triggerCommand, error)) : null;
this.logCommandStderr("trigger", stderr);
const failure = error ? new Error(this.formatCommandDiagnostics("trigger", this.triggerCommand, error)) : null;
if (failure) this.log.error(failure.message);
else this.log.info(`Triggered ${this.name} stateless action`);
for (const cb of callbacks) cb(failure, failure ? null : powerOn);
Expand Down Expand Up @@ -782,3 +792,4 @@ Script2DeviceLogic.prototype.updateReachabilityFault = function (hasFault) {

module.exports.Script2DeviceLogic = Script2DeviceLogic;
module.exports.Script2Platform = Script2Platform;

5 changes: 3 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 2 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "homebridge-script2",
"version": "1.0.3",
"version": "1.0.4",
"license": "MIT",
"description": "HomeKit script switches with file or command state, shared reads, serialized actions and optional early acknowledgement",
"keywords": [
Expand Down Expand Up @@ -63,3 +63,4 @@
"ajv": "8.17.1"
}
}

23 changes: 23 additions & 0 deletions releases/v1.0.4.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# Script2 1.0.4

**Users on version 1.0.x can update normally. No configuration changes or migration are required. This also applies to 1.0.0-beta.1.**

## ⚠️ Upgrading from a version before 1.0.0

**Only these older versions require migration. Back up your Homebridge config.json before updating, then follow the [migration guide](https://github.com/pponce/homebridge-script2/blob/master/MIGRATION.md).** Legacy Script2 accessory mode and old platform configuration formats are no longer supported.

## Successful commands with stderr

- ON/OFF and stateless trigger commands that exit `0` now succeed even when they write stderr. This also applies to ON/OFF scripts that create or delete a state file, and addresses the failure mechanism suspected in [issue #125](https://github.com/pponce/homebridge-script2/issues/125).
- Nonzero action exits, timeouts, termination, and other execution errors still return failures to HomeKit.
- Preserve the state-script policy from [issue #29](https://github.com/pponce/homebridge-script2/issues/29): by default, log ordinary nonzero exits and use usable stdout; with `fail_on_state_exit_code` enabled, return a state-read error to HomeKit. This option applies only to state scripts.

## Stderr diagnostics

- Normal logs show a warning when ON, OFF, trigger, or state commands write nonblank stderr.
- Enable Homebridge debug logging to see stderr text, limited to 4,096 characters with control characters escaped.
- Raw command text and stdout remain omitted. Debug stderr may contain credentials or other sensitive script output; remove secrets before sharing logs.

## Update

Select **1.0.4** / **latest** in Homebridge UI and restart the instance or child bridge running Script2.
Loading
Loading