#2049: Add initial calm workspace commands

.gitignore

@@ -47,3 +47,5 @@ coverage/
 .github/chatmodes
 .github/agents
 shared/test-output/
+.calm-workspace/
+cli/test_fixtures/getting-started/actual-output/

calm-hub-ui/vitest.setup.ts

@@ -2,11 +2,28 @@ import '@testing-library/jest-dom/vitest';
 import { afterEach } from 'vitest';
 import { cleanup } from '@testing-library/react';
 
+// Node.js 25+ defines a non-functional localStorage on globalThis that
+// shadows jsdom's implementation. Override it with a proper Storage polyfill.
+if (typeof globalThis.localStorage === 'object' && typeof globalThis.localStorage.clear !== 'function') {
+    const storage = new Map<string, string>();
+    Object.defineProperty(globalThis, 'localStorage', {
+        configurable: true,
+        enumerable: true,
+        value: {
+            getItem: (key: string) => storage.get(key) ?? null,
+            setItem: (key: string, value: string) => storage.set(key, String(value)),
+            removeItem: (key: string) => storage.delete(key),
+            clear: () => storage.clear(),
+            get length() { return storage.size; },
+            key: (index: number) => [...storage.keys()][index] ?? null,
+        },
+    });
+}
 // Polyfill ResizeObserver for ReactFlow tests
 global.ResizeObserver = class ResizeObserver {
-    observe() {}
-    unobserve() {}
-    disconnect() {}
+    observe() { }
+    unobserve() { }
+    disconnect() { }
 };
 
 // runs a clean after each test case (e.g. clearing jsdom)

cli/package.json

@@ -45,6 +45,7 @@
         "execa": "^9.6.0",
         "express-rate-limit": "^8.0.0",
         "mkdirp": "^3.0.1",
