wize-dev-kit 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -7,7 +7,11 @@ Format inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 > **0.10.0 and earlier are in Brazilian Portuguese** and are kept verbatim as a
 > historical record (not back-translated).
 
-## [Unreleased]
+## [0.18.0] — 2026-09-18
+
+### Added
+
+- **`wize-update`** (orchestrator skill) + **`wize-dev-kit version-check`** (CLI) — an agent-facing way to ask "is there a newer kit?" without hitting the network on every invocation. `version-check --json` reads a local 1h cache first, caps any registry call at ~1.5s, and degrades to `{"latest":null}` silently when offline; it honors `WIZE_DISABLE_UPDATE_CHECK=1` like the existing opportunistic hint. `wize-help`/`wize`'s proactive version-skew check (Step 2.5) now calls it instead of a live `npm view` on every invocation, says the hint at most once per conversation, and points to `/wize-update` — which shows the version jump + changelog excerpt, asks for a one-line confirmation, then runs `npx wize-dev-kit@latest update` and relays the result. Intent phrases: "atualizar o kit", "tem atualização", "nova versão do kit".
 
 ## [0.17.0] — 2026-09-08
 

package/README.es.md

@@ -157,6 +157,8 @@ Transversales:
     /wize-check                 Checklist de avance de la demanda en vuelo: hecho
                                 (con evidencia), en curso, lo que falta — luego
                                 retoma el trabajo interrumpido.
+    /wize-update                Revisa si el kit está desactualizado, muestra el
+                                changelog, confirma y aplica la actualización.
     /wize-grill                 Entrevista-hasta-entendimiento antes de cualquier
                                 paso de autoría.
     /wize-quick-dev             Shuri toma un arreglo pequeño sin el ciclo completo.
