@skyramp/skyramp 1.3.8 → 1.3.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyramp/skyramp",
-  "version": "1.3.8",
+  "version": "1.3.10",
   "description": "module for leveraging skyramp cli functionality",
   "scripts": {
     "lint": "eslint 'src/**/*.js' 'src/**/*.ts' --fix",
@@ -24,7 +24,8 @@
     "@aws-sdk/client-s3": "^3.812.0",
     "fs": "^0.0.1-security",
     "js-yaml": "^4.1.0",
-    "koffi": "2.5.12"
+    "koffi": "2.5.12",
+    "zod": "^3.25.3"
   },
   "devDependencies": {
     "@typescript-eslint/eslint-plugin": "^6.14.0",

package/src/classes/SkyrampClient.d.ts

@@ -126,6 +126,8 @@ interface GenerateRestTestOptions {
   playwrightViewportSize?: string;
   playwrightStoragePath?: string;
   playwrightSaveStoragePath?: string;
+  browser?: string;
+  device?: string;
   loadCount?: string;
   loadDuration?: string;
   loadNumThreads?: string;

package/src/classes/SkyrampClient.js

@@ -15,11 +15,6 @@ const testerInfoType = koffi.struct({
   error: 'char*',
 });
 
-const testerGenerateType = koffi.struct({
-  generated_files: 'char*',
-  error: 'char*',
-});
-
 const contractResponseType = koffi.struct({
   response: 'char*',
   error: 'char*',
@@ -55,9 +50,8 @@ const applyMockObjectWrapper = lib.func('applyMockObjectWrapper', 'string', ['st
 const initTargetWrapper = lib.func('initTargetWrapper', 'string', ['string']);
 const deployTargetWrapper = lib.func('deployTargetWrapper', 'string', ['string', 'string', 'string', 'string', 'string', 'string', 'bool']);
 const deleteTargetWrapper = lib.func('deleteTargetWrapper', 'string', ['string', 'string', 'string', 'string', 'string']);
-const runTesterGenerateRestWrapper = lib.func('runTesterGenerateRestWrapper', testerGenerateType, ['string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'int', 'bool', 'bool', 'bool']);
 
-const generateRestTestWrapper = lib.func('generateRestTestWrapper', 'string', ['string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'bool', 'bool', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'bool', 'string', 'bool', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'bool', 'string', 'string']);
+const generateRestTestWrapper = lib.func('generateRestTestWrapper', 'string', ['string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'bool', 'bool', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'bool', 'string', 'bool', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'bool', 'string', 'string']);
 const generateRestMockWrapper = lib.func('generateRestMockWrapper', 'string', ['string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'bool', 'bool', 'string', 'string', 'string', 'string', 'string', 'string']);
 const traceCollectWrapper = lib.func('traceCollectWrapper', 'string', ['string', 'string', 'bool', 'string', 'string']);
 const analyzeOpenapiWrapper = lib.func('analyzeOpenapiWrapper', 'string', ['string', 'string']);
@@ -104,8 +98,6 @@ class SkyrampClient {
     this.local_image = false;
     this.timestamp = Date.now();
 
-    checkForUpdate("npm")
-
     if (typeof kubeconfigPathOrOptions === 'object') {
       const options = kubeconfigPathOrOptions;
       this.workerNamespaces = [];
@@ -666,41 +658,6 @@ class SkyrampClient {
     return mockDescription;
   }
 
-  /**
-   * Generates test scenarios based on the provided parameters.
-   *
-   * @param {Protocol} protocol - The protocol to be used.
-   * @param {string} apiSchemaPath - The path to the API schema.
-   * @param {string} alias - The alias for the generated tests.
-   * @param {string} endpointPath - Endpoint REST path to filter for.
-   * @param {Language} language - The programming language for the generated tests.
-   * @param {string} tag - Tag to filter OpenAPI endpoint paths for.
-   * @param {string} sampleRequestPath - The path to the sample request.
-   * @param {int} port - The port number.
-   * @param {boolean} generateRobot - Whether to generate robot tests.
-   * @param {boolean} functionalScenario - Whether to generate functional scenarios.
-   * @param {boolean} negativeScenario - Whether to generate negative scenarios.
-   * @returns {Promise<string[]>} A promise that resolves with a list of generated test file paths.
-   */
-  async testerGenerate(protocol, apiSchemaPath, alias, endpointPath, language, tag, sampleRequestPath, port, generateRobot, functionalScenario, negativeScenario) {
-    return new Promise((resolve, reject) => {
-      runTesterGenerateRestWrapper.async(protocol, apiSchemaPath, alias, endpointPath, language, tag, sampleRequestPath, this.projectPath, port, generateRobot, functionalScenario, negativeScenario, (err, res) => {
-        if (err) {
-          console.error(`Error generating tests: ${err.name} - ${err.message}`);
-          reject(err);
-        } else if (res.error) {
-          console.error(`Error generating tests: ${res.error}`);
-          reject(new Error(res.error));
-        } else {
-          console.log(`Test generation completed successfully. Generated files: ${res.generated_files}`);
-
-          const generatedTestNames = res.generated_files.split(',');
-          resolve(generatedTestNames);
-        }
-      });
-    });
-  }
-
   /**
    * Sends a request to a Skyramp worker using the V2 API
    * @param {Object} options - The options for sending the request
@@ -868,6 +825,8 @@ class SkyrampClient {
         options.playwrightViewportSize || "",
         options.playwrightStoragePath || "",
         options.playwrightSaveStoragePath || "",
+        options.browser || "",
+        options.device || "",
         options.loadCount || "0",
         options.loadDuration || "0",
         options.loadNumThreads || "0",
@@ -1054,6 +1013,7 @@ class SkyrampClient {
    * @returns {Promise<string>} A promise that resolves with the initialization output message.
    */
   async initAgent(options) {
+    await checkForUpdate("npm");
     return new Promise((resolve, reject) => {
       initAgentWrapper.async(
         options.version || "",

package/src/classes/SmartPlaywright.js

@@ -290,13 +290,30 @@ class SkyrampPlaywrightLocator {
         });
     }
 
-    async execute() {
+    /**
+     * execute locator's actions
+     *
+     * @param {bool} reducedTimeout - it forces 3sec timeout when set to true
+     */
+    async execute(reducedTimeout) {
         debug(`    execute ${ this._locator}.${this.execFname} ${this.execParam ?? ''} ${this.execArgs ?? ''}`)
+        var newArgs = this.execArgs
+        if (reducedTimeout !== undefined && reducedTimeout) {
+            if (this.execArgs !== null && this.execArgs !== undefined) {
+                // we can safetly assume option is the first element in the execArgs
+                newArgs = [ { ...this.execArgs[0], timeout: 3000}, ...this.execArgs.slice(1)];
+                debug('    reduce timeout', this.execArgs, newArgs)
+            } else {
+                newArgs = [{ timeout: 3000 }];
+                debug('    reduce timeout', newArgs)
+            }
+        }
+
         const func = this._locator[this.execFname];
         if (this.execParam !== null && this.execParam !== undefined) {
-            return func.call(this._locator, this.execParam, ...this.execArgs);
+            return func.call(this._locator, this.execParam, ...newArgs);
         } else {
-            return func.call(this._locator, ...this.execArgs);
+            return func.call(this._locator, ...newArgs);
         }
     }
 
@@ -339,7 +356,7 @@ class SkyrampPlaywrightLocator {
 
     newPrevHydrationErrorMsg() {
         return `Cannot find locator ${this._locator} and likely a hydration issue on ${this._previousLocator._locator}.\n` +
-               `Please add enough waitForTimeout() on ${this._previoousLocator._locator}`;
+               `Please add enough waitForTimeout() on ${this._previousLocator._locator}`;
     }
 
     newMultiLocatorErrorMsg() {
@@ -392,16 +409,16 @@ class SkyrampPlaywrightLocator {
                     await this.wait(defaultWaitForTimeout);
 
                     // Is this really necessary?
-                    await this.execute().then(result => {
+                    await this.execute(true).then(result => {
                         return this._skyrampPage.checkNavigation(currentUrl, result);
                     }).catch(() => {
                         debug(`  failed second time and execute previous locator ${this._previousLocator._locator} again`);
-                        this._previousLocator.execute();
+                        this._previousLocator.execute(true);
                     }).catch(() => {
                         debug(`  failed to execute previous locator ${this._previousLocator._locator} again, continue`);
                     });
 
-                    return this.execute().catch(newError => {
+                    return this.execute(true).catch(newError => {
                         debug(`  third attempt on ${this._locator} failed ${newError.name}`);
                         if (newError.name == "TimeoutError") {
                             // this hadn't happened yet. we need to validate if this is indeed hydration case
@@ -455,7 +472,7 @@ class SkyrampPlaywrightLocator {
                 const previousCount = await this._previousLocator.count();
                 debug(`  re-execute the previous one ${this._previousLocator._locator}, new locator count = ${previousCount}, ${currentUrl}`);
                 // re-execute the previous locator
-                await this._previousLocator.execute().catch(() => {
+                await this._previousLocator.execute(true).catch(() => {
                     // log the failure but continues to the current one
                     debug(`  failed to execute previous locator ${this._previousLocator._locator} again, continue`);
                 });
@@ -470,7 +487,7 @@ class SkyrampPlaywrightLocator {
                         debug(`  ${this._locator} failed at first try. attempting again with some timeout`);
                         // wait for some time and re execute
                         await this.wait(defaultWaitForTimeout);
-                        return this.execute().then(result => {
+                        return this.execute(true).then(result => {
                             return this._skyrampPage.checkNavigation(currentUrl, result);
                         }).catch(newError => {
                             return this._retryWithLLM(newError, this.newPrevHydrationErrorMsg());
@@ -504,7 +521,7 @@ class SkyrampPlaywrightLocator {
                     if (error.name == "TimeoutError") {
                         debug(`${this._locator} failed at first try. attempting again with some timeout`);
                         await this.wait(defaultWaitForTimeout);
-                        return this.execute().then(result=> {
+                        return this.execute(true).then(result=> {
                             return this._skyrampPage.checkNavigation(currentUrl, result);
                         }).catch(newError => {
                             if (newError.name == "TimeoutError") {
@@ -717,7 +734,9 @@ class SkyrampPlaywrightLocator {
 
 class SkyrampPlaywrightPage {
     constructor(page, testInfo) {
-        checkForUpdate("npm")
+        checkForUpdate("npm").catch((error) => {
+            console.error('checkForUpdate("npm") failed:', error);
+        });
 
         this._page = page;
         this._testInfo = testInfo; // Store testInfo for screenshot auto-baseline
@@ -822,6 +841,17 @@ class SkyrampPlaywrightPage {
         return this.newSkyrampPlaywrightLocator(originalLocator, alt, options);
     }
 
+    async waitForResponse(arg, options) {
+        // we increase timeout for waitForResponse to 30 sec
+        // so that in case smart selector is required
+        var newOptions = { timeout: 60000 }
+        if (options !== null && options !== undefined) {
+            newOptions = { ...options, timeout: 60000 }
+        }
+        debug(` waitforresponse`, newOptions)
+        return this._page.waitForResponse(arg, newOptions)
+    }
+
     async goto(url, options) {
         const transformedUrl = transformUrlForDocker(url);
         const result = await this._page.goto(transformedUrl, options);

package/src/index.d.ts

@@ -19,3 +19,4 @@ export * from "./classes/AsyncTestStatus";
 export * from "./utils";
 export * from "./function";
 export * from "./classes/SmartPlaywright";
+export * from "./workspace";

package/src/index.js

@@ -20,6 +20,15 @@ const MockV2 = require('./classes/MockV2');
 const { getValue, getResponseValue, checkSchema, iterate, pushToolEvent } = require('./utils');
 const { checkStatusCode } = require('./function');
 const { newSkyrampPlaywrightPage, expect } = require('./classes/SmartPlaywright');
+const {
+  workspaceConfigSchema,
+  serviceSchema,
+  WorkspaceConfigManager,
+  validateWorkspaceConfig,
+  createDefaultConfig,
+  WORKSPACE_DIR,
+  WORKSPACE_FILENAME,
+} = require('./workspace');
 
 module.exports = {
   SkyrampClient,
@@ -50,4 +59,11 @@ module.exports = {
   pushToolEvent,
   newSkyrampPlaywrightPage,
   expect,
+  workspaceConfigSchema,
+  serviceSchema,
+  WorkspaceConfigManager,
+  validateWorkspaceConfig,
+  createDefaultConfig,
+  WORKSPACE_FILENAME,
+  WORKSPACE_DIR,
 }

package/src/utils.d.ts

@@ -93,12 +93,12 @@ export function iterate(jsonInput: object): object;
  * @param {string} error - error message if it failed
  * @param {Object} params - any parameters associated with the tool call. Disctionary
  */
-export function pushToolEvent(entryPoint: string, toolName: string, err: string, params: object): void;
+export function pushToolEvent(entryPoint: string, toolName: string, err: string, params: object): Promise<void>;
 
 /**
  * check for update
  */
-export function checkForUpdate(component: string): void;
+export function checkForUpdate(component: string): Promise<void>;
 
 /**
  * The Skyramp YAML version constant.

package/src/utils.js

@@ -234,16 +234,27 @@ function iterate(fuzz_body) {
 function pushToolEvent(entryPoint, toolName, err, params) {
     const paramsStr = JSON.stringify(params);
 
-    pushToolEventWrapper(entryPoint, toolName, err, paramsStr);
+    return new Promise((resolve, reject) => {
+        pushToolEventWrapper.async(entryPoint, toolName, err, paramsStr, (err) => {
+            if (err) reject(err);
+            else resolve();
+        });
+    });
 }
 
 /**
  * check if new library is available
  *
- * @param {string} component - NAme of component
+ * @param {string} component - Name of component
+ * @returns {Promise<void>}
  */
 function checkForUpdate(component) {
-    checkForUpdateWrapper(component)
+    return new Promise((resolve, reject) => {
+        checkForUpdateWrapper.async(component, (err) => {
+            if (err) reject(err);
+            else resolve();
+        });
+    });
 }
 
 module.exports = {

package/src/workspace.d.ts

@@ -0,0 +1,119 @@
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Types (defined to match Zod schemas)
+// ---------------------------------------------------------------------------
+
+// Note: These types match the runtime Zod schemas in workspace.js
+// Changes to schemas should be reflected here
+
+export interface ServiceApi {
+  schemaPath?: string;
+  authType?: "bearer" | "basic" | "oauth" | "apiKey" | "none";
+  authHeader?: string;
+  baseUrl?: string;
+}
+
+export interface ServiceRuntimeDetails {
+  serverStartCommand: string;
+  runtime: "local" | "docker" | "k8s";
+  dockerNetwork?: string;
+  k8sNamespace?: string;
+  k8sContext?: string;
+}
+
+export interface Service {
+  serviceName: string;
+  language?: "python" | "typescript" | "javascript" | "java";
+  framework?: "playwright" | "pytest" | "robot" | "junit";
+  outputDir: string;
+  api?: ServiceApi;
+  runtimeDetails?: ServiceRuntimeDetails;
+}
+
+export interface WorkspaceSection {
+  repoName?: string;
+  repoUrl?: string;
+}
+
+export interface MetadataSection {
+  schemaVersion: string;
+  mcpVersion: string;
+  executorVersion: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface WorkspaceConfig {
+  workspace?: WorkspaceSection;
+  metadata?: MetadataSection;
+  services?: Service[];
+}
+
+// ---------------------------------------------------------------------------
+// Zod schemas
+// ---------------------------------------------------------------------------
+
+export const serviceSchema: z.ZodType<Service>;
+export const workspaceConfigSchema: z.ZodType<WorkspaceConfig>;
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+export function validateWorkspaceConfig(
+  config: unknown,
+): z.SafeParseReturnType<WorkspaceConfig, WorkspaceConfig>;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+export function createDefaultConfig(): WorkspaceConfig;
+
+// ---------------------------------------------------------------------------
+// WorkspaceConfigManager
+// ---------------------------------------------------------------------------
+
+export class WorkspaceConfigManager {
+  constructor(workspacePath: string);
+
+  /** Check if workspace config file exists */
+  exists(): Promise<boolean>;
+
+  /** Get the absolute path to the config file */
+  getConfigPath(): string;
+
+  /** Get the workspace root path */
+  getWorkspacePath(): string;
+
+  /** Read and parse workspace config */
+  read(): Promise<WorkspaceConfig>;
+
+  /**
+   * Initialize workspace — creates .skyramp/workspace.yml with repo info.
+   * Auto-detects repoName and repoUrl from git when not provided.
+   */
+  initialize(workspaceInfo?: WorkspaceSection): Promise<WorkspaceConfig>;
+
+  /**
+   * Update the metadata section of an existing workspace config.
+   * Only the provided fields are merged; metadata.updatedAt is refreshed
+   * automatically.
+   */
+  updateMetadata(metadata: Partial<MetadataSection>): Promise<WorkspaceConfig>;
+
+  /**
+   * Add a single service entry to the services array.
+   * If a service with the same serviceName already exists it is replaced
+   * (upsert semantics), otherwise the new entry is appended.
+   */
+  addService(service: Service): Promise<WorkspaceConfig>;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+export const WORKSPACE_DIR: string;
+export const WORKSPACE_FILENAME: string;

package/src/workspace.js

@@ -0,0 +1,448 @@
+const fs = require('fs').promises;
+const path = require('path');
+const yaml = require('js-yaml');
+const { execFile } = require('child_process');
+const { promisify } = require('util');
+
+const execFileAsync = promisify(execFile);
+const { z } = require('zod');
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const WORKSPACE_DIR = '.skyramp';
+const WORKSPACE_FILENAME = 'workspace.yml';
+
+// ---------------------------------------------------------------------------
+// Zod schemas
+// ---------------------------------------------------------------------------
+
+const serviceSchema = z.object({
+  serviceName: z.string(),
+  language: z
+    .enum(['python', 'typescript', 'javascript', 'java'])
+    .optional(),
+  framework: z
+    .enum(['playwright', 'pytest', 'robot', 'junit'])
+    .optional(),
+  outputDir: z.string().optional(),
+  api: z
+    .object({
+      schemaPath: z.string().optional(),
+      authType: z
+        .enum(['bearer', 'basic', 'oauth', 'apiKey', 'none'])
+        .optional(),
+      authHeader: z.string().optional(),
+      baseUrl: z.string().optional(),
+    })
+    .strict()
+    .optional(),
+  runtimeDetails: z
+    .object({
+      serverStartCommand: z.string(),
+      runtime: z.enum(['local', 'docker', 'k8s']),
+      dockerNetwork: z.string().optional(),
+      k8sNamespace: z.string().optional(),
+      k8sContext: z.string().optional(),
+    })
+    .strict()
+    .optional(),
+}).strict();
+
+const workspaceConfigSchema = z.object({
+  workspace: z
+    .object({
+      repoName: z.string().optional(),
+      repoUrl: z.string().optional(),
+    })
+    .strict()
+    .optional(),
+  metadata: z
+    .object({
+      schemaVersion: z.string(),
+      mcpVersion: z.string(),
+      executorVersion: z.string(),
+      createdAt: z.string(),
+      updatedAt: z.string(),
+    })
+    .strict()
+    .optional(),
+  services: z.array(serviceSchema).optional(),
+}).strict();
+
+// ---------------------------------------------------------------------------
+// Validation helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Throws a formatted Error from a failed Zod safe-parse result.
+ *
+ * @param {string} label - Human-readable context (e.g. "Workspace validation").
+ * @param {import('zod').SafeParseError} zodError - The `.error` from safeParse.
+ */
+function throwValidationError(label, zodError) {
+  const messages = zodError.issues.map((i) => {
+    const pathLabel =
+      Array.isArray(i.path) && i.path.length > 0 ? i.path.join('.') : '<root>';
+    return `${pathLabel}: ${i.message}`;
+  });
+  throw new Error(`${label} failed:\n  - ${messages.join('\n  - ')}`);
+}
+
+/**
+ * Validates a workspace configuration object against the Zod schema.
+ *
+ * @param {unknown} config - The configuration to validate.
+ * @returns {import('zod').SafeParseReturnType} Zod safe-parse result.
+ */
+function validateWorkspaceConfig(config) {
+  return workspaceConfigSchema.safeParse(config);
+}
+
+/**
+ * Validates and returns the parsed data, or throws on failure.
+ *
+ * @param {unknown} config - The configuration to validate.
+ * @param {string} [label='Workspace validation'] - Error label.
+ * @returns {Object} The validated config data.
+ */
+function validateOrThrow(config, label = 'Workspace validation') {
+  const result = validateWorkspaceConfig(config);
+  if (!result.success) {
+    throwValidationError(label, result.error);
+  }
+  return result.data;
+}
+
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a default workspace config with empty sections and timestamps.
+ *
+ * @returns {Object} Default workspace config.
+ */
+function createDefaultConfig() {
+  const now = new Date().toISOString();
+  return {
+    workspace: {},
+    metadata: {
+      schemaVersion: 'v1',
+      mcpVersion: '',
+      executorVersion: '',
+      createdAt: now,
+      updatedAt: now,
+    },
+    services: [],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Low-level I/O helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Writes a workspace config to disk as YAML.
+ *
+ * @param {string} filePath - Absolute path to write to.
+ * @param {Object} config - The workspace config object.
+ * @returns {Promise<void>}
+ */
+async function writeWorkspaceFile(filePath, config) {
+  const header = '# Skyramp Workspace Configuration\n';
+  const body = yaml.dump(config, {
+    lineWidth: 120,
+    noRefs: true,
+    quotingType: '"',
+    forceQuotes: false,
+  });
+
+  try {
+    await fs.writeFile(filePath, header + body, 'utf8');
+  } catch (err) {
+    throw new Error(
+      `Failed to write workspace file to ${filePath}: ${err.message}`
+    );
+  }
+}
+
+/**
+ * Auto-detects repo name and URL from git.
+ * Throws an error if the directory is not a git repository.
+ *
+ * @param {string} [dirPath=process.cwd()]
+ * @param {boolean} [requireGit=true] - If true, throws error when not a git repo
+ * @returns {Promise<{ repoName: string|null, repoUrl: string|null }>}
+ */
+async function detectRepoInfo(dirPath, requireGit = true) {
+  const cwd = dirPath ? path.resolve(dirPath) : process.cwd();
+  let repoUrl = null;
+  let repoName = null;
+  let isGitRepo = false;
+
+  // First, check if this is a git repository
+  try {
+    await execFileAsync('git', ['rev-parse', '--git-dir'], {
+      cwd,
+      timeout: 5000,
+    });
+    isGitRepo = true;
+  } catch (err) {
+    if (requireGit) {
+      throw new Error(
+        `Workspace initialization requires a git repository. Directory '${cwd}' is not a git repository. ` +
+        `We cannot initialize the workspace in a non-git repository.`
+      );
+    }
+  }
+
+  // If it's a git repo, try to get the remote URL
+  if (isGitRepo) {
+    try {
+      const { stdout } = await execFileAsync('git', ['remote', 'get-url', 'origin'], {
+        cwd,
+        timeout: 5000,
+      });
+      repoUrl = stdout.trim();
+    } catch {
+      // Git repo exists but no remote configured - this is OK
+    }
+
+    if (repoUrl) {
+      const match = repoUrl.match(/[:/]([^/]+\/[^/]+?)(?:\.git)?$/);
+      if (match) repoName = match[1];
+    }
+
+    if (!repoName) {
+      repoName = path.basename(cwd);
+    }
+  }
+
+  return { repoName, repoUrl };
+}
+
+// ---------------------------------------------------------------------------
+// Low-level state management (standalone, path-based API)
+// ---------------------------------------------------------------------------
+
+/**
+ * Loads and validates a workspace YAML file from disk.
+ *
+ * @param {string} filePath - Absolute path to the workspace file.
+ * @returns {Promise<{ config: Object, filePath: string }>}
+ */
+async function loadWorkspaceFile(filePath) {
+  const resolvedPath = path.resolve(filePath);
+
+  try {
+    await fs.access(resolvedPath);
+  } catch {
+    throw new Error(`Workspace file not found: ${resolvedPath}`);
+  }
+
+  const content = await fs.readFile(resolvedPath, 'utf8');
+  let rawConfig;
+  try {
+    // Use JSON_SCHEMA to prevent timestamp auto-conversion to Date objects
+    rawConfig = yaml.load(content, { schema: yaml.JSON_SCHEMA });
+  } catch (err) {
+    throw new Error(`Failed to parse workspace YAML: ${err.message}`);
+  }
+
+  const validated = validateOrThrow(rawConfig);
+  return { config: validated, filePath: resolvedPath };
+}
+
+// ---------------------------------------------------------------------------
+// WorkspaceConfigManager
+// ---------------------------------------------------------------------------
+
+/**
+ * High-level manager for .skyramp/workspace.yml.
+ *
+ * Provides three focused mutation methods:
+ *   1. initialize()    — create workspace file with repo info
+ *   2. updateMetadata() — update metadata section
+ *   3. addService()     — upsert a single service entry
+ *
+ * @param {string} workspacePath - Repository / project root.
+ */
+class WorkspaceConfigManager {
+  constructor(workspacePath) {
+    this.workspacePath = path.resolve(workspacePath);
+    this.skyrampDir = path.join(this.workspacePath, WORKSPACE_DIR);
+    this.configPath = path.join(this.skyrampDir, WORKSPACE_FILENAME);
+  }
+
+  /** Check if workspace config file exists */
+  async exists() {
+    try {
+      await fs.access(this.configPath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /** Get the absolute path to the config file */
+  getConfigPath() {
+    return this.configPath;
+  }
+
+  /** Get the workspace root path */
+  getWorkspacePath() {
+    return this.workspacePath;
+  }
+
+  /**
+   * Read and parse workspace config from disk.
+   *
+   * @returns {Promise<Object>} The validated WorkspaceConfig.
+   */
+  async read() {
+    if (!(await this.exists())) {
+      throw new Error(
+        `Workspace config not found at ${this.configPath}. Initialize the workspace first.`,
+      );
+    }
+    const result = await loadWorkspaceFile(this.configPath);
+    return result.config;
+  }
+
+  // -----------------------------------------------------------------------
+  // 1. Initialize workspace with repo info
+  // -----------------------------------------------------------------------
+
+  /**
+   * Initialize workspace — creates .skyramp/workspace.yml with repo info.
+   * Auto-detects repoName and repoUrl from git when not provided.
+   * Produces an empty services array and default metadata timestamps.
+   *
+   * @param {Object} [workspaceInfo] - Optional explicit repo info.
+   * @param {string} [workspaceInfo.repoName] - Repository name.
+   * @param {string} [workspaceInfo.repoUrl]  - Repository URL.
+   * @returns {Promise<Object>} The validated WorkspaceConfig.
+   */
+  async initialize(workspaceInfo = {}) {
+    await fs.mkdir(this.skyrampDir, { recursive: true });
+
+    // Auto-detect repo info from workspace root when not explicitly provided
+    const detected = await detectRepoInfo(this.workspacePath);
+
+    const config = createDefaultConfig();
+    config.workspace = {
+      repoName: workspaceInfo.repoName || detected.repoName || undefined,
+      repoUrl: workspaceInfo.repoUrl || detected.repoUrl || undefined,
+    };
+
+    const validated = validateOrThrow(config);
+    await writeWorkspaceFile(this.configPath, validated);
+    return validated;
+  }
+
+  // -----------------------------------------------------------------------
+  // 2. Update metadata
+  // -----------------------------------------------------------------------
+
+  /**
+   * Update the metadata section of an existing workspace config.
+   * Only the provided fields are merged; others are left untouched.
+   * metadata.updatedAt is refreshed automatically.
+   *
+   * @param {Object} metadata - Partial metadata fields to merge.
+   * @param {string} [metadata.schemaVersion]
+   * @param {string} [metadata.mcpVersion]
+   * @param {string} [metadata.executorVersion]
+   * @returns {Promise<Object>} The updated, validated WorkspaceConfig.
+   */
+  async updateMetadata(metadata) {
+    if (!metadata || typeof metadata !== 'object') {
+      throw new Error('metadata must be a non-null object');
+    }
+
+    const config = await this.read();
+    const existingMetadata = config.metadata || createDefaultConfig().metadata;
+
+    config.metadata = {
+      ...existingMetadata,
+      ...metadata,
+      createdAt: existingMetadata.createdAt, // Preserve original createdAt
+      updatedAt: new Date().toISOString(),
+    };
+
+    const validated = validateOrThrow(config);
+    await writeWorkspaceFile(this.configPath, validated);
+    return validated;
+  }
+
+  // -----------------------------------------------------------------------
+  // 3. Add / upsert a single service
+  // -----------------------------------------------------------------------
+
+  /**
+   * Add a single service entry to the services array.
+   * If a service with the same serviceName already exists it is replaced
+   * (upsert semantics), otherwise the new entry is appended.
+   * metadata.updatedAt is refreshed automatically.
+   *
+   * @param {Object} service - A service object matching the serviceSchema.
+   * @param {string} service.serviceName - Unique service identifier (required).
+   * @returns {Promise<Object>} The updated, validated WorkspaceConfig.
+   */
+  async addService(service) {
+    if (!service || typeof service !== 'object') {
+      throw new Error('service must be a non-null object');
+    }
+
+    // Validate the individual service entry first
+    const svcResult = serviceSchema.safeParse(service);
+    if (!svcResult.success) {
+      throwValidationError('Service validation', svcResult.error);
+    }
+
+    const config = await this.read();
+    const services = config.services || [];
+
+    // Upsert: replace existing entry with same serviceName, or append
+    const idx = services.findIndex(
+      (s) => s.serviceName === svcResult.data.serviceName,
+    );
+    if (idx >= 0) {
+      services[idx] = svcResult.data;
+    } else {
+      services.push(svcResult.data);
+    }
+    config.services = services;
+
+    // Refresh timestamp
+    if (!config.metadata) {
+      config.metadata = createDefaultConfig().metadata;
+    }
+    config.metadata.updatedAt = new Date().toISOString();
+
+    const validated = validateOrThrow(config);
+    await writeWorkspaceFile(this.configPath, validated);
+    return validated;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  // Schema
+  workspaceConfigSchema,
+  serviceSchema,
+  // High-level manager
+  WorkspaceConfigManager,
+  // Validation
+  validateWorkspaceConfig,
+  // Helpers
+  createDefaultConfig,
+  // Constants
+  WORKSPACE_DIR,
+  WORKSPACE_FILENAME,
+};