### Query Google Compute Networks with StackQL

Source: https://github.com/stackql/stackql-provider-registry/blob/dev/test/robot/stackql/live/readwrite/google_networks_lifecycle.md

This snippet demonstrates querying existing Google Compute Engine networks by name and project. It returns the network's ID, name, description, and subnetwork information. The example shows a successful query returning a created network.

```sql
--
select id, name, description, subnetworks from google.compute.networks where name = 'robot-vpc-01' and project = 'stackql-robot';
|--------------------|--------------|-------------|-------------|
|         id         |     name     | description | subnetworks |
|--------------------|--------------|-------------|-------------|
| 987158103920671616 | robot-vpc-01 | null        | null        |
|--------------------|--------------|-------------|-------------|
```

--------------------------------

### Setup Environment and Generate Keys/Certificates (Bash)

Source: https://github.com/stackql/stackql-provider-registry/blob/dev/docs/command-line-tool.md

Sets up the necessary environment variables and then uses the built `ed25519tool` to create a private key, public key, certificate, and certificate signing request. This prepares the files for signing and verification.

```bash
. ./scripts/setup-env.sh

CREDENTIALS_DIR="${REPOSITORY_ROOT_DIR}/signing/Ed25519/setup/scratchpad"
TESTING_INPUT_DIR="${REPOSITORY_ROOT_DIR}/signing/Ed25519/test"
TESTING_OUTPUT_DIR="${CREDENTIALS_DIR}"

PRIVATE_KEY_FILE="smoke-testing-private-key.pem"
PUBLIC_KEY_FILE="smoke-testing-public-key.pem"
CERT_FILE="smoke-testing-cert.pem"
CSR_FILE="smoke-testing.csr"

## Create key pair and cert
./ed25519tool createkeys ${CREDENTIALS_DIR}/${PRIVATE_KEY_FILE} ${CREDENTIALS_DIR}/${PUBLIC_KEY_FILE} ${CREDENTIALS_DIR}/${CERT_FILE} ${CREDENTIALS_DIR}/${CSR_FILE}
```

--------------------------------

### Create Google Compute Network with StackQL

Source: https://github.com/stackql/stackql-provider-registry/blob/dev/test/robot/stackql/live/readwrite/google_networks_lifecycle.md

This snippet shows how to create a new Google Compute Engine network. It specifies the network name and whether to auto-create subnetworks. The output confirms the operation was dispatched successfully.

```sql
--
insert into google.compute.networks(data__name, data__autoCreateSubnetworks, project) 
select 'robot-vpc-01', false, 'stackql-robot';
The operation was despatched successfully
```

--------------------------------

### Query Google Compute Subnetworks with StackQL

Source: https://github.com/stackql/stackql-provider-registry/blob/dev/test/robot/stackql/live/readwrite/google_networks_lifecycle.md

This snippet shows how to query Google Compute Engine subnetworks based on name, region, and project. It returns details such as name, ID, secondary IP ranges, and fingerprint. The example displays a subnetwork with its details.

```sql
--
select name, id, secondaryIpRanges, fingerprint from google.compute.subnetworks where name = 'robot-subnet-01' and region = 'australia-southeast1' and project = 'stackql-robot' ;
|-----------------|---------------------|-------------------|--------------|
|      name       |         id          | secondaryIpRanges | fingerprint  |
|-----------------|---------------------|-------------------|--------------|
| robot-subnet-01 | 7691273977604797678 | null              | UNiA_jWveJI= |
|-----------------|---------------------|-------------------|--------------|
```

--------------------------------

### Create Google Compute Subnetwork with StackQL

Source: https://github.com/stackql/stackql-provider-registry/blob/dev/test/robot/stackql/live/readwrite/google_networks_lifecycle.md

This snippet illustrates creating a Google Compute Engine subnetwork within a specified network. It includes the subnetwork name, IP range, description, and the parent network. The operation confirmation is displayed.

```sql
--
insert into google.compute.subnetworks(data__name, data__ipCidrRange, data__description, data__network, project, region) 
select 
'robot-subnet-01', 
'10.0.0.0/8',
'An immutable ROBOT subnet description.', 
'projects/stackql-robot/global/networks/robot-vpc-01',
'stackql-robot',
'australia-southeast1'
;
The operation was despatched successfully
```

--------------------------------

### Verify Network Deletion with StackQL

Source: https://github.com/stackql/stackql-provider-registry/blob/dev/test/robot/stackql/live/readwrite/google_networks_lifecycle.md

This snippet attempts to query a Google Compute Engine network after its deletion. The result is an empty table, confirming that the network has been successfully removed. This query serves as a verification step.

```sql
--
select id, name, description, subnetworks from google.compute.networks where name = 'robot-vpc-01' and project = 'stackql-robot';
|----|------|-------------|-------------|
| id | name | description | subnetworks |
|----|------|-------------|-------------|
```

--------------------------------

### Provider YAML Configuration Example

Source: https://context7.com/stackql/stackql-provider-registry/llms.txt

This YAML file defines a StackQL provider, including its services, authentication configuration, and versioning. It uses OpenAPI specification with StackQL extensions to describe services like 'repos' and 'actions' for the GitHub provider. The configuration specifies authentication type, location, and the environment variable for credentials.

```yaml
# providers/src/github/v00.00.00000/provider.yaml
id: github
name: github
version: v00.00.00000
providerServices:
  repos:
    id: 'repos:v00.00.00000'
    name: repos
    preferred: true
    service:
      $ref: github/v00.00.00000/services/repos.yaml
    title: GitHub V3 REST API - Repositories
    version: v00.00.00000
    description: Endpoints to manage GitHub repositories.

  actions:
    id: 'actions:v00.00.00000'
    name: actions
    preferred: true
    service:
      $ref: github/v00.00.00000/services/actions.yaml
    title: GitHub V3 REST API - Actions
    version: v00.00.00000
    description: Endpoints to manage GitHub Actions.

config:
  auth:
    type: bearer
    location: header
    name: Authorization
    credentialsenvvar: "GITHUB_TOKEN"

```

--------------------------------

### Service OpenAPI with StackQL Extensions Example

Source: https://context7.com/stackql/stackql-provider-registry/llms.txt

This YAML file defines the OpenAPI specification for a service, extended with StackQL-specific configurations for resource mapping. It details API paths, operation IDs, parameters, and response schemas. The `x-stackQL-resources` section maps these API operations to SQL-like resources and verbs, enabling querying of the service data using SQL syntax.

```yaml
# providers/src/github/v00.00.00000/services/repos.yaml
openapi: 3.0.0
info:
  title: GitHub Repositories API
  version: v00.00.00000

paths:
  /repos/{owner}/{repo}:
    get:
      operationId: getRepository
      parameters:
        - name: owner
          in: path
          required: true
        - name: repo
          in: path
          required: true
      responses:
        '200':
          description: Repository details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Repository'

components:
  schemas:
    Repository:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        full_name:
          type: string

  x-stackQL-resources:
    repositories:
      id: github.repos.repositories
      name: repositories
      title: Repositories
      methods:
        list_repos:
          operation:
            $ref: '#/paths/~1repos~1{owner}~1{repo}/get'
          response:
            mediaType: application/json
            openAPIDocKey: '200'
      sqlVerbs:
        select:
          - $ref: '#/components/x-stackQL-resources/repositories/methods/list_repos'

```

--------------------------------

### Verify Subnetwork Deletion with StackQL

Source: https://github.com/stackql/stackql-provider-registry/blob/dev/test/robot/stackql/live/readwrite/google_networks_lifecycle.md

This snippet attempts to query a Google Compute Engine subnetwork after it has been deleted. The expected output is an empty table, confirming that the subnetwork no longer exists. This is useful for verification after a delete operation.

```sql
--
select name, id, secondaryIpRanges, fingerprint from google.compute.subnetworks where name = 'robot-subnet-01' and region = 'australia-southeast1' and project = 'stackql-robot' ;
|------|----|-------------------|-------------|
| name | id | secondaryIpRanges | fingerprint |
|------|----|-------------------|-------------|
```

--------------------------------

### Sign Files with Ed25519 Tool (Bash)

Source: https://github.com/stackql/stackql-provider-registry/blob/dev/docs/command-line-tool.md

Signs a given input file using the `ed25519tool`. This process utilizes a private key stored in an environment variable and allows for specifying a custom signature timestamp. Multiple examples demonstrate signing with different timestamp values.

```bash
## Store the private key in an env var
SIGNING_KEY_SECRET=$(cat ${CREDENTIALS_DIR}/${PRIVATE_KEY_FILE})

## Sign some files
./ed25519tool sign --privatekeyenvvar="SIGNING_KEY_SECRET" --signaturetime="Jan 2 15:04:05 2006" ${TESTING_INPUT_DIR}/sample-infile.txt -o ${TESTING_OUTPUT_DIR}/old-timestamp-sample-infile.txt.sig

./ed25519tool sign --privatekeyenvvar="SIGNING_KEY_SECRET"  --signaturetime="Jan 2 15:04:05 2023" ${TESTING_INPUT_DIR}/sample-infile.txt -o ${TESTING_OUTPUT_DIR}/acceptable-timestamp-sample-infile.txt.sig

./ed25519tool sign --privatekeyenvvar="SIGNING_KEY_SECRET"  --signaturetime="now" ${TESTING_INPUT_DIR}/sample-infile.txt -o ${TESTING_OUTPUT_DIR}/now-timestamp-sample-infile.txt.sig

./ed25519tool sign --privatekeyenvvar="SIGNING_KEY_SECRET"  --signaturetime="Jan 2 15:04:05 2033" ${TESTING_INPUT_DIR}/sample-infile.txt -o ${TESTING_OUTPUT_DIR}/future-timestamp-sample-infile.txt.sig
```

--------------------------------

### Verify Signatures with Ed25519 Tool (Bash)

Source: https://github.com/stackql/stackql-provider-registry/blob/dev/docs/command-line-tool.md

Performs signature verification using the `ed25519tool`. This includes basic public key verification and certificate-based verification (`certverify`). Examples cover successful verifications and scenarios expected to fail due to timestamp mismatches or strict certificate validation.

```bash
## Now, verify

## will succeed
./ed25519tool verify --publickeypath=${CREDENTIALS_DIR}/${PUBLIC_KEY_FILE} ${TESTING_INPUT_DIR}/sample-infile.txt ${TESTING_OUTPUT_DIR}/old-timestamp-sample-infile.txt.sig

## should and will fail with timestamp message
./ed25519tool certverify --localcerts.signingbundle=${CREDENTIALS_DIR}/${CERT_FILE} --localcerts.cabundle=${CREDENTIALS_DIR}/${CERT_FILE} ${TESTING_INPUT_DIR}/sample-infile.txt ${TESTING_OUTPUT_DIR}/old-timestamp-sample-infile.txt.sig

## will succeed
./ed25519tool verify --publickeypath=${CREDENTIALS_DIR}/${PUBLIC_KEY_FILE} ${TESTING_INPUT_DIR}/sample-infile.txt ${TESTING_OUTPUT_DIR}/acceptable-timestamp-sample-infile.txt.sig

## will succeed
./ed25519tool certverify --localcerts.signingbundle=${CREDENTIALS_DIR}/${CERT_FILE} --localcerts.cabundle=${CREDENTIALS_DIR}/${CERT_FILE} ${TESTING_INPUT_DIR}/sample-infile.txt ${TESTING_OUTPUT_DIR}/acceptable-timestamp-sample-infile.txt.sig

## will succeed
./ed25519tool verify --publickeypath=${CREDENTIALS_DIR}/${PUBLIC_KEY_FILE} ${TESTING_INPUT_DIR}/sample-infile.txt ${TESTING_OUTPUT_DIR}/now-timestamp-sample-infile.txt.sig

## will succeed
./ed25519tool certverify --localcerts.signingbundle=${CREDENTIALS_DIR}/${CERT_FILE} --localcerts.cabundle=${CREDENTIALS_DIR}/${CERT_FILE} ${TESTING_INPUT_DIR}/sample-infile.txt ${TESTING_OUTPUT_DIR}/now-timestamp-sample-infile.txt.sig


## all good with self signed CA if we supply it as a command line arg
./ed25519tool certverify --localcerts.signingbundle=${CREDENTIALS_DIR}/${CERT_FILE} --localcerts.cabundle=${CREDENTIALS_DIR}/${CERT_FILE} ${TESTING_INPUT_DIR}/sample-infile.txt --strict=true ${TESTING_OUTPUT_DIR}/acceptable-timestamp-sample-infile.txt.sig

## will fail due to self-signed certificate in strict mode, if we do not supply same as CA
./ed25519tool certverify --localcerts.signingbundle=${CREDENTIALS_DIR}/${CERT_FILE} ${TESTING_INPUT_DIR}/sample-infile.txt --strict=true ${TESTING_OUTPUT_DIR}/acceptable-timestamp-sample-infile.txt.sig

## will succeed
./ed25519tool verify --publickeypath=${CREDENTIALS_DIR}/${PUBLIC_KEY_FILE} ${TESTING_INPUT_DIR}/sample-infile.txt ${TESTING_OUTPUT_DIR}/future-timestamp-sample-infile.txt.sig

## should and will fail with timestamp message
./ed25519tool certverify --localcerts.signingbundle=${CREDENTIALS_DIR}/${CERT_FILE} --localcerts.cabundle=${CREDENTIALS_DIR}/${CERT_FILE} ${TESTING_INPUT_DIR}/sample-infile.txt ${TESTING_OUTPUT_DIR}/future-timestamp-sample-infile.txt.sig
```

--------------------------------

### Delete Google Compute Network with StackQL

Source: https://github.com/stackql/stackql-provider-registry/blob/dev/test/robot/stackql/live/readwrite/google_networks_lifecycle.md

This snippet shows the command to delete a Google Compute Engine network using StackQL. It requires specifying the project and network name. Similar to subnetwork deletion, a nil response indicates success.

```sql
--
delete from 
google.compute.networks
WHERE
project = 'stackql-robot'
and
network = 'robot-vpc-01'
;
<nil displayed response>
```

--------------------------------

### Delete Google Compute Subnetwork with StackQL

Source: https://github.com/stackql/stackql-provider-registry/blob/dev/test/robot/stackql/live/readwrite/google_networks_lifecycle.md

This snippet demonstrates how to delete a Google Compute Engine subnetwork using StackQL. It requires specifying the project, region, and subnetwork name. The output indicates a nil response, signifying successful deletion.

```sql
--
delete from 
google.compute.subnetworks
WHERE
project = 'stackql-robot'
and
region = 'australia-southeast1'
and
subnetwork = 'robot-subnet-01'
;
<nil displayed response>
```

--------------------------------

### Query Updated Google Compute Subnetwork with StackQL

Source: https://github.com/stackql/stackql-provider-registry/blob/dev/test/robot/stackql/live/readwrite/google_networks_lifecycle.md

This snippet queries a Google Compute Engine subnetwork after an update, specifically to verify the addition of secondary IP ranges. It returns the subnetwork's name, ID, secondary IP ranges, and the updated fingerprint. The result shows the newly added range.

```sql
--
select name, id, secondaryIpRanges, fingerprint from google.compute.subnetworks where name = 'robot-subnet-01' and region = 'australia-southeast1' and project = 'stackql-robot' ;
|-----------------|---------------------|-----------------------------------------------------------------|--------------|
|      name       |         id          |                        secondaryIpRanges                        | fingerprint  |
|-----------------|---------------------|-----------------------------------------------------------------|--------------|
| robot-subnet-01 | 7691273977604797678 | [{"ipCidrRange":"192.168.0.0/24","rangeName":"robot-range-01"}] | vmdP1iA6Cfc= |
|-----------------|---------------------|-----------------------------------------------------------------|--------------|
```

--------------------------------

### Update Google Compute Subnetwork Secondary IP Ranges with StackQL

Source: https://github.com/stackql/stackql-provider-registry/blob/dev/test/robot/stackql/live/readwrite/google_networks_lifecycle.md

This snippet demonstrates updating a Google Compute Engine subnetwork to add secondary IP ranges. It uses the `SET` clause with `data__secondaryIpRanges` and requires the current `data__fingerprint` for optimistic concurrency control. The operation confirmation is shown.

```sql
--
update google.compute.subnetworks
SET
data__secondaryIpRanges = '[
   {
     "ipCidrRange": "192.168.0.0/24",
     "rangeName": "robot-range-01"
   }
 ]',
data__fingerprint = 'UNiA_jWveJI='
WHERE
project = 'stackql-robot'
and
region = 'australia-southeast1'
and
subnetwork = 'robot-subnet-01'
;
The operation was despatched successfully
```

--------------------------------

### Local Testing Workflow (Bash)

Source: https://context7.com/stackql/stackql-provider-registry/llms.txt

A bash script outlining the steps for setting up and running local tests for StackQL providers. It covers gathering dependencies, configuring the environment, building the signing tool, creating test credentials, setting up read-only credentials, and running read-only tests. It also includes commented-out steps for write tests, emphasizing caution.

```bash
#!/usr/bin/env bash
# Local testing workflow

# 1. Gather dependencies
./scripts/local/ci/01-gather.sh

# 2. Configure environment
source ./scripts/local/ci/02-setup.sh

# 3. Build signing tool
go build -o ed25519tool ./signing/Ed25519/app/cmd/main

# 4. Create test credentials (if needed)
./ed25519tool createkeys \
  ./test-private-key.pem \
  ./test-public-key.pem \
  ./test-cert.pem \
  ./test.csr

# 5. Set up test environment with read-only credentials
source ./scripts/sec/sec-ro-stackql.sh

# 6. Run read-only tests (safe, no side effects)
./scripts/local/ci/03-run-live-readonly.sh

# 7. For write tests (creates real resources - use with caution!)
# source ./scripts/sec/sec-rw-stackql.sh

```

--------------------------------

### StackQL Usage - Querying providers via the registry

Source: https://context7.com/stackql/stackql-provider-registry/llms.txt

Demonstrates how to use the StackQL CLI to interact with the provider registry, including setting up the registry URL, entering the shell, listing available providers, and pulling specific versions.

```APIDOC
## StackQL Usage - Querying providers via the registry

### Description
Using StackQL CLI to pull and query providers from the registry API.

### Method
`bash`

### Endpoint
StackQL CLI commands

### Parameters
#### Environment Variables
- **DEV_REG** (string) - Required - JSON string defining the registry URL, e.g., `{"url": "https://registry-dev.stackql.app/providers"}`.

### Request Example
```bash
# Configure StackQL to use dev registry
export DEV_REG='{"url": "https://registry-dev.stackql.app/providers"}'
./stackql --registry="${DEV_REG}" shell

# Inside StackQL shell - list available providers
REGISTRY LIST;

# Pull a specific provider version
REGISTRY PULL github:v23.11.00234;
```

### Response
#### Success Response (CLI Output)
- **output** (string) - The console output from the StackQL CLI commands, showing results of `REGISTRY LIST` or confirmation of `REGISTRY PULL`.
```

--------------------------------

### Ed25519 Signing Tool CLI

Source: https://context7.com/stackql/stackql-provider-registry/llms.txt

Command-line interface for building, creating keys, signing, and verifying files using Ed25519 cryptography. Supports signing with private keys from environment variables and verification with public keys or certificates. Requires Go for building.

