From 3d2be00890415be58dcc51b1a05985347eae1b9e Mon Sep 17 00:00:00 2001 From: Bradley Hilton Date: Mon, 16 Nov 2026 17:07:46 -0800 Subject: [PATCH] fix: show Atomic installation help before repository initialization --- CHANGELOG.md | 3 ++ README.md | 2 + package.json | 2 +- scripts/atomicDiscovery.test.mjs | 11 ++++ scripts/atomicDiscoverySmoke.mjs | 87 +++++++++++++++++++++++++++++++ src/atomic/sourceControl.ts | 13 ++++- vendor/nodeatomic/NOTICE | 2 +- vendor/nodeatomic/README.md | 7 +++ vendor/nodeatomic/dist/index.d.ts | 2 +- vendor/nodeatomic/dist/index.js | 2 +- 10 files changed, 125 insertions(+), 6 deletions(-) create mode 100644 scripts/atomicDiscovery.test.mjs create mode 100644 scripts/atomicDiscoverySmoke.mjs diff --git a/CHANGELOG.md b/CHANGELOG.md index ea2072e..d19a152 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,8 @@ # Atomic Sherpa +## Unreleased +- Detect missing Atomic installations in trusted local workspaces before repository initialization, including Git-only projects, and link the warning to the installation guide. Reuse nodeatomic's metadata-only discovery without native loading or CLI execution; retain trust gating and full validation for existing Atomic repositories. + ## 0.0.1 - 2026-11-16 - First GitHub release of Atomic Sherpa under `atomicdotdev/sherpa-vscode`. - Rename the extension to Atomic Sherpa (`atomic-sherpa`) and use the backpack artwork as its icon. diff --git a/README.md b/README.md index 7864111..0cd6400 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,8 @@ Local packages are written to `releases/`. Use the version confirmed by the buil **Setup help:** Run **Atomic: Installation Guide**, use the book button in **Atomic History & Views**, or click a missing/incompatible Atomic warning. The read-only guide identifies the extension host, links to the official instructions, and offers **Refresh Atomic** and **View diagnostics**. It does not run an installer or terminal commands. Repository-upgrade and other backend errors still open diagnostics rather than installation guidance. +Trusted local workspaces show **Install Atomic to enable version control** when Atomic is missing, even before `atomic init` or in a Git-only project. This startup check reads installation metadata without loading native code or running the CLI. Opening an Atomic repository still performs full native integrity and contract validation. Untrusted, virtual-only, and empty workspaces do not probe the local installation. + 1. In VS Code, VSCodium, or another compatible editor, open the Command Palette. 2. Run **Extensions: Install from VSIX…** and select that file. 3. Reload the editor window if prompted. diff --git a/package.json b/package.json index b87b090..51f86b0 100644 --- a/package.json +++ b/package.json @@ -930,7 +930,7 @@ "scripts": { "install:all": "npm ci", "test": "bun test scripts/", - "test:atomic": "bun test scripts/atomicIntent.test.mjs scripts/atomicIntentView.test.mjs scripts/atomicSourceControl.test.mjs scripts/atomicErrors.test.mjs scripts/atomicEvidence.test.mjs scripts/atomicDraftView.test.mjs scripts/atomicChangeMetadata.test.mjs scripts/atomicBlastRadius.test.mjs scripts/atomicFileDiff.test.mjs scripts/atomicPlanContext.test.mjs", + "test:atomic": "bun test scripts/atomicIntent.test.mjs scripts/atomicIntentView.test.mjs scripts/atomicSourceControl.test.mjs scripts/atomicDiscovery.test.mjs scripts/atomicErrors.test.mjs scripts/atomicEvidence.test.mjs scripts/atomicDraftView.test.mjs scripts/atomicChangeMetadata.test.mjs scripts/atomicBlastRadius.test.mjs scripts/atomicFileDiff.test.mjs scripts/atomicPlanContext.test.mjs", "test:atomic:graph": "bun run build:extension:graph && bun scripts/atomicViewHostSmoke.mjs && bun scripts/atomicDiffHostSmoke.mjs && bun scripts/atomicGraphSmoke.mjs", "test:atomic:native": "bun run build:extension:atomic && node scripts/atomicNativeSmoke.mjs", "test:atomic:runtime": "node scripts/atomicRuntimeSmoke.mjs --native", diff --git a/scripts/atomicDiscovery.test.mjs b/scripts/atomicDiscovery.test.mjs new file mode 100644 index 0000000..a952724 --- /dev/null +++ b/scripts/atomicDiscovery.test.mjs @@ -0,0 +1,11 @@ +import { expect, test } from 'bun:test'; +import { spawnSync } from 'node:child_process'; +import { fileURLToPath } from 'node:url'; + +test('fresh-workspace installation guidance respects trust, native laziness, and refresh', () => { + const result = spawnSync(process.execPath, [fileURLToPath(new URL('./atomicDiscoverySmoke.mjs', import.meta.url))], { + encoding: 'utf8', timeout: 15_000, + }); + expect(result.error).toBeUndefined(); + expect(result.status, result.stderr || result.stdout).toBe(0); +}, 20_000); diff --git a/scripts/atomicDiscoverySmoke.mjs b/scripts/atomicDiscoverySmoke.mjs new file mode 100644 index 0000000..07f5bae --- /dev/null +++ b/scripts/atomicDiscoverySmoke.mjs @@ -0,0 +1,87 @@ +// Real installation discovery and filesystem fixtures; only the VS Code host API is doubled. +// Run separately so its vscode module double cannot affect other suites. +import assert from 'node:assert/strict'; +import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { mock } from 'bun:test'; + +const root = await mkdtemp(join(tmpdir(), 'sherpa-discovery-')); +const workspacePath = join(root, 'workspace'); +const extensionPath = join(root, 'extension'); +const commands = new Map(); +const disposable = () => ({ dispose() {} }); +const workspace = { isTrusted: false, workspaceFolders: [{ uri: { scheme: 'file', fsPath: workspacePath } }], + onDidChangeWorkspaceFolders: disposable, onDidGrantWorkspaceTrust: disposable }; +let provider; +mock.module('vscode', () => ({ + EventEmitter: class { event = () => disposable(); fire() {} dispose() {} }, + ThemeIcon: class { constructor(id) { this.id = id; } }, + workspace, + commands: { registerCommand: (id, handler) => { commands.set(id, handler); return disposable(); } }, + window: { registerTreeDataProvider: (_id, value) => { provider = value; return disposable(); }, + createOutputChannel: () => ({ appendLine() {}, show() {}, dispose() {} }), + showErrorMessage: (message) => { throw new Error(message); } }, +})); +const keys = ['PATH', 'Path', 'HOME', 'USERPROFILE', 'APPDATA', 'LOCALAPPDATA', 'XDG_STATE_HOME', + 'ATOMIC_RUNTIME_DIR', 'LIBATOMIC_ADDON', 'ATOMIC_BIN']; +const previousEnv = Object.fromEntries(keys.map((key) => [key, process.env[key]])); +const refresh = () => commands.get('sherpaAtomic.refresh')(); +const action = () => provider.getChildren()[0].command?.command; +try { + for (const key of keys) delete process.env[key]; + Object.assign(process.env, { PATH: '', HOME: root, USERPROFILE: root, APPDATA: root, + LOCALAPPDATA: root, XDG_STATE_HOME: root }); + await mkdir(join(workspacePath, '.git'), { recursive: true }); + await mkdir(join(extensionPath, 'dist', 'nodeatomic'), { recursive: true }); + const consumer = new URL('../vendor/nodeatomic/dist/index.js', import.meta.url).href; + await writeFile(join(extensionPath, 'dist', 'nodeatomic', 'index.mjs'), `export * from ${JSON.stringify(consumer)};\n`); + const { registerAtomicSourceControl } = await import('../src/atomic/sourceControl.ts'); + registerAtomicSourceControl({ subscriptions: [], extensionPath }); + assert.equal(action(), undefined, 'Untrusted workspaces must not probe the runtime'); + + workspace.isTrusted = true; + await refresh(); + assert.equal(action(), 'sherpaAtomic.installGuide', 'A Git-only workspace without Atomic must offer installation help'); + + const installation = join(root, 'installation'); + const [library, target] = { darwin: ['libatomic.dylib', 'aarch64-apple-darwin'], + linux: ['libatomic.so', 'x86_64-unknown-linux-gnu'], win32: ['libatomic.dll', 'x86_64-pc-windows-msvc'] }[process.platform]; + await mkdir(installation); + await writeFile(join(installation, library), 'Not a native library: discovery must not load this'); + await writeFile(join(installation, 'libatomic-runtime.json'), JSON.stringify({ schemaVersion: 1, + version: '0.22.0', revision: 'a'.repeat(40), platform: process.platform, arch: process.arch, + target, nodeApiVersion: 8, library, librarySha256: '0'.repeat(64), descriptorSha256: '0'.repeat(64) })); + process.env.ATOMIC_RUNTIME_DIR = installation; + await refresh(); + assert.equal(action(), undefined, 'A discovered installation needs no native loading in a Git-only workspace'); + + await mkdir(join(workspacePath, '.atomic')); + await refresh(); + assert.equal(action(), 'sherpaAtomic.installGuide', 'Existing Atomic repositories must still fully validate the native runtime'); + await rm(join(workspacePath, '.atomic'), { recursive: true }); + await refresh(); + assert.equal(action(), undefined, 'Removing the Atomic repository must restore metadata-only discovery'); + + delete process.env.ATOMIC_RUNTIME_DIR; + await refresh(); + assert.equal(action(), 'sherpaAtomic.installGuide', 'Refresh must retry discovery rather than cache successful availability'); + + workspace.isTrusted = false; + await refresh(); + assert.equal(action(), undefined, 'A previous installation warning must not survive an untrusted workspace'); + workspace.isTrusted = true; + workspace.workspaceFolders = [{ uri: { scheme: 'vscode-vfs', fsPath: workspacePath } }]; + await refresh(); + assert.equal(action(), undefined, 'Virtual-only workspaces must not probe the local runtime'); + workspace.workspaceFolders = []; + await refresh(); + assert.equal(action(), undefined, 'Empty windows must retain the open-workspace guidance'); + console.log('Discovery passed: Git-only missing/install/retry, native validation for Atomic repositories, trust, virtual and empty workspaces.'); +} finally { + provider?.dispose(); + for (const [key, value] of Object.entries(previousEnv)) { + if (value === undefined) delete process.env[key]; else process.env[key] = value; + } + await rm(root, { recursive: true, force: true }); +} diff --git a/src/atomic/sourceControl.ts b/src/atomic/sourceControl.ts index 2ef87f9..734bed8 100644 --- a/src/atomic/sourceControl.ts +++ b/src/atomic/sourceControl.ts @@ -13,7 +13,7 @@ import { AtomicDiffEditor } from './diffEditor'; import { revisionText } from './fileDiff'; import type { Status } from './model'; -type Consumer = { openRepository(root: string): Promise }; +type Consumer = { openRepository(root: string): Promise; resolveRuntime(): unknown }; type Resource = vscode.SourceControlResourceState & { atomicPath: string; owner: RepositoryUI }; type RepositoryUI = { session: RepositorySession; @@ -272,18 +272,20 @@ class AtomicSourceControl implements vscode.TreeDataProvider, vscode.Dispo private async discover(): Promise { if (this.disposed || this.connecting) return; + this.discoveryIssue = undefined; if (!vscode.workspace.isTrusted) { this.message = 'Trust this workspace to enable Atomic version control.'; this.changed.fire(undefined); return; } this.connecting = true; - this.discoveryIssue = undefined; this.message = 'Open a local Atomic repository workspace to see history and views.'; try { const roots = new Set(); + let hasLocalWorkspace = false; for (const folder of vscode.workspace.workspaceFolders ?? []) { if (folder.uri.scheme !== 'file') continue; + hasLocalWorkspace = true; let root = folder.uri.fsPath; while (true) { if (await stat(path.join(root, '.atomic')).then((s) => s.isDirectory(), () => false)) { @@ -299,6 +301,9 @@ class AtomicSourceControl implements vscode.TreeDataProvider, vscode.Dispo for (const [root, owner] of this.repositories) { if (!roots.has(root)) { this.disposeRepository(owner); this.repositories.delete(root); } } + // Fresh/Git-only workspaces still need installation guidance. Discovery + // reads metadata only; defer native loading/validation until repository use. + if (!roots.size && hasLocalWorkspace) (await this.loadConsumer()).resolveRuntime(); for (const root of roots) { if (this.repositories.has(root)) continue; try { @@ -328,6 +333,10 @@ class AtomicSourceControl implements vscode.TreeDataProvider, vscode.Dispo this.output.appendLine(`${root}: ${this.discoveryIssue.detail}\n${this.discoveryIssue.recovery}`); } } + } catch (error) { + this.discoveryIssue = describeAtomicError(error); + this.message = this.discoveryIssue.title; + this.output.appendLine(`${this.discoveryIssue.detail}\n${this.discoveryIssue.recovery}`); } finally { this.connecting = false; this.changed.fire(undefined); diff --git a/vendor/nodeatomic/NOTICE b/vendor/nodeatomic/NOTICE index 1b5a6f6..34630ad 100644 --- a/vendor/nodeatomic/NOTICE +++ b/vendor/nodeatomic/NOTICE @@ -1,7 +1,7 @@ Vendored nodeatomic JavaScript consumer and generated protobuf codecs. Source: https://github.com/atomicdotdev/nodeatomic -Source revision: fd91a76bcbef416b8114ab9885d462c5a2783dff +Source revision: ec31722a1237f42147f4eba3b172e4455b19271f Generated codecs/fingerprint use the published Atomic v0.22.0 descriptor. Native producer revision: 61d8040ed25508ca00b778ae01d7c32499f1cab3 License: MIT OR Apache-2.0 diff --git a/vendor/nodeatomic/README.md b/vendor/nodeatomic/README.md index d249d71..e921dde 100644 --- a/vendor/nodeatomic/README.md +++ b/vendor/nodeatomic/README.md @@ -63,6 +63,13 @@ tries a different installation or a package-bundled binary. Missing installation report how to install Atomic or configure `ATOMIC_RUNTIME_DIR`. Errors expose a stable `code` through the exported `AtomicRuntimeError` class. +Use `resolveRuntime()` from `nodeatomic` to check installation discovery before +opening a repository, including in a Git-only workspace. It returns the selected +library path and optional manifest, or throws an `AtomicRuntimeError`. It reads +installation metadata only; it does not load native code, execute the CLI, or +verify binary integrity or the loaded protobuf descriptor. Those checks still +run on the first Atomic operation. Discovery failures are not cached. + ### Validation and compatibility This consumer is generated from the published **Atomic v0.22.0** native runtime diff --git a/vendor/nodeatomic/dist/index.d.ts b/vendor/nodeatomic/dist/index.d.ts index 1bddc0f..9fa6ffe 100644 --- a/vendor/nodeatomic/dist/index.d.ts +++ b/vendor/nodeatomic/dist/index.d.ts @@ -1,6 +1,6 @@ import type { atomic as Contract } from './generated/proto.cjs'; export { call, proto } from './native.js'; -export { AtomicRuntimeError } from './runtime/loader.mjs'; +export { AtomicRuntimeError, resolveRuntime } from './runtime/loader.mjs'; export { openRepository, AtomicRepository } from './repository.js'; export { KnowledgeClient } from './knowledge.js'; export type { GetVaultOptions, ListVaultOptions, VaultContextOptions, VerificationOptions, AddOptions, RecordOptions, LogOptions, ChangeOptions, ChangeReference, StatusOptions, ListViewsOptions, CreateViewOptions, SwitchViewOptions, DeleteViewOptions, PushOptions, PullOptions, AddRemoteOptions, InsertViewOptions, PushResponse, PullResponse, InsertViewResponse, ChangeMetadata, ChangeAIUsage, ChangeTokenUsage, ChangeGraphSummary, ChangeFileSummary, ChangeBlastRadius, ChangeImpactFile, ChangeImpactEdge, ChangeIntentContext, ChangePlanBinding, ChangeIntentIdentity, ChangeIntentAssociation, } from './repository.js'; diff --git a/vendor/nodeatomic/dist/index.js b/vendor/nodeatomic/dist/index.js index 469edc7..84c12e9 100644 --- a/vendor/nodeatomic/dist/index.js +++ b/vendor/nodeatomic/dist/index.js @@ -1,7 +1,7 @@ import { resolve } from 'node:path'; import { call, proto as atomic } from './native.js'; export { call, proto } from './native.js'; -export { AtomicRuntimeError } from './runtime/loader.mjs'; +export { AtomicRuntimeError, resolveRuntime } from './runtime/loader.mjs'; export { openRepository, AtomicRepository } from './repository.js'; export { KnowledgeClient } from './knowledge.js'; const statusNames = {