@microwiseai/snapshot 0.3.71 → 0.5.0

package/dist/commands/clone-all.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `snapshot clone-all` — clone the full SOURCE closure a snapshot declares.
+ *
+ * Thin adapter over the published, typed @gitdot/clone-lib@0.2.0: it loads
+ * snapshot.json (the install set + registry scope→group), resolves it to a
+ * resolved-lock (S2), writes snapshot.lock.json, and clones the closure. All
+ * real logic — name→projectId resolution, coordinate/visibility/commitSha
+ * pinning, closure cloning, structured reporting — lives in the library.
+ *
+ * The GitLab token is the caller's own (getGitlabToken → glpkg token /
+ * GITLAB_TOKEN), decoupled from the install proxy: cloning is plain git, judged
+ * by repo visibility + caller access.
+ */
+export interface CloneAllOptions {
+    manifest?: string;
+    mode?: string;
+    dest?: string;
+    json?: boolean;
+}
+export declare function cloneAllCommand(options?: CloneAllOptions): Promise<void>;
+//# sourceMappingURL=clone-all.d.ts.map

package/dist/commands/clone-all.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clone-all.d.ts","sourceRoot":"","sources":["../../src/commands/clone-all.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,wBAAsB,eAAe,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6DlF"}

package/dist/commands/clone-all.js

