psadt-deploy-skill 0.23.1 → 0.25.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Patrick Taubert, PHAT Consulting GmbH
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Patrick Taubert, PHAT Consulting GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -369,6 +369,45 @@ pre-flight fails on non-ASCII without a BOM), and anything that lands in a packa
 Recent releases below; the complete history is in **[CHANGELOG.md](CHANGELOG.md)** (nothing is ever removed
 from either).
 
+### 0.25.0 - 05.09.2026
+- **New: `Get-PsadtMsiFacts.ps1` reads an MSI in one pass** — identity, signature, SHA256, features with
+  component counts, *decoded* upgrade flags, shortcuts, directories, file versions, registry rows and the
+  Icon table. For an MSI this probe **is** the research: it is what reveals an auto-updater sitting in its
+  own feature (so `ADDLOCAL` replaces post-install cleanup), a `DesktopFeature` you must not install, and
+  `MigrateFeatures` on the upgrade row — the flag that means `ADDLOCAL` alone is not enough. Five
+  regression guards, each verified to fail on its reintroduced bug.
+- **Fixed: the sandbox test left litter and put the evidence in the wrong place.** It kept one work folder
+  per app under the config home forever, and `result.json` plus the PSADT logs lived there with the
+  manifest pointing into a profile directory. Evidence now lands in
+  `<outputRoot>\<Stem>\SandboxTest\` beside the dossier — not in the package folder, which is what
+  IntuneWinAppUtil packs — the logs are recorded in `artifacts.logs[]`, and the scratch is removed.
+  `-KeepWorkFolder` keeps it, and a failed run keeps it automatically.
+- **Fixed: the test suite wrote into the real config home.** It now redirects `PSADT_DEPLOY_HOME` to a temp
+  directory, with a test that asserts it.
+- **Measured:** PuTTY 0.85 packaged with these lessons applied took **13 min 45 s end to end** — versus 75
+  minutes for the Notepad++ run that produced them. The largest single factor: the sandbox test costs zero
+  wall-clock time when started as soon as pre-flight goes GREEN, because packaging and the dossier do not
+  depend on its verdict.
+
+### 0.24.0 - 05.09.2026
+- **New: `Invoke-PsadtSandboxTest.ps1` runs the whole Phase 6 loop in a throwaway Windows Sandbox** —
+  Install, detection, Uninstall, detection, Reinstall, Repair, final Uninstall, every action as
+  `NT AUTHORITY\SYSTEM` via a scheduled task. **No elevation on the host, and the host is never touched**,
+  so the SYSTEM test stops being the step that gets deferred to "a DEV VM later". Every action starts from
+  a machine that has never seen the app, so a pass cannot be an artefact of the previous run. The verdict
+  is keyed on the detection script; package-specific facts go in via `-PathsPresentAfterInstall` /
+  `-PathsAbsentAfterInstall` / `-PathsAbsentAfterUninstall`. Verified end to end on Notepad++ 8.9.8 x64:
+  GREEN, all seven steps, 5 min 58 s.
+- **Why it is a script and not a snippet:** a hand-rolled version hit three bugs that each destroyed a full
+  VM run and each present as a timeout or a null-reference minutes after launch — `echo %ERRORLEVEL%>file`
+  silently becoming the `0>` stdin redirection (empty file, never a number), file existence read as
+  completion, and `[string]$null` still being `$null` in Windows PowerShell 5.1 (an empty detection output
+  is the *normal* result, so the harness crashed because the package was clean). All three now have
+  regression guards that were each verified to fail on the reintroduced bug.
+- Phase 6 in SKILL.md and the guide now lead with the sandbox route; the per-action route stays for apps a
+  VM cannot host. New anti-patterns cover hand-rolled harnesses, debugging through a long job instead of a
+  two-second local check, and "speeding up" the test by disabling Defender or dropping Uninstall/Repair.
+
 ### 0.23.1 - 04.09.2026
 - **Fixed: two generators were broken since 0.21.0.** `New-BrowserExtensionPackage.ps1` and
   `New-WindowsFeaturePackage.ps1` died at run time — the per-run `LogName` change had wedged a statement

package/bin/install.mjs

@@ -1,214 +1,214 @@
-#!/usr/bin/env node
-/**
- * psadt-deploy-skill - installer for the psadt-deploy Claude Code skill.
- *
- *   npx psadt-deploy-skill                 install/update in ~/.claude/skills/psadt-deploy
- *   npx psadt-deploy-skill --project       install into ./.claude/skills/psadt-deploy instead
- *   npx psadt-deploy-skill --dir <path>    install into an explicit folder
- *   npx psadt-deploy-skill --ref <ref>     a branch or tag instead of main
- *   npx psadt-deploy-skill --no-setup      skip the setup doctor
- *
- * Design notes that matter:
- *
- * - Zero dependencies. Node 18 has global fetch, Windows ships bsdtar as tar.exe, and an installer that
- *   pulls in a dependency tree is an installer that can break for reasons unrelated to the skill.
- * - The package ships ONLY bin/. The skill itself comes from GitHub at install time, so a new skill
- *   version needs no npm republish - only a change to this file does.
- * - This script never writes the skill config. Resolving the config home is Get-PsadtConfig's job
- *   (explicit -SkillRoot > $env:PSADT_DEPLOY_HOME > %LOCALAPPDATA%\psadt-deploy), and a second
- *   implementation in JavaScript would drift from it. So it spawns Set-PsadtConfig.ps1 and
- *   Initialize-PsadtSkill.ps1 and lets them decide.
- */
-
-import { spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, rmSync, writeFileSync, readFileSync } from 'node:fs';
-import { homedir, tmpdir } from 'node:os';
-import { join, resolve } from 'node:path';
-
-const REPO = 'pt1987/claude-code-psadt-skill';
-const SKILL_FOLDER = 'psadt-deploy';
-
-// --- arguments ---------------------------------------------------------------------------------
-const argv = process.argv.slice(2);
-function flagValue(name) {
-  const i = argv.indexOf(name);
-  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : null;
-}
-const wantHelp = argv.includes('--help') || argv.includes('-h');
-const ref = flagValue('--ref') || 'main';
-const noSetup = argv.includes('--no-setup');
-const explicitDir = flagValue('--dir');
-const projectScope = argv.includes('--project');
-
-if (wantHelp) {
-  console.log(`psadt-deploy-skill - install the psadt-deploy Claude Code skill
-
-  npx psadt-deploy-skill [--dir <path>] [--project] [--ref <branch|tag>] [--no-setup]
-
-  --dir <path>   install into this folder
-  --project      install into ./.claude/skills/${SKILL_FOLDER} (default is the user's ~/.claude/skills)
-  --ref <ref>    branch or tag to install (default: main)
-  --no-setup     do not run the setup doctor afterwards
-`);
-  process.exit(0);
-}
-
-const target = explicitDir
-  ? resolve(explicitDir)
-  : projectScope
-    ? resolve(join(process.cwd(), '.claude', 'skills', SKILL_FOLDER))
-    : resolve(join(homedir(), '.claude', 'skills', SKILL_FOLDER));
-
-// --- small helpers -----------------------------------------------------------------------------
-function run(exe, args, opts = {}) {
-  return spawnSync(exe, args, { stdio: 'inherit', shell: false, ...opts });
-}
-function runCapture(exe, args) {
-  return spawnSync(exe, args, { encoding: 'utf8', shell: false });
-}
-function has(exe) {
-  const r = runCapture(exe, ['--version']);
-  return !r.error && r.status === 0;
-}
-function fail(msg) {
-  console.error(`\n  ERROR  ${msg}\n`);
-  process.exit(1);
-}
-
-if (process.platform !== 'win32') {
-  fail('This skill builds Windows Intune packages and needs Windows (PowerShell, IntuneWinAppUtil, PSADT).');
-}
-
-console.log(`\npsadt-deploy-skill\n  target : ${target}\n  ref    : ${ref}`);
-
-// --- 1. get the skill --------------------------------------------------------------------------
-// Order of preference: update an existing clone, else clone, else tarball. The tarball route exists
-// because plenty of managed machines have no git at all.
-const gitAvailable = has('git');
-mkdirSync(target, { recursive: true });
-
-if (existsSync(join(target, '.git'))) {
-  if (!gitAvailable) fail(`${target} is a git clone but git is not available to update it.`);
-  console.log('\n  updating the existing clone (git pull --ff-only)');
-  const r = run('git', ['-C', target, 'pull', '--ff-only', 'origin', ref]);
-  if (r.status !== 0) {
-    fail('git pull --ff-only failed. Local changes in the skill folder? Commit or discard them, or install into a fresh folder with --dir.');
-  }
-} else if (gitAvailable) {
-  console.log('\n  cloning (git clone --depth 1)');
-  // Clone into a temp folder and move the contents, because git refuses a non-empty target.
-  const stage = join(tmpdir(), `psadt-skill-${Date.now()}`);
-  const r = run('git', ['clone', '--depth', '1', '--branch', ref, `https://github.com/${REPO}.git`, stage]);
-  if (r.status !== 0) {
-    fail(
-      `git clone failed. If ${REPO} is private you need access to it: sign in with the GitHub CLI (gh auth login), ` +
-        'configure a credential helper, or clone it manually and point this installer at the folder with --dir.'
-    );
-  }
-  // robocopy is on every Windows box and handles the merge without a shell. 0-7 are success codes.
-  const c = runCapture('robocopy', [stage, target, '/E', '/NFL', '/NDL', '/NJH', '/NJS', '/NP']);
-  rmSync(stage, { recursive: true, force: true });
-  if ((c.status ?? 8) > 7) fail('Copying the clone into the target folder failed.');
-} else {
-  console.log('\n  no git found - downloading the tarball');
-  const url = `https://codeload.github.com/${REPO}/tar.gz/refs/heads/${ref}`;
-  const tgz = join(tmpdir(), `psadt-skill-${Date.now()}.tar.gz`);
-  try {
-    const res = await fetch(url);
-    if (res.status === 404) {
-      // GitHub answers 404 - not 403 - for a private repository you cannot see. Without git there is no
-      // way to authenticate here, so say what is actually wrong instead of "download failed".
-      fail(
-        `${REPO} is not publicly readable (HTTP 404), and without git this installer cannot authenticate. ` +
-          'Either install git and sign in to GitHub, or clone the repository manually and re-run with ' +
-          '--dir <folder>.'
-      );
-    }
-    if (!res.ok) throw new Error(`HTTP ${res.status} for ${url}`);
-    writeFileSync(tgz, Buffer.from(await res.arrayBuffer()));
-  } catch (e) {
-    fail(`Download failed: ${e.message}`);
-  }
-  // The archive's top-level directory is <repo>-<ref>/, so strip exactly one component.
-  const r = run('tar', ['-xzf', tgz, '-C', target, '--strip-components=1']);
-  rmSync(tgz, { force: true });
-  if (r.status !== 0) fail('Extracting the tarball failed (tar.exe is expected in C:\\Windows\\System32).');
-}
-
-if (!existsSync(join(target, 'SKILL.md'))) {
-  fail(`${target} has no SKILL.md - the download did not produce a skill folder.`);
-}
-console.log('  OK  skill files in place');
-
-// --- 2. PowerShell ------------------------------------------------------------------------------
-// pwsh first; powershell.exe as the fallback. -ExecutionPolicy Bypass on BOTH: 5.1 defaults to
-// Restricted, and a GPO can pin pwsh to AllSigned - either way an unsigned script would not run.
-const psExe = has('pwsh') ? 'pwsh' : 'powershell';
-const psBase = ['-NoProfile', '-ExecutionPolicy', 'Bypass'];
-
-// --- 3. record the commit (via the script that owns the config, not from here) -------------------
-try {
-  const res = await fetch(`https://api.github.com/repos/${REPO}/commits/${ref}`, {
-    headers: { 'User-Agent': 'psadt-deploy-skill', Accept: 'application/vnd.github+json' },
-  });
-  if (res.ok) {
-    const sha = (await res.json()).sha;
-    if (sha) {
-      const setCfg = join(target, 'scripts', 'Set-PsadtConfig.ps1');
-      // -Command, not -File: -File passes every argument as a string and -Updates wants a hashtable.
-      run(psExe, [...psBase, '-Command', `& '${setCfg}' -Updates @{'tooling.skillCommit'='${sha}'}`]);
-      console.log(`  OK  recorded commit ${sha.slice(0, 7)}`);
-    }
-  } else if (res.status === 404) {
-    // 404 on a repo you just cloned = the repo is private and this call is unauthenticated. Worth saying
-    // once: the skill works, only the sha-based update check falls back to comparing versions.
-    console.log(`  --  ${REPO} is not publicly readable, so the commit sha was not recorded.`);
-    console.log('      The skill works; "update skill" compares CHANGELOG versions instead of shas.');
-  } else {
-    console.log(`  --  could not read the commit sha (HTTP ${res.status}) - not fatal`);
-  }
-} catch {
-  // A missing commit sha only means the next update check compares versions instead of shas.
-  console.log('  --  could not record the commit sha (offline?) - not fatal');
-}
-
-// --- 4. the setup doctor ------------------------------------------------------------------------
-if (noSetup) {
-  console.log('\n  skipped the setup doctor (--no-setup). Run it later:');
-  console.log(`    ${psExe} -File "${join(target, 'scripts', 'Initialize-PsadtSkill.ps1')}" -Fix\n`);
-  process.exit(0);
-}
-
-const doctor = join(target, 'scripts', 'Initialize-PsadtSkill.ps1');
-const jsonPath = join(tmpdir(), `psadt-doctor-${Date.now()}.json`);
-console.log('\n  running the setup doctor (-Fix)\n');
-// -JsonPath rather than -Json: stdout is inherited so the user sees the doctor's own table live, and the
-// machine-readable copy comes back through the file.
-// -Command with Out-Null rather than -File: the doctor also RETURNS its result object, and with inherited
-// stdout that object gets dumped underneath its own table. Out-Null drops the object; Write-Host output
-// (the table) is unaffected.
-const d = run(psExe, [...psBase, '-Command', `& '${doctor}' -Fix -JsonPath '${jsonPath}' | Out-Null`]);
-
-let verdict = null;
-try {
-  if (existsSync(jsonPath)) verdict = JSON.parse(readFileSync(jsonPath, 'utf8'));
-} catch {
-  /* the doctor printed its table anyway */
-}
-rmSync(jsonPath, { force: true });
-
-if (verdict) {
-  console.log(`\n  setup: ${verdict.Overall}`);
-  const missing = Array.isArray(verdict.Missing) ? verdict.Missing : [];
-  if (missing.length) {
-    console.log(`\n  ${missing.length} value(s) still need you: ${missing.join(', ')}`);
-    console.log("  Open Claude Code in a package folder and say: \"psadt setup\"");
-  } else if (verdict.Overall === 'GREEN') {
-    console.log('  Ready. Open Claude Code and say what you want packaged.');
-  }
-} else if (d.status !== 0) {
-  console.log('\n  The setup doctor did not complete. Run it manually:');
-  console.log(`    ${psExe} -File "${doctor}" -Fix`);
-}
-
-console.log('');
+#!/usr/bin/env node
+/**
+ * psadt-deploy-skill - installer for the psadt-deploy Claude Code skill.
+ *
+ *   npx psadt-deploy-skill                 install/update in ~/.claude/skills/psadt-deploy
+ *   npx psadt-deploy-skill --project       install into ./.claude/skills/psadt-deploy instead
+ *   npx psadt-deploy-skill --dir <path>    install into an explicit folder
+ *   npx psadt-deploy-skill --ref <ref>     a branch or tag instead of main
+ *   npx psadt-deploy-skill --no-setup      skip the setup doctor
+ *
+ * Design notes that matter:
+ *
+ * - Zero dependencies. Node 18 has global fetch, Windows ships bsdtar as tar.exe, and an installer that
+ *   pulls in a dependency tree is an installer that can break for reasons unrelated to the skill.
+ * - The package ships ONLY bin/. The skill itself comes from GitHub at install time, so a new skill
+ *   version needs no npm republish - only a change to this file does.
+ * - This script never writes the skill config. Resolving the config home is Get-PsadtConfig's job
+ *   (explicit -SkillRoot > $env:PSADT_DEPLOY_HOME > %LOCALAPPDATA%\psadt-deploy), and a second
+ *   implementation in JavaScript would drift from it. So it spawns Set-PsadtConfig.ps1 and
+ *   Initialize-PsadtSkill.ps1 and lets them decide.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, rmSync, writeFileSync, readFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+const REPO = 'pt1987/claude-code-psadt-skill';
+const SKILL_FOLDER = 'psadt-deploy';
+
+// --- arguments ---------------------------------------------------------------------------------
+const argv = process.argv.slice(2);
+function flagValue(name) {
+  const i = argv.indexOf(name);
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : null;
+}
+const wantHelp = argv.includes('--help') || argv.includes('-h');
+const ref = flagValue('--ref') || 'main';
+const noSetup = argv.includes('--no-setup');
+const explicitDir = flagValue('--dir');
+const projectScope = argv.includes('--project');
+
+if (wantHelp) {
+  console.log(`psadt-deploy-skill - install the psadt-deploy Claude Code skill
+
+  npx psadt-deploy-skill [--dir <path>] [--project] [--ref <branch|tag>] [--no-setup]
+
+  --dir <path>   install into this folder
+  --project      install into ./.claude/skills/${SKILL_FOLDER} (default is the user's ~/.claude/skills)
+  --ref <ref>    branch or tag to install (default: main)
+  --no-setup     do not run the setup doctor afterwards
+`);
+  process.exit(0);
+}
+
+const target = explicitDir
+  ? resolve(explicitDir)
+  : projectScope
+    ? resolve(join(process.cwd(), '.claude', 'skills', SKILL_FOLDER))
+    : resolve(join(homedir(), '.claude', 'skills', SKILL_FOLDER));
+
+// --- small helpers -----------------------------------------------------------------------------
+function run(exe, args, opts = {}) {
+  return spawnSync(exe, args, { stdio: 'inherit', shell: false, ...opts });
+}
+function runCapture(exe, args) {
+  return spawnSync(exe, args, { encoding: 'utf8', shell: false });
+}
+function has(exe) {
+  const r = runCapture(exe, ['--version']);
+  return !r.error && r.status === 0;
+}
+function fail(msg) {
+  console.error(`\n  ERROR  ${msg}\n`);
+  process.exit(1);
+}
+
+if (process.platform !== 'win32') {
+  fail('This skill builds Windows Intune packages and needs Windows (PowerShell, IntuneWinAppUtil, PSADT).');
+}
+
+console.log(`\npsadt-deploy-skill\n  target : ${target}\n  ref    : ${ref}`);
+
+// --- 1. get the skill --------------------------------------------------------------------------
+// Order of preference: update an existing clone, else clone, else tarball. The tarball route exists
+// because plenty of managed machines have no git at all.
+const gitAvailable = has('git');
+mkdirSync(target, { recursive: true });
+
+if (existsSync(join(target, '.git'))) {
+  if (!gitAvailable) fail(`${target} is a git clone but git is not available to update it.`);
+  console.log('\n  updating the existing clone (git pull --ff-only)');
+  const r = run('git', ['-C', target, 'pull', '--ff-only', 'origin', ref]);
+  if (r.status !== 0) {
+    fail('git pull --ff-only failed. Local changes in the skill folder? Commit or discard them, or install into a fresh folder with --dir.');
+  }
+} else if (gitAvailable) {
+  console.log('\n  cloning (git clone --depth 1)');
+  // Clone into a temp folder and move the contents, because git refuses a non-empty target.
+  const stage = join(tmpdir(), `psadt-skill-${Date.now()}`);
+  const r = run('git', ['clone', '--depth', '1', '--branch', ref, `https://github.com/${REPO}.git`, stage]);
+  if (r.status !== 0) {
+    fail(
+      `git clone failed. If ${REPO} is private you need access to it: sign in with the GitHub CLI (gh auth login), ` +
+        'configure a credential helper, or clone it manually and point this installer at the folder with --dir.'
+    );
+  }
+  // robocopy is on every Windows box and handles the merge without a shell. 0-7 are success codes.
+  const c = runCapture('robocopy', [stage, target, '/E', '/NFL', '/NDL', '/NJH', '/NJS', '/NP']);
+  rmSync(stage, { recursive: true, force: true });
+  if ((c.status ?? 8) > 7) fail('Copying the clone into the target folder failed.');
+} else {
+  console.log('\n  no git found - downloading the tarball');
+  const url = `https://codeload.github.com/${REPO}/tar.gz/refs/heads/${ref}`;
+  const tgz = join(tmpdir(), `psadt-skill-${Date.now()}.tar.gz`);
+  try {
+    const res = await fetch(url);
+    if (res.status === 404) {
+      // GitHub answers 404 - not 403 - for a private repository you cannot see. Without git there is no
+      // way to authenticate here, so say what is actually wrong instead of "download failed".
+      fail(
+        `${REPO} is not publicly readable (HTTP 404), and without git this installer cannot authenticate. ` +
+          'Either install git and sign in to GitHub, or clone the repository manually and re-run with ' +
+          '--dir <folder>.'
+      );
+    }
+    if (!res.ok) throw new Error(`HTTP ${res.status} for ${url}`);
+    writeFileSync(tgz, Buffer.from(await res.arrayBuffer()));
+  } catch (e) {
+    fail(`Download failed: ${e.message}`);
+  }
+  // The archive's top-level directory is <repo>-<ref>/, so strip exactly one component.
+  const r = run('tar', ['-xzf', tgz, '-C', target, '--strip-components=1']);
+  rmSync(tgz, { force: true });
+  if (r.status !== 0) fail('Extracting the tarball failed (tar.exe is expected in C:\\Windows\\System32).');
+}
+
+if (!existsSync(join(target, 'SKILL.md'))) {
+  fail(`${target} has no SKILL.md - the download did not produce a skill folder.`);
+}
+console.log('  OK  skill files in place');
+
+// --- 2. PowerShell ------------------------------------------------------------------------------
+// pwsh first; powershell.exe as the fallback. -ExecutionPolicy Bypass on BOTH: 5.1 defaults to
+// Restricted, and a GPO can pin pwsh to AllSigned - either way an unsigned script would not run.
+const psExe = has('pwsh') ? 'pwsh' : 'powershell';
+const psBase = ['-NoProfile', '-ExecutionPolicy', 'Bypass'];
+
+// --- 3. record the commit (via the script that owns the config, not from here) -------------------
+try {
+  const res = await fetch(`https://api.github.com/repos/${REPO}/commits/${ref}`, {
+    headers: { 'User-Agent': 'psadt-deploy-skill', Accept: 'application/vnd.github+json' },
+  });
+  if (res.ok) {
+    const sha = (await res.json()).sha;
+    if (sha) {
+      const setCfg = join(target, 'scripts', 'Set-PsadtConfig.ps1');
+      // -Command, not -File: -File passes every argument as a string and -Updates wants a hashtable.
+      run(psExe, [...psBase, '-Command', `& '${setCfg}' -Updates @{'tooling.skillCommit'='${sha}'}`]);
+      console.log(`  OK  recorded commit ${sha.slice(0, 7)}`);
+    }
+  } else if (res.status === 404) {
+    // 404 on a repo you just cloned = the repo is private and this call is unauthenticated. Worth saying
+    // once: the skill works, only the sha-based update check falls back to comparing versions.
+    console.log(`  --  ${REPO} is not publicly readable, so the commit sha was not recorded.`);
+    console.log('      The skill works; "update skill" compares CHANGELOG versions instead of shas.');
+  } else {
+    console.log(`  --  could not read the commit sha (HTTP ${res.status}) - not fatal`);
+  }
+} catch {
+  // A missing commit sha only means the next update check compares versions instead of shas.
+  console.log('  --  could not record the commit sha (offline?) - not fatal');
+}
+
+// --- 4. the setup doctor ------------------------------------------------------------------------
+if (noSetup) {
+  console.log('\n  skipped the setup doctor (--no-setup). Run it later:');
+  console.log(`    ${psExe} -File "${join(target, 'scripts', 'Initialize-PsadtSkill.ps1')}" -Fix\n`);
+  process.exit(0);
+}
+
+const doctor = join(target, 'scripts', 'Initialize-PsadtSkill.ps1');
+const jsonPath = join(tmpdir(), `psadt-doctor-${Date.now()}.json`);
+console.log('\n  running the setup doctor (-Fix)\n');
+// -JsonPath rather than -Json: stdout is inherited so the user sees the doctor's own table live, and the
+// machine-readable copy comes back through the file.
+// -Command with Out-Null rather than -File: the doctor also RETURNS its result object, and with inherited
+// stdout that object gets dumped underneath its own table. Out-Null drops the object; Write-Host output
+// (the table) is unaffected.
+const d = run(psExe, [...psBase, '-Command', `& '${doctor}' -Fix -JsonPath '${jsonPath}' | Out-Null`]);
+
+let verdict = null;
+try {
+  if (existsSync(jsonPath)) verdict = JSON.parse(readFileSync(jsonPath, 'utf8'));
+} catch {
+  /* the doctor printed its table anyway */
+}
+rmSync(jsonPath, { force: true });
+
+if (verdict) {
+  console.log(`\n  setup: ${verdict.Overall}`);
+  const missing = Array.isArray(verdict.Missing) ? verdict.Missing : [];
+  if (missing.length) {
+    console.log(`\n  ${missing.length} value(s) still need you: ${missing.join(', ')}`);
+    console.log("  Open Claude Code in a package folder and say: \"psadt setup\"");
+  } else if (verdict.Overall === 'GREEN') {
+    console.log('  Ready. Open Claude Code and say what you want packaged.');
+  }
+} else if (d.status !== 0) {
+  console.log('\n  The setup doctor did not complete. Run it manually:');
+  console.log(`    ${psExe} -File "${doctor}" -Fix`);
+}
+
+console.log('');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "psadt-deploy-skill",
-  "version": "0.23.1",
+  "version": "0.25.0",
   "description": "Installer for the psadt-deploy Claude Code skill: build, test and deploy PSADT v4.x Intune Win32 packages.",
   "keywords": [
     "psadt",