@alteriom/mqtt-schema 0.3.0 → 0.3.2

package/README.md

@@ -1,6 +1,8 @@
 # @alteriom/mqtt-schema
 
 ![Metadata Compliance](https://github.com/Alteriom/alteriom-mqtt-schema/actions/workflows/metadata-compliance.yml/badge.svg)
+![OTA Manifest Validation](https://github.com/Alteriom/alteriom-mqtt-schema/actions/workflows/validate-ota-manifest.yml/badge.svg)
+![Schema Verify](https://github.com/Alteriom/alteriom-mqtt-schema/actions/workflows/schema-verify.yml/badge.svg)
 ![npm version](https://img.shields.io/npm/v/@alteriom/mqtt-schema.svg)
 ![npm downloads](https://img.shields.io/npm/dm/@alteriom/mqtt-schema.svg)
 ![license](https://img.shields.io/npm/l/@alteriom/mqtt-schema.svg)
@@ -10,62 +12,10 @@
 ![latest tag](https://img.shields.io/github/v/tag/Alteriom/alteriom-mqtt-schema?label=tag)
 [![bundle size](https://img.shields.io/bundlephobia/minzip/@alteriom/mqtt-schema)](https://bundlephobia.com/package/@alteriom/mqtt-schema)
 
-Alteriom MQTT v1 JSON Schemas, TypeScript types, and production‑ready validation helpers for integrating firmware MQTT payloads into web or backend services.
-
-> NOTE: OTA manifest CI validation workflow file could not be added via automated API due to path constraints; it can be added manually post-merge if still absent.
-
-See also: `docs/SCHEMA_MAP.md` for complete schema listing.
-
-## OTA Firmware Manifest Schema (NEW in 0.3.0)
-
-The package now includes the OTA firmware manifest schema used by build + deployment tooling.
-
-Import the schema JSON directly:
-```ts
-import otaManifestSchema from '@alteriom/mqtt-schema/schemas/ota/ota-manifest.schema.json';
-```
-
-Types:
-```ts
-import { OtaManifest, isRichManifest } from '@alteriom/mqtt-schema/types/ota-manifest';
-```
-
-Shapes supported (oneOf):
-- Rich manifest:
-```json
-{
-  "environment": "universal-sensor",
-  "branch": "main",
-  "manifests": { "dev": { /* richEntry */ }, "prod": { /* richEntry */ } }
-}
-```
-- Minimal environment map:
-```json
-{
-  "universal-sensor": { "dev": { /* minimalChannel */ } }
-}
-```
-
-Chunk hashing variants (mutually exclusive):
-1. Structured objects (offset + size + sha256)
-2. Array of lowercase sha256 strings
-
-Validation example:
-```ts
-import Ajv from 'ajv';
-import schema from '@alteriom/mqtt-schema/schemas/ota/ota-manifest.schema.json';
-import { OtaManifest } from '@alteriom/mqtt-schema/types/ota-manifest';
 
-const ajv = new Ajv({ allErrors: true });
-const validate = ajv.compile<OtaManifest>(schema as any);
-const manifest: OtaManifest = JSON.parse(raw);
-if (!validate(manifest)) {
-  console.error(validate.errors);
-}
-```
-
----
+Alteriom MQTT v1 JSON Schemas, TypeScript types, and production‑ready validation helpers for integrating firmware MQTT payloads into web or backend services.
 
+ 
 ## Why this exists
 Firmware emits structured MQTT payloads that must remain tightly aligned with web, analytics, and gateway logic. This package is the single source of truth for:
 
@@ -90,6 +40,8 @@ Firmware emits structured MQTT payloads that must remain tightly aligned with we
 npm install @alteriom/mqtt-schema ajv ajv-formats
 ```
 
+**Support & Compatibility**: Node 18+ tested; Node 20 primary. Dual CJS/ESM builds.
+
 ## Quick Start
 
 Validate a JSON payload (object already parsed):
@@ -137,6 +89,43 @@ Access raw schema JSON (if you need to introspect or power form generation):
 import envelopeSchema from '@alteriom/mqtt-schema/schemas/envelope.schema.json';
 ```
 
+## OTA Firmware Manifest Schema (v0.3.1+)
+
+The package includes OTA firmware manifest schema with both rich and minimal formats.
+
+**Preferred: Stable alias import** (v0.3.1+):
+```ts
+import otaManifestSchema from '@alteriom/mqtt-schema/ota-manifest';
+import { OtaManifest, isRichManifest } from '@alteriom/mqtt-schema/types/ota-manifest';
+```
+
+**Legacy: Deep path import** (still supported):
+```ts
+import otaManifestSchema from '@alteriom/mqtt-schema/schemas/ota/ota-manifest.schema.json';
+```
+
+**Usage example:**
+```ts
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+import otaManifestSchema from '@alteriom/mqtt-schema/ota-manifest';
+import { OtaManifest } from '@alteriom/mqtt-schema/types/ota-manifest';
+
+const ajv = new Ajv({ allErrors: true, strict: false });
+addFormats(ajv);
+const validate = ajv.compile<OtaManifest>(otaManifestSchema as any);
+
+const manifest: OtaManifest = JSON.parse(manifestJson);
+if (!validate(manifest)) {
+  console.error('Invalid OTA manifest:', validate.errors);
+}
+```
+
+Supported formats:
+- **Rich manifest**: environment + branch + manifests object
+- **Minimal environment map**: environment → channels mapping  
+- **Chunk variants**: structured objects or SHA256 array
+
 ## API Surface
 
 ```ts
@@ -195,8 +184,6 @@ All Ajv validator functions are compiled once at module load. For typical web us
 | `SensorDataMessage` etc. | TS interfaces | Strongly typed shapes |
 | `isSensorDataMessage` etc. | type guards | Runtime narrowing helpers |
 | `schemas/*.json` | JSON | Original schema assets (optional) |
-| `schemas/ota/ota-manifest.schema.json` | JSON | OTA firmware manifest schema (rich + minimal) |
-| `types/ota-manifest` | TS types | OtaManifest union + helpers |
 
 ### Validator Keys
 
@@ -223,8 +210,6 @@ Schema stability is paramount. We track two related versions:
 
 Backward‑compatible additions: new optional properties or enums, documented in CHANGELOG. Breaking: new required fields, structural changes, or removed properties (triggers parallel `v2` schema path & coordinated firmware rollout).
 
-Backward-compatible schema additions to OTA manifest WILL use minor bumps.
-
 ## TypeScript / Bundler Notes
 
 - Works in TS >= 5, Node >= 16, Vite / Webpack / ESBuild.
@@ -236,13 +221,44 @@ Backward-compatible schema additions to OTA manifest WILL use minor bumps.
 - Optional custom Ajv injection hook
 - JSON Schema → Zod conversion example
 - Runtime metrics helper (count validation categories)
-- Signed OTA manifest extension
-- Delta / compressed OTA metadata fields
 
 ## Contributing
 
 Issues & PRs welcome. Ensure firmware repo schemas remain the authoritative source—do not manually edit generated `schema_data.ts`.
 
+### Development Workflow
+
+**Before opening a PR:** Run the comprehensive validation suite:
+
+```bash
+npm run verify        # Schema sync + changelog + fixtures
+npm run verify:all    # Additional schema compilation + OTA manifest validation  
+npm test              # Enhanced fixture validation with detailed reporting
+```
+
+**Available validation scripts:**
+- `npm run test` - Cross-platform fixture validation (CJS/ESM) with enhanced error reporting
+- `npm run test:ota` - OTA manifest fixture validation
+- `npm run verify:schemas` - Ensure schemas are synced from source directory
+- `npm run verify:release` - Check changelog contains current version
+- `npm run verify:all` - Comprehensive schema compilation and fixture validation
+
+### Script Organization
+
+Scripts are organized by category in `package.json`:
+- **Build Scripts**: `build`, `build:cjs`, `build:esm`, `clean`, etc.
+- **Testing & Validation**: `test`, `verify:*`, etc.  
+- **Release Management**: `release:prepare`, `wiki:generate`
+- **Repository Metadata**: `metadata:*` (organization compliance)
+
+### Release Process
+
+See `PUBLISH_CHECKLIST.md` for detailed release procedures. Quick summary:
+1. Update schemas in `docs/mqtt_schema/`
+2. Run `npm run verify` to ensure everything is valid
+3. Use `npm run release:prepare -- patch|minor|major` for version bumping
+4. Follow checklist for tagging and publishing
+
 ## Security
 
 Schemas are static. No network access. Supply-chain risk minimized by keeping dependencies minimal (Ajv + formats only).
@@ -250,3 +266,107 @@ Schemas are static. No network access. Supply-chain risk minimized by keeping de
 ## License
 
 MIT
+
+## Registry Mirrors
+
+This package is published to BOTH:
+
+- Public npm registry: `https://registry.npmjs.org` (primary)
+- GitHub Packages registry: `https://npm.pkg.github.com` (mirror for visibility in repo Packages tab)
+
+### Installing from GitHub Packages (optional)
+
+Create or update an `.npmrc` with a scoped registry override (auth token with `read:packages` required):
+
+```bash
+@alteriom:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
+```
+
+Then install normally:
+
+```bash
+npm install @alteriom/mqtt-schema ajv ajv-formats
+```
+
+If you omit the override, npmjs.org is used (recommended for most consumers).
+
+### Why dual publish?
+
+- GitHub Packages listing provides provenance + quick visibility in the repo UI.
+- npm remains the canonical public distribution source (faster, anonymous installs allowed).
+
+### Operational Notes
+
+| Aspect | Behavior |
+|--------|----------|
+| Build artifact | Built once, same tarball published to both registries. |
+| Version uniqueness | Same version must not be republished; bump if any change needed. |
+| Auth (GitHub) | Always required for install from GitHub Packages, even for public repos. |
+| Tarball parity | Do not rebuild between publishes; workflows ensure single build. |
+| Fallback strategy | If mirror publish fails (e.g., transient), primary npm publish still stands. |
+| Provenance flag | Applied for npm (GitHub ignores currently). |
+
+### Verifying a Release
+
+```bash
+npm view @alteriom/mqtt-schema version
+npm view @alteriom/mqtt-schema version --registry=https://npm.pkg.github.com
+```
+
+Both should return the same version.
+
+## Repository Metadata Compliance
+
+This repository integrates the `@alteriom/repository-metadata-manager` tooling to continuously validate and report on repository metadata health (description, topics, documentation signals, etc.) within the Alteriom organization standards.
+
+### Local Usage
+
+Run a validation (non‑destructive):
+
+```bash
+npm run metadata:validate
+```
+
+Generate a detailed report:
+
+```bash
+npm run metadata:report
+```
+
+Configuration lives in `metadata-config.json` (organizationTag `alteriom`). Default detection is auto; adjust if repository classification needs overriding.
+
+### CI Workflow
+
+Workflow file: `.github/workflows/metadata-compliance.yml`
+
+On each push / PR against `main` it will:
+
+1. Install dependencies
+2. Run `metadata:validate` (fails job on hard non‑compliance)
+3. Always attempt a best‑effort report (`metadata:report`) for visibility
+
+### Tokens / Permissions
+
+The workflow relies only on the default `GITHUB_TOKEN` for read operations. If future auto‑apply operations are desired, a token with elevated repo scope would be needed and the `metadata:apply` script could be wired (currently omitted to keep CI read‑only).
+
+### Extending
+
+If you add new categories of tooling or documentation, re‑run the report to see updated recommendations. For cross‑repo analytics or policy generation, use the original project directly.
+
+### Applying Metadata (Manual Workflow)
+
+For authorized maintainers you can run adjustments via GitHub Actions:
+
+1. Open the "Repository Metadata Apply" workflow under the Actions tab.
+2. Choose whether to keep `dryRun` (default) or set to `false` to apply.
+3. Run the workflow; the log will show proposed or applied changes.
+
+Local dry‑run vs apply:
+
+```bash
+npm run metadata:apply:dry  # show what would change
+npm run metadata:apply      # apply changes (requires proper permissions via GITHUB_TOKEN)
+```
+
+Note: Applying metadata modifies repository settings (description, topics) through the GitHub API; ensure the default token has the necessary repo scopes (in public repositories the workflow GITHUB_TOKEN normally suffices for these fields).

package/dist/cjs/schema_data.d.ts

@@ -317,3 +317,184 @@ export declare const mqtt_v1_bundle_json: {
         readonly control_response: "control_response.schema.json";
     };
 };
+export declare const ota_ota_manifest_schema: {
+    readonly $id: "https://schemas.alteriom.com/ota/ota-manifest.schema.json";
+    readonly title: "Alteriom OTA Firmware Manifest";
+    readonly description: "Schema for Alteriom OTA firmware manifests supporting both rich and minimal variants";
+    readonly type: "object";
+    readonly oneOf: readonly [{
+        readonly title: "Rich Manifest";
+        readonly description: "Rich manifest format with environment, branch, and manifests object";
+        readonly type: "object";
+        readonly properties: {
+            readonly environment: {
+                readonly type: "string";
+                readonly description: "Target environment (e.g., universal-sensor)";
+            };
+            readonly branch: {
+                readonly type: "string";
+                readonly description: "Source control branch the build originated from";
+            };
+            readonly manifests: {
+                readonly type: "object";
+                readonly description: "Build variants keyed by type (dev, prod, etc.)";
+                readonly patternProperties: {
+                    readonly "^[a-z][a-z0-9-]*$": {
+                        readonly $ref: "#/$defs/richEntry";
+                    };
+                };
+                readonly additionalProperties: false;
+                readonly minProperties: 1;
+            };
+        };
+        readonly required: readonly ["environment", "branch", "manifests"];
+        readonly additionalProperties: true;
+    }, {
+        readonly title: "Minimal Environment Map";
+        readonly description: "Minimal manifest format as environment -> channels mapping";
+        readonly type: "object";
+        readonly patternProperties: {
+            readonly "^[a-z][a-z0-9-]*$": {
+                readonly type: "object";
+                readonly description: "Environment entry with channel mappings";
+                readonly patternProperties: {
+                    readonly "^[a-z][a-z0-9-]*$": {
+                        readonly $ref: "#/$defs/minimalChannel";
+                    };
+                };
+                readonly additionalProperties: false;
+                readonly minProperties: 1;
+            };
+        };
+        readonly additionalProperties: false;
+        readonly minProperties: 1;
+    }];
+    readonly $defs: {
+        readonly richEntry: {
+            readonly title: "Rich Build Entry";
+            readonly description: "Rich manifest build entry (dev or prod)";
+            readonly type: "object";
+            readonly properties: {
+                readonly build_type: {
+                    readonly type: "string";
+                    readonly enum: readonly ["dev", "prod"];
+                    readonly description: "Build type identifier";
+                };
+                readonly file: {
+                    readonly type: "string";
+                    readonly description: "Firmware binary filename";
+                };
+                readonly size: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly description: "Total firmware size in bytes";
+                };
+                readonly sha256: {
+                    readonly type: "string";
+                    readonly pattern: "^[a-f0-9]{64}$";
+                    readonly description: "SHA256 hash of the full firmware binary (lowercase hex)";
+                };
+                readonly firmware_version: {
+                    readonly type: "string";
+                    readonly description: "Semantic or build version string";
+                };
+                readonly built: {
+                    readonly type: "string";
+                    readonly format: "date-time";
+                    readonly description: "ISO8601 timestamp when built";
+                };
+                readonly ota_url: {
+                    readonly type: "string";
+                    readonly format: "uri";
+                    readonly description: "Absolute or relative URL to fetch the firmware";
+                };
+                readonly chunk_size: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly description: "Size of each chunk except possibly the last";
+                };
+                readonly chunks: {
+                    readonly description: "Either structured chunk objects or array of SHA256 strings";
+                    readonly oneOf: readonly [{
+                        readonly type: "array";
+                        readonly items: {
+                            readonly $ref: "#/$defs/chunkObject";
+                        };
+                        readonly description: "Array of structured chunk objects with metadata";
+                    }, {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                            readonly pattern: "^[a-f0-9]{64}$";
+                            readonly description: "SHA256 hash of chunk (lowercase hex)";
+                        };
+                        readonly description: "Array of SHA256 strings for chunks";
+                    }];
+                };
+            };
+            readonly required: readonly ["build_type", "file", "size", "sha256", "firmware_version", "built", "ota_url"];
+            readonly additionalProperties: true;
+        };
+        readonly chunkObject: {
+            readonly title: "OTA Chunk Object";
+            readonly description: "Structured chunk metadata with offset and size";
+            readonly type: "object";
+            readonly properties: {
+                readonly index: {
+                    readonly type: "integer";
+                    readonly minimum: 0;
+                    readonly description: "0-based sequential chunk index";
+                };
+                readonly offset: {
+                    readonly type: "integer";
+                    readonly minimum: 0;
+                    readonly description: "Byte offset within firmware binary";
+                };
+                readonly size: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly description: "Chunk size in bytes";
+                };
+                readonly sha256: {
+                    readonly type: "string";
+                    readonly pattern: "^[a-f0-9]{64}$";
+                    readonly description: "SHA256 hash of the chunk (lowercase hex)";
+                };
+            };
+            readonly required: readonly ["index", "offset", "size", "sha256"];
+            readonly additionalProperties: true;
+        };
+        readonly minimalChannel: {
+            readonly title: "Minimal Channel Entry";
+            readonly description: "Minimal manifest channel entry";
+            readonly type: "object";
+            readonly properties: {
+                readonly file: {
+                    readonly type: "string";
+                    readonly description: "Firmware binary filename";
+                };
+                readonly size: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly description: "Total firmware size in bytes";
+                };
+                readonly sha256: {
+                    readonly type: "string";
+                    readonly pattern: "^[a-f0-9]{64}$";
+                    readonly description: "SHA256 hash of the firmware binary (lowercase hex)";
+                };
+                readonly version: {
+                    readonly type: "string";
+                    readonly description: "Firmware version string";
+                };
+                readonly timestamp: {
+                    readonly type: "string";
+                    readonly format: "date-time";
+                    readonly description: "ISO8601 timestamp";
+                };
+            };
+            readonly required: readonly ["file", "size", "sha256", "version", "timestamp"];
+            readonly additionalProperties: true;
+        };
+    };
+};