RFC: Include CLI packaging information within the connector metadata

.github/workflows/validate-connector-metadata-schema.yml

@@ -0,0 +1,43 @@
+name: Validate Connector Metadata JSON Schema
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  validate-schema:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v3
+
+    - name: Use Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '18'
+
+    - name: Install dependencies
+      working-directory: connector-metadata-types
+      run: npm ci
+
+    - name: Generate and compare schema
+      working-directory: connector-metadata-types
+      run: |
+        npm run generate-schema new-schema.json
+        if [ -f schema.json ]; then
+          if cmp -s schema.json new-schema.json; then
+            echo "Schema is up to date"
+          else
+            echo "Error: Generated schema does not match the existing schema"
+            echo "Diff between schema.json and new-schema.json:"
+            diff -u schema.json new-schema.json || true
+            exit 1
+          fi
+        else
+          echo "Error: schema.json does not exist"
+          exit 1
+        fi
+        rm new-schema.json

README.md

@@ -40,4 +40,4 @@ implementation][NDC reference].
 
 [NDC specification]: http://hasura.github.io/ndc-spec/
 [NDC reference]: https://github.com/hasura/ndc-spec/tree/main/ndc-reference
-
+[Connector metadata packaging]: ./connector-metadata-types/README.md

connector-metadata-types/.gitignore

@@ -0,0 +1,11 @@
+# Dependency directories
+node_modules/
+
+# TypeScript compiled output
+dist/
+build/
+*.js
+*.js.map
+
+# TypeScript configuration
+tsconfig.tsbuildinfo

connector-metadata-types/README.md

@@ -0,0 +1,24 @@
+# Connector metadata types
+
+This project contains the schema of the connector-metadata.json file that is used in the
+package.tgz file of a connector, whenever a new version of a connector is released.
+
+It is expected that whenever authors propose a new RFC that changes the schema
+of the connector-metadata.json file, they will update this schema file accordingly in the `connectorTypes.ts` file.
+
+The `schema.json` file is the JSON schema of the current `connector-metadata.json` structure.
+
+
+## How to update the schema
+
+1. Update the `connectorTypes.ts` file with the new schema.
+2. Run `npm run generate-schema schema.json` to update the `schema.json` file.
+
+## Github Actions workflow
+
+
+The repo includes a GitHub Actions workflow that generates the schema and
+compares it with the existing schema file.
+
+This ensures that any changes to the schema generation logic are reflected
+in the committed schema file.

connector-metadata-types/connectorTypes.ts

@@ -0,0 +1,118 @@
+export type ConnectorMetadataDefinition = {
+  version?: 1;
+  packagingDefinition: PackagingDefinition;
+  nativeToolchainDefinition?: NativeToolchainDefinition;
+  supportedEnvironmentVariables: EnvironmentVariableDefinition[];
+  commands: Commands;
+  cliPlugin?: BinaryCliPluginDefinition | DockerCliPluginDefinition;
+  dockerComposeWatch: DockerComposeWatch;
+  documentationPage?: string;
+};
+
+export type PackagingDefinition =
+  | PrebuiltDockerImagePackaging
+  | ManagedDockerBuildPackaging;
+
+export type PrebuiltDockerImagePackaging = {
+  type: "PrebuiltDockerImage";
+  dockerImage: string;
+};
+
+export type ManagedDockerBuildPackaging = {
+  type: "ManagedDockerBuild";
+};
+
+export type NativeToolchainCommands = {
+  start: string | DockerizedCommand | ShellScriptCommand;
+  update?: string | DockerizedCommand | ShellScriptCommand;
+  watch: string | DockerizedCommand | ShellScriptCommand;
+};
+
+export type NativeToolchainDefinition = {
+  commands: NativeToolchainCommands;
+};
+
+export type Commands = {
+  update?: string | DockerizedCommand | ShellScriptCommand;
+  watch?: string | DockerizedCommand | ShellScriptCommand;
+  printSchemaAndCapabilities?: string | DockerizedCommand | ShellScriptCommand;
+  upgradeConfiguration?: string | DockerizedCommand | ShellScriptCommand;
+};
+
+export type EnvironmentVariableDefinition = {
+  name: string;
+  description: string;
+  defaultValue?: string;
+};
+
+export type DockerizedCommand = {
+  type: "Dockerized";
+  dockerImage: string;
+  commandArgs: string[];
+};
+
+export type ShellScriptCommand = {
+  type: "ShellScript";
+  bash: string;
+  powershell: string;
+};
+
+export type DockerCliPluginDefinition = {
+  type: "Docker";
+  dockerImage: string; // eg "hasura/postgres-data-connector:1.0.0"
+};
+
+export type BinaryCliPluginPlatform = {
+  /**
+   * The selector identifies the target platform for this configuration.
+   * It follows the format: <os>-<architecture>
+   *
+   * Possible values:
+   * - darwin-arm64: macOS on ARM64 architecture (e.g., M1 Macs)
+   * - linux-arm64: Linux on ARM64 architecture
+   * - darwin-amd64: macOS on x86-64 architecture
+   * - windows-amd64: Windows on x86-64 architecture
+   * - linux-amd64: Linux on x86-64 architecture
+   */
+  selector:
+    | "darwin-arm64"
+    | "linux-arm64"
+    | "darwin-amd64"
+    | "windows-amd64"
+    | "linux-amd64";
+  /**
+   * The URI of the binary file. This should be a URL from which the binary can be downloaded,
+   * without any authentication.
+   */
+  uri: string;
+  /**
+   * The SHA256 hash of the binary file. This is used to verify the integrity of the downloaded binary.
+   */
+  sha256: string;
+  /**
+   * The name of the binary file. This is the name of the binary file that will be placed in the bin directory.
+   */
+  bin: string;
+
+  files: FilePath[];
+};
+
+export type FilePath = {
+  from: string;
+  to: string;
+};
+
+export type BinaryCliPluginDefinition = {
+  type: "Binary";
+  name: string;
+  platforms: BinaryCliPluginPlatform[];
+};
+
+export type DockerComposeWatch = DockerComposeWatchItem[];
+
+export type DockerComposeWatchItem = {
+  path: string;
+  action: "rebuild" | "sync" | "sync+restart";
+  target?: string;
+  ignore?: string[];
+};