chore: add eslint and prettier, automate versioning from PR titles

ESLint uses the type-aware strict ruleset, because the rules that matter for
a tool doing async I/O against a live house — floating promises, misused
promises — cannot be detected without type information.

Two rules encode existing invariants instead of taste:

- no-console is an error everywhere in src/ except cli.ts, which owns
  stdout/stderr. This immediately caught three console.warn calls in
  sync/manifest.ts that bypassed ctx.log entirely: they could not be
  captured by tests and ignored --json. loadManifest now takes a warn
  callback and every caller threads ctx.log.warn through.
- no-floating-promises is an error. node:test's describe/it are declared
  safe via allowForKnownSafeCalls rather than disabling the rule in tests,
  which would have hidden real cases.

Three strictTypeChecked rules are off with reasoning recorded in the config.
The significant one is no-unnecessary-condition: socket.emit<T>() returns T,
but that type is a claim about what the server should send rather than a
guarantee, so guards like `result?.rows ?? []` look redundant to the rule
and are essential at runtime. prefer-nullish-coalescing exempts strings
because ioBroker represents "unset" as an empty string, making `||` the
correct operator and `??` a silent bug.

Fixes found while clearing the remaining reports: dead imports in new.ts,
pull.ts, list.ts and cli.ts; non-null assertions replaced with narrowing;
and WebSocket RawData stringified properly — the array-of-Buffers form
produced "[object Object]" and would have failed to parse for a reason
invisible in a stack trace.

PR titles are validated as conventional commits, since the title becomes
the squash commit and drives the version bump. release-please maintains a
release PR rather than publishing automatically; npm publish stays manual.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: mschmicking

.github/workflows/ci.yml

@@ -27,6 +27,12 @@ jobs:
 
       - run: npm ci
 
+      - name: Lint
+        run: npm run lint
+
+      - name: Formatting
+        run: npm run format:check
+
       - name: Typecheck
         run: npx tsc -p tsconfig.json --noEmit
 

.github/workflows/pr-title.yml

@@ -0,0 +1,49 @@
+name: PR title
+
+# The PR title becomes the squashed commit message, and release-please derives the
+# next version from it. A title that does not parse means a release that silently
+# does not happen, so it is validated before merge rather than discovered after.
+on:
+  pull_request_target:
+    types: [opened, edited, synchronize, reopened]
+
+permissions:
+  pull-requests: read
+
+jobs:
+  conventional-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          # feat -> minor, fix/perf -> patch, feat! or a BREAKING CHANGE footer -> major.
+          # The rest are patch-or-nothing and never drive a release on their own.
+          types: |
+            feat
+            fix
+            perf
+            refactor
+            docs
+            test
+            build
+            ci
+            chore
+            revert
+          # Optional, but keep the vocabulary small so it stays meaningful.
+          scopes: |
+            sync
+            auth
+            watch
+            logs
+            json
+            cli
+            deps
+            docs
+          requireScope: false
+          # Subject should read like a sentence fragment, lower-case, no full stop.
+          subjectPattern: ^(?![A-Z])(?!.*\.$).+$
+          subjectPatternError: |
+            The subject "{subject}" is invalid: start lower-case and omit the trailing
+            full stop, e.g. "feat(logs): stream the server log".

.github/workflows/release-please.yml

@@ -0,0 +1,27 @@
+name: Release PR
+
+# Maintains an open "chore(main): release x.y.z" pull request that accumulates every
+# merged change, derives the next version from the conventional-commit history, and
+# rewrites CHANGELOG.md. Nothing is versioned or tagged until that PR is merged.
+#
+# Chosen over fully automatic publishing on purpose: releasing is irreversible on npm,
+# so there is a human gate. Merging the release PR tags the commit; the actual
+# `npm publish` stays in release.yml, which is manual.
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v4
+        with:
+          release-type: node
+          # Keeps the existing hand-written CHANGELOG entries intact by appending
+          # below the header rather than replacing the file.
+          changelog-notes-type: default

.prettierignore

