reis-mobile 0.7.0 → 0.7.1

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "AI agents for mobile engineering",
-    "version": "0.7.0"
+    "version": "0.7.1"
   },
   "plugins": [
     {
       "name": "reis-mobile",
       "source": "./",
       "description": "AI agents, skills and workflows for Flutter, Android, iOS and React Native development.",
-      "version": "0.7.0",
+      "version": "0.7.1",
       "author": {
         "name": "Warleson Reis"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "reis-mobile",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "AI agents, skills and workflows for Flutter, Android, iOS and React Native development. Use /reis-mobile:doctor, /reis-mobile:review and /reis-mobile:test.",
   "author": {
     "name": "Warleson Reis"
@@ -8,5 +8,15 @@
   "license": "MIT",
   "repository": "https://github.com/wrsilva/reis-mobile",
   "homepage": "https://github.com/wrsilva/reis-mobile",
-  "keywords": ["mobile", "flutter", "android", "ios", "react-native", "kotlin-multiplatform", "code-review", "agents", "skills"]
+  "keywords": [
+    "mobile",
+    "flutter",
+    "android",
+    "ios",
+    "react-native",
+    "kotlin-multiplatform",
+    "code-review",
+    "agents",
+    "skills"
+  ]
 }

package/CHANGELOG.md

@@ -4,6 +4,18 @@ Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). The pr
 
 ## [Unreleased]
 
+## [0.7.1] - 2026-09-17
+
+### Added
+
+- A `SessionStart` hook for Claude Code and Codex that warns when the installed plugin is behind npm's latest release. It caches registry results for 24 hours, stays silent offline and can be disabled with `REIS_MOBILE_UPDATE_CHECK=0`.
+- `reis-mobile update-check [--force]` for manually checking the CLI version.
+
+### Changed
+
+- `package.json` is the only editable version source. CI synchronizes the plugin manifests and the Release workflow tests, tags and publishes a new version after it reaches `main`.
+- Version synchronization now promotes authored `[Unreleased]` notes to a dated changelog section and refreshes the README's latest-release summary without changing historical entries.
+
 ## [0.7.0] - 2026-09-17
 
 ### Added

package/README.md

@@ -6,7 +6,7 @@ A mobile app is not a generic project. A code review that does not know about `B
 
 <p align="center">
   <a href="https://github.com/wrsilva/reis-mobile/actions/workflows/ci.yml"><img src="https://github.com/wrsilva/reis-mobile/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
-  <img src="https://img.shields.io/badge/Version-0.7.0-blue" alt="Version 0.7.0">
+  <img src="https://img.shields.io/npm/v/reis-mobile" alt="Latest npm version">
   <img src="https://img.shields.io/badge/Claude_Code-plugin-blueviolet" alt="Claude Code plugin">
   <img src="https://img.shields.io/badge/Node.js-22+-339933?logo=node.js&logoColor=white" alt="Node.js 22+">
   <img src="https://img.shields.io/badge/Dependencies-0-brightgreen" alt="Zero dependencies">
@@ -35,12 +35,29 @@ A mobile app is not a generic project. A code review that does not know about `B
 
 🔒 **Secrets never reach the model.** The diff sent for review goes through a layer that masks API keys, tokens, JWTs, private keys and keystore passwords.
 
-🪶 **Two commands to install.** `npm install -g reis-mobile` and `reis-mobile init eng` set it up in Claude Code and Codex, with zero npm dependencies, no hooks and no external provider.
+🪶 **Two commands to install.** `npm install -g reis-mobile` and `reis-mobile init eng` set it up in Claude Code and Codex, with zero npm dependencies and no external provider.
 
 ---
 
 ## What's new
 
+<!-- reis-mobile:latest-release:start -->
+### v0.7.1
+
+#### Added
+
+- A `SessionStart` hook for Claude Code and Codex that warns when the installed plugin is behind npm's latest release. It caches registry results for 24 hours, stays silent offline and can be disabled with `REIS_MOBILE_UPDATE_CHECK=0`.
+- `reis-mobile update-check [--force]` for manually checking the CLI version.
+
+#### Changed
+
+- `package.json` is the only editable version source. CI synchronizes the plugin manifests and the Release workflow tests, tags and publishes a new version after it reaches `main`.
+- Version synchronization now promotes authored `[Unreleased]` notes to a dated changelog section and refreshes the README's latest-release summary without changing historical entries.
+
+<!-- reis-mobile:latest-release:end -->
+
+### Earlier highlights
+
 **v0.7.0:** `/reis-mobile:test` runs, writes, audits or fixes tests using the app's existing setup, including XCTest/XCUITest and Espresso. The 18 agents now use a shared project brief and role-specific investigations tied to actual files, symbols and constraints.
 
 > 🆕 **v0.4.0: every mobile stack.** Native Android, native iOS and React Native get their own architect, performance and test specialists, and `/reis-mobile:debug` finds the cause of a failing build with the toolchain versions in hand.
@@ -54,7 +71,8 @@ A mobile app is not a generic project. A code review that does not know about `B
 
 | Version | Highlights |
 |--------|-----------|
-| **v0.7.0** (current) | `/reis-mobile:test`, native XCTest and Espresso guidance, and project-specific contracts for the 18 specialists. |
+| **v0.7.1** | Update notices on Claude Code and Codex session start, plus a single-source version and CI-driven release process. |
+| **v0.7.0** | `/reis-mobile:test`, native XCTest and Espresso guidance, and project-specific contracts for the 18 specialists. |
 | **v0.6.0** | `mobile-accessibility-auditor` and `mobile-release-engineer` agents with the new `mobile-accessibility` and `mobile-release` skills: accessibility audits on every stack, release readiness with a go/no-go verdict, release notes and store copy, CI/CD. `mobile-debug` gains guides for ANRs, Android memory leaks and deep links. |
 | **v0.5.0** | 11 skills instead of 60: topic skills with a guide per platform (`mobile-architecture`, `mobile-code-review`, `mobile-debug`, `mobile-test`, `mobile-security`, `mobile-firebase`) and platform skills (`mobile-flutter`, `mobile-android`, and the new `mobile-ios` and `mobile-rn`). Half the fixed context cost. |
 | **v0.4.0** | Native Android, iOS and React Native: architect, performance and test agents for each; `/reis-mobile:debug` for Gradle, Xcode, CocoaPods and Flutter failures; `mobile-test` and `mobile-firebase` with a guide per platform; the Android team's skills; `.reis-mobile/config.yaml` for monorepos. Skills now use stack prefixes. |
@@ -104,6 +122,8 @@ reis-mobile init eng
 
 Then restart Claude Code and Codex. See what changed in the [CHANGELOG](CHANGELOG.md).
 
+The plugin checks the npm `latest` tag when a Claude Code or Codex session starts or resumes. If a newer release exists, it shows an update notice; it never installs anything automatically. The registry result is cached for 24 hours, the request times out after 1.5 seconds, and offline failures are silent in the hook. Codex requires you to trust the new hook through `/hooks` before it runs. To check the CLI manually, run `reis-mobile update-check --force`; set `REIS_MOBILE_UPDATE_CHECK=0` to disable the automatic check. Versions released before this hook cannot display the notice until they are updated once.
+
 ### Uninstall
 
 ```bash
@@ -397,17 +417,17 @@ About 85 guides come from [flutter/skills](https://github.com/flutter/skills), [
 
 **Secrets masked.** The diff goes through [`core/security/redact.mjs`](core/security/redact.mjs) before reaching the model. Lock files and generated code (`*.g.dart`, `*.freezed.dart`, `*.pbxproj`) stay out of the diff. Redaction is a protection layer, not a guarantee. See [SECURITY.md](SECURITY.md).
 
-**No telemetry.** `detect`, `doctor`, `route`, `review`, `debug` and `test` make no network calls. Only installation touches the network, to download the package and register the plugin. The Google Play policy guide in `mobile-android` runs Python scripts that download your app's public Google Play listing when the model uses it. The AI analysis uses the model of the session you are working in, such as Claude Code or Codex.
+**No telemetry.** `detect`, `doctor`, `route`, `review`, `debug` and `test` make no network calls. The update hook and `update-check` request the public npm package metadata; they send no project files or identifiers. Installation downloads the package and registers the plugin. The Google Play policy guide in `mobile-android` runs Python scripts that download your app's public Google Play listing when the model uses it. The AI analysis uses the model of the session you are working in, such as Claude Code or Codex.
 
-**Exception: `/reis-mobile:debate --external`.** This flag, and only this flag, sends the debate context — including excerpts of the files mentioned in the question — to the `codex` and `gemini` CLIs, which are third-party and have their own data policies. Without the flag, nothing leaves your session. The `review` diff is masked by `redact.mjs`, but the context you cite in a debate question does not go through that layer: check what you are sending before using `--external`.
+**Exception: `/reis-mobile:debate --external`.** This flag, and only this flag, sends the debate context — including excerpts of the files mentioned in the question — to the `codex` and `gemini` CLIs, which are third-party and have their own data policies. Without the flag, the debate context stays in your session. The `review` diff is masked by `redact.mjs`, but the context you cite in a debate question does not go through that layer: check what you are sending before using `--external`.
 
 **Context cost.** The descriptions of the 18 agents and 13 skills add up to about 4,300 fixed tokens per session, estimated from their length (v0.3 measured about 4,800 with `claude plugin details reis-mobile`). The full content of each skill is only loaded when it is used.
 
-**No hooks.** The plugin does not attach to Claude Code events. It only acts when you call a command or when a skill is relevant.
+**One session hook.** On session startup or resume, the plugin checks for a newer release and warns only when the installed plugin is outdated. It does not read the project or modify the plugin installation.
 
 **Own namespace.** Commands live under `/reis-mobile:*` and do not conflict with the built-in `/review` or `/security-review`.
 
-**Clean uninstall.** `reis-mobile init --uninstall` removes the plugin and its marketplace from Claude Code and Codex, and the saved language, without leaving configuration behind.
+**Clean uninstall.** `reis-mobile init --uninstall` removes the plugin and its marketplace from Claude Code and Codex, the saved language and the update-check cache.
 
 ---
 
@@ -427,6 +447,7 @@ About 85 guides come from [flutter/skills](https://github.com/flutter/skills), [
 | v0.5.0 | Topic and platform skills (`mobile-*`), with guides for Flutter, Android, iOS and React Native in each; new `mobile-ios` and `mobile-rn` | ✅ |
 | v0.6.0 | Accessibility auditor and release engineer agents, `mobile-accessibility` and `mobile-release` skills, ANR, memory leak and deep link debugging guides | ✅ |
 | v0.7.0 | `/reis-mobile:test`, native tests (XCTest, Espresso) and project-specific specialist contracts | ✅ |
+| v0.7.1 | Update notices, single-source version and release automation | ✅ |
 | v0.8.0 | `/reis-mobile:release` with quality gates | ⏳ |
 | v0.9.0 | MCP server | ⏳ |
 | v0.10.0 | Multi-provider (OpenAI, Gemini, OpenRouter, Ollama) beyond the debate's `--external` | ⏳ |
@@ -461,7 +482,7 @@ Yes: `reis-mobile init eng` installs the plugin in Codex too. See [installation]
 The Cursor integration has not been validated yet. The MCP server remains on the roadmap for v0.8.0.
 
 **What does reis-mobile send outside my machine?**
-The CLI sends nothing. What the model reads during `/reis-mobile:review` follows the same rules as any Claude Code session.
+The project analysis commands do not make network requests. The update hook and `reis-mobile update-check` request the public npm package metadata without sending project files or identifiers. What the model reads during `/reis-mobile:review` follows the same rules as any Claude Code session.
 
 ---
 

package/bin/reis-mobile.mjs

@@ -13,6 +13,7 @@ import { PLUGIN_ROOT } from '../core/paths.mjs';
 import { loadRegistry, validateRegistry } from '../core/registry/registry.mjs';
 import { INTENT_IDS } from '../core/router/intents.mjs';
 import { route } from '../core/router/router.mjs';
+import { checkForUpdate, clearUpdateCache } from '../core/update/check.mjs';
 
 const USAGE = `reis-mobile — AI agents for mobile engineering
 
@@ -29,6 +30,7 @@ Commands:
   test [request...]          Prepare test routing, git context and toolchain checks (does not run tests)
   agents | skills | stacks   List registered components
   validate                   Validate the plugin's agents, skills and stacks
+  update-check               Check npm for a newer reis-mobile release
 
 Options:
   --dir <path>      Project directory (default: current directory, or "app" in .reis-mobile/config.yaml)
@@ -39,6 +41,7 @@ Options:
   --local           init: install the plugin from this installation instead of GitHub
   --scope <scope>   init: Claude Code scope, user (default), project or local
   --uninstall       init: remove the plugin and its marketplace from Claude Code and Codex, and the saved language
+  --force           update-check: ignore the cached registry result
   --lang <en|pt>    Override the saved language for this run
   --json            Machine-readable output
   -v, --version     Print the version
@@ -53,6 +56,7 @@ const OPTIONS = {
   local: { type: 'boolean' },
   scope: { type: 'string' },
   uninstall: { type: 'boolean' },
+  force: { type: 'boolean' },
   lang: { type: 'string' },
   json: { type: 'boolean' },
   version: { type: 'boolean', short: 'v' },
@@ -72,6 +76,7 @@ const COMMANDS = {
   skills: (options) => commandList('skills', options),
   stacks: (options) => commandList('stacks', options),
   validate: commandValidate,
+  'update-check': commandUpdateCheck,
 };
 
 async function main(argv) {
@@ -103,6 +108,15 @@ async function main(argv) {
 
 const PROJECT_COMMANDS = new Set(['detect', 'doctor', 'route', 'review', 'debug', 'test']);
 
+async function commandUpdateCheck({ force, json }) {
+  const result = await checkForUpdate({ force });
+  if (json) return print(result);
+  if (result.status === 'outdated') console.log(`reis-mobile ${result.current} is outdated; ${result.latest} is available. Run npm update -g reis-mobile && reis-mobile init.`);
+  else if (result.status === 'current') console.log(`reis-mobile ${result.current} is up to date (latest: ${result.latest}).`);
+  else console.error('Could not check the latest reis-mobile release. Try again with --force when online.');
+  return result.status === 'unavailable' ? 1 : 0;
+}
+
 async function commandInit({ local, scope, uninstall, lang, prompt }) {
   const requested = lang ?? (prompt || process.env.REIS_MOBILE_LANG || undefined);
   // Validate before touching Claude Code or Codex, so a typo does not leave a half-done install.
@@ -123,6 +137,7 @@ async function commandInit({ local, scope, uninstall, lang, prompt }) {
   }
   if (uninstall) {
     await removeConfig();
+    await clearUpdateCache();
     console.log(`✓ ${'Language'.padEnd(12)}saved setting removed`);
     return ok ? 0 : 1;
   }

package/bin/update-check.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { checkForUpdate, updateMessage } from '../core/update/check.mjs';
+
+if (process.env.REIS_MOBILE_UPDATE_CHECK !== '0') {
+  try {
+    const result = await checkForUpdate();
+    if (result.status === 'outdated') {
+      const tool = process.env.PLUGIN_ROOT ? 'codex' : 'claude';
+      process.stdout.write(`${JSON.stringify({ systemMessage: updateMessage(result, tool) })}\n`);
+    }
+  } catch {
+    // Update checks are advisory and must never fail a session.
+  }
+}

package/core/update/check.mjs

@@ -0,0 +1,119 @@
+import { readFile, mkdir, rm, rmdir, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+import { PLUGIN_ROOT } from '../paths.mjs';
+
+const REGISTRY_URL = 'https://registry.npmjs.org/reis-mobile/latest';
+const SUCCESS_TTL_MS = 24 * 60 * 60 * 1000;
+const FAILURE_TTL_MS = 60 * 60 * 1000;
+
+export function updateCachePath(env = process.env) {
+  const base = process.platform === 'win32'
+    ? env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local')
+    : env.XDG_CACHE_HOME || join(homedir(), '.cache');
+  return join(base, 'reis-mobile', 'update-check.json');
+}
+
+export async function clearUpdateCache(path = updateCachePath()) {
+  try {
+    await rm(path, { force: true });
+    await rmdir(dirname(path));
+  } catch {
+    // Cache cleanup must not prevent uninstalling the plugin.
+  }
+}
+
+export async function installedVersion(root = PLUGIN_ROOT) {
+  return JSON.parse(await readFile(join(root, 'package.json'), 'utf8')).version;
+}
+
+export function compareVersions(left, right) {
+  const parse = (value) => {
+    if (typeof value !== 'string') return null;
+    const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(value);
+    if (!match) return null;
+    const numbers = match.slice(1, 4).map(Number);
+    return numbers.every(Number.isSafeInteger) ? { numbers, prerelease: match[4] } : null;
+  };
+  const a = parse(left);
+  const b = parse(right);
+  if (!a || !b) return null;
+  for (let index = 0; index < 3; index++) {
+    if (a.numbers[index] !== b.numbers[index]) return Math.sign(a.numbers[index] - b.numbers[index]);
+  }
+  if (a.prerelease === b.prerelease) return 0;
+  if (!a.prerelease) return 1;
+  if (!b.prerelease) return -1;
+  // The package is published under the stable npm dist-tag. An unknown prerelease
+  // ordering should never generate an update warning for the same base version.
+  return null;
+}
+
+export async function fetchLatestVersion(fetcher = fetch) {
+  const response = await fetcher(REGISTRY_URL, {
+    headers: { accept: 'application/json' },
+    signal: AbortSignal.timeout(1500),
+  });
+  if (!response.ok) throw new Error(`Registry returned ${response.status}`);
+  const { version } = await response.json();
+  if (typeof version !== 'string' || compareVersions(version, version) === null) {
+    throw new Error('Registry returned an invalid version');
+  }
+  return version;
+}
+
+export async function checkForUpdate({
+  current,
+  cachePath = updateCachePath(),
+  now = Date.now(),
+  force = false,
+  fetchVersion = fetchLatestVersion,
+} = {}) {
+  const version = current ?? await installedVersion();
+  let cached;
+  try {
+    cached = JSON.parse(await readFile(cachePath, 'utf8'));
+  } catch {
+    cached = null;
+  }
+  const cachedLatest = compareVersions(cached?.latest, cached?.latest) === 0 ? cached.latest : null;
+  const age = now - cached?.checkedAt;
+  const ttl = cachedLatest ? SUCCESS_TTL_MS : FAILURE_TTL_MS;
+  let latest = cachedLatest;
+  if (force || !Number.isFinite(age) || age < 0 || age >= ttl) {
+    try {
+      latest = await fetchVersion();
+      if (compareVersions(latest, latest) === null) throw new Error('Invalid version');
+    } catch {
+      latest = cachedLatest;
+      if (!latest) {
+        await saveCache(cachePath, { checkedAt: now, latest: null });
+        return { status: 'unavailable', current: version };
+      }
+    }
+    await saveCache(cachePath, { checkedAt: now, latest });
+  }
+  if (!latest || compareVersions(version, latest) === null) return { status: 'unavailable', current: version };
+  return {
+    status: compareVersions(version, latest) < 0 ? 'outdated' : 'current',
+    current: version,
+    latest,
+  };
+}
+
+async function saveCache(path, value) {
+  try {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(value), { mode: 0o600 });
+  } catch {
+    // A read-only home must not interrupt a session.
+  }
+}
+
+export function updateMessage({ current, latest }, tool = 'claude') {
+  const update = tool === 'codex'
+    ? 'codex plugin marketplace upgrade reis-mobile && codex plugin add reis-mobile@reis-mobile'
+    : 'claude plugin marketplace update reis-mobile && claude plugin update reis-mobile@reis-mobile';
+  return `reis-mobile ${current} is outdated; ${latest} is available. Update the plugin: ${update}. If you installed the CLI with npm, also run npm update -g reis-mobile.`;
+}

package/hooks/hooks.json

@@ -0,0 +1,17 @@
+{
+  "description": "Warn when a newer reis-mobile release is available.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/update-check.mjs\"",
+            "timeout": 3
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reis-mobile",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "AI agents and skills for mobile development — Flutter, Android, iOS and React Native — as a plugin for Claude Code and Codex: code review, debugging, tests, architecture, security and Firebase.",
   "type": "module",
   "license": "MIT",
@@ -19,6 +19,7 @@
     "commands",
     "core",
     "docs/agent-context.md",
+    "hooks",
     "skills",
     "stacks",
     "THIRD_PARTY_NOTICES.md",
@@ -30,7 +31,8 @@
   "scripts": {
     "test": "node --test",
     "validate": "node bin/reis-mobile.mjs validate",
-    "check": "npm run validate && npm test"
+    "check": "npm run validate && npm test",
+    "version:sync": "node scripts/versions.mjs --sync"
   },
   "keywords": [
     "flutter",