```bash
# Build the signing tool
go build -o ed25519tool ./signing/Ed25519/app/cmd/main

# Create Ed25519 key pair and self-signed certificate
./ed25519tool createkeys \
  ./private-key.pem \
  ./public-key.pem \
  ./certificate.pem \
  ./certificate.csr

# Sign a file with timestamp using environment variable
export SIGNING_KEY_SECRET=$(cat private-key.pem)
./ed25519tool sign \
  --privatekeyenvvar="SIGNING_KEY_SECRET" \
  --signaturetime="now" \
  input.yaml \
  -o input.yaml.sig

# Verify signature using public key
./ed25519tool verify \
  --publickeypath=public-key.pem \
  input.yaml \
  input.yaml.sig

# Verify signature using certificate with chain of trust
./ed25519tool certverify \
  --localcerts.signingbundle=certificate.pem \
  --localcerts.cabundle=ca-bundle.pem \
  --strict=true \
  input.yaml \
  input.yaml.sig
```

--------------------------------

### Build Ed25519 Command Line Tool (Go)

Source: https://github.com/stackql/stackql-provider-registry/blob/dev/docs/command-line-tool.md

Compiles the Ed25519 signing and verification tool from source code. This is a prerequisite for all subsequent operations. It requires a Go development environment.

```bash
go build -o ed25519tool ./signing/Ed25519/app/cmd/main
```

--------------------------------

### GitHub Actions CI/CD for Provider Registry

Source: https://context7.com/stackql/stackql-provider-registry/llms.txt

Automates the build, signing, testing, and deployment of provider documents. This workflow triggers on push or pull requests to the main or dev branches. It includes steps for checking out code, detecting changes, building a signing tool, signing and packaging documents, running end-to-end tests, and publishing to an artifact repository.

```yaml
# .github/workflows/main.yml
name: Build and Deploy Registry Providers

on:
  push:
    branches: [main, dev]
  pull_request:
    branches: [main, dev]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    env:
      REG_VERSION: "v23.11.00234"  # Auto-generated
      SIGNING_PRIV_KEY: ${{ secrets.SIGNING_PRIV_KEY }}

    steps:
      # Setup: Detect changed providers
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Find changed providers
        run: |
          git diff --name-status --diff-filter=ACMRT \
            ${{ github.event.before }} \
            ${{ github.sha }} > diff.txt
          python scripts/setup/get-updated-providers.py

      # Build: Compile signing tool
      - name: Build signing tool
        if: env.NUM_PROVIDERS > 0
        run: |
          go build -o ed25519tool ./signing/Ed25519/app/cmd/main

      # Package: Sign and compress
      - name: Sign provider documents
        if: env.NUM_PROVIDERS > 0
        run: |
          python scripts/package/sign-provider-docs.py
          python scripts/package/package-provider-docs.py

      # Test: Validate signatures and schemas
      - name: Run E2E tests
        if: env.NUM_PROVIDERS > 0
        run: |
          robot --outputdir test/log test/*.robot

      # Deploy: Publish to S3 and Deno Deploy
      - name: Publish to artifact repository
        if: github.ref == 'refs/heads/main'
        run: |
          python scripts/publish/publish-provider-docs-to-artifact-repo.py

```

--------------------------------

### SignFile - Core Signing Functionality

Source: https://context7.com/stackql/stackql-provider-registry/llms.txt

Go function for programmatically signing files using Ed25519 private keys, with support for embedding timestamps for time-bounded verification. Reads private keys from environment variables and writes signatures in base64 format. Depends on the 'edcrypto' library.

```go
package main

import (
    "fmt"
    "os"
    "github.com/stackql/stackql-provider-registry/signing/Ed25519/app/edcrypto"
)

func signProviderDocument() error {
    // Sign using private key from environment variable
    privateKeyEnvVar := "SIGNING_PRIV_KEY"
    keyFormat := "pem"
    fileToSign := "providers/src/github/v00.00.00000/provider.yaml"
    timestamp := "now" // or "Jan 2 15:04:05 2006" format

    signature, err := edcrypto.SignFileWithTimestampUsingEnvVar(
        privateKeyEnvVar,
        keyFormat,
        fileToSign,
        timestamp,
    )
    if err != nil {
        return fmt.Errorf("signing failed: %w", err)
    }

    // Write signature to file
    signaturePath := fileToSign + ".sig"
    err = edcrypto.WriteOutFile(signature, signaturePath, "base64")
    if err != nil {
        return fmt.Errorf("failed to write signature: %w", err)
    }

    fmt.Printf("Successfully signed %s\n", fileToSign)
    return nil
}
```

--------------------------------

### Query GitHub Repositories with SQL

Source: https://context7.com/stackql/stackql-provider-registry/llms.txt

Demonstrates how to query GitHub repositories using SQL syntax via StackQL. It selects repository details like name, full name, star count, and fork count for a specified owner. Assumes the 'github' provider is configured.

```sql
SELECT
  name,
  full_name,
  stargazers_count,
  forks_count
FROM github.repos.repositories
WHERE owner = 'stackql';
```

--------------------------------

### Insert GitHub Repository using SQL

Source: https://context7.com/stackql/stackql-provider-registry/llms.txt

Shows how to insert a new repository into GitHub using SQL INSERT statements through StackQL. This maps to an API POST request. It requires owner, name, description, and private status as input.

```sql
INSERT INTO github.repos.repositories (
  owner,
  name,
  description,
  private
) VALUES (
  'myorg',
  'new-repo',
  'Created via StackQL',
  false
);
```

