revisium 2.3.0 → 2.5.0-alpha.0

package/src/services/connection/connection.service.ts

@@ -5,12 +5,15 @@ import {
   ConnectionFactoryService,
   ConnectionInfo,
 } from './connection-factory.service';
-import { UrlBuilderService, UrlEnvConfig } from '../url';
+import { LoggerService } from '../common';
+import { RevisiumUrlComplete, UrlBuilderService, UrlEnvConfig } from '../url';
+import { LoadedWorkspaceConfig, WorkspaceConfigService } from '../workspace';
 
 export { ConnectionInfo } from './connection-factory.service';
 
 export interface ConnectionOptions {
   url?: string;
+  context?: string;
   createProject?: boolean;
 }
 
@@ -22,6 +25,8 @@ export class ConnectionService {
     private readonly configService: ConfigService,
     private readonly urlBuilder: UrlBuilderService,
     private readonly connectionFactory: ConnectionFactoryService,
+    private readonly workspaceConfig: WorkspaceConfigService,
+    private readonly logger: LoggerService,
   ) {}
 
   public get connection(): ConnectionInfo {
@@ -36,14 +41,80 @@ export class ConnectionService {
   }
 
   public async connect(options: ConnectionOptions = {}): Promise<void> {
-    const env = this.getEnvConfig();
-    const url = await this.urlBuilder.parseAndComplete(options.url, 'api', env);
+    const url = await this.resolveTarget(options);
 
     this._connection = await this.connectionFactory.createConnection(url, {
       createProject: options.createProject,
     });
   }
 
+  public async resolveTarget(
+    options: ConnectionOptions = {},
+  ): Promise<RevisiumUrlComplete> {
+    return this.resolveUrl(options, this.getEnvConfig());
+  }
+
+  private async resolveUrl(
+    options: ConnectionOptions,
+    env: UrlEnvConfig,
+  ): Promise<RevisiumUrlComplete> {
+    if (options.url) {
+      return this.urlBuilder.parseAndComplete(options.url, 'api', env);
+    }
+
+    if (options.context) {
+      const workspace = await this.workspaceConfig.load();
+      if (!workspace) {
+        throw new Error(
+          `No Revisium workspace config found for context "${options.context}". Run: revisium instance add <instance> --url <revisium-server-url>, then revisium context create ${options.context} --instance <instance> --org <org> --project <project>`,
+        );
+      }
+      const url = this.workspaceConfig.resolveConnection(
+        workspace,
+        options.context,
+        env,
+      );
+      this.logWorkspaceContext(workspace, options.context);
+      return url;
+    }
+
+    if (env.url) {
+      return this.urlBuilder.parseAndComplete(undefined, 'api', env);
+    }
+
+    const workspace = await this.workspaceConfig.load();
+    if (workspace) {
+      const url = this.workspaceConfig.resolveConnection(
+        workspace,
+        undefined,
+        env,
+      );
+      this.logWorkspaceContext(workspace);
+      return url;
+    }
+
+    return this.urlBuilder.parseAndComplete(undefined, 'api', env);
+  }
+
+  private logWorkspaceContext(
+    loaded: LoadedWorkspaceConfig,
+    contextName?: string,
+  ): void {
+    const selectedContext = contextName || loaded.config.currentContext;
+    if (!selectedContext) {
+      return;
+    }
+
+    const context = loaded.config.contexts[selectedContext];
+    if (!context) {
+      return;
+    }
+
+    this.logger.info(
+      `Using context ${selectedContext} (instance: ${context.instance})`,
+    );
+  }
+
   private getEnvConfig(): UrlEnvConfig {
     return {
       url: this.configService.get<string>('REVISIUM_URL'),

package/src/services/credentials/__tests__/credential-store.service.spec.ts

@@ -0,0 +1,128 @@
+import { CredentialStoreService } from '../credential-store.service';
+
+const keyringEntries = new Map<string, string>();
+
+jest.mock('@napi-rs/keyring', () => ({
+  Entry: jest.fn().mockImplementation((service: string, account: string) => ({
+    setPassword: jest.fn((password: string) => {
+      keyringEntries.set(`${service}:${account}`, password);
+    }),
+    getPassword: jest.fn(() => {
+      if (account.includes('credential:missing-code')) {
+        const error = new Error('mock missing credential');
+        Object.assign(error, { code: 'NoEntry' });
+        throw error;
+      }
+
+      if (account.includes('credential:missing-name')) {
+        const error = new Error('mock missing credential');
+        error.name = 'NoEntry';
+        throw error;
+      }
+
+      return keyringEntries.get(`${service}:${account}`) ?? null;
+    }),
+    deleteCredential: jest.fn(() => {
+      if (account.includes('credential:missing-code')) {
+        const error = new Error('mock missing credential');
+        Object.assign(error, { code: 'NoEntry' });
+        throw error;
+      }
+
+      return keyringEntries.delete(`${service}:${account}`);
+    }),
+  })),
+}));
+
+describe('CredentialStoreService', () => {
+  let service: CredentialStoreService;
+  const originalServiceName = process.env.REVISIUM_CREDENTIAL_STORE_SERVICE;
+
+  beforeEach(() => {
+    delete process.env.REVISIUM_CREDENTIAL_STORE_SERVICE;
+    keyringEntries.clear();
+    service = new CredentialStoreService();
+  });
+
+  afterAll(() => {
+    if (originalServiceName === undefined) {
+      delete process.env.REVISIUM_CREDENTIAL_STORE_SERVICE;
+      return;
+    }
+    process.env.REVISIUM_CREDENTIAL_STORE_SERVICE = originalServiceName;
+  });
+
+  it('saves, reads, and deletes API key credentials by base URL and credential name', () => {
+    const ref = {
+      baseUrl: 'https://cloud.revisium.io',
+      credential: 'admin',
+    };
+
+    service.saveApiKey(ref, ' rev_saved ');
+
+    expect(service.hasCredential(ref)).toBe(true);
+    expect(service.getCredential(ref)).toEqual({
+      method: 'apikey',
+      apikey: 'rev_saved',
+    });
+    expect(service.deleteCredential(ref)).toBe(true);
+    expect(service.getCredential(ref)).toBeUndefined();
+  });
+
+  it('uses normalized base URL and credential name in the account key', () => {
+    expect(
+      service.getAccountName({
+        baseUrl: 'https://cloud.revisium.io',
+        credential: 'admin',
+      }),
+    ).toBe('instance:https://cloud.revisium.io|credential:admin');
+  });
+
+  it('rejects empty API keys before writing to the store', () => {
+    expect(() =>
+      service.saveApiKey(
+        {
+          baseUrl: 'https://cloud.revisium.io',
+          credential: 'default',
+        },
+        ' ',
+      ),
+    ).toThrow('API key cannot be empty');
+  });
+
+  it('fails clearly when a saved credential has unsupported JSON', () => {
+    const ref = {
+      baseUrl: 'https://cloud.revisium.io',
+      credential: 'default',
+    };
+    keyringEntries.set(
+      `revisium-cli:${service.getAccountName(ref)}`,
+      JSON.stringify({ method: 'token', token: 'jwt' }),
+    );
+
+    expect(() => service.getCredential(ref)).toThrow(
+      'Saved Revisium credential "default" for https://cloud.revisium.io has an unsupported format',
+    );
+  });
+
+  it('treats keyring NoEntry errors as missing credentials', () => {
+    expect(
+      service.getCredential({
+        baseUrl: 'https://cloud.revisium.io',
+        credential: 'missing-code',
+      }),
+    ).toBeUndefined();
+    expect(
+      service.getCredential({
+        baseUrl: 'https://cloud.revisium.io',
+        credential: 'missing-name',
+      }),
+    ).toBeUndefined();
+    expect(
+      service.deleteCredential({
+        baseUrl: 'https://cloud.revisium.io',
+        credential: 'missing-code',
+      }),
+    ).toBe(false);
+  });
+});

package/src/services/credentials/__tests__/credential-target.service.spec.ts

@@ -0,0 +1,126 @@
+import { CredentialTargetService } from '../credential-target.service';
+import { WorkspaceConfigService } from '../../workspace';
+
+describe('CredentialTargetService', () => {
+  let workspaceConfig: {
+    load: jest.Mock;
+    normalizeBaseUrl: jest.Mock;
+    findInstanceNameByBaseUrl: jest.Mock;
+  };
+  let service: CredentialTargetService;
+
+  beforeEach(() => {
+    workspaceConfig = {
+      load: jest.fn(),
+      normalizeBaseUrl: jest.fn(),
+      findInstanceNameByBaseUrl: jest.fn(),
+    };
+    service = new CredentialTargetService(
+      workspaceConfig as unknown as WorkspaceConfigService,
+    );
+  });
+
+  it('resolves explicit instance targets from workspace config', async () => {
+    workspaceConfig.load.mockResolvedValue({
+      path: '/repo/.revisium/revisium-cli.config.json',
+      config: {
+        version: 1,
+        currentContext: 'dictionary',
+        instances: {
+          cloud: {
+            baseUrl: 'https://cloud.revisium.io',
+            authMode: 'stored',
+          },
+        },
+        contexts: {},
+      },
+    });
+
+    await expect(
+      service.resolveRequired({
+        instance: 'cloud',
+        credential: 'admin',
+      }),
+    ).resolves.toEqual({
+      baseUrl: 'https://cloud.revisium.io',
+      credential: 'admin',
+      instanceName: 'cloud',
+      authMode: 'stored',
+      configPath: '/repo/.revisium/revisium-cli.config.json',
+    });
+  });
+
+  it('resolves URL targets and attaches matching instance metadata when available', async () => {
+    workspaceConfig.normalizeBaseUrl.mockReturnValue(
+      'https://cloud.revisium.io',
+    );
+    workspaceConfig.findInstanceNameByBaseUrl.mockReturnValue('cloud');
+    workspaceConfig.load.mockResolvedValue({
+      path: '/repo/.revisium/revisium-cli.config.json',
+      config: {
+        version: 1,
+        instances: {
+          cloud: {
+            baseUrl: 'https://cloud.revisium.io',
+            authMode: 'none',
+          },
+        },
+        contexts: {},
+      },
+    });
+
+    await expect(
+      service.resolveRequired({
+        url: 'revisium://cloud.revisium.io/admin/dictionary/master',
+      }),
+    ).resolves.toEqual({
+      baseUrl: 'https://cloud.revisium.io',
+      credential: 'default',
+      instanceName: 'cloud',
+      authMode: 'none',
+      configPath: '/repo/.revisium/revisium-cli.config.json',
+    });
+  });
+
+  it('uses the current context when status/logout omit target selectors', async () => {
+    workspaceConfig.load.mockResolvedValue({
+      path: '/repo/.revisium/revisium-cli.config.json',
+      config: {
+        version: 1,
+        currentContext: 'dictionary',
+        instances: {
+          cloud: {
+            baseUrl: 'https://cloud.revisium.io',
+            authMode: 'stored',
+          },
+        },
+        contexts: {
+          dictionary: {
+            instance: 'cloud',
+            credential: 'admin',
+            organization: 'admin',
+            project: 'dictionary',
+          },
+        },
+      },
+    });
+
+    await expect(service.resolveOrCurrentContext({})).resolves.toEqual({
+      baseUrl: 'https://cloud.revisium.io',
+      credential: 'admin',
+      instanceName: 'cloud',
+      contextName: 'dictionary',
+      authMode: 'stored',
+      configPath: '/repo/.revisium/revisium-cli.config.json',
+    });
+  });
+
+  it('rejects ambiguous target selectors', async () => {
+    await expect(
+      service.resolveRequired({
+        url: 'revisium://cloud.revisium.io',
+        instance: 'cloud',
+      }),
+    ).rejects.toThrow('Use only one target selector: --instance or --url');
+  });
+});

package/src/services/credentials/credential-store.service.ts

@@ -0,0 +1,145 @@
+import { Injectable } from '@nestjs/common';
+import { Entry } from '@napi-rs/keyring';
+import { AuthCredentials } from 'src/services/url';
+
+const SERVICE_NAME = 'revisium-cli';
+
+export interface CredentialRef {
+  baseUrl: string;
+  credential: string;
+}
+
+interface StoredApiKeyCredential {
+  method: 'apikey';
+  apiKey: string;
+}
+
+type StoredCredential = StoredApiKeyCredential;
+
+@Injectable()
+export class CredentialStoreService {
+  private readonly serviceName =
+    process.env.REVISIUM_CREDENTIAL_STORE_SERVICE || SERVICE_NAME;
+
+  saveApiKey(ref: CredentialRef, apiKey: string): void {
+    const trimmedApiKey = apiKey.trim();
+    if (!trimmedApiKey) {
+      throw new Error('API key cannot be empty');
+    }
+
+    this.writeCredential(ref, {
+      method: 'apikey',
+      apiKey: trimmedApiKey,
+    });
+  }
+
+  getCredential(ref: CredentialRef): AuthCredentials | undefined {
+    const raw = this.readCredential(ref);
+    if (!raw) {
+      return undefined;
+    }
+
+    const stored = this.parseStoredCredential(raw, ref);
+    return { method: 'apikey', apikey: stored.apiKey };
+  }
+
+  hasCredential(ref: CredentialRef): boolean {
+    return this.readCredential(ref) !== undefined;
+  }
+
+  deleteCredential(ref: CredentialRef): boolean {
+    try {
+      return this.createEntry(ref).deleteCredential();
+    } catch (error) {
+      if (this.isMissingCredentialError(error)) {
+        return false;
+      }
+      throw this.wrapStoreError('delete', ref, error);
+    }
+  }
+
+  getAccountName(ref: CredentialRef): string {
+    return `instance:${ref.baseUrl}|credential:${ref.credential}`;
+  }
+
+  private writeCredential(ref: CredentialRef, credential: StoredCredential) {
+    try {
+      this.createEntry(ref).setPassword(JSON.stringify(credential));
+    } catch (error) {
+      throw this.wrapStoreError('save', ref, error);
+    }
+  }
+
+  private readCredential(ref: CredentialRef): string | undefined {
+    try {
+      return this.createEntry(ref).getPassword() ?? undefined;
+    } catch (error) {
+      if (this.isMissingCredentialError(error)) {
+        return undefined;
+      }
+      throw this.wrapStoreError('read', ref, error);
+    }
+  }
+
+  private createEntry(ref: CredentialRef): Entry {
+    return new Entry(this.serviceName, this.getAccountName(ref));
+  }
+
+  private parseStoredCredential(
+    raw: string,
+    ref: CredentialRef,
+  ): StoredCredential {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw new Error(
+        `Saved Revisium credential "${ref.credential}" for ${ref.baseUrl} is invalid. Run: revisium auth login --url revisium://${ref.baseUrl.replace(/^https?:\/\//, '')} --credential ${ref.credential} --api-key`,
+      );
+    }
+
+    if (
+      typeof parsed !== 'object' ||
+      parsed === null ||
+      !('method' in parsed) ||
+      parsed.method !== 'apikey' ||
+      !('apiKey' in parsed) ||
+      typeof parsed.apiKey !== 'string' ||
+      parsed.apiKey.trim() === ''
+    ) {
+      throw new Error(
+        `Saved Revisium credential "${ref.credential}" for ${ref.baseUrl} has an unsupported format. Run: revisium auth login --url revisium://${ref.baseUrl.replace(/^https?:\/\//, '')} --credential ${ref.credential} --api-key`,
+      );
+    }
+
+    return {
+      method: 'apikey',
+      apiKey: parsed.apiKey.trim(),
+    };
+  }
+
+  private isMissingCredentialError(error: unknown): boolean {
+    if (!(error instanceof Error)) {
+      return false;
+    }
+
+    const keyringError = error as Error & { code?: unknown };
+
+    return (
+      keyringError.code === 'NoEntry' ||
+      error.name === 'NoEntry' ||
+      error.message.includes('NoEntry')
+    );
+  }
+
+  private wrapStoreError(
+    action: 'save' | 'read' | 'delete',
+    ref: CredentialRef,
+    error: unknown,
+  ): Error {
+    const message = error instanceof Error ? error.message : String(error);
+    return new Error(
+      `Could not ${action} Revisium credential "${ref.credential}" for ${ref.baseUrl}: ${message}`,
+    );
+  }
+}

package/src/services/credentials/credential-target.service.ts

@@ -0,0 +1,145 @@
+import { Injectable } from '@nestjs/common';
+import {
+  DEFAULT_CREDENTIAL,
+  WorkspaceAuthMode,
+  WorkspaceConfigService,
+} from 'src/services/workspace';
+
+export interface CredentialTargetOptions {
+  url?: string;
+  instance?: string;
+  credential?: string;
+}
+
+export interface CredentialTarget {
+  baseUrl: string;
+  credential: string;
+  instanceName?: string;
+  contextName?: string;
+  authMode?: WorkspaceAuthMode;
+  configPath?: string;
+}
+
+@Injectable()
+export class CredentialTargetService {
+  constructor(private readonly workspaceConfig: WorkspaceConfigService) {}
+
+  async resolveRequired(
+    options: CredentialTargetOptions,
+  ): Promise<CredentialTarget> {
+    if (!options.url && !options.instance) {
+      throw new Error('Pass --instance <name> or --url <revisium-url>');
+    }
+
+    return this.resolve(options, false);
+  }
+
+  async resolveOrCurrentContext(
+    options: CredentialTargetOptions,
+  ): Promise<CredentialTarget> {
+    return this.resolve(options, true);
+  }
+
+  private async resolve(
+    options: CredentialTargetOptions,
+    allowCurrentContext: boolean,
+  ): Promise<CredentialTarget> {
+    if (options.url && options.instance) {
+      throw new Error('Use only one target selector: --instance or --url');
+    }
+
+    if (options.url) {
+      return this.resolveUrlTarget(options);
+    }
+
+    const loaded = await this.workspaceConfig.load();
+    if (!loaded) {
+      throw new Error(
+        'No Revisium workspace config found. Pass --url <revisium-url> or run revisium instance add first.',
+      );
+    }
+
+    if (options.instance) {
+      const instance = loaded.config.instances[options.instance];
+      if (!instance) {
+        throw new Error(
+          `Revisium instance "${options.instance}" was not found`,
+        );
+      }
+
+      return {
+        baseUrl: instance.baseUrl,
+        credential: options.credential || DEFAULT_CREDENTIAL,
+        instanceName: options.instance,
+        authMode: instance.authMode || 'stored',
+        configPath: loaded.path,
+      };
+    }
+
+    if (!allowCurrentContext) {
+      throw new Error('Pass --instance <name> or --url <revisium-url>');
+    }
+
+    const contextName = loaded.config.currentContext;
+    if (!contextName) {
+      throw new Error(
+        `No current Revisium context is configured in ${loaded.path}. Run: revisium context use <name>`,
+      );
+    }
+
+    const context = loaded.config.contexts[contextName];
+    if (!context) {
+      throw new Error(`Revisium context "${contextName}" was not found`);
+    }
+
+    const instance = loaded.config.instances[context.instance];
+    if (!instance) {
+      throw new Error(
+        `Revisium instance "${context.instance}" for context "${contextName}" was not found`,
+      );
+    }
+
+    return {
+      baseUrl: instance.baseUrl,
+      credential:
+        options.credential || context.credential || DEFAULT_CREDENTIAL,
+      instanceName: context.instance,
+      contextName,
+      authMode: instance.authMode || 'stored',
+      configPath: loaded.path,
+    };
+  }
+
+  private async resolveUrlTarget(
+    options: CredentialTargetOptions,
+  ): Promise<CredentialTarget> {
+    if (!options.url) {
+      throw new Error('Pass --url <revisium-url>');
+    }
+
+    const baseUrl = this.workspaceConfig.normalizeBaseUrl(options.url);
+    const loaded = await this.workspaceConfig.load();
+    if (!loaded) {
+      return {
+        baseUrl,
+        credential: options.credential || DEFAULT_CREDENTIAL,
+      };
+    }
+
+    const instanceName = this.workspaceConfig.findInstanceNameByBaseUrl(
+      loaded.config,
+      baseUrl,
+    );
+    const instance = instanceName
+      ? loaded.config.instances[instanceName]
+      : undefined;
+
+    return {
+      baseUrl,
+      credential: options.credential || DEFAULT_CREDENTIAL,
+      instanceName,
+      authMode: instance?.authMode || 'stored',
+      configPath: loaded.path,
+    };
+  }
+}

package/src/services/credentials/index.ts

@@ -0,0 +1,9 @@
+export {
+  CredentialRef,
+  CredentialStoreService,
+} from './credential-store.service';
+export {
+  CredentialTarget,
+  CredentialTargetOptions,
+  CredentialTargetService,
+} from './credential-target.service';

package/src/services/index.ts

@@ -2,3 +2,6 @@ export * from './connection';
 export * from './url';
 export * from './sync';
 export * from './common';
+export * from './workspace';
+export * from './credentials';
+export * from './bootstrap';

package/src/services/url/__tests__/url-builder.service.spec.ts

@@ -508,6 +508,23 @@ describe('UrlBuilderService', () => {
       );
     });
 
+    it('formats URL with no auth', () => {
+      const url = {
+        baseUrl: 'http://localhost:9222',
+        auth: {
+          method: 'none' as const,
+        },
+        organization: 'admin',
+        project: 'dictionary',
+        branch: 'master',
+        revision: 'draft',
+      };
+
+      expect(service.formatAsRevisiumUrl(url)).toBe(
+        'revisium://localhost:9222/admin/dictionary/master',
+      );
+    });
+
     it('formats URL with revision', () => {
       const url = {
         baseUrl: 'https://cloud.revisium.io',