@@ -0,0 +1,5 @@
+dist/
+dist-test/
+node_modules/
+package-lock.json
+test/fixtures/*.pem

.prettierrc.json

@@ -0,0 +1,7 @@
+{
+  "printWidth": 100,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "semi": true,
+  "arrowParens": "always"
+}

AGENTS.md

@@ -30,13 +30,13 @@ instruction from the user:
 3. **Conflicts block.** If local and remote both changed, refuse and exit non-zero.
 4. **Deletion is explicit.** Only `remove`, `rename` and `move` delete anything, each
    requires `--yes`, and each writes the full object JSON to `.iobroker-sync/trash/`
-   *before* deleting. A failed backup aborts the operation.
+   _before_ deleting. A failed backup aborts the operation.
 5. **Copy-then-delete must verify first.** ioBroker has no native rename/move, so both
    are implemented as copy-verify-delete. The verification compares the actual source
    text. Checking only that "something exists at the new id" is not verification — a
    truncated copy would pass and the original would be destroyed.
 6. **`backup` is read-only and all-or-nothing.** It fetches objects and writes files,
-   never mutating the server. It stores the *whole* object, not just the source, because
+   never mutating the server. It stores the _whole_ object, not just the source, because
    `push` cannot write `common.enabled` or `common.engine` back (invariant 2) — so
    `objects/*.json` is the only record of those. A partial snapshot is worse than none,
    so any write failure aborts with a `UserError` rather than leaving a plausible-looking
@@ -111,7 +111,7 @@ infinite-loops on connection errors against this server.
   never be closed, and nothing would appear until exit.
 - User-facing failures are `UserError` (message + optional hint); `cli.ts` prints them
   without a stack trace and sets exit code 1.
-- Comments explain *why*, not *what*. The non-obvious protocol and safety reasoning is
+- Comments explain _why_, not _what_. The non-obvious protocol and safety reasoning is
   worth writing down; restating the code is not.
 - No new npm dependencies without a good reason. Current set: `ws`, `commander`,
   `chokidar`, `diff`.
@@ -138,7 +138,7 @@ and the commands `pull`, `push`, `status`, `diff` (including `--against`), `watc
 `sync/manifest` and `sync/scan` are covered indirectly by every pull/push test.
 
 `test/cli.test.ts` spawns the built `dist/cli.js` and asserts on real argv handling.
-It exists because a duplicate `--password-stdin` declaration — global *and* on the
+It exists because a duplicate `--password-stdin` declaration — global _and_ on the
 `login` subcommand — was silently shadowed by commander, and no in-process test could
 see it. **Anything about option wiring, exit codes or stdout/stderr separation belongs
 there, and it needs `dist/` built first.**
@@ -178,7 +178,7 @@ The password must never reach the project directory, argv, or a log line:
   (override with `IOBROKER_SYNC_CREDENTIALS`, which every test does so the suite never
   reads the developer's real store), mode `0600` in a `0700` directory, written
   temp-then-rename so an interrupted write cannot truncate it.
-- `iob-sync login` verifies a password against the live instance *before* saving, so a
+- `iob-sync login` verifies a password against the live instance _before_ saving, so a
   typo fails now rather than on the next command.
 - Prompts require stdin **and** stdout to be TTYs, so a script, CI job or agent gets a
   `UserError` instead of a hang.
@@ -200,7 +200,7 @@ that can actually drive the watcher:
 
 1. `watch()` returned before chokidar finished its initial scan, so any edit saved in
    that window was silently dropped. It now awaits the `ready` event.
-2. `lastPushedHash` was recorded *after* the server write completed, so an adapter
+2. `lastPushedHash` was recorded _after_ the server write completed, so an adapter
    echo arriving mid-flight escaped the echo guard and produced a spurious pull. The
    hash is now recorded before the write.
 
@@ -237,3 +237,30 @@ The CLI is a tool; the scripts it syncs belong in their own repository. Do not a
 `scripts/` directory here — running `iob-sync init` inside this repo is what caused the
 `tsconfig.json` breakage above. Test commands against `test/fake-server.ts` and
 temporary project directories instead.
+
+## Linting and formatting
+
+```bash
+npm run lint          # eslint, type-aware
+npm run format        # prettier --write
+npm run verify        # lint + format check + typecheck + tests
+```
+
+Two rules encode invariants rather than taste, and must not be relaxed:
+
+- **`no-console` is an error everywhere in `src/` except `cli.ts`.** Only the CLI layer
+  owns stdout/stderr; everything else goes through `ctx.log`. This caught three
+  `console.warn` calls in `sync/manifest.ts` that bypassed the logger entirely — they
+  could not be captured by tests and ignored `--json`. `loadManifest` now takes a
+  `warn` callback.
+- **`no-floating-promises` is an error.** An unawaited write to a live instance means the
+  command reports success and exits with the request still in flight. `node:test`'s
+  `describe`/`it` are declared safe via `allowForKnownSafeCalls` rather than switching
+  the rule off in tests.
+
+Three rules from `strictTypeChecked` are deliberately **off**, with the reasoning in
+`eslint.config.mjs`. The important one: `no-unnecessary-condition`. `socket.emit<T>()`
+returns `T`, but that type is a _claim_ about what the server should send, not a
+guarantee — so guards like `result?.rows ?? []` look redundant to the rule and are
+essential at runtime. Following it would trade a handled edge case for a crash against
+someone's house.

CHANGELOG.md

@@ -21,7 +21,7 @@ for the first release.
   than the server. `latest` resolves to the newest.
 - `login` / `logout` — save or remove the password for an instance. Verified against the
   live server before saving.
-- `backup` — read-only snapshot of every script's source *and* full object, since `push`
+- `backup` — read-only snapshot of every script's source _and_ full object, since `push`
   cannot restore `common.enabled` or `common.engine`.
 - Interactive `init`, which asks for URL, certificate handling, script root and username
   when run without flags, and adds `.iobroker-sync/` to `.gitignore`.
@@ -43,7 +43,7 @@ for the first release.
 - `watch` dropped edits saved before chokidar finished its initial scan. It now waits for
   the watcher to be ready before reporting that it is watching.
 - `watch` could re-pull its own push. The hash used to suppress the javascript adapter's
-  `compiled`/`sourceHash` echo was recorded *after* the server write, so an echo arriving
+  `compiled`/`sourceHash` echo was recorded _after_ the server write, so an echo arriving
   mid-write escaped the guard.
 - `login --password-stdin` always reported "no terminal available". The option was
   declared both globally and on the subcommand, and the parent silently shadowed the

README.md

@@ -8,6 +8,7 @@ search across scripts, no editor of your choice, and no way to touch them from a
 or a CI job. `iobroker-sync` maps them to a local folder and keeps the two in step.
 
 <!-- Screenshot to add before v1.0 — see docs/images/README.md for exactly what to capture. -->
+
 ![Two terminal panes side by side. On the left, a script is edited and iob-sync push reports it was uploaded. On the right, iob-sync logs is streaming the ioBroker log, where the script's own output appears a moment later.](docs/images/edit-loop.png)
 
 ## Quick start
@@ -41,13 +42,13 @@ That is the whole loop. `git init` in that folder and your home automation has h
 
 The five commands worth knowing on day one:
 
-| | |
-| --- | --- |
-| `iob-sync pull` | bring the server's scripts down |
-| `iob-sync status` | what differs, locally and remotely |
-| `iob-sync push` | send your edits up |
-| `iob-sync logs` | watch script output — **this is how you find out a push actually worked** |
-| `iob-sync backup` | snapshot everything before you touch something important |
+|                   |                                                                           |
+| ----------------- | ------------------------------------------------------------------------- |
+| `iob-sync pull`   | bring the server's scripts down                                           |
+| `iob-sync status` | what differs, locally and remotely                                        |
+| `iob-sync push`   | send your edits up                                                        |
+| `iob-sync logs`   | watch script output — **this is how you find out a push actually worked** |
+| `iob-sync backup` | snapshot everything before you touch something important                  |
 
 ## Contents
 
@@ -84,24 +85,24 @@ The [ioBroker JavaScript VS Code extension](https://github.com/nokxs/iobroker-ja
 by nokxs solves the same core problem and inspired this tool. If you work in VS Code, it
 is genuinely good and does things a CLI cannot — go use it.
 
-| | iobroker-sync | VS Code extension |
-| --- | --- | --- |
-| Editor | any, or none | VS Code |
-| State-ID autocompletion, hover values | — | yes |
-| Script tree, buttons, context menus | — (`iob-sync list`) | yes |
-| Works over SSH, in CI, headless | yes | — |
-| Machine-readable output | yes | — |
-| Scriptable from a shell or an agent | yes | — |
+|                                       | iobroker-sync       | VS Code extension |
+| ------------------------------------- | ------------------- | ----------------- |
+| Editor                                | any, or none        | VS Code           |
+| State-ID autocompletion, hover values | —                   | yes               |
+| Script tree, buttons, context menus   | — (`iob-sync list`) | yes               |
+| Works over SSH, in CI, headless       | yes                 | —                 |
+| Machine-readable output               | yes                 | —                 |
+| Scriptable from a shell or an agent   | yes                 | —                 |
 
 Rough rule: **if you live in VS Code, use the extension.** If you want your own editor, a
 git-first workflow, or anything automated, use this. They are not exclusive — both talk
 to the same Admin API, and this tool never writes fields it does not own.
 
 ## How scripts map to files
 
-| ioBroker object | local file |
-| --- | --- |
-| `script.js.common.garage` (`TypeScript/ts`) | `scripts/common/garage.ts` |
+| ioBroker object                                | local file                    |
+| ---------------------------------------------- | ----------------------------- |
+| `script.js.common.garage` (`TypeScript/ts`)    | `scripts/common/garage.ts`    |
 | `script.js.Switch-Musiccast` (`Javascript/js`) | `scripts/Switch-Musiccast.js` |
 
 Script folders are ioBroker `channel` objects; nested folders map to nested directories.
@@ -134,26 +135,26 @@ iob-sync logs --level error    # only failures
 
 **Sync**
 
-| Command | Description |
-| --- | --- |
-| `init` | Write `.iobroker-sync.json`, verify the connection, create the script folder. Asks interactively when run without flags. `--types` also sets up TypeScript definitions. |
-| `login` / `logout` | Save or remove the password for this instance. Never stored in the project. |
-| `pull [pattern]` | Download scripts to disk. Never deletes local files. |
-| `push [pattern]` | Upload locally modified scripts. Never deletes remote objects. |
-| `status` | Show what changed, locally and remotely. |
-| `diff [pattern]` | Unified diff of local vs server. `--against <snapshot>` compares with a backup instead. |
-| `watch` | Push on save. `--pull` also applies remote changes. |
-| `logs [pattern]` | Stream the server log. `--level`, `--limit`. Read-only. |
-| `backup [pattern]` | Snapshot every script — source *and* full object — to `.iobroker-sync/backup/<timestamp>/`. Read-only against the server. |
+| Command            | Description                                                                                                                                                             |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `init`             | Write `.iobroker-sync.json`, verify the connection, create the script folder. Asks interactively when run without flags. `--types` also sets up TypeScript definitions. |
+| `login` / `logout` | Save or remove the password for this instance. Never stored in the project.                                                                                             |
+| `pull [pattern]`   | Download scripts to disk. Never deletes local files.                                                                                                                    |
+| `push [pattern]`   | Upload locally modified scripts. Never deletes remote objects.                                                                                                          |
+| `status`           | Show what changed, locally and remotely.                                                                                                                                |
+| `diff [pattern]`   | Unified diff of local vs server. `--against <snapshot>` compares with a backup instead.                                                                                 |
+| `watch`            | Push on save. `--pull` also applies remote changes.                                                                                                                     |
+| `logs [pattern]`   | Stream the server log. `--level`, `--limit`. Read-only.                                                                                                                 |
+| `backup [pattern]` | Snapshot every script — source _and_ full object — to `.iobroker-sync/backup/<timestamp>/`. Read-only against the server.                                               |
 
 **Lifecycle**
 
-| Command | Description |
-| --- | --- |
-| `list` | All scripts with instance and enabled state. |
-| `start` / `stop` / `restart` `<pattern>` | Toggle `common.enabled`. |
-| `new <path>` | Create a new script (disabled) plus any missing folders. |
-| `rename` / `move` / `remove` | Destructive. Require `--yes` and back up the object first. `remove` keeps the local file unless `--delete-local`. |
+| Command                                  | Description                                                                                                       |
+| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `list`                                   | All scripts with instance and enabled state.                                                                      |
+| `start` / `stop` / `restart` `<pattern>` | Toggle `common.enabled`.                                                                                          |
+| `new <path>`                             | Create a new script (disabled) plus any missing folders.                                                          |
+| `rename` / `move` / `remove`             | Destructive. Require `--yes` and back up the object first. `remove` keeps the local file unless `--delete-local`. |
 
 `--dry-run`, `--verbose`, `--json` and `-C <dir>` are global options and work with every
 command. When in doubt, `--dry-run` shows what would happen and changes nothing.
@@ -172,7 +173,7 @@ destroying work:
 - **`pull` never deletes local files.** A script removed on the server shows up in `status`
   as `remote-missing`; what to do about it is your call.
 - **`push` never deletes remote objects**, and writes only `common.source` and
-  `common.engineType`. It *cannot* disable a running script or move it to a different
+  `common.engineType`. It _cannot_ disable a running script or move it to a different
   javascript instance, because it never sends those fields — a sync bug structurally
   cannot stop your heating.
 - **Conflicts block.** A manifest at `.iobroker-sync/state.json` records the source hash at
@@ -215,12 +216,12 @@ in a `0700` directory, outside your repo. `iob-sync logout` removes it.
 There is deliberately **no `--password` flag**: argv is visible to other local processes
 via `ps` and is recorded in shell history. The alternatives, in the order they are tried:
 
-| Source | Use |
-| --- | --- |
-| `--password-stdin` | scripts and CI: `printf '%s' "$PW" \| iob-sync --password-stdin login` |
-| `IOBROKER_PASSWORD` | ad-hoc shells |
-| saved credentials | normal interactive use, after `iob-sync login` |
-| hidden prompt | when nothing else is available and a terminal is attached |
+| Source              | Use                                                                    |
+| ------------------- | ---------------------------------------------------------------------- |
+| `--password-stdin`  | scripts and CI: `printf '%s' "$PW" \| iob-sync --password-stdin login` |
+| `IOBROKER_PASSWORD` | ad-hoc shells                                                          |
+| saved credentials   | normal interactive use, after `iob-sync login`                         |
+| hidden prompt       | when nothing else is available and a terminal is attached              |
 
 OAuth2 (`/oauth/token`) is tried first, falling back to the legacy `/login` endpoint.
 `--verbose` reports which path was used.