@mudraforge/statutory 2.4.1 → 2.4.2

package/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [2.4.2] - 2026-10-24
+
+### Added
+- **npm Package Update Notifier**: Lightweight, zero-dependency update notifier querying `registry.npmjs.org` with a 24-hour temporary file cache (`checkForPackageUpdate()`).
+- **Unified `check-update` CLI Command**: Now audits both npm package code updates against the npm registry and legal rule updates against the Cloudflare Edge manifest.
+- **Non-Intrusive Terminal Footers**: Automatically surfaces `[NOTICE]` prompts when a newer npm release is available, with opt-out support via `NO_UPDATE_NOTIFIER=1` or `CI=true`.
+
+---
+
+## [2.4.1] - 2026-10-24
+
+### Added
+- **Developer Navigation & Usability**: Compact, audited Table of Contents in `README.md` targeting all key documentation sections.
+- **Package Metadata**: Official `homepage` pointing to `https://mudraforge.in/docs` and `bugs` pointing to GitHub Issues.
+- **Supported Application Patterns**: Documented clear integration boundaries across AI Agents (local `SKILL.md`), Finance Software (declarative threshold schemas), and Developer Tooling.
+- **Corporate M&A Restructuring Domain**: Section 50B slump sale capital gains based on WDV net worth (Section 43(6)), Form 3CEA CA certification schema, and Section 281 clearance checklist.
+- **Dual-Act Successor Mapping**: Section 393 (*Income-tax Act, 2025*) successor provision mapping for Section 194Q.
+- **Cryptographic Trust Anchor & Anti-Tamper Hardening**: Ed25519 digital signature verification for remote bundles, CRL key revocation enforcement, replay protections, Windows reserved device name protection, and strict production bypass locks (36 passing regression suites).
+
+### Changed
+- **Statutory Rate Enforcements**: Section 194J non-PAN deduction rate updated to the statutory 20% penalty tier under Section 206AA.
+- **Quotas & Error Semantics**: Documented Cloudflare Edge API rate limits, error codes, and HTTP semantics.
+
+---
+
 ## [2.4.0] - 2026-10-22
 
 ### Added

package/README.md

@@ -15,7 +15,7 @@
 
 | Item | Value |
 |---|---|
-| **Package Release** | **`v2.4.1`** (Public Beta) |
+| **Package Release** | **`v2.4.2`** (Public Beta) |
 | **Knowledge Specification** | **Google Open Knowledge Format (OKF v0.2) + MudraForge Statutory Schema Extension** |
 | **Regulatory Snapshot** | **CBDT / CBIC / MCA / MSME Baseline: October 2026** |
 | **Corpus Quality Card** | 100% Citation Resolution (15/15 URLs) in [`docs/CORPUS_QUALITY.md`](./docs/CORPUS_QUALITY.md) |

package/bin/cli.js

@@ -16,6 +16,8 @@ import {
     checkUpdates,
     syncOkf,
     getLocalManifest,
+    checkForPackageUpdate,
+    STATUTORY_CLIENT_VERSION,
     DEFAULT_LOCAL_OKF_DIR
 } from '../src/index.js';
 
@@ -68,10 +70,36 @@ async function main() {
             printHelp();
             break;
     }
