feat: add publish/sync/share commands and registry service for sharing and registry operations

docs/usage.md

@@ -905,8 +905,8 @@ validate asyncapi file
 USAGE
   $ asyncapi validate [SPEC-FILE] [-h] [-w] [--log-diagnostics] [--diagnostics-format
     json|stylish|junit|html|text|teamcity|pretty|github-actions|sarif|code-climate|gitlab|markdown] [--fail-severity
-    error|warn|info|hint] [-s <value>] [--score] [--suppressWarnings <value>...] [--suppressAllWarnings] [--proxyHost
-    <value>] [--proxyPort <value>]
+    error|warn|info|hint] [-s <value>] [--score] [--suppressWarnings <value>...] [--suppressAllWarnings] [--ruleset
+    <value>] [--proxyHost <value>] [--proxyPort <value>]
 
 ARGUMENTS
   [SPEC-FILE]  spec path, url, or context-name
@@ -928,6 +928,7 @@ FLAGS
                                      document has description, license, server and/or channels.
       --suppressAllWarnings          Suppress all warnings from the validation output.
       --suppressWarnings=<value>...  List of warning codes to suppress from the validation output.
+      --ruleset=<value>              Path to a custom Spectral ruleset file used during validation.
 
 DESCRIPTION
   validate asyncapi file

src/apps/cli/commands/publish.ts

@@ -0,0 +1,40 @@
+import { Args, Flags } from '@oclif/core';
+import Command from '@cli/internal/base';
+import { load } from '@models/SpecificationFile';
+import { RegistryService } from '@services/registry.service';
+import { proxyFlags } from '@cli/internal/flags/proxy.flags';
+import { applyProxyToPath } from '@utils/proxy';
+
+export default class Publish extends Command {
+  static description = 'publish AsyncAPI file to a schema registry or endpoint';
+
+  static flags = {
+    endpoint: Flags.string({ description: 'Full registry endpoint URL to publish to' }),
+    'content-type': Flags.string({ description: 'Content-Type for the published document', default: 'application/yaml' }),
+    ...proxyFlags(),
+  };
+
+  static args = {
+    'spec-file': Args.string({ description: 'Spec path or url', required: true }),
+  };
+
+  async run() {
+    const { args, flags } = await this.parse(Publish);
+    const filePath = applyProxyToPath(args['spec-file'], flags['proxyHost'], flags['proxyPort']);
+    this.specFile = await load(filePath);
+
+    const registry = new RegistryService();
+    const endpoint = flags.endpoint || '';
+
+    const { success, location, error } = await registry.publish(this.specFile, endpoint || filePath || '', {
+      endpoint: endpoint || undefined,
+      contentType: flags['content-type'],
+    });
+
+    if (!success) {
+      this.error(error || 'Publish failed', { exit: 1 });
+    }
+
+    this.log(`Published successfully${location ? ` at ${location}` : ''}`);
+  }
+}

src/apps/cli/commands/share.ts

@@ -0,0 +1,39 @@
+import { Args, Flags } from '@oclif/core';
+import Command from '@cli/internal/base';
+import { load } from '@models/SpecificationFile';
+import { RegistryService } from '@services/registry.service';
+import { proxyFlags } from '@cli/internal/flags/proxy.flags';
+import { applyProxyToPath } from '@utils/proxy';
+
+export default class Share extends Command {
+  static description = 'share AsyncAPI file (convenience wrapper around publish)';
+
+  static flags = {
+    endpoint: Flags.string({ description: 'Share endpoint URL' }),
+    ...proxyFlags(),
+  };
+
+  static args = {
+    'spec-file': Args.string({ description: 'Spec path or url', required: true }),
+  };
+
+  async run() {
+    const { args, flags } = await this.parse(Share);
+    const filePath = applyProxyToPath(args['spec-file'], flags['proxyHost'], flags['proxyPort']);
+    this.specFile = await load(filePath);
+
+    const registry = new RegistryService();
+    const endpoint = flags.endpoint || '';
+
+    const { success, location, error } = await registry.publish(this.specFile, endpoint || filePath || '', {
+      endpoint: endpoint || undefined,
+      contentType: 'application/yaml',
+    });
+
+    if (!success) {
+      this.error(error || 'Share failed', { exit: 1 });
+    }
+
+    this.log(`Shared successfully${location ? ` at ${location}` : ''}`);
+  }
+}

src/apps/cli/commands/sync.ts

