Skip to content

Add an Atomic installation guide without managing Atomic - #14

Merged
graywolf336 merged 1 commit into
releasefrom
feat/atomic-install-guide
Nov 17, 2026
Merged

graywolf336 merged 1 commit into
releasefrom
feat/atomic-install-guide

Conversation

@graywolf336

Copy link
Copy Markdown
Contributor

Change

Add a read-only, script-free Atomic installation guide inside Sherpa. Atomic remains a separate product installed and managed by the user; no installer download, execution, update, or repair is added.

Entry points

  • Click the missing/incompatible Atomic warning in Atomic History & Views.
  • Run Atomic: Installation Guide from the Command Palette.
  • Use the book button in the Atomic history/view toolbar.
  • Runtime-failure status/recovery actions use the same guide. Repository migrations and other backend errors still open diagnostics.

Guide

  • Links to the verified official human-readable installation instructions: https://docs.atomic.dev/getting-started/installation
  • Identifies the actual extension host OS/architecture and remote context, with SSH/WSL/container guidance.
  • Documents this build's complete Atomic v0.22.0 requirement and restart step.
  • Provides Refresh Atomic (discovery only) and View diagnostics.
  • Reuses one panel; closing it allows a fresh guide to be opened.

Security and scope

  • enableScripts: false, no local resource roots, default-deny CSP with a nonce for styles only.
  • Only the existing refresh and diagnostics command URIs are enabled; no command arguments from page content.
  • External links are fixed official URLs. Host labels are HTML-escaped.
  • No new dependencies, terminal commands, runtime provisioning, version bump, or publication.

Verification

  • npm ci, npm run typecheck, npm test: 225 passed, 0 failed.
  • npm run package:vsix and final node scripts/package-universal.mjs: passed universal archive/extracted-consumer checks.
  • bun scripts/atomicViewHostSmoke.mjs: passed existing view-tree behavior smoke.
  • npm audit --omit=dev --audit-level=low: 0 vulnerabilities.
  • Installed the VSIX into actual VS Code 1.145.3 on macOS ARM64, with isolated HOME/XDG state and PATH. A separate probe inside that extension host confirmed ATOMIC_RUNTIME_NOT_FOUND.
  • Opened the guide by clicking the real warning, from the Command Palette, and using the toolbar button by keyboard.
  • Visually inspected the actual page; confirmed zero script elements, default-deny CSP, correct official URL/host label, and only the two intended command links.
  • Clicked Refresh and View diagnostics; the actual Atomic output log showed the initial discovery error and the subsequent refresh error.
  • Verified singleton reuse and close/reopen lifecycle.
  • After README/changelog packaging, all 100 runtime/webview files were byte-for-byte identical to the installed payload exercised above.
  • Windows/Linux actual extension-host checks are not claimed. Disposable smoke fixtures/probes were removed.

Local verified artifact: releases/atomic-sherpa-1.0.0-install-guide.vsix

SHA-256: 161b331b463a1ecad5b495dba14e11757cb9d761917a4eca8bd60c2ec35eb209

@graywolf336

Copy link
Copy Markdown
Contributor Author

CI passed on Windows, macOS, and Linux: https://github.com/atomicdotdev/sherpa-vscode/actions/runs/43977726643 . Local checks passed: 225 tests, typecheck, existing view-tree host smoke, universal VSIX/extracted-consumer verification, and production audit (0 vulnerabilities). The packaged guide was exercised in actual VS Code with ATOMIC_RUNTIME_NOT_FOUND, including warning/Command Palette/toolbar entry points, refresh/diagnostics, and close/reopen. Verified VSIX retained locally as releases/atomic-sherpa-1.0.0-install-guide.vsix; temporary smoke fixtures and isolated implementation worktree removed. No Atomic provisioning, extension version bump, or publication.

@graywolf336
graywolf336 merged commit 25624e4 into release Nov 17, 2026
3 checks passed
@graywolf336
graywolf336 deleted the feat/atomic-install-guide branch November 17, 2026 00:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant