wize-dev-kit 0.26.1 → 0.27.2

package/tools/installer/render-targets.js

@@ -0,0 +1,112 @@
+// One runner for "render these adapters into this project", shared by
+// install, update, sync and hydrate. Per-adapter failures are isolated, the
+// write guard is always cleared, and counts come from render-shared's write
+// stats rather than from each adapter's own return value.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const shared = require('./render-shared.js');
+const { ALIAS_BY_TARGET } = require('./setup-helpers.js');
+
+// Where each adapter drops its `wize-*` entries. A configured target whose
+// directory has no top-level `wize-` entry, or lacks its `wize` alias
+// entrypoint, has not been rendered in this checkout, whatever else lives there.
+const SENTINEL_DIRS = {
+  'claude-code': '.claude/skills',
+  copilot: '.github/skills',
+  antigravity: '.agent/skills',
+  codex: '.agents/skills',
+  'kimi-code': '.kimi/skills',
+  hermes: '.hermes/skills',
+  kiro: '.kiro/skills',
+  cursor: '.cursor/rules',
+  windsurf: '.windsurf/rules',
+  continue: '.continue/prompts',
+  opencode: '.opencode/agents',
+  generic: '.wize/agents'
+};
+
+// Directories an adapter writes besides its sentinel dir (personas and commands).
+const EXTRA_OUTPUT_DIRS = {
+  copilot: ['.github/agents'],
+  opencode: ['.opencode/commands']
+};
+
+// Every path an adapter's render can overwrite: sentinel dir, extra dirs and aliases.
+function outputSpecs(code) {
+  return [SENTINEL_DIRS[code], ...(EXTRA_OUTPUT_DIRS[code] || []), ...(ALIAS_BY_TARGET[code] || [])].filter(Boolean);
+}
+
+function hasSentinel(projectRoot, code) {
+  const rel = SENTINEL_DIRS[code];
+  if (!rel) return true; // unknown (custom) target: nothing to check
+  try {
+    if (!fs.readdirSync(path.join(projectRoot, rel)).some(n => n.startsWith('wize-'))) return false;
+  } catch {
+    return false;
+  }
+  return (ALIAS_BY_TARGET[code] || []).every(a => fs.existsSync(path.join(projectRoot, a)));
+}
+
+function missingTargets(projectRoot, targets) {
+  return (targets || []).map(t => (typeof t === 'string' ? t : t && t.code)).filter(c => c && !hasSentinel(projectRoot, c));
+}
+
+const codeOf = (x) => (typeof x === 'string' ? x : x && x.code);
+
+function renderTargets({ kitRoot, projectRoot, targets, profiles, guard = null, probe = false, skipAgentsMd = false, log = () => {} }) {
+  const profileCodes = (profiles || ['core']).map(codeOf);
+  const adapters = [];
+  if (guard) shared.setWriteGuard(guard);
+  shared.setProbeMode(probe);
+  try {
+    for (const target of targets || []) {
+      const code = codeOf(target);
+      const entry = { code, written: 0, unchanged: 0, skippedTracked: [] };
+      adapters.push(entry);
+      const renderPath = path.join(kitRoot, 'adapters', code, 'render.js');
+      if (!fs.existsSync(renderPath)) {
+        entry.skipped = true;
+        entry.reason = 'adapter missing';
+        log(`  - ${code}: skipped (adapter missing in this kit version)`);
+        continue;
+      }
+      delete require.cache[require.resolve(renderPath)]; // keep repeated runs in one process honest
+      shared.resetWriteStats();
+      try {
+        const mod = require(renderPath);
+        if (typeof mod.render !== 'function') {
+          entry.skipped = true;
+          entry.reason = 'no render() export';
+          log(`  - ${code}: skipped (no render() export)`);
+          continue;
+        }
+        const out = mod.render(kitRoot, projectRoot, { profiles: profileCodes, skipAgentsMd });
+        if (!out || !Array.isArray(out.written)) {
+          entry.skipped = true;
+          entry.reason = 'stub (no skills emitted)';
+          log(`  - ${code}: skipped (stub, no skills emitted)`);
+          continue;
+        }
+        const stats = shared.getWriteStats();
+        entry.written = stats.written;
+        entry.unchanged = stats.unchanged;
+        entry.skippedTracked = stats.skippedTracked;
+        const tracked = entry.skippedTracked.length ? `, ${entry.skippedTracked.length} tracked left alone` : '';
+        log(`  ✓ ${code}: ${entry.written} written, ${entry.unchanged} unchanged${tracked}`);
+      } catch (err) {
+        entry.error = err.message;
+        log(`  ✖ ${code}: ${err.message}`);
+      }
+    }
+  } finally {
+    shared.clearWriteGuard();
+    shared.setProbeMode(false);
+    shared.resetWriteStats();
+  }
+  return { ok: adapters.every(a => !a.error), adapters };
+}
+
+module.exports = { renderTargets, SENTINEL_DIRS, EXTRA_OUTPUT_DIRS, outputSpecs, missingTargets };

