Develop

.github/workflows/http-tests.yml

@@ -33,6 +33,11 @@ jobs:
       - name: Add bin/ and its subdirectories to PATH
         run: |
           find "$GITHUB_WORKSPACE/bin" -type d >> "$GITHUB_PATH"
+      - name: Build the ldh CLI
+        run: mvn -B package # the CLI unit tests run here; the suite drives ldh for its fixtures
+        working-directory: cli
+      - name: Add the ldh launcher to PATH
+        run: echo "$GITHUB_WORKSPACE/cli/bin" >> "$GITHUB_PATH"
       - name: Generating server certificate
         run: |
           server-cert-gen.sh .env nginx ssl
@@ -46,11 +51,22 @@ jobs:
         shell: bash
       - name: Enable graph versioning
         if: env.VERSIONING_TEST_TOKEN != ''
+        env:
+          GH_TOKEN: ${{ secrets.VERSIONING_TEST_TOKEN }}
         run: |
+          # Each run commits to its own branch. The Contents API takes an optimistic lock on the branch
+          # head rather than the file, so concurrent runs sharing one branch lose the race against each
+          # other; versioning is best-effort and async, so the lost commits surface as unrelated test
+          # timeouts. A per-run path prefix isolates the files but not the head, which is the contended part.
+          branch="ci-${{ github.run_id }}"
+          base_sha=$(gh api "repos/$VERSIONING_TEST_REPO/git/ref/heads/main" --jq '.object.sha')
+          gh api "repos/$VERSIONING_TEST_REPO/git/refs" -f ref="refs/heads/$branch" -f sha="$base_sha" > /dev/null
+          echo "Created versioning test branch '$branch' at ${base_sha:0:9}"
+
           printf '@prefix a:\t<https://w3id.org/atomgraph/core#> .\n\n<urn:linkeddatahub:versioning/end-user>\n{\n    <urn:linkeddatahub:versioning/end-user> a:authToken "%s" .\n}\n' "$VERSIONING_TEST_TOKEN" > ./secrets/credentials.trig
           cat >> ./http-tests/config/system.trig <<EOF
 
-          # GitHub-backed graph versioning (appended by CI; per-run path prefix isolates concurrent runs)
+          # GitHub-backed graph versioning (appended by CI; per-run branch isolates concurrent runs)
 
           @prefix doap:	<http://usefulinc.com/ns/doap#> .
           @prefix github:	<https://w3id.org/atomgraph/linkeddatahub/services/github#> .
@@ -64,27 +80,29 @@ jobs:
           {
               <urn:linkeddatahub:versioning/end-user> a doap:GitRepository ;
                   doap:location <https://github.com/$VERSIONING_TEST_REPO> ;
-                  github:branch "main" ;
+                  github:branch "$branch" ;
                   github:pathPrefix "graphs-${{ github.run_id }}" .
           }
           EOF
           echo "COMPOSE_VERSIONING=-f ./http-tests/docker-compose.versioning.yml" >> "$GITHUB_ENV"
           echo "VERSIONING_PATH_PREFIX=graphs-${{ github.run_id }}" >> "$GITHUB_ENV"
