@liustack/pptwise 0.22.0

package/skills/pptwise/scripts/run.ps1

@@ -0,0 +1,192 @@
+# pptwise skill launcher (Windows, PowerShell 5.1 compatible).
+#
+# The Windows twin of run.sh: identical resolution order, identical diagnostic
+# fields, identical exit codes. One stable action for the agent ("run
+# pptwise"); this script picks a working way to run it here.
+#
+# Invoke it per-process so no global policy is touched:
+#   powershell -ExecutionPolicy Bypass -File run.ps1 validate deck.json
+#
+# Resolution order (kept identical in run.sh):
+#   1. A compatible pptwise already on PATH -> run it directly.
+#   2. npx present, on a node meeting the floor -> run the pinned npm version.
+#   3. bunx present -> run the pinned version via Bun.
+#   4. Nothing usable -> structured diagnosis, exit 78.
+#
+# It never writes PATH, never needs admin rights, never fetches a second script,
+# and has no postinstall step.
+
+$ErrorActionPreference = 'Stop'
+
+# --- Version constants: stamped by scripts/stamp.mts at release time. ---------
+# Do not edit $Pinned by hand; scripts/stamp.test.mts asserts it equals the
+# package.json version, and `pnpm release:version` rewrites it on every bump.
+$Package = '@liustack/pptwise'
+$Bin = 'pptwise'
+$Pinned = '0.22.0'
+# ------------------------------------------------------------------------------
+
+# Environment snapshot, filled by Collect and read by the emitter.
+$script:Arch = ''
+$script:CliPresent = $false
+$script:CliPath = $null
+$script:CliVer = $null
+$script:CliCompat = $false
+$script:NpxPresent = $false
+$script:NpxPath = $null
+$script:BunxPresent = $false
+$script:BunxPath = $null
+$script:NodePresent = $false
+$script:NodeVer = $null
+$script:NodeFloorOk = $false
+$script:Selected = 'none'
+
+# First "X.Y.Z" token printed by `$Bin --version`.
+function Get-CliVersion {
+    try { $out = & $Bin --version 2>$null } catch { return '' }
+    if (-not $out) { return '' }
+    $line = [string]($out | Select-Object -First 1)
+    $m = [regex]::Match($line, '[0-9]+\.[0-9]+\.[0-9]+')
+    if ($m.Success) { return $m.Value } else { return '' }
+}
+
+# Compatible = same major version as $Pinned AND not older than $Pinned.
+# Same major keeps a globally installed CLI usable without a forced re-download;
+# not-older refuses a stale build that predates the version this skill needs.
+function Test-Compatible {
+    param([string] $Ver)
+    $f = $Ver -split '\.'
+    $p = $Pinned -split '\.'
+    if ($f.Count -lt 3 -or $p.Count -lt 3) { return $false }
+    $fMaj = [int]$f[0]; $fMin = [int]$f[1]; $fPat = [int]$f[2]
+    $pMaj = [int]$p[0]; $pMin = [int]$p[1]; $pPat = [int]$p[2]
+    if ($fMaj -ne $pMaj) { return $false }
+    if ($fMin -gt $pMin) { return $true }
+    if ($fMin -lt $pMin) { return $false }
+    return ($fPat -ge $pPat)
+}
+
+# The npx path runs the CLI on this machine's node, so npx is only usable when
+# node itself meets the package's floor (package.json engines).
+$NodeFloor = '22.19.0'
+function Test-NodeMeetsFloor {
+    if (-not (Get-Command node -ErrorAction SilentlyContinue)) { return $false }
+    try { $nv = ((& node --version 2>$null) -replace '^v', '') } catch { return $false }
+    if (-not $nv) { return $false }
+    $n = $nv -split '\.'
+    $f = $NodeFloor -split '\.'
+    if ($n.Count -lt 2) { return $false }
+    $nMaj = [int]$n[0]; $nMin = [int]$n[1]
+    $fMaj = [int]$f[0]; $fMin = [int]$f[1]
+    if ($nMaj -gt $fMaj) { return $true }
+    if ($nMaj -lt $fMaj) { return $false }
+    return ($nMin -ge $fMin)
+}
+
+# Return exactly one word: the chosen launch path.
+function Resolve-LaunchKind {
+    $cli = Get-Command $Bin -ErrorAction SilentlyContinue
+    if ($cli) {
+        $v = Get-CliVersion
+        if ($v -and (Test-Compatible $v)) { return 'path' }
+    }
+    if ((Get-Command npx -ErrorAction SilentlyContinue) -and (Test-NodeMeetsFloor)) { return 'npx' }
+    if (Get-Command bunx -ErrorAction SilentlyContinue) { return 'bunx' }
+    return 'none'
+}
+
+function Get-Arch {
+    switch ($env:PROCESSOR_ARCHITECTURE) {
+        'AMD64' { return 'x64' }
+        'ARM64' { return 'arm64' }
+        'x86' { return 'x86' }
+        default { return $env:PROCESSOR_ARCHITECTURE }
+    }
+}
+
+# Probe the environment once into the $script:* snapshot.
+function Collect {
+    $script:Arch = Get-Arch
+
+    $cli = Get-Command $Bin -ErrorAction SilentlyContinue
+    if ($cli) {
+        $script:CliPresent = $true
+        $script:CliPath = $cli.Source
+        $script:CliVer = Get-CliVersion
+        $script:CliCompat = [bool]($script:CliVer -and (Test-Compatible $script:CliVer))
+    }
+
+    $npx = Get-Command npx -ErrorAction SilentlyContinue
+    if ($npx) { $script:NpxPresent = $true; $script:NpxPath = $npx.Source }
+
+    $bunx = Get-Command bunx -ErrorAction SilentlyContinue
+    if ($bunx) { $script:BunxPresent = $true; $script:BunxPath = $bunx.Source }
+
+    $node = Get-Command node -ErrorAction SilentlyContinue
+    if ($node) {
+        $script:NodePresent = $true
+        try { $script:NodeVer = ((& node --version 2>$null) -replace '^v', '') } catch { $script:NodeVer = $null }
+        $script:NodeFloorOk = Test-NodeMeetsFloor
+    }
+
+    $script:Selected = Resolve-LaunchKind
+}
+
+# Assemble the structured diagnosis.
+function Build-DiagnosisJson {
+    $checked = [ordered]@{
+        pathCli = [ordered]@{ present = $script:CliPresent; path = $script:CliPath; version = $script:CliVer; compatible = $script:CliCompat }
+        npx     = [ordered]@{ present = $script:NpxPresent; path = $script:NpxPath; nodeMeetsFloor = $script:NodeFloorOk }
+        bunx    = [ordered]@{ present = $script:BunxPresent; path = $script:BunxPath }
+        node    = [ordered]@{ present = $script:NodePresent; version = $script:NodeVer }
+    }
+    $steps = @()
+    if ($script:Selected -eq 'none') {
+        $major = $Pinned.Split('.')[0]
+        $first = "Install Node 22.19+ from https://nodejs.org so npx can run $Package@$Pinned, then re-run this launcher."
+        if ($script:NpxPresent -and (-not $script:NodeFloorOk)) {
+            $first = "npx is present but node $(if ($script:NodeVer) { $script:NodeVer } else { 'missing' }) is below the $NodeFloor floor this CLI needs. Upgrade Node at https://nodejs.org, then re-run this launcher."
+        }
+        $steps = @(
+            $first,
+            "No JavaScript runtime? Install Bun from https://bun.sh to use bunx, or put a compatible $Bin (major $major, at or above $Pinned) on PATH."
+        )
+    }
+    $obj = [ordered]@{
+        tool          = $Bin
+        package       = $Package
+        pinnedVersion = $Pinned
+        os            = 'windows'
+        arch          = $script:Arch
+        checked       = $checked
+        selected      = $script:Selected
+        nextSteps     = @($steps)
+    }
+    return ($obj | ConvertTo-Json -Depth 20)
+}
+
+# Default action: forward every argument to the resolved CLI and exit with its
+# code. No usable runtime -> structured diagnosis on stderr, exit 78 (EX_CONFIG)
+# so the agent never mistakes the diagnosis for a result.
+function Invoke-Run {
+    param([string[]] $CliArgs)
+    $sel = Resolve-LaunchKind
+    switch ($sel) {
+        'path' { & $Bin @CliArgs; exit $LASTEXITCODE }
+        'npx' { & npx --yes --package "$Package@$Pinned" $Bin @CliArgs; exit $LASTEXITCODE }
+        'bunx' { & bunx --bun "$Package@$Pinned" @CliArgs; exit $LASTEXITCODE }
+        'none' {
+            Collect
+            [Console]::Error.WriteLine((Build-DiagnosisJson))
+            exit 78
+        }
+    }
+}
+
+$Command = ''
+if ($args.Count -ge 1) { $Command = [string]$args[0] }
+
+switch ($Command) {
+    'where' { Collect; Write-Output $script:Selected }
+    default { Invoke-Run -CliArgs $args }
+}