--------------------------------

### StackQL CLI Usage for Registry Interaction

Source: https://context7.com/stackql/stackql-provider-registry/llms.txt

These bash commands demonstrate how to use the StackQL CLI to interact with the provider registry. It includes configuring the CLI to use a development registry, entering the StackQL shell, listing available providers in the registry, and pulling a specific provider version.

```bash
# Configure StackQL to use dev registry
export DEV_REG='{"url": "https://registry-dev.stackql.app/providers"}'
./stackql --registry="${DEV_REG}" shell

# Inside StackQL shell - list available providers
REGISTRY LIST;

# Pull a specific provider version
REGISTRY PULL github:v23.11.00234;

```

--------------------------------

### Sign Files with Ed25519 Tool (Bash)

Source: https://context7.com/stackql/stackql-provider-registry/llms.txt

A bash script that acts as a wrapper for the Ed25519 signing tool. It simplifies the process of signing files by using environment variables for authentication and including a timestamp in the signature for time-bounded verification. Requires the SIGNING_PRIV_KEY environment variable to be set.

```bash
#!/usr/bin/env bash
# scripts/package/sign-file.sh

infile=$1
outfile=$2

echo "Signing $infile..."

# SIGNING_PRIV_KEY must be set in environment
# Signature includes timestamp for time-bounded verification
./ed25519tool sign \
  --privatekeyenvvar=SIGNING_PRIV_KEY \
  --signaturetime="now" \
  "$infile" \
  -o "$outfile"

if [ $? -eq 0 ]; then
  echo "✓ Created signature: $outfile"
else
  echo "✗ Signing failed for $infile"
  exit 1
fi
```

--------------------------------

### Python Script for Provider Document Signing Automation

Source: https://context7.com/stackql/stackql-provider-registry/llms.txt

This Python script automates the signing of provider YAML files and their associated service documents using the Ed25519 tool. It reads provider information from environment variables, iterates through each provider, signs the main provider.yaml file and all service YAML files using a shell wrapper, and creates signed output in a specified directory structure. Errors during the signing process are reported, and the script requires the 'providers' environment variable to be set with provider details.

```python
# scripts/package/sign-provider-docs.py
import os
import json
import subprocess

def sign_provider_documents():
    # Read providers from environment (set by get-updated-providers.py)
    providers_json = os.getenv('PROVIDERS')
    providers = json.loads(providers_json)

    signing_version = os.getenv('SIGNING_VERSION', 'v1')

    for provider in providers:
        provider_name = provider['provider']
        provider_dir = provider['provider_dir']
        source_version = provider['source_version']
        target_version = provider['target_version']

        print(f"Signing provider: {provider_name}")

        # Sign provider.yaml
        provider_file = f"providers/src/{provider_dir}/{source_version}/provider.yaml"
        signed_file = f"signed/providers/src/{provider_dir}/{target_version}/provider.yaml"

        os.makedirs(os.path.dirname(signed_file), exist_ok=True)

        # Call sign-file.sh wrapper
        result = subprocess.run([
            './scripts/package/sign-file.sh',
            provider_file,
            signed_file
        ], capture_output=True, text=True)

        if result.returncode != 0:
            print(f"Error signing {provider_file}: {result.stderr}")
            raise Exception(f"Signing failed for {provider_name}")

        # Sign all service YAML files
        services_dir = f"providers/src/{provider_dir}/{source_version}/services"
        if os.path.exists(services_dir):
            for service_file in os.listdir(services_dir):
                if service_file.endswith('.yaml'):
                    service_path = f"{services_dir}/{service_file}"
                    signed_service = f"signed/{services_dir}/{service_file}"

                    os.makedirs(os.path.dirname(signed_service), exist_ok=True)

                    subprocess.run([
                        './scripts/package/sign-file.sh',
                        service_path,
                        signed_service
                    ], check=True)

        print(f"✓ Signed {provider_name} v{target_version}")

if __name__ == '__main__':
    sign_provider_documents()

```

--------------------------------

### Discover Updated Providers from Git Diff (Python)

Source: https://context7.com/stackql/stackql-provider-registry/llms.txt

A Python script that analyzes a 'diff.txt' file (presumably containing git diff output) to identify changed providers. It determines the provider name, version, and action (added, modified, deleted), and sets GitHub Actions environment variables with the list of updated providers. It also handles a special case for 'googleapis.com' and ensures a baseline version check.

