@homebridge-plugins/homebridge-august 3.2.3 → 3.3.0-beta.1

package/.github/copilot-instructions.md

@@ -1,200 +0,0 @@
-# Copilot Instructions for Homebridge August Plugin
-
-## Repository Overview
-
-This repository is a Homebridge dynamic platform plugin for August and Yale locks.
-
-- Runtime uses TypeScript + ES modules.
-- The plugin supports a dual runtime path:
-  - HAP path via AugustPlatform.
-  - Matter path via AugustMatterPlatform when Homebridge Matter is available and enabled.
-
-## Current Architecture
-
-- Plugin type: dynamic platform plugin.
-- Entry point: src/index.ts.
-- HAP platform class: src/Platform.HAP.ts (AugustPlatform).
-- Matter platform class: src/Platform.Matter.ts (AugustMatterPlatform).
-- Shared device logic: src/devices/device.ts and src/devices/lock.ts.
-- Connectivity state machine: src/connectivity-manager.ts.
-- Config/types/constants: src/settings.ts.
-- UI backend/static assets: src/homebridge-ui/.
-
-The entry point in src/index.ts registers a proxy constructor that selects Matter or HAP at runtime based on:
-- api.isMatterAvailable()
-- api.isMatterEnabled()
-- config.options.disableMatter
-
-## Toolchain and Runtime
-
-Use the values from package.json and tsconfig.json as source of truth.
-
-- Node support: ^22 || ^24
-- Homebridge support: ^2.0.0
-- TypeScript target: ES2022
-- Module: ES2022
-- Module resolution: bundler
-- Strict mode: enabled (noImplicitAny is false)
-
-## Commands
-
-### Build and Packaging
-
-```bash
-npm run clean
-npm run build
-npm run prepublishOnly
-```
-
-### Lint
-
-```bash
-npm run lint
-npm run lint:fix
-```
-
-### Test
-
-```bash
-npm test
-npm run test:watch
-npm run test-coverage
-```
-
-### Docs
-
-```bash
-npm run docs
-npm run docs:lint
-```
-
-### Development
-
-```bash
-npm run watch
-npm run plugin-ui
-```
-
-## Branch and Release Workflow
-
-This repo follows a beta-first workflow.
-
-- Do not target main directly.
-- Target a beta branch named beta-X.Y.Z.
-- Use issue labels to determine bump type:
-  - patch
-  - minor
-  - major
-
-If no matching beta branch exists, create one from the next expected version.
-
-## Coding Expectations
-
-1. Keep imports as ES module paths ending in .js.
-2. Preserve Homebridge plugin constants:
-   - PLATFORM_NAME = August
-   - PLUGIN_NAME = homebridge-august
-3. Maintain backward compatibility unless issue scope is explicitly breaking.
-4. Keep runtime and schema aligned:
-   - Update src/settings.ts and config.schema.json together for option changes.
-5. Add or update Vitest coverage for behavior changes.
-6. Never commit generated output from dist/.
-
-## Homebridge and August/Yale Patterns
-
-- Use Homebridge DynamicPlatformPlugin patterns for lifecycle methods.
-- Use PlatformAccessory caching and proper unregister/update behavior.
-- Handle August auth and refresh flows defensively.
-- Respect polling and push/update intervals from options.
-- Prefer robust error classification and graceful retries over broad catch-and-ignore.
-
-## Matter and HomeKit Integration
-
-### Matter Implementation
-
-The plugin uses a dual-mode runtime that selects HAP or Matter at startup.
-
-- HAP mode (HomeKit Accessory Protocol): implemented by AugustPlatform in src/Platform.HAP.ts.
-- Matter mode: implemented by AugustMatterPlatform in src/Platform.Matter.ts.
-
-In src/index.ts, the platform proxy chooses AugustMatterPlatform only when Matter is available and enabled, and the user has not disabled Matter via config.options.disableMatter. Otherwise it falls back to AugustPlatform.
-
-### Matter Device Type Mapping
-
-Matter registrations use api.matter.deviceTypes.* and api.matter.types.* from Homebridge's Matter API.
-
-| August Device | HAP Service | Matter DeviceType | Matter Clusters |
-|---|---|---|---|
-| August/Yale lock | LockMechanism (plus optional ContactSensor in HAP mode) | DoorLock | doorLock |
-
-Notes:
-- AugustMatterPlatform currently maps lock accessories to Matter DoorLock.
-- Lock state updates are written through the doorLock cluster (for example lockState) and mirrored from August API polling/push updates.
-
-### Authoritative Matter References
-
-1. https://matter-js.github.io/docs/index.html
-2. https://github.com/homebridge-plugins/homebridge-matter
-
-For cluster, attribute, deviceType, and conversion details, use the homebridge-matter wiki:
-- Introduction: https://github.com/homebridge-plugins/homebridge-matter/wiki/Introduction
-- Core Concepts: https://github.com/homebridge-plugins/homebridge-matter/wiki/Core-Concepts
-- Getting Started: https://github.com/homebridge-plugins/homebridge-matter/wiki/Getting-Started
-- State Management: https://github.com/homebridge-plugins/homebridge-matter/wiki/State-Management
-- Monitoring External Changes: https://github.com/homebridge-plugins/homebridge-matter/wiki/Monitoring-External-Changes
-- Best Practices: https://github.com/homebridge-plugins/homebridge-matter/wiki/Best-Practices
-- Advanced Patterns: https://github.com/homebridge-plugins/homebridge-matter/wiki/Advanced-Patterns
-- API Reference: https://github.com/homebridge-plugins/homebridge-matter/wiki/API-Reference
-- Matter Types: https://github.com/homebridge-plugins/homebridge-matter/wiki/Matter-Types
-- Value Conversions: https://github.com/homebridge-plugins/homebridge-matter/wiki/Value-Conversions
-
-Device reference pages:
-- Sensors (Section 7): https://github.com/homebridge-plugins/homebridge-matter/wiki/Section-7-Sensors
-- Closure (Section 8): https://github.com/homebridge-plugins/homebridge-matter/wiki/Section-8-Closure
-
-## Testing Guidelines
-
-- Test files live under test/ with .test.ts suffix.
-- Mock external dependencies:
-  - august-yale
-  - file system
-  - Homebridge API surfaces
-- Cover:
-  - startup and discovery
-  - polling loops
-  - push/pull state sync
-  - Matter fallback behavior
-  - error paths and retries
-
-## Files to Avoid Editing Directly
-
-- dist/
-- node_modules/
-- docs/ generated output unless intentionally regenerating docs
-
-## Changelog Requirements
-
-When adding a release entry to CHANGELOG.md:
-
-1. Header format:
-
-```md
-## [X.Y.Z](https://github.com/homebridge-plugins/homebridge-august/releases/tag/vX.Y.Z) (YYYY-MM-DD)
-```
-
-2. Add sections as needed (for example Bug Fixes, Features, Documentation).
-
-3. Include a trailing full changelog comparison line:
-
-```md
-**Full Changelog**: https://github.com/homebridge-plugins/homebridge-august/compare/vX.Y.(Z-1)...vX.Y.Z
-```
-
-4. Ensure commit links point to this repository:
-- https://github.com/homebridge-plugins/homebridge-august/commit/<sha>
-
-## Security and Privacy
-
-- Never log secrets (passwords, tokens, validation codes).
-- Avoid exposing sensitive values in thrown errors.
-- Validate user-supplied config inputs before use.