package/tools/installer/semver.js

@@ -0,0 +1,59 @@
+// Single semver implementation for the installer: parse, compare, greater.
+// Prerelease-aware (0.27.0-rc.1 < 0.27.0); build metadata is ignored.
+
+'use strict';
+
+const SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z.-]+)?$/;
+
+// Returns { major, minor, patch, pre: [] } or null when `v` is not semver.
+function parse(v) {
+  if (typeof v !== 'string') return null;
+  const m = SEMVER_RE.exec(v.trim().replace(/^v/i, ''));
+  if (!m) return null;
+  const pre = m[4] ? m[4].split('.').map(id => (/^\d+$/.test(id) ? Number(id) : id)) : [];
+  return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]), pre };
+}
+
+function comparePre(a, b) {
+  if (!a.length && !b.length) return 0;
+  if (!a.length) return 1;   // a release outranks any prerelease
+  if (!b.length) return -1;
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    if (i >= a.length) return -1;
+    if (i >= b.length) return 1;
+    const x = a[i];
+    const y = b[i];
+    if (x === y) continue;
+    const xn = typeof x === 'number';
+    const yn = typeof y === 'number';
+    if (xn && yn) return x < y ? -1 : 1;
+    if (xn) return -1;         // numeric identifiers sort below alphanumeric
+    if (yn) return 1;
+    return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+// -1 | 0 | 1. An unparseable argument counts as 0.0.0, so garbage never
+// outranks a real version.
+function compareVersions(a, b) {
+  const zero = { major: 0, minor: 0, patch: 0, pre: [] };
+  const pa = parse(a) || zero;
+  const pb = parse(b) || zero;
+  for (const k of ['major', 'minor', 'patch']) {
+    if (pa[k] !== pb[k]) return pa[k] < pb[k] ? -1 : 1;
+  }
+  return comparePre(pa.pre, pb.pre);
+}
+
+// A pin that is safe to put in a command line: plain semver, no `v` prefix,
+// whitespace or build metadata (same rule as .wize/hooks/hydrate.sh).
+const SAFE_PIN_RE = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$/;
+const isSafePin = (v) => typeof v === 'string' && SAFE_PIN_RE.test(v);
+const safePin = (v) => (isSafePin(v) ? v : null);
+
+function semverGreater(a, b) {
+  return compareVersions(a, b) > 0;
+}
+
+module.exports = { parse, compareVersions, semverGreater, isSafePin, safePin };

package/tools/installer/setup-helpers.js

@@ -12,6 +12,45 @@ const path = require('node:path');
 const GITIGNORE_BEGIN = '# >>> wize-dev-kit (managed) >>>';
 const GITIGNORE_END = '# <<< wize-dev-kit (managed) <<<';
 
+// The 12 entrypoints for the `wize` alias skill/command each adapter emits,
+// per adapter target. `wize-*` globs do not match them (no hyphen), so each gets
+// an explicit line. Never widen to `wize*`: that would swallow user files such
+// as wizebar.
+const ALIAS_BY_TARGET = {
+  'claude-code': ['.claude/skills/wize/'],
+  copilot: ['.github/skills/wize/'],
+  antigravity: ['.agent/skills/wize/'],
+  codex: ['.agents/skills/wize/'],
+  'kimi-code': ['.kimi/skills/wize/'],
+  hermes: ['.hermes/skills/wize/'],
+  kiro: ['.kiro/skills/wize/'],
+  cursor: ['.cursor/rules/wize.mdc'],
+  windsurf: ['.windsurf/rules/wize.md'],
+  continue: ['.continue/prompts/wize.prompt'],
+  opencode: ['.opencode/commands/wize.md'],
+  generic: ['.wize/agents/wize.md']
+};
+
+const ALIAS_PATHS = Object.values(ALIAS_BY_TARGET).flat();
+
+// Generated outputs: the `wize-*` glob per location plus its explicit alias line.
+const GENERATED_PATHS = [
+  { dir: '.claude/skills/', glob: 'wize-*', alias: 'wize/' },
+  { dir: '.github/skills/', glob: 'wize-*', alias: 'wize/' },
+  { dir: '.github/agents/', glob: 'wize-*.agent.md', alias: null },
+  { dir: '.agent/skills/', glob: 'wize-*', alias: 'wize/' },
+  { dir: '.agents/skills/', glob: 'wize-*', alias: 'wize/' },
+  { dir: '.kimi/skills/', glob: 'wize-*', alias: 'wize/' },
+  { dir: '.hermes/skills/', glob: 'wize-*', alias: 'wize/' },
+  { dir: '.kiro/skills/', glob: 'wize-*', alias: 'wize/' },
+  { dir: '.cursor/rules/', glob: 'wize-*.mdc', alias: 'wize.mdc' },
+  { dir: '.windsurf/rules/', glob: 'wize-*.md', alias: 'wize.md' },
+  { dir: '.continue/prompts/', glob: 'wize-*.prompt', alias: 'wize.prompt' },
+  { dir: '.opencode/agents/', glob: 'wize-*.md', alias: null },
+  { dir: '.opencode/commands/', glob: 'wize-*.md', alias: 'wize.md' },
+  { dir: '.wize/agents/', glob: 'wize-*.md', alias: 'wize.md' }
+];
+
 const GITIGNORE_BODY = [
   '# Personal / per-developer (do NOT commit)',
   '.wize/config/user.toml',
@@ -19,27 +58,17 @@ const GITIGNORE_BODY = [
   '.wize/.local/',
   '.wize/implementation/quick-dev-log.md',
   '',
-  '# Generated IDE adapter outputs (regenerate with `npx wize-dev-kit install`)',
-  '.claude/skills/wize-*',
-  '.github/skills/wize-*',
-  '.github/agents/wize-*.agent.md',
-  '.agent/skills/wize-*',
-  '.agents/skills/wize-*',
-  '.kimi/skills/wize-*',
-  '.hermes/skills/wize-*',
-  '.kiro/skills/wize-*',
-  '.cursor/rules/wize-*.mdc',
-  '.windsurf/rules/wize-*.md',
-  '.continue/prompts/wize-*.prompt',
-  '.opencode/agents/wize-*.md',
-  '.opencode/commands/wize-*.md',
-  '.wize/agents/wize-*.md'
+  '# Generated IDE adapter outputs (regenerate with `npx wize-dev-kit hydrate`)',
+  ...GENERATED_PATHS.flatMap(g => [g.dir + g.glob, ...(g.alias ? [g.dir + g.alias] : [])]),
+  '',
+  '# Worktrees created inside the repo (Claude Code)',
+  '.claude/worktrees/'
 ].join('\n');
 
 function buildGitignoreBlock() {
   return [
     GITIGNORE_BEGIN,
-    '# Managed by `npx wize-dev-kit install`. Re-running install will update',
+    '# Managed by wize-dev-kit (install/update). Re-running either updates',
     '# the lines between the markers below; lines outside are untouched.',
     '',
     GITIGNORE_BODY,
@@ -47,35 +76,51 @@ function buildGitignoreBlock() {
   ].join('\n');
 }
 
-// Idempotent: if the block exists, replace it; otherwise append.
-// Returns { changed: boolean, mode: 'created'|'replaced'|'appended'|'unchanged' }.
-function applyGitignore(projectRoot, { dryRun = false } = {}) {
-  const file = path.join(projectRoot, '.gitignore');
+// Pure: the .gitignore text after the managed block is applied to `current`
+// (null/'' for no file). Returns { next, changed, mode } with mode
+// 'created'|'replaced'|'appended'|'unchanged'.
+function computeGitignore(current) {
+  const exists = current !== null && current !== undefined;
+  const text = exists ? current : '';
   const block = buildGitignoreBlock();
-  let current = '';
-  let exists = fs.existsSync(file);
-  if (exists) current = fs.readFileSync(file, 'utf-8');
-
-  const startIdx = current.indexOf(GITIGNORE_BEGIN);
-  const endIdx = current.indexOf(GITIGNORE_END);
+  const startIdx = text.indexOf(GITIGNORE_BEGIN);
+  const endIdx = text.indexOf(GITIGNORE_END);
   let next;
   let mode;
 
   if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
-    const before = current.slice(0, startIdx).replace(/\n+$/, '');
-    const after = current.slice(endIdx + GITIGNORE_END.length).replace(/^\n+/, '');
+    const before = text.slice(0, startIdx).replace(/\n+$/, '');
+    const after = text.slice(endIdx + GITIGNORE_END.length).replace(/^\n+/, '');
     next = [before, block, after].filter(Boolean).join('\n\n');
     if (!next.endsWith('\n')) next += '\n';
-    mode = current.includes(block) ? 'unchanged' : 'replaced';
+    mode = text.includes(block) ? 'unchanged' : 'replaced';
   } else if (exists) {
-    next = current.replace(/\n+$/, '') + '\n\n' + block + '\n';
+    next = text.replace(/\n+$/, '') + '\n\n' + block + '\n';
     mode = 'appended';
   } else {
     next = block + '\n';
     mode = 'created';
   }
+  return { next, changed: next !== text, mode };
+}
+
+// 'ok' | 'drift' | 'missing': whether the managed block in `current` (null
+// for no file) is byte-for-byte what this kit would write.
+function gitignoreBlockStatus(current) {
+  if (current === null || current === undefined) return 'missing';
+  const text = String(current).replace(/\r\n/g, '\n');
+  const startIdx = text.indexOf(GITIGNORE_BEGIN);
+  const endIdx = text.indexOf(GITIGNORE_END);
+  if (startIdx === -1 || endIdx === -1 || endIdx < startIdx) return 'missing';
+  return text.slice(startIdx, endIdx + GITIGNORE_END.length) === buildGitignoreBlock() ? 'ok' : 'drift';
+}
 
-  const changed = next !== current;
+// Idempotent: if the block exists, replace it; otherwise append.
+// Returns { changed: boolean, mode: 'created'|'replaced'|'appended'|'unchanged' }.
+function applyGitignore(projectRoot, { dryRun = false } = {}) {
+  const file = path.join(projectRoot, '.gitignore');
+  const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf-8') : null;
+  const { next, changed, mode } = computeGitignore(current);
   if (changed && !dryRun) fs.writeFileSync(file, next, 'utf-8');
   return { changed, mode };
 }
@@ -100,10 +145,23 @@ ${roleLine}
 `;
 }
 
+// user.toml content for a checkout that has no copy to inherit: the name comes
+// from `git config user.name`, then $USER, then "Developer".
+function deriveUserToml(root, env = process.env) {
+  const { configUserName } = require('./git-context.js');
+  const name = configUserName(root) || env.USER || env.USERNAME || 'Developer';
+  return generateUserToml({ name });
+}
+
 module.exports = {
+  deriveUserToml,
   GITIGNORE_BEGIN,
   GITIGNORE_END,
+  ALIAS_PATHS,
+  ALIAS_BY_TARGET,
   buildGitignoreBlock,
+  computeGitignore,
+  gitignoreBlockStatus,
   applyGitignore,
   generateUserToml
 };

package/tools/installer/templates/hydrate.sh

@@ -0,0 +1,163 @@
+#!/bin/sh
+# wize-dev-kit managed hook v1
+# Hydrates this checkout from .wize/config/project.toml without touching tracked
+# files. `wize-dev-kit update` refreshes this file; local edits are overwritten.
+# Always exits 0 so a failure never blocks worktree creation or a session start.
+# Messages go to stderr: a Claude Code SessionStart hook adds stdout to the context.
+
+# Same precedence as the CLI's resolveRoot: CLAUDE_PROJECT_DIR (the Claude session's
+# own checkout), then the project found from the current directory (up to the git
+# boundary), and only then ORCA_WORKTREE_PATH, which may be inherited from an Orca
+# terminal of another worktree. The child hydrates this directory whatever else the
+# environment says.
+root=""
+if [ -n "$CLAUDE_PROJECT_DIR" ]; then
+  root=$CLAUDE_PROJECT_DIR
+else
+  # The walk ends at the first directory holding .git; with none above, only $PWD counts.
+  boundary=""
+  d=$PWD
+  while :; do
+    if [ -e "$d/.git" ]; then boundary=$d; break; fi
+    parent=$(dirname "$d")
+    [ "$parent" = "$d" ] && break
+    d=$parent
+  done
+  d=$PWD
+  while :; do
+    if [ -f "$d/.wize/config/project.toml" ]; then root=$d; break; fi
+    { [ -z "$boundary" ] || [ "$d" = "$boundary" ]; } && break
+    d=$(dirname "$d")
+  done
+  [ -n "$root" ] || root=${ORCA_WORKTREE_PATH:-$PWD}
+fi
+cd "$root" || exit 0
+WIZE_PROJECT_ROOT=$PWD
+export WIZE_PROJECT_ROOT
+toml=.wize/config/project.toml
+[ -f "$toml" ] || { echo "wize: no $toml here, skipping" >&2; exit 0; }
+
+pin=$(sed -n 's/^kit_version *= *"\([^"]*\)".*/\1/p' "$toml" | head -1)
+# Anchored: a glob would let "1.2.3.4:host/repo" through, which npm reads as a git spec.
+printf '%s' "$pin" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$' || pin=""
+pkg="wize-dev-kit@${pin:-latest}"
+
+# Where the first configured target keeps its wize-* entries and its `wize`
+# entrypoint (mirrors ALIAS_BY_TARGET in setup-helpers.js).
+target=$(sed -n 's/^ide_targets *= *\[ *"\([^"]*\)".*/\1/p' "$toml" | head -1)
+case "${target:-claude-code}" in
+  claude-code) dir=.claude/skills;     alias=.claude/skills/wize ;;
+  copilot)     dir=.github/skills;     alias=.github/skills/wize ;;
+  antigravity) dir=.agent/skills;      alias=.agent/skills/wize ;;
+  codex)       dir=.agents/skills;     alias=.agents/skills/wize ;;
+  kimi-code)   dir=.kimi/skills;       alias=.kimi/skills/wize ;;
+  hermes)      dir=.hermes/skills;     alias=.hermes/skills/wize ;;
+  kiro)        dir=.kiro/skills;       alias=.kiro/skills/wize ;;
+  cursor)      dir=.cursor/rules;      alias=.cursor/rules/wize.mdc ;;
+  windsurf)    dir=.windsurf/rules;    alias=.windsurf/rules/wize.md ;;
+  continue)    dir=.continue/prompts;  alias=.continue/prompts/wize.prompt ;;
+  opencode)    dir=.opencode/agents;   alias=.opencode/commands/wize.md ;;
+  generic)     dir=.wize/agents;       alias=.wize/agents/wize.md ;;
+  *)           dir="";                 alias="" ;;
+esac
+
+# True when `dir` holds wize-* entries and the `wize` entrypoint exists.
+has_wize() {
+  [ -n "$dir" ] && [ -n "$alias" ] && [ -e "$alias" ] || return 1
+  for f in "$dir"/wize-*; do [ -e "$f" ] && return 0; done
+  return 1
+}
+
+# hydrate ships in 0.27.0; older pins only know sync.
+legacy=0
+if [ -n "$pin" ] && [ "$(printf '%s\n' 0.27.0 "$pin" | sort -V | head -1)" != 0.27.0 ]; then legacy=1; fi
+# sort -V ranks 0.27.0-rc.1 after 0.27.0; semver ranks it before.
+case "$pin" in 0.27.0-*) legacy=1 ;; esac
+
+# The pin a marker records: its "pin" when present, else "kit_version".
+marker=.wize/.local/hydrated.json
+marker_matches() {
+  [ -f "$marker" ] || return 1
+  # A fallback render (the pinned kit could not be run) is current for an hour only.
+  if grep -q '"fallback": *true' "$marker" 2>/dev/null && [ -z "$(find "$marker" -mmin -60 2>/dev/null)" ]; then return 1; fi
+  if grep -q '"pin": *"' "$marker" 2>/dev/null; then
+    grep -Fq "\"pin\": \"$pin\"" "$marker"
+  else
+    grep -Fq "\"kit_version\": \"$pin\"" "$marker"
+  fi
+}
+
+# Fast path: already hydrated for this pin. No npx, no network. A legacy pin's
+# own `sync` writes no marker and no user.toml, and an exact pin is immutable,
+# so its files being present is enough (a marker, when there is one, must match).
+if [ -n "$pin" ] && has_wize; then
+  if [ "$legacy" = 1 ]; then
+    if [ ! -f "$marker" ] || marker_matches; then exit 0; fi
+  elif [ -f .wize/config/user.toml ] && marker_matches; then
+    exit 0
+  fi
+fi
+
+# user.toml is per developer and git-ignored: copy it from the primary checkout.
+common_dir() { (cd "$1" 2>/dev/null && d=$(git rev-parse --git-common-dir 2>/dev/null) && cd "$d" 2>/dev/null && pwd -P); }
+primary=""
+if [ -n "$ORCA_ROOT_PATH" ] && [ -n "$(common_dir .)" ] && [ "$(common_dir "$ORCA_ROOT_PATH")" = "$(common_dir .)" ]; then
+  primary=$ORCA_ROOT_PATH
+fi
+[ -n "$primary" ] || primary=$(git worktree list --porcelain 2>/dev/null | sed -n '1s/^worktree //p')
+if [ ! -f .wize/config/user.toml ] && [ -n "$primary" ] && [ -f "$primary/.wize/config/user.toml" ]; then
+  cp "$primary/.wize/config/user.toml" .wize/config/user.toml && echo "wize: user.toml copied from $primary" >&2
+fi
+
+if [ "$legacy" = 1 ]; then
+  cmd=sync
+  quiet=""
+else
+  cmd=hydrate
+  quiet="--quiet"
+fi
+
+# Offline, npx spends about 70 s revalidating the packument even for a cached
+# version, which would outlast the 180 s SessionStart timeout over 3 attempts.
+# An exact pin is immutable, so use the cache as is; npm's own retries are off
+# because this loop retries, and each attempt is capped by `timeout` when it
+# exists. Without `timeout`, npm's fetch timeout (20 s per request) bounds a
+# refused or slow answer, but not a registry that silently drops packets.
+offline=""
+[ -n "$pin" ] && offline="--prefer-offline"
+cap=""
+command -v timeout >/dev/null 2>&1 && cap="timeout 55"
+
+backoff="${WIZE_HOOK_BACKOFF_S:-2}"
+errf=$(mktemp 2>/dev/null) || errf=""
+ok=0
+i=1
+while [ "$i" -le 3 ]; do
+  # shellcheck disable=SC2086
+  if [ -n "$errf" ]; then
+    WIZE_SKIP_BASELINE=1 npm_config_fetch_retries=0 npm_config_fetch_timeout=20000 $cap npx --yes $offline "$pkg" "$cmd" $quiet >&2 2>"$errf"
+    rc=$?
+    cat "$errf" >&2
+  else
+    WIZE_SKIP_BASELINE=1 npm_config_fetch_retries=0 npm_config_fetch_timeout=20000 $cap npx --yes $offline "$pkg" "$cmd" $quiet >&2
+    rc=$?
+  fi
+  if [ "$rc" = 0 ]; then ok=1; break; fi
+  # ETARGET / notarget: the pin is not on the registry; retrying gets the same answer.
+  if [ -n "$errf" ] && grep -Eq 'ETARGET|notarget' "$errf" 2>/dev/null; then break; fi
+  # 124: `timeout` killed the attempt (a network that drops packets); retrying only waits again.
+  [ "$rc" = 124 ] && break
+  [ "$i" -lt 3 ] && sleep $((i * backoff))
+  i=$((i + 1))
+done
+[ -z "$errf" ] || rm -f "$errf"
+[ "$ok" = 1 ] || echo "wize: $cmd failed; run: npx $pkg $cmd" >&2
+
+# hydrate prints its own update notice; older pins get one from the registry.
+if [ "$cmd" = sync ] && [ "$WIZE_DISABLE_UPDATE_CHECK" != 1 ] && command -v npm >/dev/null 2>&1; then
+  if command -v timeout >/dev/null 2>&1; then latest=$(timeout 5 npm view wize-dev-kit version 2>/dev/null); else latest=""; fi
+  if [ -n "$latest" ] && [ "$latest" != "$pin" ]; then
+    echo "wize: project pinned to $pin, latest is $latest (update on the default branch: npx wize-dev-kit@latest update)" >&2
+  fi
+fi
+exit 0

package/tools/installer/templates/wize-kit-update.yml

@@ -0,0 +1,38 @@
+# Managed by `wize-dev-kit hooks install --github-action`; safe to edit.
+# Opens a pull request that bumps the wize-dev-kit pin once a week.
+#
+# Pull requests created with GITHUB_TOKEN do not trigger other workflows, so
+# required checks will not run on them until someone pushes to the branch.
+# The repository setting "Allow GitHub Actions to create and approve pull
+# requests" (Settings > Actions > General) must be enabled.
+name: Wize kit update
+
+on:
+  schedule:
+    - cron: '17 6 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - name: Set git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+      - name: Prepare the kit update PR
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          BASE_BRANCH: ${{ github.event.repository.default_branch }}
+        # A fresh checkout has no origin/HEAD, so name the default branch explicitly.
+        run: npx --yes wize-dev-kit@latest update --pr --base "origin/$BASE_BRANCH"

package/tools/installer/toml.js

@@ -0,0 +1,133 @@
+// Minimal TOML reader/writer for the subset the kit emits: `[section]`
+// headers, `key = "value"` scalars and `key = ["a", "b"]` string arrays.
+// The writer is surgical: it edits one string value in place and verifies the
+// result, so a caller can never report a rewrite that did not happen.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Drops a trailing `# comment`, but only when the `#` sits outside a string.
+function stripComment(line) {
+  let quote = null;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (quote === '"') {
+      if (ch === '\\') i++;
+      else if (ch === '"') quote = null;
+    } else if (quote === "'") {
+      if (ch === "'") quote = null;
+    } else if (ch === '"' || ch === "'") {
+      quote = ch;
+    } else if (ch === '#') {
+      return line.slice(0, i);
+    }
+  }
+  return line;
+}
+
+function parseTomlValue(raw) {
+  if (raw.startsWith('"') && raw.endsWith('"')) return raw.slice(1, -1);
+  if (raw.startsWith("'") && raw.endsWith("'")) return raw.slice(1, -1);
+  if (raw.startsWith('[') && raw.endsWith(']')) {
+    return raw.slice(1, -1).split(',').map(s => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+  }
+  if (raw === 'true') return true;
+  if (raw === 'false') return false;
+  if (!isNaN(Number(raw))) return Number(raw);
+  return raw;
+}
+
+function parseToml(content) {
+  const out = {};
+  let section = null;
+  for (const raw of content.split('\n')) {
+    const line = stripComment(raw).trim();
+    if (!line) continue;
+    const head = line.match(/^\[([^\]]+)\]$/);
+    if (head) { section = head[1]; out[section] = out[section] || {}; continue; }
+    const kv = line.match(/^([a-zA-Z_][\w-]*)\s*=\s*(.+)$/);
+    if (!kv) continue;
+    const [, key, valRaw] = kv;
+    const v = parseTomlValue(valRaw.trim());
+    if (section) out[section][key] = v;
+    else out[key] = v;
+  }
+  return out;
+}
+
+function readToml(file) {
+  let content;
+  try { content = fs.readFileSync(file, 'utf-8'); } catch { return {}; }
+  return parseToml(content);
+}
+
+function loadProjectConfig(projectRoot) {
+  return readToml(path.join(projectRoot, '.wize/config/project.toml'));
+}
+
+function escapeRe(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Pure rewrite of `key = "value"` inside `[section]`: keeps a trailing
+// comment, inserts the key right after the header when absent. Returns the new
+// text (identical to `content` when nothing changes), or null when the value
+// is unsafe to write, the section is missing, the key holds a non-string
+// value, or the result does not parse back to the new value.
+function rewriteTomlValue(content, section, key, value) {
+  const val = String(value);
+  if (/["\\\r\n]/.test(val)) return null;
+
+  const eol = content.includes('\r\n') ? '\r\n' : '\n';
+  const lines = content.split('\n');
+  const headRe = new RegExp('^\\s*\\[' + escapeRe(section) + '\\]\\s*(#.*)?\\r?$');
+  const start = lines.findIndex(l => headRe.test(l));
+  if (start === -1) return null;
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^\s*\[/.test(lines[i])) { end = i; break; }
+  }
+
+  const keyRe = new RegExp('^\\s*' + escapeRe(key) + '\\s*=');
+  const strRe = new RegExp('^(\\s*' + escapeRe(key) + '\\s*=\\s*)"[^"]*"(\\s*(#.*)?)$');
+  let idx = -1;
+  for (let i = start + 1; i < end; i++) {
+    if (keyRe.test(lines[i])) { idx = i; break; }
+  }
+
+  if (idx === -1) {
+    lines.splice(start + 1, 0, `${key} = "${val}"` + (eol === '\r\n' ? '\r' : ''));
+  } else {
+    if (!strRe.test(lines[idx])) return null;
+    lines[idx] = lines[idx].replace(strRe, (_, pre, post) => `${pre}"${val}"${post}`);
+  }
+
+  const next = lines.join('\n');
+  const parsed = parseToml(next);
+  return parsed[section] && parsed[section][key] === val ? next : null;
+}
+
+// Sets `key = "value"` inside `[section]` on disk. Returns false when the
+// rewrite is refused or the re-read file does not carry the new value.
+function setTomlValue(file, section, key, value) {
+  let content;
+  try { content = fs.readFileSync(file, 'utf-8'); } catch { return false; }
+  const next = rewriteTomlValue(content, section, key, value);
+  if (next === null) return false;
+  if (next !== content) {
+    const tmp = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`);
+    try {
+      fs.writeFileSync(tmp, next, 'utf-8');
+      fs.renameSync(tmp, file);
+    } catch {
+      try { fs.rmSync(tmp, { force: true }); } catch { /* ignore */ }
+      return false;
+    }
+  }
+  const parsed = readToml(file);
+  return !!(parsed[section] && parsed[section][key] === String(value));
+}
+
+module.exports = { readToml, parseToml, loadProjectConfig, rewriteTomlValue, setTomlValue };