feat(run): add debug mode to execute use cases on non-workspaces (#3)

Author: MarcScheib

README.md

@@ -91,9 +91,10 @@ the top-level workspace directory.
 
 The following options are available:
 
-| Option                      | Description         |
-| --------------------------- | ------------------- |
-| `-u, --use-case [use-case]` | the use case to run |
+| Option                      | Description                                                                                         |
+| --------------------------- | --------------------------------------------------------------------------------------------------- |
+| `-u, --use-case [use-case]` | the use case to run                                                                                 |
+| `--debug`                   | enable debug mode; allows to run use cases from any location, assuming the config structure matches |
 
 For example, to run the `check-requirements` use case, execute:
 
@@ -395,3 +396,13 @@ After testing, the symlink can be removed via:
 ```bash
 npm uninstall ws-ctrl -g
 ```
+
+### Use cases
+
+It is possible to test use cases directly in the workspace. To do so, the use case
+should be placed in the `assets/templates/config/use-cases` directory.
+The use case can then be executed via:
+
+```bash
+npm run dev -- run ./assets/templates -u <use-case-name> --debug
+```

dist/index.js

@@ -65,9 +65,9 @@ export async function init(
   const config = initConfig(workspacePath, organization, templatesRepository);
 
   // copy templates from package/repo to workspace
-  const templatesAccess = TemplatesAccess.create(config);
+  const templatesAccess = TemplatesAccess.create(config.store);
   await templatesAccess.initWorkspace();
 
-  const useCaseRunner = UseCaseRunner.create(config, templatesAccess);
+  const useCaseRunner = UseCaseRunner.create(templatesAccess);
   await useCaseRunner.run('init');
 }

src/commands/init/action.ts

@@ -10,18 +10,20 @@ const useCaseOption = new Option(
   '-u, --use-case [use-case]',
   'execute the use case with the given name'
 );
+const debugOption = new Option('--debug', 'enable debug mode');
 
 interface RunActionOptions {
   useCase: OptionInput;
+  debug: boolean;
 }
 
 export async function runAction(
   workspacePathRaw: string,
   options: RunActionOptions
 ) {
-  const config = await loadWorkspaceConfig(workspacePathRaw);
+  const config = await loadWorkspaceConfig(workspacePathRaw, options.debug);
   const templatesAccess = TemplatesAccess.create(config);
-  const useCaseRunner = UseCaseRunner.create(config, templatesAccess);
+  const useCaseRunner = UseCaseRunner.create(templatesAccess);
   const useCaseRepository = UseCasesRepository.create(templatesAccess);
 
   const useCases = await useCaseRepository.loadUseCases('INITIAL');
@@ -43,4 +45,5 @@ export const run = new Command()
   .description('run a use case in the workspace')
   .addArgument(defaultWorkspacePathArgument)
   .addOption(useCaseOption)
+  .addOption(debugOption)
   .action(runAction);

src/commands/run/run.ts

@@ -8,7 +8,7 @@ async function syncAction(workspacePathRaw: string): Promise<void> {
   const templatesAccess = TemplatesAccess.create(config);
   await templatesAccess.syncTemplates();
 
-  const useCaseRunner = UseCaseRunner.create(config, templatesAccess);
+  const useCaseRunner = UseCaseRunner.create(templatesAccess);
   await useCaseRunner.run('sync');
 }
 

src/commands/sync/sync.ts

@@ -2,10 +2,11 @@ import Conf from 'conf';
 import {
   getWorkspacePathIdentifier,
   isExistingWorkspace,
+  logger,
   resolveWorkspacePath,
 } from './utils/index.js';
 
-interface Config {
+export interface Config {
   workspacePath: string;
   organization: string;
   templatesRepository: string | null;
@@ -27,6 +28,23 @@ const schema = {
 
 export let config: WorkspaceConfig;
 
+function loadConfig(workspacePath: string): WorkspaceConfig {
+  config = new Conf<Config>({
+    schema,
+    cwd: resolveWorkspacePath(workspacePath),
+    configName: getWorkspacePathIdentifier(workspacePath),
+  });
+  return config;
+}
+
+function loadBlankConfig(workspacePath: string): Config {
+  return {
+    workspacePath: resolveWorkspacePath(workspacePath),
+    organization: 'none',
+    templatesRepository: null,
+  };
+}
+
 export function initConfig(
   workspacePath: string,
   organization: string,
@@ -39,20 +57,19 @@ export function initConfig(
   return config;
 }
 
-export function loadConfig(workspacePath: string): WorkspaceConfig {
-  config = new Conf<Config>({
-    schema,
-    cwd: resolveWorkspacePath(workspacePath),
-    configName: getWorkspacePathIdentifier(workspacePath),
-  });
-  return config;
-}
-
-export async function loadWorkspaceConfig(workspacePathRaw: string) {
+export async function loadWorkspaceConfig(
+  workspacePathRaw: string,
+  debug: boolean = false
+): Promise<Config> {
   const workspacePath = workspacePathRaw.trim();
+  if (debug) {
+    logger.log('Running within non-workspace directory...');
+    return loadBlankConfig(workspacePath);
+  }
+
   const existingWorkspace = await isExistingWorkspace(workspacePath);
   if (!existingWorkspace) {
     throw new Error(`The given path is no valid workspace.`);
   }
-  return loadConfig(workspacePath);
+  return loadConfig(workspacePath).store;
 }

src/config.ts

@@ -1,5 +1,5 @@
 import { join } from 'node:path';
-import { WorkspaceConfig } from '../../config.js';
+import { Config } from '../../config.js';
 import { copyDirectory, gitUpdate, logger } from '../../utils/index.js';
 import {
   DIR_CONFIG,
@@ -19,11 +19,11 @@ enum Location {
 }
 
 export class TemplatesAccess {
-  static create(config: WorkspaceConfig): TemplatesAccess {
+  static create(config: Config): TemplatesAccess {
     return new TemplatesAccess(config);
   }
 
-  constructor(private readonly config: WorkspaceConfig) {}
+  constructor(private readonly config: Config) {}
 
   getPackageTemplatesDir(): string {
     return join(this.#getBaseDir(Location.PACKAGE), DIR_TEMPLATES);
@@ -68,19 +68,19 @@ export class TemplatesAccess {
   }
 
   getWorkspacePath(): string {
-    return this.config.get('workspacePath');
+    return this.config.workspacePath;
   }
 
   getTemplatesRepository(): string | null {
-    return this.config.get('templatesRepository');
+    return this.config.templatesRepository;
   }
 
-  createRepositoryUrl(organization: string, name: string): string {
+  createRepositoryUrl(name: string): string {
     // TODO:
     // - add support for HTTPS URLs when provided in config
     // - add support for different repository hosts
     // - add support for different tenants
-    return `git@bitbucket.org:${organization}/${name}.git`;
+    return `git@bitbucket.org:${this.config.organization}/${name}.git`;
   }
 
   async initWorkspace(): Promise<void> {
@@ -102,10 +102,7 @@ export class TemplatesAccess {
     // sync the templates from the repository if configured
     const templatesRepository = this.getTemplatesRepository();
     if (templatesRepository) {
-      const url = this.createRepositoryUrl(
-        this.config.get('organization'),
-        templatesRepository
-      );
+      const url = this.createRepositoryUrl(templatesRepository);
       logger.log(`Syncing templates from repository ${url}...`);
 
       await gitUpdate(url, this.getWorkspacePath(), this.getGitTemplatesDir());

src/services/access/templates-access.ts

@@ -1,17 +1,13 @@
-import { WorkspaceConfig } from '../config.js';
 import { Repository } from '../types/index.js';
 import { loadFilesFromDirectory } from '../utils/index.js';
 import { TemplatesAccess } from './access/index.js';
 
 export class RepositoriesRepository {
-  static create(config: WorkspaceConfig, templatesAccess: TemplatesAccess) {
-    return new RepositoriesRepository(config, templatesAccess);
+  static create(templatesAccess: TemplatesAccess) {
+    return new RepositoriesRepository(templatesAccess);
   }
 
-  constructor(
-    private readonly config: WorkspaceConfig,
-    private readonly templatesAccess: TemplatesAccess
-  ) {}
+  constructor(private readonly templatesAccess: TemplatesAccess) {}
 
   async loadRepositories(): Promise<Required<Repository>[]> {
     return this.loadFiles().then(repositories =>
@@ -31,10 +27,7 @@ export class RepositoriesRepository {
       alias: repository.alias || repository.name,
       url:
         repository.url ||
-        this.templatesAccess.createRepositoryUrl(
-          this.config.get('organization'),
-          repository.name
-        ),
+        this.templatesAccess.createRepositoryUrl(repository.name),
       attributes: {
         type: 'UNKNOWN',
         ...repository.attributes,

src/services/repositories.repository.ts

@@ -1,15 +1,14 @@
-import { WorkspaceConfig } from '../../config.js';
 import { Context } from '../../types/index.js';
 import { TemplatesAccess } from '../access/index.js';
 import { RepositoriesRepository } from '../repositories.repository.js';
 import { ServersRepository } from '../servers.repository.js';
 
 export class ContextCreator {
-  static create(config: WorkspaceConfig, templatesAccess: TemplatesAccess) {
+  static create(templatesAccess: TemplatesAccess) {
     return new ContextCreator(
       templatesAccess,
       ServersRepository.create(templatesAccess),
-      RepositoriesRepository.create(config, templatesAccess)
+      RepositoriesRepository.create(templatesAccess)
     );
   }
 

src/services/use-cases/context-creator.ts

@@ -1,4 +1,3 @@
-import { WorkspaceConfig } from '../../config.js';
 import { Context, UseCase, UseCaseStep } from '../../types/index.js';
 import {
   bold,
@@ -16,14 +15,13 @@ import { executorMapping } from './executors/index.js';
 
 export class UseCaseRunner {
   static create(
-    config: WorkspaceConfig,
     templatesAccess: TemplatesAccess,
     scriptExecutor?: ScriptExecutor
   ): UseCaseRunner {
     return new UseCaseRunner(
       templatesAccess,
       UseCasesRepository.create(templatesAccess),
-      ContextCreator.create(config, templatesAccess),
+      ContextCreator.create(templatesAccess),
       scriptExecutor || ScriptExecutor.create()
     );
   }