@@ -0,0 +1,57 @@
+import chalk from 'chalk';
+import { readFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { resolveFromManifest, cloneFromLock, writeLock, createGitLabApi } from '@gitdot/clone-lib';
+import { getGitlabToken } from '../lib/config.js';
+export async function cloneAllCommand(options = {}) {
+    const manifestPath = options.manifest || 'snapshot.json';
+    const mode = options.mode === 'pinned' ? 'pinned' : 'head';
+    const dest = options.dest || process.cwd();
+    const token = getGitlabToken();
+    if (!token) {
+        console.error(chalk.red('Error: no GitLab token. Set GITLAB_TOKEN or configure glpkg (glpkg config save <token>).'));
+        process.exit(1);
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    }
+    catch (err) {
+        console.error(chalk.red(`Error: could not read manifest "${manifestPath}": ${err.message}`));
+        process.exit(1);
+        return;
+    }
+    const registry = manifest.registry || {};
+    const subset = manifest.name;
+    const api = createGitLabApi({ token, host: 'gitlab.com' });
+    const { lock, warnings } = await resolveFromManifest(manifest, {
+        api,
+        scopes: Object.keys(registry),
+        subset,
+    });
+    mkdirSync(dest, { recursive: true });
+    const lockPath = join(dest, 'snapshot.lock.json');
+    writeLock(lockPath, lock);
+    const report = await cloneFromLock(lockPath, { mode, dest });
+    if (options.json) {
+        // --json is the primary contract: emit the structured report verbatim.
+        console.log(JSON.stringify({ report, lock: lockPath, warnings }, null, 2));
+    }
+    else {
+        console.log(chalk.blue.bold('snapshot clone-all'));
+        console.log(chalk.gray(`manifest: ${manifestPath} | mode: ${mode} | dest: ${dest}`));
+        console.log(chalk.gray(`lock: ${lockPath}`));
+        console.log(`cloned ${chalk.green(report.cloned.length)} | ` +
+            `skipped ${report.skipped.length} | ` +
+            `no-access ${report['skipped-no-access'].length} | ` +
+            `not-found ${report['not-found'].length} | ` +
+            `failed ${chalk.red(report.failed.length)}`);
+        console.log(chalk.gray(`closureSize ${report.closureSize} | credentialsNeeded ${report.credentialsNeeded}`));
+        for (const w of warnings)
+            console.log(chalk.yellow(`⚠ ${w}`));
+    }
+    if (report.failed.length > 0 || report['not-found'].length > 0) {
+        process.exitCode = 1;
+    }
+}
+//# sourceMappingURL=clone-all.js.map

package/dist/commands/clone-all.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clone-all.js","sourceRoot":"","sources":["../../src/commands/clone-all.ts"],"names":[],"mappings":"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"}

package/dist/commands/install.d.ts

@@ -12,5 +12,13 @@ export declare function installSnapshot(snapshot: Snapshot, depth?: number, pare
     result: InstallResult;
     installers: Record<string, InstallerConfig>;
 }>;
-export declare function installCommand(name: string): Promise<void>;
+export interface InstallCommandOptions {
+    /** Converge onto the new version: remove previous-version-only packages (ADR 001). */
+    replace?: boolean;
+    /** With --replace, show what would change without modifying anything. */
+    dryRun?: boolean;
+    /** Skip the removal confirmation prompt. */
+    yes?: boolean;
+}
+export declare function installCommand(name: string, options?: InstallCommandOptions): Promise<void>;
 //# sourceMappingURL=install.d.ts.map

package/dist/commands/install.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../src/commands/install.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAMjE,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AA2eD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,eAAe,CACnC,QAAQ,EAAE,QAAQ,EAClB,KAAK,GAAE,MAAU,EACjB,gBAAgB,GAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAM,EACtD,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;CAAE,CAAC,CA8VjF;AA4FD,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAqYhE"}
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../src/commands/install.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAiBjE,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAkeD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,eAAe,CACnC,QAAQ,EAAE,QAAQ,EAClB,KAAK,GAAE,MAAU,EACjB,gBAAgB,GAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAM,EACtD,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;CAAE,CAAC,CA8VjF;AA4FD,MAAM,WAAW,qBAAqB;IACpC,sFAAsF;IACtF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yEAAyE;IACzE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,4CAA4C;IAC5C,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAoLD,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAuZrG"}

package/dist/commands/install.js

@@ -12,7 +12,8 @@ import { installSkitPackage } from '../lib/skit-adapter.js';
 import { markLicenseChecked } from '@microwiseai/license';
 import { authorizeSession, packagesToSpecs } from '../lib/session.js';
 import { parallelInstall, recordToEntries } from '@microwiseai/snapshot-parallel';
-import { dedupWithReport, dedupInstallBlock, recordInstalledSpecs } from '@microwiseai/snapshot-dedup';
+import { dedupWithReport, dedupInstallBlock, recordInstalledSpecs, recordReferences, computeReplacePlan, applyReplaceHistory, } from '@microwiseai/snapshot-dedup';
+import { createInterface } from 'readline';
 // CLI version — dynamically read from package.json (SSOT)
 import { createRequire } from 'module';
 const _require = createRequire(import.meta.url);
@@ -60,22 +61,28 @@ const DEFAULT_INSTALLERS = {
         command: 'glpkg install {pkg}',
         check: 'glpkg --version',
         hint: 'npm install -g @glpkg/cli',
+        // glpkg has no `uninstall` subcommand; its packages are global npm packages,
+        // so removal falls back to npm. (ADR 001 §d)
+        uninstall: 'npm uninstall -g {pkg}',
     },
     // Legacy alias for backward compatibility
     'gitlab-install': {
         command: 'glpkg install {pkg}',
         check: 'glpkg --version',
         hint: 'npm install -g @glpkg/cli (gitlab-install is deprecated, use glpkg)',
+        uninstall: 'npm uninstall -g {pkg}',
     },
     'skit': {
         command: 'skit install {pkg}',
         check: 'skit --version',
         hint: 'npm install -g @microwiseai/skit',
+        uninstall: 'skit uninstall {pkg}', // verified: `skit uninstall|rm <package>`
     },
     'npm-proxy': {
         command: 'npm install -g {pkg}',
         check: 'npm --version',
         hint: 'npm is required',
+        uninstall: 'npm uninstall -g {pkg}', // verified: `npm uninstall`
     },
 };
 /**
@@ -209,20 +216,6 @@ function runCommand(command) {
         return false;
     }
 }
-/**
- * PackageType을 installer 이름으로 변환
- */
-function packageTypeToInstaller(type, useProxy) {
-    switch (type) {
-        case 'skit':
-            return 'skit';
-        case 'npm':
-            return useProxy ? 'npm-proxy' : 'glpkg';
-        case 'generic':
-        default:
-            return 'glpkg';
-    }
-}
 /**
  * Check if a skit package is already installed with the specified version
  */
@@ -793,7 +786,169 @@ async function collectAllPackages(snapshot) {
     }
     return allPackages;
 }