```python
# scripts/setup/get-updated-providers.py
import os
import json
import sys

def get_updated_providers():
    target_version = os.getenv('REG_VERSION')

    with open('diff.txt', 'r') as f:
        lines = f.readlines()
        updates = []
        all_provider_versions = []

        for line in lines:
            fields = line.split('\t')
            action = fields[0]  # A (added), M (modified), D (deleted)
            path = fields[1].strip()

            if path.startswith('providers/src/'):
                parts = path.split('/')
                provider_dir = parts[2]

                # Handle googleapis.com special case
                provider_name = 'google' if provider_dir == 'googleapis.com' else provider_dir

                source_version = parts[3]

                # Validate baseline version
                if source_version != 'v00.00.00000':
                    print('ERROR: baseline version must be v00.00.00000')
                    sys.exit(1)

                provider = {
                    'provider': provider_name,
                    'provider_dir': provider_dir,
                    'source_version': source_version,
                    'target_version': target_version,
                    'action': action,
                    'path': path
                }

                updates.append(provider)
                all_provider_versions.append(json.dumps(provider))

                # Handle awscc dependency on aws
                if provider_name == 'awscc':
                    aws_provider = {
                        'provider': 'aws',
                        'provider_dir': 'aws',
                        'source_version': 'v00.00.00000',
                        'target_version': target_version,
                        'action': 'M',
                        'path': 'providers/src/aws/v00.00.00000/provider.yaml'
                    }
                    updates.append(aws_provider)
                    all_provider_versions.append(json.dumps(aws_provider))

        # Deduplicate providers
        providers = []
        for provider_json in set(all_provider_versions):
            providers.append(json.loads(provider_json))

        num_providers = len(providers)

        if num_providers > 0:
            # Set GitHub Actions environment variables
            os.system(f"echo 'PROVIDERS={json.dumps(providers)}' >> $GITHUB_ENV")
            os.system(f"echo 'NUM_PROVIDERS={num_providers}' >> $GITHUB_ENV")

            # Write output files for downstream steps
            with open('providers.txt', 'w') as f:
                for p in providers:
                    f.write(f"{p['provider']}\n")

            with open('provider_dirs.txt', 'w') as f:
                for p in providers:
                    f.write(f"{p['provider_dir']}\n")

            with open('updates.json', 'w') as f:
                json.dump(updates, f, indent=2)

            print(f"✓ Found {num_providers} updated providers")
            return providers

        return []

if __name__ == '__main__':
    get_updated_providers()

```

--------------------------------

### Python Build Script - Provider Document Signing

Source: https://context7.com/stackql/stackql-provider-registry/llms.txt

Orchestrates the signing of all provider YAML files and their service documents using the Ed25519 tool. This script automates the signing process for provider documentation.

```APIDOC
## Python Build Script - Provider Document Signing

### Description
Orchestrates signing of all provider YAML files and their service documents using the Ed25519 tool.

### Method
`python`

### Endpoint
`scripts/package/sign-provider-docs.py`

### Parameters
#### Environment Variables
- **PROVIDERS** (string) - Required - JSON string of providers to process, typically set by `get-updated-providers.py`.
- **SIGNING_VERSION** (string) - Optional - The signing version to use, defaults to 'v1'.

### Request Example
```bash
export PROVIDERS='[{"provider": "github", "provider_dir": "github", "source_version": "v00.00.00000", "target_version": "v00.00.00000"}]'
export SIGNING_VERSION='v1'
python scripts/package/sign-provider-docs.py
```

### Response
#### Success Response (0)
- **output** (string) - Console output indicating the signing progress and success for each provider.

#### Error Response (non-zero)
- **error** (string) - Console output indicating the error message if signing fails.
```

--------------------------------

### Provider YAML Configuration

Source: https://context7.com/stackql/stackql-provider-registry/llms.txt

Defines the structure for provider configurations using OpenAPI specification with StackQL extensions. This file specifies services, versions, and authentication methods for a provider.

```APIDOC
## Provider YAML Configuration

### Description
OpenAPI specification with StackQL extensions defining provider services and authentication.

### Method
`YAML`

### Endpoint
`providers/src/{provider}/{version}/provider.yaml`

### Parameters
N/A (File structure)

### Request Example
```yaml
# providers/src/github/v00.00.00000/provider.yaml
id: github
name: github
version: v00.00.00000
providerServices:
  repos:
    id: 'repos:v00.00.00000'
    name: repos
    preferred: true
    service:
      $ref: github/v00.00.00000/services/repos.yaml
    title: GitHub V3 REST API - Repositories
    version: v00.00.00000
    description: Endpoints to manage GitHub repositories.

  actions:
    id: 'actions:v00.00.00000'
    name: actions
    preferred: true
    service:
      $ref: github/v00.00.00000/services/actions.yaml
    title: GitHub V3 REST API - Actions
    version: v00.00.00000
    description: Endpoints to manage GitHub Actions.

config:
  auth:
    type: bearer
    location: header
    name: Authorization
    credentialsenvvar: "GITHUB_TOKEN"
```

### Response
#### Success Response (N/A - Configuration file)
- **id** (string) - Unique identifier for the provider.
- **name** (string) - Name of the provider.
- **version** (string) - Version of the provider.
- **providerServices** (object) - A map of services provided by this provider.
- **config** (object) - Provider-specific configuration, including authentication details.
```

--------------------------------

### Service OpenAPI with StackQL Extensions

Source: https://context7.com/stackql/stackql-provider-registry/llms.txt

An OpenAPI specification file that includes StackQL-specific extensions (x-stackQL-resources) for mapping API operations to SQL-like resources and methods.