@@ -240,6 +242,7 @@ npx wize-dev-kit document-project [quick|initial_scan|full_rescan|deep_dive] [--
 npx wize-dev-kit uninstall       # elimina .wize/ (tu código queda intacto)
 npx wize-dev-kit help            # referencia de comandos
 npx wize-dev-kit version         # imprime la versión instalada del kit
+npx wize-dev-kit version-check [--json]  # instalada vs. más reciente (con caché; scriptable; nunca bloquea)
 ```
 
 ---

package/README.md

@@ -155,6 +155,8 @@ Cross-cutting:
     /wize-check                 Progress checklist for the demand in flight:
                                 done (with evidence), in progress, what's left —
                                 then resumes the interrupted work.
+    /wize-update                Checks kit version skew, shows the changelog
+                                jump, confirms, then applies the update.
     /wize-grill                 Interview-to-understanding before any authoring step.
     /wize-eli5                  Explain anything to anyone — vocabulary, analogies,
                                 tone, depth and framing calibrated to the audience
@@ -238,6 +240,7 @@ npx wize-dev-kit document-project [quick|initial_scan|full_rescan|deep_dive] [--
 npx wize-dev-kit uninstall       # remove .wize/ (your code is left untouched)
 npx wize-dev-kit help            # command reference
 npx wize-dev-kit version         # print the installed kit version
+npx wize-dev-kit version-check [--json]  # installed vs latest (cached; scriptable; never blocks)
 ```
 
 ---

package/README.pt-BR.md

@@ -156,6 +156,8 @@ Transversais:
     /wize-check                 Checklist de acompanhamento da demanda em voo:
                                 feito (com evidência), em andamento, o que falta —
                                 depois retoma o trabalho interrompido.
+    /wize-update                Verifica se o kit está desatualizado, mostra o
+                                changelog, confirma e aplica o update.
     /wize-grill                 Entrevista-até-entendimento antes de qualquer passo
                                 de autoria.
     /wize-quick-dev             Shuri pega uma correção pequena sem o ciclo completo.
@@ -238,6 +240,7 @@ npx wize-dev-kit document-project [quick|initial_scan|full_rescan|deep_dive] [--
 npx wize-dev-kit uninstall       # remove .wize/ (seu código permanece intacto)
 npx wize-dev-kit help            # referência de comandos
 npx wize-dev-kit version         # imprime a versão instalada do kit
+npx wize-dev-kit version-check [--json]  # instalada vs. mais recente (com cache; scriptável; nunca bloqueia)
 ```
 
 ---

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "wize-dev-kit",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Full-lifecycle AI-assisted development kit with Test Architect and Whiteport Design Studio embedded. Inspired by BMAD Method and WDS.",
   "keywords": [
     "ai",

package/src/orchestrator-skills/module.yaml

@@ -22,6 +22,9 @@ skills:
   - code: wize-check
     name: "Check (Wizer)"
     description: "Progress checklist for the demand in flight: done (with evidence), in progress, left, blocked. Read-only — reports, then resumes the interrupted work."
+  - code: wize-update
+    name: "Update (Wizer)"
+    description: "Checks kit version skew, shows the changelog jump, confirms, then applies `wize-dev-kit update` and reports the result."
   - code: wize-onboarding
     name: "Onboarding"
     description: "Post-install triage: greenfield vs brownfield, profile, objective. Delegates to specialists."

package/src/orchestrator-skills/wize/skill.md

@@ -99,15 +99,15 @@ See the full intent routing table in `wize-help/skill.md` (Step 2a). The same ta
 
 ## Step 2.5 — version skew (proactive)
 
-Compare `kit_version` (project.toml) vs the installed kit vs (if you have a terminal, 2s timeout) `npm view wize-dev-kit version`:
+If you have Bash, run `npx wize-dev-kit version-check --json` once — it reads a local 1h cache before touching the network, caps any registry call at ~1.5s, and degrades to `{"latest":null}` silently if offline, so this never blocks the response. Compare its `installed` field against `kit_version` (project.toml):
 
 | Condition | Suggest |
 |---|---|
-| installed > project.toml | `npx wize-dev-kit update` |
-| registry > installed | `npx wize-dev-kit@latest update` |
-| all match | nothing |
+| `installed` > `kit_version` (project.toml) | `/wize-update` |
+| `latest` > `installed` | `/wize-update` |
+| everything matches, or `latest` is `null` | nothing |
 
-Phrase as one short line, not a banner. If the user agrees and you have Bash, run it in the project root.
+Phrase as one short line, not a banner — and only the **first time in this conversation**. If you already mentioned it earlier in this session, don't repeat it.
 
 ## Step 3 — respond
 

package/src/orchestrator-skills/wize-help/skill.md

@@ -201,18 +201,19 @@ Match is case-insensitive, substring-based. Longest match wins. When no intent m
 | "create workflow", "criar workflow", "novo workflow" | `wize-create-workflow` |
 | "onboarding", "instalar kit", "primeiro uso" | `wize-onboarding` |
 | "party mode", "multi-agent", "reunir agentes" | `wize-party-mode` |
+| "atualizar o kit", "tem atualização", "nova versão do kit", "update the kit", "wize update" | `wize-update` |
 
 ## Step 2.5 — version skew (proactive)
 
-Compare `kit_version` (project.toml) vs the installed kit vs (if you have a terminal, 2s timeout) `npm view wize-dev-kit version`:
+If you have Bash, run `npx wize-dev-kit version-check --json` once — it reads a local 1h cache before touching the network, caps any registry call at ~1.5s, and degrades to `{"latest":null}` silently if offline, so this never blocks the response. Compare its `installed` field against `kit_version` (project.toml):
 
 | Condition | Suggest |
 |---|---|
-| installed > project.toml | `npx wize-dev-kit update` |
-| registry > installed | `npx wize-dev-kit@latest update` |
-| all match | nothing |
+| `installed` > `kit_version` (project.toml) | `/wize-update` |
+| `latest` > `installed` | `/wize-update` |
+| everything matches, or `latest` is `null` | nothing |
 
-Phrase as one short line, not a banner. If the user agrees and you have Bash, run it in the project root.
+Phrase as one short line, not a banner — and only the **first time in this conversation**. If you already mentioned it earlier in this session, don't repeat it.
 
 ## Step 3 — respond
 

package/src/orchestrator-skills/wize-update/skill.md

@@ -0,0 +1,61 @@
+---
+
+code: wize-update
+description: "Use quando o usuário pedir para atualizar o Wize Dev Kit, perguntar se há uma versão nova, ou quando o Wizer notar version skew (Step 2.5) e ele confirmar o update."
+name: Update (Wizer)
+module: orchestrator
+owner: wize-orchestrator
+status: ready
+aliases: []
+---
+
+# Wizer · `/wize-update`
+
+**Goal.** Bring the installed kit up to date safely: check the real version skew, show what changes before anything runs, get a one-line confirmation, apply it, report the result. Never a surprise — this rewrites files under version control.
+
+## Step 1 — check version skew
+
+If you have Bash, run:
+
+```
+npx wize-dev-kit version-check --json
+```
+
+Cheap by design: it reads a local 1h cache before touching the network, caps any registry call at ~1.5s, and degrades to `{"latest":null}` silently if offline — it never blocks this step.
+
+Read `kit_version` from `.wize/config/project.toml` — that is the version **this project's** rendered skills are on. `version-check`'s `installed` field is the kit version currently resolved by `npx` (it can already be newer than what is rendered here, if someone bumped the resolved package without running `update`).
+
+| Condition | Meaning |
+|---|---|
+| `latest` (registry) > `installed` | A newer kit exists upstream. |
+| `installed` > project's `kit_version` | This project is behind what npx already resolves. |
+| everything matches, or `latest` is `null` | Nothing to do — say so in one line and stop. Do not continue to Step 2. |
+
+## Step 2 — show the jump, then confirm
+
+State the version jump plainly (`{from} → {to}`). If you have Bash, `sed -n`/`cat` the relevant excerpt of `CHANGELOG.md` between those versions for a one-line summary of what changed — or trust the excerpt `update` itself prints in Step 3 and summarize that instead.
+
+Ask one line: *"Atualizar o kit de {from} para {to}? Isso vai re-renderizar os adapters instalados (claude-code, generic, …) e regravar `kit_version` em `project.toml`."*
+
+Never run Step 3 without this confirmation — it rewrites rendered skill/command files that live under version control, and the resulting diff should land as the user's own reviewed commit, not an unreviewed surprise.
+
+## Step 3 — run it
+
+On confirmation:
+
+```
+npx wize-dev-kit@latest update
+```
+
+Relay its output — it already reports per-adapter results and a CHANGELOG excerpt. It is idempotent and additive: it never touches `.wize/config/user.toml`, never removes custom agents/skills under `.wize/custom/`, and only rewrites the `kit_version` line in `project.toml`.
+
+## Step 4 — close the loop
+
+- Flag any adapter the output reported as `skipped` or `error` — those need a manual look.
+- Repeat, in one line, that the IDE/harness needs a restart to pick up refreshed slash commands.
+- Suggest reviewing the diff (`git status` / `git diff`) before committing — this is a real file change, not a no-op.
+
+## When NOT to use
+
+- No `.wize/` folder at all → this is a fresh install, not an update. Route to `npx wize-dev-kit install` (see `wize-onboarding`).
+- The user only wants to know whether an update exists, without applying it → Step 1 alone answers that; do not push into Step 2/3 unasked.

package/tools/installer/commands/version-check.js

@@ -0,0 +1,39 @@
+// `wize-dev-kit version-check` — explicit, agent-friendly version check.
+//
+// The other CLI commands print an opportunistic hint (version-check.js's
+// printUpdateHintIfAny) that stays silent on a non-TTY stdout so it never
+// spams a pipe. This command is the opposite: it was asked for by name —
+// by a human, or by an AI agent shelling out from a skill instruction where
+// stdout is never a TTY — so it always answers, in `--json` when a caller
+// needs to parse it.
+
+'use strict';
+
+const { getVersionCheckResult } = require('../version-check.js');
+
+async function cmdVersionCheck({ currentVersion, json = false, log = console.log } = {}) {
+  const result = await getVersionCheckResult(currentVersion);
+
+  if (json) {
+    log(JSON.stringify(result));
+    return result;
+  }
+
+  if (result.disabled) {
+    log('Update check disabled (WIZE_DISABLE_UPDATE_CHECK=1).');
+    return result;
+  }
+  if (!result.latest) {
+    log(`wize-dev-kit ${result.installed} (could not reach the registry — offline or timed out).`);
+    return result;
+  }
+  if (result.updateAvailable) {
+    log(`↑ Update available: wize-dev-kit ${result.installed} → ${result.latest}`);
+    log('  Run `npx wize-dev-kit@latest update` in your project to refresh adapters — or `/wize-update` from inside your AI harness.');
+  } else {
+    log(`wize-dev-kit ${result.installed} is up to date.`);
+  }
+  return result;
+}
+
+module.exports = { cmdVersionCheck };

package/tools/installer/version-check.js

@@ -104,6 +104,25 @@ async function printUpdateHintIfAny(currentVersion, { log = console.log, isTTY =
   }
 }
 
+// Pure, TTY-agnostic version check. printUpdateHintIfAny above is an
+// opportunistic hint meant for a human's terminal (gated on isTTY so it
+// never spams a pipe or a script); this is the explicit-invocation
+// counterpart behind the `version-check` CLI command, which an AI agent
+// shells out to non-interactively — stdout there is never a TTY, so a
+// TTY-gated check would go silent exactly when it's needed. Always resolves
+// to a plain object, never throws, and shares the same 1h cache.
+async function getVersionCheckResult(currentVersion, { skipCache = false } = {}) {
+  if (process.env.WIZE_DISABLE_UPDATE_CHECK === '1') {
+    return { installed: currentVersion, latest: null, updateAvailable: false, disabled: true };
+  }
+  const latest = await getLatestVersion({ skipCache });
+  return {
+    installed: currentVersion,
+    latest: latest || null,
+    updateAvailable: latest ? semverGreater(latest, currentVersion) : false
+  };
+}
+
 module.exports = {
   CACHE_TTL_MS,
   NETWORK_TIMEOUT_MS,
@@ -113,5 +132,6 @@ module.exports = {
   fetchLatestFromRegistry,
   getLatestVersion,
   semverGreater,
-  printUpdateHintIfAny
+  printUpdateHintIfAny,
+  getVersionCheckResult
 };

package/tools/installer/wize-cli.js

@@ -19,6 +19,7 @@ const prompts = require('prompts');
 const { applyGitignore, generateUserToml } = require('./setup-helpers.js');
 const { cmdUpdate, loadProjectConfig } = require('./commands/update.js');
 const { printUpdateHintIfAny } = require('./version-check.js');
+const { cmdVersionCheck } = require('./commands/version-check.js');
 const { cmdSync: cmdSyncReal } = require('./commands/sync.js');
 const { cmdAgentList, cmdAgentCreate, cmdAgentEdit } = require('./commands/agent.js');
 const { cmdDoctor, adapterTargetPath } = require('./commands/doctor.js');
@@ -73,6 +74,7 @@ Usage:
 Commands:
   install                 Install the kit into the current repo (interactive).
   update                  Apply upstream diff while preserving customizations.
+  version-check [--json]  Check installed vs. latest version (scriptable; never blocks).
   uninstall               Remove the kit from the current repo (preserves code).
   list                    List installed agents, skills and workflows.
   sync                    Regenerate IDE adapters for active targets.
@@ -891,6 +893,8 @@ async function main() {
   switch (cmd) {
     case 'install':   return cmdInstall(rest);
     case 'update':    return cmdUpdate({ kitRoot: KIT_ROOT, projectRoot: process.cwd() });
+    case 'version-check':
+      return cmdVersionCheck({ currentVersion: KIT_VERSION, json: rest.includes('--json') });
     case 'uninstall': return cmdUninstall(rest);
     case 'list':      return cmdList();
     case 'sync':      return cmdSync();