Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
11 changes: 11 additions & 0 deletions scripts/atomicDiscovery.test.mjs
Original file line number Diff line number Diff line change
@@ -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);
87 changes: 87 additions & 0 deletions scripts/atomicDiscoverySmoke.mjs
Original file line number Diff line number Diff line change
@@ -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 });
}
13 changes: 11 additions & 2 deletions src/atomic/sourceControl.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ import { AtomicDiffEditor } from './diffEditor';
import { revisionText } from './fileDiff';
import type { Status } from './model';

type Consumer = { openRepository(root: string): Promise<AtomicRepository> };
type Consumer = { openRepository(root: string): Promise<AtomicRepository>; resolveRuntime(): unknown };
type Resource = vscode.SourceControlResourceState & { atomicPath: string; owner: RepositoryUI };
type RepositoryUI = {
session: RepositorySession;
Expand Down Expand Up @@ -272,18 +272,20 @@ class AtomicSourceControl implements vscode.TreeDataProvider<Node>, vscode.Dispo

private async discover(): Promise<void> {
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<string>();
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)) {
Expand All @@ -299,6 +301,9 @@ class AtomicSourceControl implements vscode.TreeDataProvider<Node>, 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 {
Expand Down Expand Up @@ -328,6 +333,10 @@ class AtomicSourceControl implements vscode.TreeDataProvider<Node>, 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);
Expand Down
2 changes: 1 addition & 1 deletion vendor/nodeatomic/NOTICE
Original file line number Diff line number Diff line change
@@ -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
Expand Down
7 changes: 7 additions & 0 deletions vendor/nodeatomic/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion vendor/nodeatomic/dist/index.d.ts
Original file line number Diff line number Diff line change
@@ -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';
Expand Down
2 changes: 1 addition & 1 deletion vendor/nodeatomic/dist/index.js
Original file line number Diff line number Diff line change
@@ -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 = {
Expand Down
Loading