```APIDOC
## Service OpenAPI with StackQL Extensions

### Description
OpenAPI specification extended with x-stackQL-resources for SQL operation mapping.

### Method
`YAML`

### Endpoint
`providers/src/{provider}/{version}/services/{service}.yaml`

### Parameters
N/A (File structure)

### Request Example
```yaml
# providers/src/github/v00.00.00000/services/repos.yaml
openapi: 3.0.0
info:
  title: GitHub Repositories API
  version: v00.00.00000

paths:
  /repos/{owner}/{repo}:
    get:
      operationId: getRepository
      parameters:
        - name: owner
          in: path
          required: true
        - name: repo
          in: path
          required: true
      responses:
        '200':
          description: Repository details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Repository'

components:
  schemas:
    Repository:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        full_name:
          type: string

  x-stackQL-resources:
    repositories:
      id: github.repos.repositories
      name: repositories
      title: Repositories
      methods:
        list_repos:
          operation:
            $ref: '#/paths/~1repos~1{owner}~1{repo}/get'
          response:
            mediaType: application/json
            openAPIDocKey: '200'
      sqlVerbs:
        select:
          - $ref: '#/components/x-stackQL-resources/repositories/methods/list_repos'
```

### Response
#### Success Response (N/A - Configuration file)
- **openapi** (string) - OpenAPI version.
- **info** (object) - API metadata.
- **paths** (object) - API endpoints and operations.
- **components.schemas** (object) - Data schemas used in the API.
- **components.x-stackQL-resources** (object) - StackQL specific resource mappings for SQL operations.
```

--------------------------------

### Parse Provider Designations with Multiple Formats

Source: https://context7.com/stackql/stackql-provider-registry/llms.txt

Parses provider designation strings, supporting various formats for including version tags and SHA references. This function takes a string as input and returns a structured object containing the provider's name, version tag, and SHA reference if present. It handles cases with only the name, name with version, and name with SHA.

```go
package main

import (
    "fmt"
    "github.com/stackql/stackql-provider-registry/registry/pkg/nomenclature"
)

func parseProviderDesignations() {
    // Parse different provider designation formats
    examples := []string{
        "github",                    // Provider name only
        "aws:v23.11.00234",         // Provider with version tag
        "google@abc123def456",      // Provider with SHA reference
    }

    for _, providerStr := range examples {
        designation, err := nomenclature.ExtractProviderDesignation(providerStr)
        if err != nil {
            fmt.Printf("Error parsing '%s': %v\n", providerStr, err)
            continue
        }

        fmt.Printf("Input: %s\n", providerStr)
        fmt.Printf("  Name: %s\n", designation.Name)

        if designation.Tag != "" {
            fmt.Printf("  Version: %s\n", designation.Tag)
        } else if designation.Tag == nomenclature.FallbackProviderVersionTag {
            fmt.Printf("  Version: %s (default)\n", designation.Tag)
        }

        if designation.Sha != "" {
            fmt.Printf("  SHA: %s\n", designation.Sha)
        }
        fmt.Println()
    }

    // Output:
    // Input: github
    //   Name: github
    //   Version: v00.00.00000 (default)
    //
    // Input: aws:v23.11.00234
    //   Name: aws
    //   Version: v23.11.00234
    //
    // Input: google@abc123def456
    //   Name: google
    //   SHA: abc123def456
}
```

--------------------------------

### Verify File Signature with Certificate Chain

Source: https://context7.com/stackql/stackql-provider-registry/llms.txt

Verifies file signatures using certificates with full chain of trust validation and timestamp checking. This function requires the paths to CA bundles and signing certificates, along with a regex for local certificate matching. It outputs whether the signature is valid and its timestamp if available.

```go
package main

import (
    "fmt"
    "github.com/stackql/stackql-provider-registry/signing/Ed25519/app/edcrypto"
)

func verifyProviderDocument() error {
    // Configure verifier with embedded and local certificates
    verifierConfig := edcrypto.NewVerifierConfig(
        "/path/to/ca-bundle.pem",           // Local CA certificates
        "/path/to/signing-certs.pem",       // Local signing certificates
        "https://registry\.stackql\.app", // Regex for local cert matching
    )

    verifier, err := edcrypto.NewVerifier(verifierConfig)
    if err != nil {
        return fmt.Errorf("verifier creation failed: %w", err)
    }

    // Verify file signature with strict mode (full chain validation)
    fileToVerify := "providers/src/github/v00.00.00000/provider.yaml"
    signatureFile := fileToVerify + ".sig"
    signatureFormat := "base64"
    strictMode := true

    response, err := verifier.VerifyFileFromCertificate(
        fileToVerify,
        signatureFile,
        signatureFormat,
        strictMode,
    )
    if err != nil {
        return fmt.Errorf("verification failed: %w", err)
    }

    if response.IsVerified {
        fmt.Printf("✓ Signature valid for %s\n", fileToVerify)
        if response.Sig.HasTimestamp() {
            fmt.Printf("  Signed at: %v\n", response.Sig.GetTimestamp())
        }
    } else {
        fmt.Printf("✗ Signature invalid for %s\n", fileToVerify)
    }

    return nil
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.