package/skills/pptwise/scripts/run.sh

@@ -0,0 +1,229 @@
+#!/bin/sh
+# pptwise skill launcher (macOS / Linux).
+#
+# One stable action for the agent ("run pptwise"); this script picks a working
+# way to run it in the current environment. Written to POSIX sh so it runs under
+# dash, busybox ash, and bash alike. Invoke it with `bash run.sh ...` (or plain
+# `sh run.sh ...`) so a lost execute bit after a file copy never matters.
+#
+# Resolution order (kept identical in run.ps1):
+#   1. A compatible pptwise already on PATH -> run it directly.
+#   2. npx present, on a node meeting the floor -> run the pinned npm version.
+#   3. bunx present -> run the pinned version via Bun.
+#   4. Nothing usable -> structured diagnosis, exit 78.
+#
+# It never writes PATH, never needs admin rights, never fetches a second script,
+# and has no postinstall step.
+set -eu
+
+# --- Version constants: stamped by scripts/stamp.mts at release time. ---------
+# Do not edit PINNED by hand; scripts/stamp.test.mts asserts it equals the
+# package.json version, and `pnpm release:version` rewrites it on every bump.
+PKG="@liustack/pptwise"
+BIN="pptwise"
+PINNED="0.22.0"
+# ------------------------------------------------------------------------------
+
+# Split "X.Y.Z" (extra suffix ignored) into the globals _MAJ, _MIN, _PAT.
+# Any non-numeric component becomes 0 so integer tests below never abort.
+parse_semver() {
+  _raw="$1"
+  _MAJ="${_raw%%.*}"
+  _rest="${_raw#*.}"
+  if [ "$_rest" = "$_raw" ]; then
+    _MIN=0
+    _PAT=0
+  else
+    _MIN="${_rest%%.*}"
+    _rest2="${_rest#*.}"
+    if [ "$_rest2" = "$_rest" ]; then _PAT=0; else _PAT="${_rest2%%.*}"; fi
+  fi
+  case "$_MAJ" in '' | *[!0-9]*) _MAJ=0 ;; esac
+  case "$_MIN" in '' | *[!0-9]*) _MIN=0 ;; esac
+  case "$_PAT" in '' | *[!0-9]*) _PAT=0 ;; esac
+}
+
+# Compatible = same major version as PINNED AND not older than PINNED.
+# Same major keeps a globally installed CLI usable without a forced re-download;
+# not-older refuses a stale build that predates the version this skill needs.
+compatible() {
+  parse_semver "$1"
+  _f_maj=$_MAJ
+  _f_min=$_MIN
+  _f_pat=$_PAT
+  parse_semver "$PINNED"
+  [ "$_f_maj" = "$_MAJ" ] || return 1
+  if [ "$_f_min" -gt "$_MIN" ]; then return 0; fi
+  if [ "$_f_min" -lt "$_MIN" ]; then return 1; fi
+  [ "$_f_pat" -ge "$_PAT" ]
+}
+
+# First "X.Y.Z" token printed by `$BIN --version`.
+cli_version() {
+  "$BIN" --version 2>/dev/null | head -n 1 |
+    sed -n 's/.*\([0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*\).*/\1/p'
+}
+
+# The npx path runs the CLI on this machine's node, so npx is only usable when
+# node itself meets the package's floor (package.json engines). An old node
+# with a working npx would otherwise be selected into a path known to fail.
+NODE_FLOOR="22.19.0"
+node_meets_floor() {
+  command -v node >/dev/null 2>&1 || return 1
+  _nv="$(node --version 2>/dev/null | sed 's/^v//')"
+  [ -n "$_nv" ] || return 1
+  parse_semver "$NODE_FLOOR"
+  _floor_maj="$_MAJ"
+  _floor_min="$_MIN"
+  parse_semver "$_nv"
+  if [ "$_MAJ" -gt "$_floor_maj" ]; then return 0; fi
+  if [ "$_MAJ" -lt "$_floor_maj" ]; then return 1; fi
+  [ "$_MIN" -ge "$_floor_min" ]
+}
+
+# Echo exactly one word: the chosen launch path.
+resolve() {
+  if command -v "$BIN" >/dev/null 2>&1; then
+    _v="$(cli_version)"
+    if [ -n "$_v" ] && compatible "$_v"; then
+      echo "path"
+      return
+    fi
+  fi
+  if command -v npx >/dev/null 2>&1 && node_meets_floor; then
+    echo "npx"
+    return
+  fi
+  if command -v bunx >/dev/null 2>&1; then
+    echo "bunx"
+    return
+  fi
+  echo "none"
+}
+
+detect_os() { uname -s 2>/dev/null | tr '[:upper:]' '[:lower:]'; }
+
+detect_arch() {
+  _a="$(uname -m 2>/dev/null)"
+  case "$_a" in
+    x86_64 | amd64) echo "x64" ;;
+    aarch64 | arm64) echo "arm64" ;;
+    *) echo "$_a" ;;
+  esac
+}
+
+# Escape a value for a JSON string literal (backslash and double quote).
+json_escape() { printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'; }
+
+# Render "null" for an empty value, else an escaped JSON string.
+jstr() {
+  if [ -z "$1" ]; then printf 'null'; else printf '"%s"' "$(json_escape "$1")"; fi
+}
+
+# 1 -> true, anything else -> false.
+jbool() { if [ "$1" = "1" ]; then printf 'true'; else printf 'false'; fi; }
+
+# Probe the environment once into G_* globals shared by the emitters.
+collect() {
+  G_OS="$(detect_os)"
+  G_ARCH="$(detect_arch)"
+
+  G_CLI_PRESENT=0
+  G_CLI_PATH=""
+  G_CLI_VER=""
+  G_CLI_COMPAT=0
+  if command -v "$BIN" >/dev/null 2>&1; then
+    G_CLI_PRESENT=1
+    G_CLI_PATH="$(command -v "$BIN")"
+    G_CLI_VER="$(cli_version)"
+    if [ -n "$G_CLI_VER" ] && compatible "$G_CLI_VER"; then G_CLI_COMPAT=1; fi
+  fi
+
+  G_NPX_PRESENT=0
+  G_NPX_PATH=""
+  if command -v npx >/dev/null 2>&1; then
+    G_NPX_PRESENT=1
+    G_NPX_PATH="$(command -v npx)"
+  fi
+
+  G_BUNX_PRESENT=0
+  G_BUNX_PATH=""
+  if command -v bunx >/dev/null 2>&1; then
+    G_BUNX_PRESENT=1
+    G_BUNX_PATH="$(command -v bunx)"
+  fi
+
+  G_NODE_PRESENT=0
+  G_NODE_VER=""
+  if command -v node >/dev/null 2>&1; then
+    G_NODE_PRESENT=1
+    G_NODE_VER="$(node --version 2>/dev/null | sed 's/^v//')"
+  fi
+
+  G_NODE_FLOOR_OK=0
+  if node_meets_floor; then G_NODE_FLOOR_OK=1; fi
+
+  G_SEL="$(resolve)"
+}
+
+# Build the nextSteps JSON array body (without the brackets) into G_NEXTSTEPS.
+compute_next_steps() {
+  if [ "$G_SEL" = "none" ]; then
+    if [ "$G_NPX_PRESENT" = 1 ] && [ "$G_NODE_FLOOR_OK" = 0 ]; then
+      _s1="npx is present but node ${G_NODE_VER:-missing} is below the $NODE_FLOOR floor this CLI needs. Upgrade Node at https://nodejs.org, then re-run this launcher."
+    else
+      _s1="Install Node 22.19+ from https://nodejs.org so npx can run $PKG@$PINNED, then re-run this launcher."
+    fi
+    _s2="No JavaScript runtime? Install Bun from https://bun.sh to use bunx, or put a compatible $BIN (major ${PINNED%%.*}, at or above $PINNED) on PATH."
+    G_NEXTSTEPS="$(printf '"%s", "%s"' "$(json_escape "$_s1")" "$(json_escape "$_s2")")"
+  else
+    G_NEXTSTEPS=""
+  fi
+}
+
+# Emit the structured diagnosis.
+emit_json() {
+  compute_next_steps
+  printf '{\n'
+  printf '  "tool": %s,\n' "$(jstr "$BIN")"
+  printf '  "package": %s,\n' "$(jstr "$PKG")"
+  printf '  "pinnedVersion": %s,\n' "$(jstr "$PINNED")"
+  printf '  "os": %s,\n' "$(jstr "$G_OS")"
+  printf '  "arch": %s,\n' "$(jstr "$G_ARCH")"
+  printf '  "checked": {\n'
+  printf '    "pathCli": { "present": %s, "path": %s, "version": %s, "compatible": %s },\n' \
+    "$(jbool "$G_CLI_PRESENT")" "$(jstr "$G_CLI_PATH")" "$(jstr "$G_CLI_VER")" "$(jbool "$G_CLI_COMPAT")"
+  printf '    "npx": { "present": %s, "path": %s, "nodeMeetsFloor": %s },\n' "$(jbool "$G_NPX_PRESENT")" "$(jstr "$G_NPX_PATH")" "$(jbool "$G_NODE_FLOOR_OK")"
+  printf '    "bunx": { "present": %s, "path": %s },\n' "$(jbool "$G_BUNX_PRESENT")" "$(jstr "$G_BUNX_PATH")"
+  printf '    "node": { "present": %s, "version": %s }\n' "$(jbool "$G_NODE_PRESENT")" "$(jstr "$G_NODE_VER")"
+  printf '  },\n'
+  printf '  "selected": %s,\n' "$(jstr "$G_SEL")"
+  printf '  "nextSteps": [%s]\n' "$G_NEXTSTEPS"
+  printf '}\n'
+}
+
+# Default action: forward every argument to the resolved CLI, inheriting stdio
+# and exit code. No usable runtime -> structured diagnosis on stderr, exit 78
+# (EX_CONFIG) so the agent never mistakes the diagnosis for a result.
+run() {
+  _sel="$(resolve)"
+  case "$_sel" in
+    path) exec "$BIN" "$@" ;;
+    npx) exec npx --yes --package "$PKG@$PINNED" "$BIN" "$@" ;;
+    bunx) exec bunx --bun "$PKG@$PINNED" "$@" ;;
+    none)
+      collect
+      emit_json >&2
+      exit 78
+      ;;
+  esac
+}
+
+case "${1:-}" in
+  where)
+    resolve
+    ;;
+  *)
+    run "$@"
+    ;;
+esac