@skyramp/skyramp 1.3.7 → 1.3.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyramp/skyramp",
-  "version": "1.3.7",
+  "version": "1.3.9",
   "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.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,7 +50,6 @@ 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 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']);
@@ -666,41 +660,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

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/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,
+};