@@ -0,0 +1,51 @@
+import { Args, Flags } from '@oclif/core';
+import Command from '@cli/internal/base';
+import { load } from '@models/SpecificationFile';
+import { RegistryService } from '@services/registry.service';
+import { applyProxyToPath } from '@utils/proxy';
+import { proxyFlags } from '@cli/internal/flags/proxy.flags';
+import { promises as fs } from 'fs';
+import path from 'path';
+
+export default class Sync extends Command {
+  static description = 'sync local AsyncAPI file with remote registry (push or pull)';
+
+  static flags = {
+    endpoint: Flags.string({ description: 'Remote registry endpoint or document URL' }),
+    direction: Flags.string({ description: 'sync direction: push or pull', options: ['push', 'pull'], default: 'push' }),
+    out: Flags.string({ description: 'Output file when pulling' }),
+    ...proxyFlags(),
+  };
+
+  static args = {
+    'spec-file': Args.string({ description: 'Local spec path (for push) or target file (for pull)', required: true }),
+  };
+
+  async run() {
+    const { args, flags } = await this.parse(Sync);
+    const registry = new RegistryService();
+    const endpoint = flags.endpoint;
+    const direction = flags.direction as 'push' | 'pull';
+
+    if (direction === 'push') {
+      const filePath = applyProxyToPath(args['spec-file'], flags['proxyHost'], flags['proxyPort']);
+      this.specFile = await load(filePath);
+      const { success, error } = await registry.publish(this.specFile, endpoint || filePath || '', { endpoint: endpoint || undefined });
+      if (!success) this.error(error || 'Push failed', { exit: 1 });
+      this.log('Push succeeded');
+      return;
+    }
+
+    // pull
+    if (!endpoint) {
+      this.error('Endpoint required for pull', { exit: 1 });
+    }
+
+    const pullRes = await registry.pull(endpoint as string);
+    if (!pullRes.success) this.error(pullRes.error || 'Pull failed', { exit: 1 });
+
+    const outPath = flags.out || args['spec-file'];
+    await fs.writeFile(path.resolve(outPath), pullRes.content || '', 'utf8');
+    this.log(`Pulled content saved to ${outPath}`);
+  }
+}

src/apps/cli/commands/validate.ts

@@ -1,4 +1,7 @@
 import { Args } from '@oclif/core';
+import { promises as fs } from 'fs';
+import yaml from 'js-yaml';
+import path from 'path';
 import Command from '@cli/internal/base';
 import { load } from '@models/SpecificationFile';
 import { specWatcher } from '@cli/internal/globals';
@@ -41,6 +44,11 @@
 
     this.specFile = await load(filePath);
     const watchMode = flags.watch;
+    const customRuleset = flags.ruleset
+      ? await this.loadCustomRuleset(flags.ruleset)
+      : undefined;
+
+    this.validationService = new ValidationService({}, customRuleset);
 
     if (watchMode) {
       specWatcher({
@@ -81,6 +89,24 @@
     }
   }
 
+  private async loadCustomRuleset(rulesetPath: string): Promise<Record<string, unknown>> {
+    const absolutePath = path.resolve(rulesetPath);
+    const rulesetContent = await fs.readFile(absolutePath, 'utf8');
+
+    try {
+      const parsedRuleset = yaml.load(rulesetContent) as Record<string, unknown>;
+
+      if (!parsedRuleset || typeof parsedRuleset !== 'object' || Array.isArray(parsedRuleset)) {
+        throw new Error('The ruleset file must resolve to an object.');
+      }
+
+      return parsedRuleset;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown error';
+      throw new Error(`Failed to load custom ruleset from ${absolutePath}: ${message}`);
+    }
+  }
+
   private async handleDiagnostics(
     result: ServiceResult<ValidationResult>,
     flags: any,

src/apps/cli/internal/flags/validate.flags.ts

@@ -24,5 +24,10 @@ export const validateFlags = () => {
       required: false,
       default: false,
     }),
+    ruleset: Flags.string({
+      description:
+        'Path to a custom Spectral ruleset file used during validation.',
+      required: false,
+    }),
   };
 };

src/domains/services/registry.service.ts

@@ -0,0 +1,77 @@
+import { BaseService } from './base.service';
+import { Specification } from '@models/SpecificationFile';
+import { ConfigService } from './config.service';
+
+export interface PublishOptions {
+  endpoint?: string; // full URL to POST the document to
+  path?: string; // path appended to endpoint
+  contentType?: string;
+}
+
+export class RegistryService extends BaseService {
+  /**
+   * Publish an AsyncAPI specification to a registry endpoint.
+   * This performs a simple POST with the document text. Authentication
+   * is taken from `ConfigService` when available for the given URL.
+   */
+  async publish(
+    spec: Specification,
+    registryUrl: string,
+    options: PublishOptions = {},
+  ): Promise<{ success: boolean; location?: string; error?: string }> {
+    try {
+      const url = options.endpoint || registryUrl;
+      const headers: Record<string, string> = {
+        'Content-Type': options.contentType || 'application/yaml',
+        'User-Agent': 'AsyncAPI-CLI',
+      };
+
+      const auth = await ConfigService.getAuthForUrl(url);
+      if (auth) {
+        headers['Authorization'] = `${auth.authType} ${auth.token}`;
+        Object.assign(headers, auth.headers || {});
+      }
+
+      const res = await fetch(url + (options.path ?? ''), {
+        method: 'POST',
+        headers,
+        body: spec.text(),
+      });
+
+      if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        return { success: false, error: `Publish failed: ${res.status} ${res.statusText} ${body}` };
+      }
+
+      const location = res.headers.get('location') || undefined;
+      return { success: true, location };
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { success: false, error: msg };
+    }
+  }
+
+  /**
+   * Pull a document from a remote registry URL.
+   */
+  async pull(url: string): Promise<{ success: boolean; content?: string; error?: string }> {
+    try {
+      const headers: Record<string, string> = { 'User-Agent': 'AsyncAPI-CLI' };
+      const auth = await ConfigService.getAuthForUrl(url);
+      if (auth) {
+        headers['Authorization'] = `${auth.authType} ${auth.token}`;
+        Object.assign(headers, auth.headers || {});
+      }
+
+      const res = await fetch(url, { headers });
+      if (!res.ok) {
+        return { success: false, error: `Failed to fetch: ${res.status} ${res.statusText}` };
+      }
+      const text = await res.text();
+      return { success: true, content: text };
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { success: false, error: msg };
+    }
+  }
+}