+          echo "VERSIONING_TEST_BRANCH=$branch" >> "$GITHUB_ENV"
         shell: bash
       - name: Build Docker image & Run Docker containers
         run: docker compose -f docker-compose.yml -f ./http-tests/docker-compose.http-tests.yml ${COMPOSE_VERSIONING:-} --env-file ./http-tests/.env up --build -d
       - name: Wait for the server to start...
         run: while ! (status=$(curl -k -s -w "%{http_code}\n" https://localhost:4443 -o /dev/null) && echo "$status" && echo "$status" | grep "403") ; do sleep 1 ; done # wait for the webapp to start (returns 403 by default)
       - name: Fix certificate permissions on the host
         run: |
-          sudo chmod 644 ./ssl/owner/cert.pem ./ssl/secretary/cert.pem
+          sudo chmod 644 ./ssl/owner/cert.pem ./ssl/secretary/cert.pem ./ssl/owner/keystore.p12 ./ssl/secretary/keystore.p12
         working-directory: http-tests
       - name: Run HTTP test scripts
         run: ./run.sh "$PWD/ssl/owner/cert.pem" "${{ secrets.HTTP_TEST_OWNER_CERT_PASSWORD }}" "$PWD/ssl/secretary/cert.pem" "${{ secrets.HTTP_TEST_SECRETARY_CERT_PASSWORD }}"
         shell: bash
         working-directory: http-tests
         env:
           GITHUB_TOKEN: ${{ secrets.VERSIONING_TEST_TOKEN }} # the versioning suite (and its gh api calls) authenticate with this; empty = suite skips
+          VERSIONING_TEST_BRANCH: ${{ env.VERSIONING_TEST_BRANCH }} # the per-run branch the suite polls; unset = main
       - name: Generate test summary
         if: always()
         run: python3 scripts/generate_test_summary.py http-tests/out http-tests/out/report.md
@@ -104,6 +122,11 @@ jobs:
       - name: Dump Tomcat logs from linkeddatahub container on failure
         if: failure()
         run: docker compose --env-file ./http-tests/.env exec -T linkeddatahub sh -c 'for f in /usr/local/tomcat/logs/*; do echo "=== $f ==="; cat "$f"; done' || true
+      - name: Delete the versioning test branch
+        if: always() && env.VERSIONING_TEST_BRANCH != ''
+        env:
+          GH_TOKEN: ${{ secrets.VERSIONING_TEST_TOKEN }}
+        run: gh api -X DELETE "repos/$VERSIONING_TEST_REPO/git/refs/heads/$VERSIONING_TEST_BRANCH" || true
       - name: Stop Docker containers and remove volumes
         run: docker compose --env-file ./http-tests/.env down -v
       - name: Remove Docker containers

.github/workflows/release.yml

@@ -0,0 +1,91 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - '*'
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Login to Docker Hub
+        uses: docker/login-action@v4
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Extract version parts
+        id: version
+        run: |
+          RAW_REF="${{ github.ref_name }}"
+          # strip the literal prefix
+          VERSION="${RAW_REF#linkeddatahub-}"
+          MAJOR="${VERSION%%.*}"
+          MINOR="${VERSION%.*}"
+          MINOR="${MINOR#*.}"
+          echo "MAJOR=$MAJOR" >> $GITHUB_ENV
+          echo "MINOR=$MAJOR.$MINOR" >> $GITHUB_ENV
+          echo "FULL_VERSION=$VERSION" >> $GITHUB_ENV
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: |
+            atomgraph/linkeddatahub:latest
+            atomgraph/linkeddatahub:${{ env.FULL_VERSION }}
+            atomgraph/linkeddatahub:${{ env.MINOR }}
+            atomgraph/linkeddatahub:${{ env.MAJOR }}
+
+  cli:
+    name: Attach the ldh CLI to the release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # gh release create/upload
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Set up Java 21
+        uses: actions/setup-java@v5
+        with:
+          distribution: 'temurin'
+          java-version: '21'
+          cache: maven
+
+      - name: Extract version
+        run: |
+          RAW_REF="${{ github.ref_name }}"
+          # strip the literal prefix
+          echo "FULL_VERSION=${RAW_REF#linkeddatahub-}" >> $GITHUB_ENV
+
+      # release.sh keeps cli/pom.xml at the platform version, so the tagged commit already carries it
+      # and the jar manifest ldh --version reads gets it from there
+      - name: Build the ldh CLI
+        run: mvn -B package
+        working-directory: cli
+
+      # the launcher prefers a jar beside it, so the archive runs from wherever it is unpacked
+      - name: Package the archive
+        run: |
+          mkdir -p "ldh-${FULL_VERSION}"
+          cp cli/bin/ldh cli/target/ldh.jar "ldh-${FULL_VERSION}/"
+          tar -czf "ldh-${FULL_VERSION}.tar.gz" "ldh-${FULL_VERSION}"
+
+      - name: Attach to the release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # the tag may be pushed before the release exists (maven-release-plugin tags, the release
+          # is drafted afterwards), so create it if it is not there yet
+          gh release view "${{ github.ref_name }}" > /dev/null 2>&1 || \
+            gh release create "${{ github.ref_name }}" --title "${{ github.ref_name }}" --notes ""
+          gh release upload "${{ github.ref_name }}" "ldh-${FULL_VERSION}.tar.gz" --clobber

AGENTS.md

@@ -35,7 +35,7 @@ Writes go through the **document URLs**, never through the SPARQL endpoint (whic
 | Update a document in place | `PATCH` document URL | `Content-Type: application/sparql-update` | A SPARQL Update (`INSERT`/`DELETE`) applied to that named graph |
 | Delete a document | `DELETE` document URL | — | Removes the named graph |
 
-Relative URIs in a request body resolve against the target URL. See `bin/post.sh`, `bin/put.sh`, `bin/patch.sh`, `bin/delete.sh` for exact, working invocations.
+Relative URIs in a request body resolve against the target URL. The `ldh post`, `ldh put`, `ldh patch` and `ldh delete` commands are working implementations of the four rows above.
 
 ## Querying (read-only)
 
@@ -55,7 +55,7 @@ A single instance hosts multiple **dataspaces**, each a subdomain (origin). Each
 
 ## Tooling
 
-- **CLI**: the `bin/` scripts wrap every operation above (`get.sh`, `post.sh`, `put.sh`, `patch.sh`, `delete.sh`, `create-container.sh`, `create-item.sh`, `add-view.sh`, `add-select.sh`, `add-construct.sh`, `add-result-set-chart.sh`, `add-file.sh`, `webid-keygen.sh`). They are the authoritative reference for request shapes.
+- **CLI**: `ldh` (built from `cli/`) wraps every operation above — `get`, `post`, `put`, `patch`, `delete`, `create-container`, `create-item`, `add-view`, `add-select`, `add-construct`, `add-result-set-chart`, `add-file`, plus the `admin`, `content` and `imports` subcommand groups. It is the authoritative reference for request shapes. Authentication is a PKCS12 WebID keystore (`-f ssl/owner/keystore.p12 -p <password>`, or `LDH_CERT_FILE`/`LDH_CERT_PASSWORD`); commands print the created document's URL on stdout so they compose in pipelines. Certificate tooling (`webid-keygen.sh`, `server-cert-gen.sh`) remains in `bin/`; the `bin/` HTTP API scripts `ldh` replaces are deprecated.
 - **Programmatic / MCP**: [Web-Algebra](https://github.com/AtomGraph/Web-Algebra) is the recommended path for agent-composed workflows — a JSON DSL and MCP server whose operations (create container/item, add view/chart, generate portal, …) compose multi-step LDH writes atomically under WebID auth.
 
 ## Standards