package/.github/dependabot.yml

@@ -1,17 +0,0 @@
-# To get started with Dependabot version updates, you'll need to specify which
-# package ecosystems to update and where the package manifests are located.
-# Please see the documentation for all configuration options:
-# https://help.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
-
-version: 2
-updates:
-  - package-ecosystem: 'npm' # See documentation for possible values
-    directory: '/' # Location of package manifests
-    target-branch: 'beta-*.*.*'
-    schedule:
-      interval: 'daily'
-  - package-ecosystem: 'github-actions' # See documentation for possible values
-    directory: '/' # Location of package manifests
-    target-branch: 'beta-*.*.*'
-    schedule:
-      interval: 'daily'

package/.github/labeler.yml

@@ -1,38 +0,0 @@
-# Add 'branding' label to any changes within 'docs' folder or any subfolders
-branding:
-- changed-files:
-  - any-glob-to-any-file: branding/**
-
-# Add 'docs' label to any change to .md files within the entire repository 
-docs:
-- changed-files:
-  - any-glob-to-any-file: '**/*.md'
-
-# Add 'enhancement' label to any change to src files within the source dir EXCEPT for the docs sub-folder
-enhancement:
-  - changed-files:
-    - any-glob-to-any-file: 'src/**/*'
-    - any-glob-to-any-file: 'config.schema.json'
-
-# Add 'dependencies' label to any change to src files within the source dir EXCEPT for the docs sub-folder
-dependencies:
-  - changed-files:
-    - any-glob-to-any-file: 'package.json'
-    - any-glob-to-any-file: 'package-lock.json'
-
-# Add 'beta' label to any PR that is opened against the `beta` branch
-beta:
-- base-branch: 'beta*'
-
-# Add 'alpha' label to any PR that is opened against the `alpha` branch
-alpha:
-- base-branch: 'alpha*'
-
-# Add 'latest' label to any PR that is opened against the `latest` branch
-latest:
-- base-branch: 'latest'
-
-# Add 'workflow' to any changes within 'workflow' folder or any subfolders
-workflow:
-- changed-files:
-  - any-glob-to-any-file: .github/**

package/.github/scripts/compute-version-override.cjs

@@ -1,51 +0,0 @@
-#!/usr/bin/env node
-
-const child = require('node:child_process')
-const fs = require('node:fs')
-
-const bump = (process.argv[2] || 'patch').toLowerCase()
-const allowed = new Set(['major', 'minor', 'patch'])
-
-if (!allowed.has(bump)) {
-  console.error(`Invalid bump level '${bump}'. Use major, minor, or patch.`)
-  process.exit(1)
-}
-
-const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'))
-
-function inc(v, level) {
-  const parts = v.split('-')[0].split('+')[0].split('.').map(Number)
-  if (level === 'major') {
-    parts[0] += 1
-    parts[1] = 0
-    parts[2] = 0
-  } else if (level === 'minor') {
-    parts[1] += 1
-    parts[2] = 0
-  } else {
-    parts[2] += 1
-  }
-  return parts.join('.')
-}
-
-function latestStable(name) {
-  try {
-    const versions = JSON.parse(child.execSync(`npm info ${name} versions --json`).toString('utf8').trim())
-    const stable = (Array.isArray(versions) ? versions : [])
-      .filter(v => /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-.]+)?(?:\+[0-9A-Za-z-.]+)?$/.test(v) && !v.includes('-'))
-    stable.sort((a, b) => {
-      const ap = a.split('.').map(Number)
-      const bp = b.split('.').map(Number)
-      for (let i = 0; i < 3; i++) {
-        if (ap[i] !== bp[i]) return bp[i] - ap[i]
-      }
-      return 0
-    })
-    return stable[0] || ''
-  } catch {
-    return ''
-  }
-}
-
-const base = latestStable(pkg.name) || pkg.version
-process.stdout.write(inc(base, bump))

package/.github/scripts/normalize-changelog-header.cjs

@@ -1,86 +0,0 @@
-#!/usr/bin/env node
-
-const child_process = require('node:child_process')
-const fs = require('node:fs')
-
-const changelogPath = 'CHANGELOG.md'
-
-function normalizeChangelogHeader(content) {
-  const headerStart = content.indexOf('# Changelog\n')
-  if (headerStart <= 0) {
-    return content
-  }
-
-  const nextSectionStart = content.indexOf('\n## ', headerStart + 1)
-  const headerBlock = (nextSectionStart === -1 ? content.slice(headerStart) : content.slice(headerStart, nextSectionStart)).trim()
-  const prependedEntries = content.slice(0, headerStart).trim()
-  const remainingEntries = (nextSectionStart === -1 ? '' : content.slice(nextSectionStart)).trim()
-
-  return [headerBlock, prependedEntries, remainingEntries].filter(Boolean).join('\n\n') + '\n'
-}
-
-function getRepoUrl() {
-  try {
-    const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'))
-    let url = (typeof pkg.repository === 'string' ? pkg.repository : pkg.repository?.url) || ''
-    url = url.replace(/^git\+/, '').replace(/\.git$/, '')
-    if (url.startsWith('https://')) return url
-  } catch {}
-  try {
-    const remote = child_process.execSync('git remote get-url origin').toString().trim()
-    return remote.replace(/^git\+/, '').replace(/\.git$/, '').replace(/^git@github\.com:/, 'https://github.com/')
-  } catch {}
-  return ''
-}
-
-function getPreviousTag() {
-  try {
-    const tags = child_process
-      .execSync('git tag --sort=-version:refname')
-      .toString()
-      .trim()
-      .split('\n')
-      .filter(Boolean)
-    return tags[0] || ''
-  } catch {
-    return ''
-  }
-}
-
-function appendFullChangelogLink(content, currentTag, repoUrl) {
-  const prefix = `**Full Changelog**: ${repoUrl}/compare/`
-  // Find the bounds of the first release section (the newly generated one)
-  const firstSectionStart = content.indexOf('\n## ')
-  if (firstSectionStart === -1) return content
-  const firstSectionEnd = content.indexOf('\n## ', firstSectionStart + 1)
-  const firstSection = firstSectionEnd === -1 ? content.slice(firstSectionStart) : content.slice(firstSectionStart, firstSectionEnd)
-
-  // Skip if a Full Changelog link is already present in that section
-  if (firstSection.includes(prefix)) return content
-
-  const prevTag = getPreviousTag()
-  if (!prevTag) return content
-
-  const link = `**Full Changelog**: ${repoUrl}/compare/${prevTag}...${currentTag}`
-  if (firstSectionEnd === -1) {
-    return content.trimEnd() + '\n\n' + link + '\n'
-  }
-  return content.slice(0, firstSectionEnd).trimEnd() + '\n\n' + link + '\n' + content.slice(firstSectionEnd)
-}
-
-exports.preCommit = (props) => {
-  if (!fs.existsSync(changelogPath)) {
-    return
-  }
-
-  let content = fs.readFileSync(changelogPath, 'utf8')
-  content = normalizeChangelogHeader(content)
-
-  const repoUrl = getRepoUrl()
-  const currentTag = props?.tag || ''
-  if (repoUrl && currentTag) {
-    content = appendFullChangelogLink(content, currentTag, repoUrl)
-  }
-
-  fs.writeFileSync(changelogPath, content)
-}

package/.github/scripts/npm-version-script-esm-auto.js

@@ -1,201 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Standalone ESM implementation — self-contained so this file can be copied
- * into other repos without pulling any other files.
- */
-
-import assert from 'node:assert'
-import child_process from 'node:child_process'
-import fs from 'node:fs'
-import process from 'node:process'
-// Minimal, in-file semver utilities used by this script.
-// This avoids an external dependency so the script can run in environments
-// where `semver` isn't installed.
-const semver = {
-	// Very small validation: match major.minor.patch with optional prerelease/build
-	valid(v) {
-		return /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-.]+)?(?:\+[0-9A-Za-z-.]+)?$/.test(v)
-	},
-	// Return prerelease identifiers array or null
-	prerelease(v) {
-		const m = v.match(/^\d+\.\d+\.\d+-(.+)$/)
-		return m ? m[1].split('.') : null
-	},
-	// Compare two semver strings in reverse order (for rcompare use)
-	rcompare(a, b) {
-		// Use standard semver precedence rules for major.minor.patch; ignore prerelease complexity except that prerelease is lower than release
-		const pa = a.split('-')
-		const pb = b.split('-')
-		const aCore = pa[0].split('.').map(Number)
-		const bCore = pb[0].split('.').map(Number)
-		for (let i = 0; i < 3; i++) {
-			if (aCore[i] > bCore[i]) return -1
-			if (aCore[i] < bCore[i]) return 1
-		}
-		// equal core; releases (no prerelease) are greater than prerelease
-		if (pa.length === 1 && pb.length > 1) return -1
-		if (pa.length > 1 && pb.length === 1) return 1
-		// both same prerelease status: compare as strings
-		if (a > b) return -1
-		if (a < b) return 1
-		return 0
-	},
-	// Increment version by 'major'|'minor'|'patch'
-	inc(v, level) {
-		if (!this.valid(v)) throw new Error(`Invalid semver passed to inc: ${v}`)
-		// strip prerelease/build
-		const core = v.split('-')[0].split('+')[0]
-		const parts = core.split('.').map(Number)
-		switch (level) {
-			case 'major':
-				parts[0] += 1
-				parts[1] = 0
-				parts[2] = 0
-				break
-			case 'minor':
-				parts[1] += 1
-				parts[2] = 0
-				break
-			case 'patch':
-			default:
-				parts[2] += 1
-				break
-		}
-		return parts.join('.')
-	}
-}
-
-const BRANCH_VERSION_PATTERN = /^([A-Z]+)-(\d+\.\d+\.\d+)$/i
-
-// Load package.json
-const packageJSON = JSON.parse(fs.readFileSync('package.json', 'utf8'))
-
-const refArgument = process.argv[2]
-const tagArgument = process.argv[3] || 'latest'
-
-if (!refArgument) {
-	console.error('ref argument is missing')
-	console.error('Usage: npm-version-script-esm.js <ref> [tag]')
-	process.exit(1)
-}
-
-/**
- * Queries the NPM registry for the latest version for the provided base version and tag.
- * If the tag is latest, then the base version is returned if it exists. For other tags, the latest
- * version found for that base version and tag is returned.
- * @param baseVersion The base version to query for, e.g. 2.0.0
- * @param tag The tag to query for, e.g. beta or latest
- * @returns {string} Returns the version, or '' if not found
- */
-function getTagVersionFromNpm(baseVersion, tag) {
-	try {
-		return JSON.parse(child_process.execSync(`npm info ${packageJSON.name} versions --json`).toString('utf8').trim())
-			.filter(v => (tag === 'latest' ? v === baseVersion : v.startsWith(`${baseVersion}-${tag}.`)))
-			.reduce((_, current) => current, '')
-	} catch (e) {
-		console.error(`Failed to query the npm registry for the latest version for tag: ${tag}`, e)
-		// throw e;
-		return ''
-	}
-}
-
-function getLatestStableVersionFromNpm() {
-	try {
-		const versions = JSON.parse(child_process.execSync(`npm info ${packageJSON.name} versions --json`).toString('utf8').trim())
-		if (!Array.isArray(versions) || versions.length === 0) return ''
-
-		// Only consider stable semver versions (no prerelease)
-		const stable = versions.filter(v => semver.valid(v) && !semver.prerelease(v))
-		if (stable.length === 0) return ''
-
-		// Sort descending and return the highest
-		const sorted = stable.sort(semver.rcompare)
-		return sorted[0]
-	} catch (e) {
-		console.error('Failed to query the npm registry for published versions', e)
-		return ''
-	}
-}
-
-function desiredTargetVersion(ref) {
-	// ref is a GitHub action ref string
-	if (ref.startsWith('refs/pull/')) {
-		throw new Error('The version script was executed inside a PR!')
-	}
-
-	assert(ref.startsWith('refs/heads/'))
-	const branchName = ref.slice('refs/heads/'.length)
-
-	const results = branchName.match(BRANCH_VERSION_PATTERN)
-	if (results !== null) {
-		if (results[1].toLowerCase() !== tagArgument.toLowerCase()) {
-			console.warn(`The base branch name (${results[1]}) differs from the tag name ${tagArgument}`)
-		}
-
-		return results[2]
-	}
-
-	if (branchName === 'latest') {
-		// For latest branch, start with package.json version as base
-		return packageJSON.version
-	}
-
-	throw new Error(`Malformed branch name for ref: ${ref}. Must be beta-x.x.x, alpha-x.x.x, or 'latest'`)
-}
-
-function bumpVersion(baseVersion, level) {
-	const normalizedLevel = (level || 'patch').toLowerCase()
-	if (!semver.valid(baseVersion)) {
-		throw new Error(`Invalid base version passed to bumpVersion: ${baseVersion}`)
-	}
-
-	switch (normalizedLevel) {
-		case 'major':
-			return semver.inc(baseVersion, 'major')
-		case 'minor':
-			return semver.inc(baseVersion, 'minor')
-		case 'patch':
-		default:
-			return semver.inc(baseVersion, 'patch')
-	}
-}
-
-const baseVersion = desiredTargetVersion(refArgument)
-let publishTag = baseVersion
-
-if (refArgument.includes('latest')) {
-	// For latest branch, determine next version based on npm and bump patch.
-	const latestPublishedStable = getLatestStableVersionFromNpm()
-	if (latestPublishedStable) {
-		console.warn(`Latest published stable version is ${latestPublishedStable}; bumping patch`)
-		publishTag = bumpVersion(latestPublishedStable, 'patch')
-	} else {
-		console.warn('No published stable versions found; bumping package.json version patch')
-		publishTag = bumpVersion(baseVersion, 'patch')
-	}
-} else {
-	// For alpha/beta, query npm for latest
-	const latestReleasedVersion = getTagVersionFromNpm(baseVersion, tagArgument)
-	if (latestReleasedVersion) {
-		console.warn(`Latest published version for ${baseVersion} with tag ${tagArgument} is ${latestReleasedVersion}`)
-		publishTag = latestReleasedVersion
-	} else {
-		console.warn(`No published versions for ${baseVersion} with tag ${tagArgument}`)
-	}
-}
-
-if (packageJSON.version !== publishTag) {
-	console.warn(`Updating version in package.json from ${packageJSON.version} to ${publishTag}`)
-	packageJSON.version = publishTag
-	fs.writeFileSync('package.json', JSON.stringify(packageJSON, null, 2))
-
-	// perform the same change to the package-lock.json
-	const packageLockJSON = JSON.parse(fs.readFileSync('package-lock.json', 'utf8'))
-	packageLockJSON.version = publishTag
-	fs.writeFileSync('package-lock.json', JSON.stringify(packageLockJSON, null, 2))
-} else {
-	console.warn(`Version in package.json is already ${packageJSON.version}`)
-}
-
-console.log(publishTag)