+        "tree-dump": "^1.1.0",
         "ts-node": "10.9.2"
     },
     "devDependencies": {

cli/src/cli.spec.ts

@@ -1,5 +1,4 @@
 import {
-    CALM_META_SCHEMA_DIRECTORY,
     Docifier,
     DocifyMode,
     TemplateProcessingMode,
@@ -15,6 +14,7 @@ let serverModule: typeof import('./server/cli-server');
 let templateModule: typeof import('./command-helpers/template');
 let optionsModule: typeof import('./command-helpers/generate-options');
 let fileSystemDocLoaderModule: typeof import('@finos/calm-shared/dist/document-loader/file-system-document-loader');
+let documentLoaderModule: typeof import('../../shared/src/document-loader/document-loader');
 let setupCLI: typeof import('./cli').setupCLI;
 let cliConfigModule: typeof import('./cli-config');
 
@@ -31,6 +31,7 @@ describe('CLI Commands', () => {
         templateModule = await import('./command-helpers/template');
         optionsModule = await import('./command-helpers/generate-options');
         fileSystemDocLoaderModule = await import('@finos/calm-shared/dist/document-loader/file-system-document-loader');
+        documentLoaderModule = await import('../../shared/src/document-loader/document-loader');
 
         vi.spyOn(calmShared, 'runGenerate').mockResolvedValue(undefined);
         vi.spyOn(calmShared.TemplateProcessor.prototype, 'processTemplate').mockResolvedValue(undefined);
@@ -47,6 +48,16 @@ describe('CLI Commands', () => {
         vi.spyOn(fileSystemDocLoaderModule, 'FileSystemDocumentLoader').mockImplementation(vi.fn());
         vi.spyOn(fileSystemDocLoaderModule.FileSystemDocumentLoader.prototype, 'loadMissingDocument').mockResolvedValue({});
 
+        // Mock buildDocumentLoader to return a mock DocumentLoader.
+        // The generate command now uses buildDocumentLoader() which creates a
+        // MultiStrategyDocumentLoader internally. We mock it to return a simple
+        // loader whose loadMissingDocument resolves with an empty object.
+        vi.spyOn(documentLoaderModule, 'buildDocumentLoader').mockReturnValue({
+            initialise: vi.fn().mockResolvedValue(undefined),
+            loadMissingDocument: vi.fn().mockResolvedValue({}),
+            resolvePath: vi.fn().mockReturnValue(undefined),
+        });
+
         const cliModule = await import('./cli');
         setupCLI = cliModule.setupCLI;
 
@@ -64,10 +75,16 @@ describe('CLI Commands', () => {
                 '--schema-directory', 'schemas',
             ]);
 
-            expect(fileSystemDocLoaderModule.FileSystemDocumentLoader.prototype.loadMissingDocument).toHaveBeenCalledWith('pattern.json', 'pattern');
-            expect(optionsModule.promptUserForOptions).toHaveBeenCalled();
+            expect(documentLoaderModule.buildDocumentLoader).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    schemaDirectoryPath: 'schemas',
+                    debug: true,
+                })
+            );
 
-            expect(fileSystemDocLoaderModule.FileSystemDocumentLoader).toHaveBeenCalledWith([CALM_META_SCHEMA_DIRECTORY, 'schemas'], true, process.cwd());
+            const mockDocLoader = vi.mocked(documentLoaderModule.buildDocumentLoader).mock.results[0].value;
+            expect(mockDocLoader.loadMissingDocument).toHaveBeenCalledWith('pattern.json', 'pattern');
+            expect(optionsModule.promptUserForOptions).toHaveBeenCalled();
 
             expect(calmShared.runGenerate).toHaveBeenCalledWith(
                 {}, 'output.json', true, expect.any(calmShared.SchemaDirectory), []

cli/src/cli.ts

@@ -3,10 +3,13 @@ import { Option, Command } from 'commander';
 import { version } from '../package.json';
 import { promptUserForOptions } from './command-helpers/generate-options';
 import { CalmChoice } from '@finos/calm-shared/dist/commands/generate/components/options';
-import { buildDocumentLoader, DocumentLoader, DocumentLoaderOptions } from '@finos/calm-shared/dist/document-loader/document-loader';
+import { buildDocumentLoader, DocumentLoader, DocumentLoaderOptions } from '../../shared/src/document-loader/document-loader';
 import { loadCliConfig } from './cli-config';
 import path from 'path';
 import inquirer from 'inquirer';
+import { findWorkspaceBundlePath } from './workspace-resolver';
+import { setupWorkspaceCommands } from './command-helpers/workspace/commands';
+import { loadManifest } from './command-helpers/workspace/bundle';
 
 // Shared options used across multiple commands
 const ARCHITECTURE_OPTION = '-a, --architecture <file>';
@@ -255,6 +258,8 @@ Validation requires:
             await setupAiTools(selectedProvider, options.directory, !!options.verbose);
         });
 
+    // Dev commands
+    setupWorkspaceCommands(program);
 }
 
 interface ParseDocumentLoaderOptions {
@@ -282,6 +287,39 @@ export async function parseDocumentLoaderConfig(
         logger.info('Using CALMHub URL from config file: ' + userConfig.calmHubUrl);
         docLoaderOpts.calmHubUrl = userConfig.calmHubUrl;
     }
+
+    // If a CALM workspace bundle is present in the repository, prefer it for resolving documents
+    try {
+        const workspaceBundle = findWorkspaceBundlePath(process.cwd());
+        if (workspaceBundle) {
+            logger.info('Using workspace bundle for document resolution: ' + workspaceBundle);
+            // Load the bundle manifest and construct a URL->local file map from it
+            try {
+                const manifest = await loadManifest(workspaceBundle);
+                const bundleMap = new Map<string, string>();
+                for (const [id, rel] of Object.entries(manifest)) {
+                    // manifest values are relative to bundlePath
+                    bundleMap.set(id, path.resolve(workspaceBundle, rel));
+                }
+
+                // Merge with any provided urlToLocalMap, allowing bundle entries to override
+                const combined = new Map<string, string>(urlToLocalMap ?? []);
+                for (const [k, v] of bundleMap.entries()) {
+                    combined.set(k, v);
+                }
+
+                docLoaderOpts.urlToLocalMap = combined;
+
+                // Ensure basePath is set so MappedDocumentLoader can resolve relative mappings if needed
+                docLoaderOpts.basePath = docLoaderOpts.basePath ?? workspaceBundle;
+            } catch (err) {
+                logger.debug('Failed to load workspace bundle manifest: ' + (err instanceof Error ? err.message : String(err)));
+            }
+        }
+    } catch (err) {
+        logger.debug('Error while checking for workspace bundle: ' + (err instanceof Error ? err.message : String(err)));
+    }
+
     return docLoaderOpts;
 }