@homebridge-plugins/homebridge-august 3.2.2 → 3.3.0-beta.0

package/.copilot/instructions.md

@@ -1,261 +0,0 @@
-# Copilot Instructions for Homebridge August Plugin
-
-## Repository Overview
-
-This is a Homebridge plugin that provides HomeKit integration for August and Yale smart locks. The plugin is written in TypeScript with ES modules and follows Homebridge platform patterns.
-
-**Branch Strategy**: This repository uses a beta-first development workflow where all changes must target beta branches before being merged to main. Version bumps are determined by issue labels (patch/minor/major) that must be set before assigning work to Copilot.
-
-## Architecture
-
-- **Plugin Type**: Homebridge dynamic platform plugin
-- **Language**: TypeScript with ES modules (ES2022)
-- **Runtime**: Node.js 20+ or 22+
-- **Build System**: TypeScript compiler (tsc) with bundler module resolution
-- **Testing**: Vitest with coverage support
-- **Linting**: ESLint with Antfu config and custom rules
-- **Documentation**: TypeDoc with modern theme
-- **External API**: august-yale package for August/Yale API communication
-
-## Key Files and Directories
-
-- `src/` - TypeScript source code
-  - `index.ts` - Plugin entry point that registers the platform
-  - `platform.ts` - Main platform class (AugustPlatform)
-  - `settings.ts` - Configuration interfaces and constants
-  - `devices/` - Device-specific implementations
-    - `lock.ts` - Lock mechanism implementation
-    - `device.ts` - Base device class
-  - `homebridge-ui/` - Custom UI for Homebridge Config UI X
-  - `*.test.ts` - Test files (Vitest)
-- `dist/` - Compiled JavaScript output (generated, excluded from git)
-- `config.schema.json` - Homebridge configuration schema with custom UI
-- `package.json` - Dependencies and npm scripts
-- `tsconfig.json` - TypeScript configuration (ES2022, bundler resolution)
-- `eslint.config.js` - ESLint configuration with Antfu base and custom rules
-
-## Development Workflow
-
-### Branch Strategy and PR Workflow
-
-**IMPORTANT**: All pull requests must target a beta branch first, never directly to the main branch.
-
-#### Beta Branch Requirements
-- All PRs must be directed to a branch that starts with "beta-" 
-- Beta branches should be named `beta-X.Y.Z` based on the expected version bump
-- If no appropriate beta branch exists, create one based on the next possible version:
-  - **patch** releases (bug fixes): `beta-X.Y.Z+1` (e.g., current 3.0.2 → beta-3.0.3)
-  - **minor** releases (new features): `beta-X.Y+1.0` (e.g., current 3.0.2 → beta-3.1.0) 
-  - **major** releases (breaking changes): `beta-X+1.0.0` (e.g., current 3.0.2 → beta-4.0.0)
-
-#### Required Labels
-Before assigning any issue to Copilot, the following labels **must** be set to determine the version bump:
-- `patch` - for bug fixes and minor improvements
-- `minor` - for new features and enhancements  
-- `major` - for breaking changes
-
-#### Workflow Steps
-1. Ensure proper label (patch/minor/major) is set on the issue
-2. Identify or create appropriate beta branch based on the label
-3. Target all development work and PRs to the beta branch
-4. Once beta testing is complete, merge beta branch to main for release
-
-### Building
-```bash
-npm run build         # Full build: clean + compile + copy UI files
-npm run clean         # Remove dist directory
-npm run watch         # Build + link + watch with nodemon
-```
-
-### Testing
-```bash
-npm test              # Run Vitest tests once
-npm run test:watch    # Run tests in watch mode
-npm run test-coverage # Run tests with coverage report
-```
-
-### Linting
-```bash
-npm run lint          # Check for ESLint issues
-npm run lint:fix      # Auto-fix ESLint issues
-```
-
-### Documentation
-```bash
-npm run docs          # Generate TypeDoc documentation
-npm run docs:lint     # Validate documentation (treat warnings as errors)
-npm run docs:theme    # Generate docs with default-modern theme
-```
-
-### Development Setup
-```bash
-npm run watch         # Start development with hot reload
-npm run plugin-ui     # Copy UI files to dist
-```
-
-## Coding Standards
-
-1. **TypeScript**: 
-   - ES2022 target with bundler module resolution
-   - Strict mode enabled (except noImplicitAny: false)
-   - Use ES modules with `.js` file extensions in imports
-   - Generate declaration files and source maps
-
-2. **ESLint**: 
-   - Antfu ESLint config as base
-   - Custom rules for import ordering (perfectionist)
-   - JSDoc alignment enforcement
-   - Multi-line curly braces only
-   - Consistent quote props
-   - Test-specific rules (no-only-tests)
-
-3. **Code Style**:
-   - Use 1TBS brace style with single line allowed
-   - Sort imports by type (builtin, external, internal, relative)
-   - Sort named imports and exports
-   - Use proper JSDoc formatting and alignment
-
-4. **Homebridge Patterns**:
-   - Implement DynamicPlatformPlugin interface
-   - Use proper platform registration in index.ts
-   - Follow accessory lifecycle management
-   - Implement proper logging with Homebridge logger
-   - Use PlatformAccessory for device management
-
-5. **Error Handling**: 
-   - Proper try-catch blocks for async operations
-   - Meaningful error messages with context
-   - Graceful degradation for API failures
-
-## Homebridge Specifics
-
-- **Platform Type**: Dynamic platform plugin (not accessory plugin)
-- **Platform Name**: "August" (defined in settings.ts)
-- **Plugin Name**: "homebridge-august" (must match package.json name)
-- **Configuration Schema**: Uses config.schema.json with custom UI
-- **Custom UI**: Located in src/homebridge-ui/ with custom configuration interface
-- **Platform Class**: AugustPlatform extends DynamicPlatformPlugin
-- **Device Management**: Uses PlatformAccessory for caching and state management
-- **HAP Services**: Implement LockMechanism service for smart locks
-- **Authentication**: Handle August API authentication with validation codes
-- **Rate Limiting**: Implement proper refresh/update/push rates for API calls
-
-## August/Yale Integration
-
-- **API Package**: Uses `august-yale` npm package for API communication
-- **Authentication Flow**:
-  1. User provides augustId (email/phone) and password
-  2. System sends validation code to user
-  3. User enters validation code to complete authentication
-  4. API credentials are stored and used for subsequent requests
-- **Device Types**: Support multiple lock types (August Smart Lock, Yale Assure Lock variants)
-- **State Synchronization**: Keep HomeKit state in sync with August/Yale API
-- **Polling**: Implement configurable refresh rates for device state updates
-- **Configuration**: Use credentials interface for API authentication settings
-
-## When Making Changes
-
-**CRITICAL**: Before starting any work, ensure the issue has the appropriate label (patch/minor/major) and target the correct beta branch.
-
-0. **Branch Targeting**:
-   - Never target PRs directly to main branch
-   - Always target a beta branch (beta-X.Y.Z format)
-   - Create beta branch if none exists for the expected version
-   - Use issue labels to determine version bump:
-     - `patch`: Bug fixes → beta-X.Y.Z+1
-     - `minor`: New features → beta-X.Y+1.0  
-     - `major`: Breaking changes → beta-X+1.0.0
-
-1. **Dependencies**: 
-   - Only add well-maintained dependencies
-   - Keep runtime dependencies minimal
-   - Update package.json and package-lock.json properly
-   - Consider bundle size impact
-
-2. **Breaking Changes**: 
-   - Follow semantic versioning
-   - Update CHANGELOG.md appropriately
-   - Consider migration paths for users
-   - Test with multiple Homebridge versions
-   - **Must** use `major` label and target appropriate beta-X+1.0.0 branch
-
-3. **Configuration**: 
-   - Update config.schema.json for new options
-   - Maintain backward compatibility
-   - Add proper validation and defaults
-   - Update TypeScript interfaces in settings.ts
-
-4. **Documentation**: 
-   - Update README.md for user-facing changes
-   - Add TSDoc comments for new APIs
-   - Update TypeDoc comments for generated docs
-   - Consider updating examples
-
-5. **Testing**: 
-   - Add Vitest tests for new features
-   - Mock external dependencies (August API)
-   - Test error scenarios and edge cases
-   - Maintain test coverage
-
-6. **Compatibility**: 
-   - Support Node.js 20+ and 22+
-   - Support Homebridge 1.9.0+ and 2.0.0+
-   - Test with Config UI X integration
-   - Verify ES module compatibility
-
-## Common Patterns
-
-- **RxJS**: Use reactive programming patterns where appropriate
-- **Async/Await**: Prefer async/await over Promise chains
-- **ES Modules**: Use ES module syntax with `.js` extensions in imports
-- **Interface Design**: Define clear TypeScript interfaces in settings.ts
-- **Error Handling**: Implement comprehensive error handling with meaningful messages
-- **Logging**: Use this.log with appropriate log levels (info, warn, error, debug)
-- **Device Lifecycle**: Implement proper setup/cleanup in platform methods
-- **Configuration Validation**: Validate user configuration and provide helpful error messages
-- **API Rate Limiting**: Respect August API rate limits with configurable intervals
-- **State Management**: Maintain device state consistency between API and HomeKit
-
-## Important Constants and Settings
-
-- **PLATFORM_NAME**: "August" (used in Homebridge registration)
-- **PLUGIN_NAME**: "homebridge-august" (must match package.json)
-- **Plugin Type**: "platform" (not accessory)
-- **Custom UI**: Enabled with path "./dist/homebridge-ui"
-- **Configuration**: Uses credentials and options interfaces
-- **Device Types**: Support for various August and Yale lock models
-
-## Testing Guidelines
-
-- **Framework**: Use Vitest for testing with TypeScript support
-- **Test Files**: Name test files with `.test.ts` extension in src/
-- **Coverage**: Aim for good test coverage, use `npm run test-coverage`
-- **Mocking**: Mock external dependencies, especially:
-  - August/Yale API calls
-  - Homebridge API interactions
-  - File system operations
-- **Test Categories**:
-  - Unit tests for individual functions and classes
-  - Integration tests for platform initialization
-  - Configuration validation tests
-  - Error handling tests
-- **Test Data**: Use realistic test data that matches August API responses
-- **Async Testing**: Properly test async operations and promises
-- **CI/CD**: Ensure tests run in continuous integration pipeline
-
-## Files to Avoid Modifying
-
-- `dist/` directory (generated by TypeScript compilation)
-- `node_modules/` directory (managed by npm)
-- `docs/` directory (generated by TypeDoc)
-- `.git/` directory and git metadata
-- Files listed in `.gitignore`
-- `package-lock.json` (only modify through npm commands)
-
-## Security Considerations
-
-- **Credentials**: Never log or expose user credentials
-- **API Keys**: Handle August API credentials securely
-- **Validation**: Validate all user inputs
-- **Error Messages**: Don't expose sensitive information in error messages
-- **Storage**: Store credentials securely using Homebridge storage mechanisms

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)