+
+    // Non-intrusive background npm package update notice
+    if (!['check-update', 'status', 'version'].includes(command)) {
+        try {
+            const updateInfo = await checkForPackageUpdate();
+            if (updateInfo && updateInfo.updateAvailable) {
+                console.log('───────────────────────────────────────────────────────────────────────────');
+                console.log(`[NOTICE] A new version of @mudraforge/statutory is available: ${updateInfo.currentVersion} -> ${updateInfo.latestVersion}`);
+                console.log(`Run: npm install @mudraforge/statutory@latest or npx @mudraforge/statutory@latest`);
+                console.log('───────────────────────────────────────────────────────────────────────────\n');
+            }
+        } catch (_) {}
+    }
 }
 
 async function handleCheckUpdate() {
     try {
+        console.log('\n[INFO] Checking npm package version against registry.npmjs.org...');
+        try {
+            const pkgUpdate = await checkForPackageUpdate({ cacheTtlMs: 0 });
+            if (pkgUpdate && pkgUpdate.updateAvailable) {
+                console.log('───────────────────────────────────────────────────────────────────────────');
+                console.log(`[WARN] New npm package version available: v${pkgUpdate.latestVersion} (installed: v${pkgUpdate.currentVersion})`);
+                console.log(`Run: npm install @mudraforge/statutory@latest`);
+                console.log('───────────────────────────────────────────────────────────────────────────');
+            } else if (pkgUpdate) {
+                console.log(`[OK] npm package code is up to date (v${pkgUpdate.currentVersion}).`);
+            }
+        } catch (_) {}
+
         console.log('\n[INFO] Checking OKF knowledge substrate status against Cloudflare edge...');
         const status = await checkUpdates();
         console.log('───────────────────────────────────────────────────────────────────────────');
@@ -82,7 +110,7 @@ async function handleCheckUpdate() {
         console.log('───────────────────────────────────────────────────────────────────────────');
 
         if (status.isOutdated) {
-            console.log(`[WARN] New version available: v${status.latestVersion}`);
+            console.log(`[WARN] New legal data version available: v${status.latestVersion}`);
             console.log(`Changelog: ${status.changelog}`);
             console.log(`Run: npx @mudraforge/statutory sync to pull the latest rules.\n`);
         } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mudraforge/statutory",
-  "version": "2.4.1",
+  "version": "2.4.2",
   "description": "Open Knowledge Format (OKF) client & AI Agent Skill for Indian and cross-border statutory tax provisions. Zero dependencies.",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -10,6 +10,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import os from 'node:os';
 import crypto from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 
@@ -17,7 +18,7 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 export const DEFAULT_LOCAL_OKF_DIR = path.resolve(__dirname, '..', 'okf');
 export const DEFAULT_BASE_URL = 'https://api.mudraforge.in';
-export const STATUTORY_CLIENT_VERSION = '2.4.1';
+export const STATUTORY_CLIENT_VERSION = '2.4.2';
 
 /**
  * Pinned official release Merkle root digests.
@@ -430,6 +431,78 @@ export async function checkUpdates(options = {}) {
     };
 }
 
+/**
+ * Check if a newer version of the @mudraforge/statutory npm package is published on npmjs.com.
+ * Uses a lightweight cached file in os.tmpdir() to prevent frequent network roundtrips.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.currentVersion] - Current installed version (defaults to STATUTORY_CLIENT_VERSION).
+ * @param {number} [options.cacheTtlMs] - Cache duration in milliseconds (default: 24 hours).
+ * @param {number} [options.timeoutMs] - Request timeout in milliseconds (default: 1500ms).
+ * @param {string} [options.registryUrl] - Registry endpoint (default: https://registry.npmjs.org/@mudraforge/statutory/latest).
+ * @returns {Promise<{ updateAvailable: boolean, currentVersion: string, latestVersion: string } | null>}
+ */
+export async function checkForPackageUpdate(options = {}) {
+    if (process.env.NO_UPDATE_NOTIFIER === '1' || process.env.CI === 'true') {
+        return null;
+    }
+
+    const currentVersion = options.currentVersion || STATUTORY_CLIENT_VERSION;
+    const cacheTtlMs = options.cacheTtlMs !== undefined ? options.cacheTtlMs : 24 * 60 * 60 * 1000;
+    const timeoutMs = options.timeoutMs || 1500;
+    const cacheFile = path.join(os.tmpdir(), '.mudraforge_statutory_npm_update.json');
+
+    let cached = null;
+    if (cacheTtlMs > 0) {
+        try {
+            if (fs.existsSync(cacheFile)) {
+                const data = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+                if (data && typeof data.lastChecked === 'number' && (Date.now() - data.lastChecked < cacheTtlMs)) {
+                    cached = data;
+                }
+            }
+        } catch (_) {}
+    }
+
+    let latestVersion = cached?.latestVersion;
+
+    if (!latestVersion) {
+        try {
+            const url = options.registryUrl || 'https://registry.npmjs.org/@mudraforge/statutory/latest';
+            const res = await fetch(url, {
+                signal: AbortSignal.timeout(timeoutMs),
+                headers: { 'Accept': 'application/json' }
+            });
+            if (res.ok) {
+                const json = await res.json();
+                if (json && json.version && typeof json.version === 'string') {
+                    latestVersion = json.version;
+                    if (cacheTtlMs > 0) {
+                        try {
+                            fs.writeFileSync(cacheFile, JSON.stringify({
+                                lastChecked: Date.now(),
+                                latestVersion
+                            }), 'utf8');
+                        } catch (_) {}
+                    }
+                }
+            }
+        } catch (_) {
+            // Fail open and silent on network error, offline, or timeout
+            return null;
+        }
+    }
+
+    if (!latestVersion) return null;
+
+    const cmp = compareSemver(latestVersion, currentVersion);
+    return {
+        updateAvailable: cmp > 0,
+        currentVersion,
+        latestVersion
+    };
+}
+
 /**
  * Download and synchronize the latest OKF knowledge bundle to disk.
  * Hardened with:

package/types/index.d.ts

@@ -148,6 +148,12 @@ export declare function getLocalManifest(okfDir?: string): any;
 export declare function lookupLocalStatute(section: string, okfDir?: string): StatutoryRecord | null;
 export declare function computeTemporalStatus(statute: StatutoryRecord, asOfDate?: string): 'ACTIVE' | 'SUNSET_SUPERSEDED' | 'FUTURE_PENDING';
 export declare function checkUpdates(options?: { baseUrl?: string; okfDir?: string }): Promise<UpdateInfo>;
+export declare function checkForPackageUpdate(options?: {
+    currentVersion?: string;
+    cacheTtlMs?: number;
+    timeoutMs?: number;
+    registryUrl?: string;
+}): Promise<{ updateAvailable: boolean; currentVersion: string; latestVersion: string } | null>;
 export declare function syncOkf(options?: { baseUrl?: string; okfDir?: string }): Promise<SyncResult>;
 
 export declare function lookupStatute(