@visual-z/xeno 0.13.1 → 0.13.2

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # xeno changelog
 
+## 0.13.2 — 2026-11-05
+
+- Skills with descriptive `version` and `argument-hint` fields now load without startup warnings. Unsupported execution fields still report errors instead of being silently ignored.
+- Trusted global installs on Windows register the actual npm/Bun bin directory in the user PATH without replacing existing entries. Reopen your terminal application afterward. Bun update commands now include `--trust` so native installation is not skipped; failed native placement on Windows reports an installation error.
+
 ## 0.13.1 — 2026-11-02
 
 Models:

package/README.md

@@ -22,7 +22,19 @@ bun add -g --trust @visual-z/xeno
 ```
 
 Without `--trust`, `xeno` still starts on macOS and Linux through a small
-launcher script.
+launcher script. Windows requires `--trust` so the native executable is placed.
+
+On Windows, the global install step adds the actual global bin directory to
+your user PATH when needed. Close and reopen the terminal application after
+installing; already-running shells keep their old environment. Local project
+installs do not change PATH. If scripts were skipped, reinstall with
+`bun add -g --trust --force @visual-z/xeno`. To use the current PowerShell too:
+
+```powershell
+$xenoBin = (bun pm bin -g).Trim()
+$env:Path = "$xenoBin;$env:Path"
+xeno --version
+```
 
 ## Start
 

package/install.cjs

@@ -9,13 +9,13 @@
 //
 // If this never runs (`bun add -g` skips dependency scripts unless trusted),
 // the placeholder is itself a POSIX sh launcher that finds the same binary.
-// A failure here never fails the install: the placeholder still works.
+// The placeholder works only on POSIX. Windows must finish native placement.
 //
 // PLATFORMS must match scripts/binary-targets.ts; test/binary-release.test.ts
 // enforces that.
 
 const { spawnSync } = require("child_process");
-const { copyFileSync, existsSync, linkSync, renameSync, unlinkSync, chmodSync } = require("fs");
+const { copyFileSync, existsSync, linkSync, renameSync, unlinkSync, chmodSync, readFileSync, realpathSync } = require("fs");
 const { arch } = require("os");
 const path = require("path");
 
@@ -62,10 +62,119 @@ function place(source, dest) {
   if (process.platform !== "win32") chmodSync(dest, 0o755);
 }
 
+function windowsPathKey(value, env) {
+  const expanded = value.trim().replace(/^"(.*)"$/, "$1").replace(/%([^%]+)%/g, (token, name) => {
+    const key = Object.keys(env).find(key => key.toLowerCase() === name.toLowerCase());
+    return key === undefined ? token : env[key];
+  });
+  return path.win32.isAbsolute(expanded) ? path.win32.normalize(expanded).replace(/[\\/]+$/, "").toLowerCase() : "";
+}
+
+// Preserve the stored PATH bytes and order; normalization is for comparison only.
+function updatedWindowsPath(user, machine, bin, env, userKind = "ExpandString", machineKind = "ExpandString") {
+  if (!path.win32.isAbsolute(bin) || /[;"\r\n\0]/.test(bin)) throw Error("The global bin is not a valid absolute PATH entry");
+  const target = windowsPathKey(bin, env);
+  if ([[user, userKind], [machine, machineKind]].some(([value, kind]) => value.split(";").some(entry => windowsPathKey(entry, kind === "ExpandString" ? env : {}) === target))) return null;
+  return user + (user && !user.endsWith(";") ? ";" : "") + bin;
+}
+
+function installQuery(program, args) {
+  const result = spawnSync(program, args, { encoding: "utf8", windowsHide: true, timeout: 10000,
+    env: { ...process.env, NO_COLOR: "1", FORCE_COLOR: "0" } });
+  if (result.error || result.status !== 0) throw Error(`Could not query ${args.join(" ")} for the global PATH directory`);
+  return result.stdout.trim();
+}
+
+function windowsGlobalBin() {
+  const env = process.env;
+  const executable = env.npm_execpath;
+  const bun = executable && /^bun(?:\.exe)?$/i.test(path.win32.basename(executable));
+  const owns = root => windowsPathKey(__dirname, env) === windowsPathKey(path.win32.join(root, "node_modules", "@visual-z", "xeno"), env);
+  if (!bun && env.npm_config_global === "true") {
+    const prefix = env.npm_config_prefix;
+    if (!prefix || !path.win32.isAbsolute(prefix) || !owns(prefix)) return null;
+    return prefix; // npm's Windows shims live directly in the global prefix.
+  }
+  if (!bun) return null;
+  // Bun has no global-install flag in lifecycle env and no lockfile yet on a
+  // fresh install. Prove ownership from the already-linked global command.
+  const bin = installQuery(executable, ["pm", "bin", "-g"]);
+  if (!path.win32.isAbsolute(bin) || /[;"\r\n\0]/.test(bin)) throw Error("Invalid Bun global bin directory for PATH setup");
+  const shim = path.win32.join(bin, "xeno.bunx");
+  if (!existsSync(shim)) return null;
+  // Bun's BinLinkingShim format starts with a UTF-16 path followed by quote/NUL.
+  // bin.zig removes the first '..\\'; resolve from the global bin's parent.
+  // Sources: Bun v1.2.17 BinLinkingShim.zig and v1.4.3 BinLinkingShim.rs,
+  // both in src/install/windows-shim; their v5 path prefix is unchanged.
+  const bytes = readFileSync(shim);
+  const header = bytes.toString("utf16le"), end = header.indexOf('"\0');
+  if (bytes.length % 2 !== 0 || end <= 0) throw Error("Unrecognized Bun command shim; could not verify the global PATH target");
+  const target = path.win32.resolve(bin, "..", header.slice(0, end));
+  return windowsPathKey(realpathSync(target), env) === windowsPathKey(realpathSync(path.win32.join(__dirname, "bin", "xeno.exe")), env) ? bin : null;
+}
+
+const READ_WINDOWS_PATH = `
+$ErrorActionPreference = 'Stop'
+[Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)
+$userKey = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment')
+$machineKey = [Microsoft.Win32.Registry]::LocalMachine.OpenSubKey('SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment')
+try {
+  $user = if ($userKey) { $userKey.GetValue('Path', '', [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames) } else { '' }
+  $kind = if ($userKey -and $userKey.GetValueNames() -contains 'Path') { $userKey.GetValueKind('Path').ToString() } else { 'String' }
+  $machine = if ($machineKey) { $machineKey.GetValue('Path', '', [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames) } else { '' }
+  $machineKind = if ($machineKey -and $machineKey.GetValueNames() -contains 'Path') { $machineKey.GetValueKind('Path').ToString() } else { 'String' }
+  @{ user = [string]$user; kind = $kind; machine = [string]$machine; machineKind = $machineKind } | ConvertTo-Json -Compress
+} finally {
+  if ($userKey) { $userKey.Dispose() }
+  if ($machineKey) { $machineKey.Dispose() }
+}
+`;
+
+const WRITE_WINDOWS_PATH = `
+$ErrorActionPreference = 'Stop'
+$update = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String([Console]::In.ReadToEnd().Trim())) | ConvertFrom-Json
+$key = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey('Environment')
+try {
+  $before = [string]$key.GetValue('Path', '', [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames)
+  $kind = if ($key.GetValueNames() -contains 'Path') { $key.GetValueKind('Path').ToString() } else { 'String' }
+  if ($before -cne $update.before -or $kind -cne $update.kind) { throw 'User PATH changed during installation; retry the install.' }
+  $key.SetValue('Path', [string]$update.after, [Microsoft.Win32.RegistryValueKind]$kind)
+  if ([string]$key.GetValue('Path', '', [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames) -cne $update.after) { throw 'User PATH readback did not match.' }
+} finally { $key.Dispose() }
+# Notify Explorer so newly launched terminal hosts inherit the changed environment.
+# Existing terminals must restart even if notification cannot be delivered.
+try {
+  Add-Type -TypeDefinition 'using System; using System.Runtime.InteropServices; public static class XenoEnvironment { [DllImport("user32.dll", CharSet = CharSet.Unicode)] public static extern IntPtr SendMessageTimeout(IntPtr window, uint message, UIntPtr wparam, string lparam, uint flags, uint timeout, out UIntPtr result); }'
+  $result = [UIntPtr]::Zero
+  [void][XenoEnvironment]::SendMessageTimeout([IntPtr]65535, 26, [UIntPtr]::Zero, 'Environment', 2, 2000, [ref]$result)
+} catch { Write-Warning 'PATH saved. Sign out and back in if restarting your terminal does not pick it up.' }
+`;
+
+function configureWindowsPath() {
+  const bin = windowsGlobalBin();
+  if (bin === null) return;
+  const powershell = path.win32.join(process.env.SystemRoot || "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+  const run = (script, input) => {
+    const result = spawnSync(powershell, ["-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")],
+      { encoding: "utf8", windowsHide: true, timeout: 15000, ...(input === undefined ? {} : { input }) });
+    if (result.error || result.status !== 0) throw Error("Could not read or update the Windows user PATH; check your environment settings and retry");
+    return result.stdout;
+  };
+  const state = JSON.parse(run(READ_WINDOWS_PATH));
+  if (typeof state.user !== "string" || typeof state.machine !== "string" || ![state.kind, state.machineKind].every(kind => ["String", "ExpandString"].includes(kind))) throw Error("Unexpected Windows PATH registry value");
+  const after = updatedWindowsPath(state.user, state.machine, bin, process.env, state.kind, state.machineKind);
+  if (after === null) return;
+  // Data travels through stdin, never PowerShell source or the command line:
+  // Unicode, quotes and long PATHs cannot become code or exceed argv limits.
+  run(WRITE_WINDOWS_PATH, Buffer.from(JSON.stringify({ before: state.user, after, kind: state.kind }), "utf8").toString("base64"));
+  console.log(`[xeno postinstall] Added ${bin} to your user PATH. Close and reopen your terminal application to run xeno.`);
+}
+
 function main() {
   const key = platformKey(), info = PLATFORMS[key];
   if (!info) {
     console.error(`[xeno postinstall] Unsupported platform: ${key}. Supported: ${Object.keys(PLATFORMS).join(", ")}`);
+    if (process.platform === "win32") process.exitCode = 1;
     return;
   }
   let dir;
@@ -73,6 +182,7 @@ function main() {
   catch {
     console.error(`[xeno postinstall] ${info.pkg} is not installed (--omit=optional, or its download failed).`);
     console.error("  Reinstall @visual-z/xeno to fetch it.");
+    if (process.platform === "win32") process.exitCode = 1;
     return;
   }
   try {
@@ -80,9 +190,17 @@ function main() {
     if (existsSync(path.join(dir, WASM))) place(path.join(dir, WASM), path.join(__dirname, "bin", WASM));
   } catch (error) {
     console.error(`[xeno postinstall] Could not place the binary: ${error.message}`);
-    console.error("  xeno still starts through its launcher, one process slower.");
+    if (process.platform === "win32") {
+      console.error("  Reinstall with npm i -g @visual-z/xeno or bun add -g --trust @visual-z/xeno. Windows requires the native binary.");
+      process.exitCode = 1;
+    } else console.error("  xeno still starts through its launcher, one process slower.");
+    return;
+  }
+  if (process.platform === "win32") {
+    try { configureWindowsPath(); }
+    catch (error) { console.error(`[xeno postinstall] PATH setup failed: ${error.message}`); }
   }
 }
 
 if (require.main === module) main();
-module.exports = { PLATFORMS, platformKey };
+module.exports = { PLATFORMS, platformKey, updatedWindowsPath };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visual-z/xeno",
-  "version": "0.13.1",
+  "version": "0.13.2",
   "license": "UNLICENSED",
   "description": "Segmented append-only agent log with pure context and handoff projections",
   "bin": {
@@ -10,14 +10,14 @@
     "postinstall": "node install.cjs"
   },
   "optionalDependencies": {
-    "@visual-z/xeno-darwin-arm64": "0.13.1",
-    "@visual-z/xeno-darwin-x64": "0.13.1",
-    "@visual-z/xeno-linux-arm64": "0.13.1",
-    "@visual-z/xeno-linux-x64": "0.13.1",
-    "@visual-z/xeno-linux-arm64-musl": "0.13.1",
-    "@visual-z/xeno-linux-x64-musl": "0.13.1",
-    "@visual-z/xeno-win32-arm64": "0.13.1",
-    "@visual-z/xeno-win32-x64": "0.13.1"
+    "@visual-z/xeno-darwin-arm64": "0.13.2",
+    "@visual-z/xeno-darwin-x64": "0.13.2",
+    "@visual-z/xeno-linux-arm64": "0.13.2",
+    "@visual-z/xeno-linux-x64": "0.13.2",
+    "@visual-z/xeno-linux-arm64-musl": "0.13.2",
+    "@visual-z/xeno-linux-x64-musl": "0.13.2",
+    "@visual-z/xeno-win32-arm64": "0.13.2",
+    "@visual-z/xeno-win32-x64": "0.13.2"
   },
   "files": [
     "bin/xeno.exe",