@aopslabs/aops 0.2.0

package/dist/lib/community-client-contract.js

@@ -0,0 +1,164 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+export const COMMUNITY_PUBLIC_CLI_PACKAGE_NAME = '@aopslabs/aops';
+export const COMMUNITY_CLI_COMMAND_SCHEMA_VERSION = 1;
+export const COMMUNITY_CLIENT_COMPATIBILITY_SCHEMA_VERSION = 1;
+export const COMMUNITY_CLIENT_COMPATIBILITY_PROTOCOL = 'aops-community-client-server';
+function nonEmpty(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const normalized = value.trim();
+    return normalized || undefined;
+}
+function validSemver(value) {
+    return /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(value);
+}
+function semverCore(value) {
+    const match = /^(\d+)\.(\d+)\.(\d+)/.exec(value);
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : undefined;
+}
+function compareCore(left, right) {
+    for (let index = 0; index < 3; index += 1) {
+        if (left[index] !== right[index])
+            return left[index] < right[index] ? -1 : 1;
+    }
+    return 0;
+}
+function resolveCommunityCliPackageVersion() {
+    try {
+        const manifest = JSON.parse(readFileSync(fileURLToPath(new URL('../../package.json', import.meta.url)), 'utf8'));
+        if (manifest.name !== COMMUNITY_PUBLIC_CLI_PACKAGE_NAME || typeof manifest.version !== 'string')
+            return undefined;
+        return nonEmpty(manifest.version);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function resolveCommunityCliIdentity(environment = process.env) {
+    const injectedVersion = typeof __AOPS_CLI_VERSION__ !== 'undefined' ? __AOPS_CLI_VERSION__ : undefined;
+    const version = nonEmpty(environment.AOPS_CLI_VERSION) ?? nonEmpty(injectedVersion) ??
+        resolveCommunityCliPackageVersion() ?? '0.0.1';
+    if (!validSemver(version))
+        throw new Error('community_cli_version_invalid');
+    const injectedSource = typeof __AOPS_CLI_ARTIFACT_SOURCE__ !== 'undefined'
+        ? __AOPS_CLI_ARTIFACT_SOURCE__
+        : undefined;
+    const requestedSource = nonEmpty(environment.AOPS_CLI_ARTIFACT_SOURCE) ?? injectedSource ?? 'repo-local';
+    const artifactSource = requestedSource === 'repo-local' || requestedSource === 'public-release-bundle'
+        ? requestedSource
+        : 'unknown';
+    const commandSchemaVersion = typeof __AOPS_CLI_COMMAND_SCHEMA_VERSION__ !== 'undefined'
+        ? __AOPS_CLI_COMMAND_SCHEMA_VERSION__
+        : COMMUNITY_CLI_COMMAND_SCHEMA_VERSION;
+    if (!Number.isSafeInteger(commandSchemaVersion) || commandSchemaVersion < 1) {
+        throw new Error('community_cli_command_schema_invalid');
+    }
+    return Object.freeze({
+        packageName: COMMUNITY_PUBLIC_CLI_PACKAGE_NAME,
+        version,
+        commandSchemaVersion,
+        artifactSource,
+        launcher: 'unknown',
+    });
+}
+export function parseCommunityServerCompatibility(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('community_compatibility_handshake_missing');
+    }
+    const input = value;
+    const server = input.server;
+    const range = input.cliCommandSchema;
+    if (input.schemaVersion !== COMMUNITY_CLIENT_COMPATIBILITY_SCHEMA_VERSION ||
+        input.protocol !== COMMUNITY_CLIENT_COMPATIBILITY_PROTOCOL ||
+        !server || typeof server !== 'object' ||
+        !['aops-server', 'south'].includes(server.name) ||
+        !validSemver(String(server.packageVersion ?? '')) ||
+        (server.releaseVersion !== null && !validSemver(String(server.releaseVersion ?? ''))) ||
+        !['release', 'development'].includes(server.source) ||
+        !range || typeof range !== 'object' ||
+        !Number.isSafeInteger(range.min) || !Number.isSafeInteger(range.max) ||
+        range.min < 1 || range.max < range.min) {
+        throw new Error('community_compatibility_handshake_invalid');
+    }
+    return Object.freeze({
+        schemaVersion: 1,
+        protocol: COMMUNITY_CLIENT_COMPATIBILITY_PROTOCOL,
+        server: Object.freeze({
+            name: server.name,
+            packageVersion: String(server.packageVersion),
+            releaseVersion: server.releaseVersion === null ? null : String(server.releaseVersion),
+            source: server.source,
+        }),
+        cliCommandSchema: Object.freeze({ min: range.min, max: range.max }),
+    });
+}
+export function evaluateCommunityCompatibility(handshakeInput, cli = resolveCommunityCliIdentity()) {
+    let handshake;
+    try {
+        handshake = parseCommunityServerCompatibility(handshakeInput);
+    }
+    catch (error) {
+        return Object.freeze({
+            status: 'incompatible',
+            compatible: false,
+            reason: error instanceof Error ? error.message : 'community_compatibility_handshake_invalid',
+            cli,
+        });
+    }
+    const accepted = handshake.cliCommandSchema;
+    if (cli.commandSchemaVersion < accepted.min || cli.commandSchemaVersion > accepted.max) {
+        return Object.freeze({
+            status: 'incompatible',
+            compatible: false,
+            reason: `community_cli_command_schema_out_of_range:${cli.commandSchemaVersion}:${accepted.min}-${accepted.max}`,
+            cli,
+            server: handshake.server,
+            acceptedCommandSchema: accepted,
+        });
+    }
+    const releaseVersion = handshake.server.releaseVersion;
+    if (!releaseVersion) {
+        return Object.freeze({
+            status: 'warning',
+            compatible: true,
+            reason: 'community_server_development_identity',
+            cli,
+            server: handshake.server,
+            acceptedCommandSchema: accepted,
+        });
+    }
+    const cliCore = semverCore(cli.version);
+    const serverCore = semverCore(releaseVersion);
+    if (cliCore[0] !== serverCore[0]) {
+        return Object.freeze({
+            status: 'incompatible',
+            compatible: false,
+            reason: `community_release_major_mismatch:cli=${cli.version}:server=${releaseVersion}`,
+            cli,
+            server: handshake.server,
+            acceptedCommandSchema: accepted,
+        });
+    }
+    const comparison = compareCore(serverCore, cliCore);
+    if (comparison !== 0 || cli.version !== releaseVersion) {
+        return Object.freeze({
+            status: 'warning',
+            compatible: true,
+            reason: comparison > 0
+                ? `community_server_newer_than_cli:cli=${cli.version}:server=${releaseVersion}`
+                : `community_cli_server_version_difference:cli=${cli.version}:server=${releaseVersion}`,
+            cli,
+            server: handshake.server,
+            acceptedCommandSchema: accepted,
+        });
+    }
+    return Object.freeze({
+        status: 'compatible',
+        compatible: true,
+        reason: 'community_client_server_compatible',
+        cli,
+        server: handshake.server,
+        acceptedCommandSchema: accepted,
+    });
+}