-export async function installCommand(name) {
+/**
+ * Whether a package was installed as a skit (→ removed via `skit uninstall`).
+ * Determined offline from ~/.ist/installed-kits.json; everything else is treated
+ * as a global npm package (`npm uninstall -g`).
+ */
+function isSkitPackage(name) {
+    try {
+        const p = join(homedir(), '.ist', 'installed-kits.json');
+        if (!existsSync(p))
+            return false;
+        const kits = JSON.parse(readFileSync(p, 'utf-8'));
+        return !!kits[name];
+    }
+    catch {
+        return false;
+    }
+}
+/** Build the uninstall command for a package, or null if no uninstaller is known. */
+function uninstallCommandFor(name, installers) {
+    const installerName = isSkitPackage(name) ? 'skit' : 'npm-proxy';
+    const cfg = installers[installerName] || DEFAULT_INSTALLERS[installerName];
+    if (!cfg?.uninstall)
+        return null;
+    return cfg.uninstall.replace('{pkg}', name); // {pkg} = name only (uninstall takes no version)
+}
+/** Yes/No confirmation. Non-interactive (no TTY) → false (safe default: don't remove). */
+async function confirmPrompt(question) {
+    if (!process.stdin.isTTY)
+        return false;
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await new Promise((resolve) => {
+            rl.question(chalk.yellow(`${question} [y/N] `), resolve);
+        });
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+function printReplacePlan(plan) {
+    console.log('');
+    console.log(chalk.cyan('► Replace mode: converging to the new version set'));
+    if (plan.remove.length > 0) {
+        console.log(chalk.yellow(`  Will remove ${plan.remove.length} package(s) no longer in this snapshot:`));
+        for (const item of plan.remove) {
+            console.log(chalk.red(`    − ${item.name}@${item.version}`));
+        }
+    }
+    if (plan.keepShared.length > 0) {
+        console.log(chalk.gray(`  Keeping ${plan.keepShared.length} shared package(s) (still used by other snapshots):`));
+        for (const item of plan.keepShared) {
+            console.log(chalk.gray(`    • ${item.name}@${item.version} ← ${item.remainingRefs.join(', ')}`));
+        }
+    }
+    if (plan.stale.length > 0) {
+        console.log(chalk.gray(`  Cleaning ${plan.stale.length} superseded history entr(y/ies) (already replaced by new version):`));
+        for (const item of plan.stale) {
+            console.log(chalk.gray(`    ~ ${item.name}@${item.version}`));
+        }
+    }
+}
+/**
+ * Replace mode (ADR 001): after a successful install of a new version, remove
+ * packages that belonged to the previous version but are no longer part of the
+ * new version — UNLESS another installed snapshot still references them.
+ */
+async function runReplaceMode(snapshotName, newSet, options, installers) {
+    const plan = computeReplacePlan(snapshotName, newSet);
+    const hasWork = plan.remove.length > 0 || plan.keepShared.length > 0 || plan.stale.length > 0;
+    if (!hasWork) {
+        console.log('');
+        console.log(chalk.gray('► Replace mode: nothing to converge — system already matches this version.'));
+        return;
+    }
+    printReplacePlan(plan);
+    if (options.dryRun) {
+        console.log('');
+        console.log(chalk.gray('Dry-run: no packages removed and history left unchanged.'));
+        return;
+    }
+    // Confirm before any destructive uninstall.
+    if (plan.remove.length > 0 && !options.yes) {
+        const ok = await confirmPrompt(`Remove ${plan.remove.length} package(s)?`);
+        if (!ok) {
+            console.log(chalk.yellow('Aborted — no packages removed.'));
+            if (!process.stdin.isTTY) {
+                console.log(chalk.gray('  (non-interactive shell — pass --yes to remove)'));
+            }
+            return;
+        }
+    }
+    // Uninstall each removal candidate; only history-delete the ones that succeed.
+    const removed = [];
+    const failed = [];
+    for (const item of plan.remove) {
+        const cmd = uninstallCommandFor(item.name, installers);
+        if (!cmd) {
+            console.log(chalk.yellow(`  ⚠ No uninstaller for ${item.name} — skipping (manual removal required).`));
+            continue;
+        }
+        console.log(chalk.gray(`  Removing ${item.name}...`));
+        if (runCommand(cmd)) {
+            console.log(`    ${item.name}${chalk.green(' ✓ removed')}`);
+            removed.push(item);
+        }
+        else {
+            console.log(`    ${item.name}${chalk.red(' ✗ removal failed')}`);
+            if (lastCommandError)
+                console.log(chalk.gray(`      ${lastCommandError}`));
+            failed.push(item);
+        }
+    }
+    // Update history: delete removed entries; drop this snapshot from kept/stale refs.
+    applyReplaceHistory(snapshotName, removed, plan.keepShared, plan.stale);
+    console.log('');
+    console.log(chalk.green(`✓ Replace complete: removed ${removed.length}, kept ${plan.keepShared.length} shared` +
+        (failed.length > 0 ? chalk.red(`, ${failed.length} failed`) : '')));
+    if (failed.length > 0) {
+        console.log(chalk.yellow('  Failed removals were left installed and remain in history for retry:'));
+        for (const item of failed)
+            console.log(chalk.red(`    − ${item.name}@${item.version}`));
+    }
+}
+/**
+ * Dry-run preview: report what an install WOULD do, with no install side
+ * effects (no install/uninstall, no ~/.npmrc, no history). Import telemetry is
+ * a separate, global concern gated in index.ts (skipped for --dry-run there).
+ * Reads only (snapshot already fetched; extends bases resolved read-only inside
+ * collectAllPackages, which swallows fetch errors and returns a partial set).
+ * Never installs, uninstalls, or writes ~/.npmrc / history.
+ */
+async function previewInstall(snapshot, options) {
+    console.log('');
+    console.log(chalk.cyan('► Dry-run: preview only — nothing will be installed or changed.'));
+    // Resolve the full package set across the entire extends chain (reads only).
+    const previewPackages = await collectAllPackages(snapshot);
+    const entries = Object.entries(previewPackages).sort(([a], [b]) => a.localeCompare(b));
+    console.log('');
+    if (entries.length === 0) {
+        console.log(chalk.gray('  (No packages declared in this snapshot or its extends chain.)'));
+    }
+    else {
+        console.log(chalk.yellow(`Would install ${entries.length} package(s) (extends chain resolved):`));
+        for (const [n, v] of entries) {
+            console.log(chalk.gray(`  + ${n}@${v}`));
+        }
+    }
+    // With --replace, preview the convergence plan too (history read only, no write).
+    if (options.replace) {
+        const plan = computeReplacePlan(snapshot.name, previewPackages);
+        if (plan.remove.length > 0 || plan.keepShared.length > 0 || plan.stale.length > 0) {
+            printReplacePlan(plan);
+        }
+        else {
+            console.log('');
+            console.log(chalk.gray('► Replace preview: nothing to converge — system already matches this version.'));
+        }
+    }
+    console.log('');
+    console.log(chalk.gray('Dry-run complete: no installs, no uninstalls, no .npmrc or history changes.'));
+}
+export async function installCommand(name, options = {}) {
     console.log(chalk.blue.bold(`
 ╔══════════════════════════════════════════════════════════════╗
 ║                    Snapshot Installer                        ║
@@ -851,45 +1006,56 @@ export async function installCommand(name) {
     }
     catch (error) {
         const errMsg = error instanceof Error ? error.message : String(error);
+        if (options.dryRun) {
+            // Pure preview: a fetch failure (offline / no auth) is not fatal — we just
+            // cannot resolve what would be installed. Report a limited preview and
+            // exit 0 without touching anything.
+            console.log(chalk.yellow('⚠ Dry-run preview limited: could not fetch snapshot metadata.'));
+            console.log(chalk.gray(`  Reason: ${errMsg}`));
+            console.log(chalk.gray('  (No packages installed, no files changed.)'));
+            return;
+        }
         console.log(chalk.red(`Error: ${errMsg}`));
-        console.log(chalk.yellow('Check available snapshots: snapshot list'));
+        console.log(chalk.yellow('Check the snapshot name and version, e.g. snapshot install @scope/name@version'));
         process.exit(1);
     }
     console.log(chalk.green('✓') + ` Snapshot: ${snapshot.name} v${snapshot.version}`);
     if (snapshot.description) {
         console.log(chalk.gray(`  ${snapshot.description}`));
     }
+    // ========== Dry-run: preview with no install side effects ==========
+    // A dry-run must not install/uninstall anything and must not touch ~/.npmrc,
+    // the global node_modules, or the install history. We only READ snapshot
+    // metadata (already fetched; extends bases resolved read-only) to report what
+    // WOULD be installed — and, with --replace, what would be removed/kept/cleaned.
+    // We exit here BEFORE the access gate, session authorization, .npmrc
+    // configuration, the npm pre-install batch, and installSnapshot — i.e. before
+    // any write or network-write. Reached before recordInstalledSpecs /
+    // recordReferences, so no history mutation occurs either.
+    if (options.dryRun) {
+        await previewInstall(snapshot, options);
+        return;
+    }
     // ========== Access Check (based on snapshot.json access field) ==========
-    // Determine access type from snapshot.json:
-    //   - access: "public"                      → no login/license required
-    //   - access: "authenticated"               → IST login required, no license needed
+    // snapshot is a general installer. Access is simplified to two tiers:
+    //   - access: "public"                        → no license required
     //   - access: { type: "licensed", productId } → license required
-    //   - access field absent                    → treated as licensed (requires license)
+    //   - anything else / absent                  → access decided SERVER-side
+    //     (registry-proxy / license API are authoritative; a 401/403 fails loud).
+    // No client-side login gate: access control is backend-authoritative.
     const accessField = snapshot.access;
     const isPublicAccess = accessField === 'public';
-    const isAuthenticatedAccess = accessField === 'authenticated';
     const isLicensedAccess = !!accessField && typeof accessField === 'object' && accessField.type === 'licensed';
-    // --- IST Login Check ---
+    // Optional identity for telemetry only (anonymous when absent). NOT a gate.
+    // A wrapper (e.g. ist-setup) may layer a login system on top of snapshot via
+    // the authToken injection point (IST_SESSION_TOKEN env / getProxyAuthToken).
     const istCredentials = getIstCredentials();
-    if (istCredentials?.userId) {
-        console.log(chalk.green('✓') + ' IST login verified');
-    }
-    else if (isPublicAccess) {
-        console.log(chalk.yellow('⚠') + ' No IST login - installing public package');
-    }
-    else {
-        console.log(chalk.red('⛔ IST login required for non-public packages'));
-        console.log(chalk.gray('   Run: ist auth login'));
-        console.log(chalk.gray('   Or install a public snapshot first (no login required)'));
-        process.exit(1);
-    }
     // --- License Check ---
     const storedLicenseKey = getLicenseKey();
     let licenseValid = false;
-    if (isPublicAccess || isAuthenticatedAccess) {
-        // Public and authenticated snapshots — skip license check entirely
-        const label = isAuthenticatedAccess ? 'Authenticated' : 'Public';
-        console.log(chalk.green('✓') + ` ${label} snapshot - no license required`);
+    if (isPublicAccess) {
+        // Public snapshots — skip license check entirely
+        console.log(chalk.green('✓') + ' Public snapshot - no license required');
     }
     else if (storedLicenseKey) {
         try {
@@ -1132,17 +1298,21 @@ export async function installCommand(name) {
         console.log('');
         console.log(chalk.green('✓') + ' Snapshot info saved');
     }
-    // Post-install: run doctor to check prerequisites
-    console.log('');
-    const { checkPrerequisites, MINIMAL_PREREQUISITES } = await import('../lib/prerequisites.js');
-    const prereqResults = checkPrerequisites(MINIMAL_PREREQUISITES);
-    const missingPrereqs = prereqResults.filter(r => !r.installed);
-    if (missingPrereqs.length > 0) {
-        console.log(chalk.yellow(`\n⚠ ${missingPrereqs.length} prerequisite(s) not satisfied:`));
-        for (const r of missingPrereqs) {
-            console.log(`  ${chalk.red('❌')} ${r.name} — required by ${r.requiredBy.join(', ')}`);
+    // Record references for the ENTIRE declared set (installed + dedup-skipped),
+    // so replace mode has accurate referencedBy data (ADR 001 §c). This runs on
+    // every install, not just --replace, to build up the reference graph.
+    recordReferences(allPackages, snapshot.name);
+    // ========== Replace mode (ADR 001) ==========
+    // Only converge after a fully successful install — never remove old packages
+    // when the new version's install partially failed.
+    if (options.replace) {
+        if (result.failed.length > 0) {
+            console.log('');
+            console.log(chalk.yellow('⚠ Skipping --replace: install had failures; not removing previous packages.'));
+        }
+        else {
+            await runReplaceMode(snapshot.name, allPackages, options, effectiveInstallers);
         }
-        console.log(chalk.gray(`\nRun 'snapshot setup' to install, or 'snapshot doctor' for details.`));
     }
     // Send telemetry (fire and forget)
     sendInstallTelemetry({