docs(astrolabe): add config docs and unit tests for internal URL

Address PR #487 reviewer feedback:

- Add documentation for `astrolabe_internal_url` config option
- Add unit tests for `IdpTokenRefresher::getNextcloudBaseUrl()`
- Fix CI workflow paths (astroglobe -> astrolabe)
- Add PHPUnit job to CI workflow for PHP 8.1, 8.2, 8.3
- Remove obsolete ApiTest that tested non-existent method

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.github/workflows/astroglobe-ci.yml

@@ -11,7 +11,7 @@ name: Astroglobe CI
 on:
   pull_request:
     paths:
-      - 'third_party/astroglobe/**'
+      - 'third_party/astrolabe/**'
       - '.github/workflows/astroglobe-ci.yml'
 
 permissions:
@@ -37,18 +37,18 @@ jobs:
         with:
           filters: |
             frontend:
-              - 'third_party/astroglobe/src/**'
+              - 'third_party/astrolabe/src/**'
-              - 'third_party/astroglobe/package.json'
+              - 'third_party/astrolabe/package.json'
-              - 'third_party/astroglobe/package-lock.json'
+              - 'third_party/astrolabe/package-lock.json'
-              - 'third_party/astroglobe/vite.config.js'
+              - 'third_party/astrolabe/vite.config.js'
-              - 'third_party/astroglobe/**/*.js'
+              - 'third_party/astrolabe/**/*.js'
-              - 'third_party/astroglobe/**/*.ts'
+              - 'third_party/astrolabe/**/*.ts'
-              - 'third_party/astroglobe/**/*.vue'
+              - 'third_party/astrolabe/**/*.vue'
             php:
-              - 'third_party/astroglobe/lib/**'
+              - 'third_party/astrolabe/lib/**'
-              - 'third_party/astroglobe/appinfo/**'
+              - 'third_party/astrolabe/appinfo/**'
-              - 'third_party/astroglobe/composer.json'
+              - 'third_party/astrolabe/composer.json'
-              - 'third_party/astroglobe/psalm.xml'
+              - 'third_party/astrolabe/psalm.xml'
 
   # Node.js build and lint
   node-build:
@@ -58,7 +58,7 @@ jobs:
     name: Node.js build
     defaults:
       run:
-        working-directory: third_party/astroglobe
+        working-directory: third_party/astrolabe
     steps:
       - name: Checkout
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
@@ -67,7 +67,7 @@ jobs:
         uses: skjnldsv/read-package-engines-version-actions@06d6baf7d8f41934ab630e97d9e6c0bc9c9ac5e4 # v3
         id: versions
         with:
-          path: third_party/astroglobe
+          path: third_party/astrolabe
           fallbackNode: '^20'
           fallbackNpm: '^10'
 
@@ -99,7 +99,7 @@ jobs:
     name: ESLint
     defaults:
       run:
-        working-directory: third_party/astroglobe
+        working-directory: third_party/astrolabe
     steps:
       - name: Checkout
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
@@ -108,7 +108,7 @@ jobs:
         uses: skjnldsv/read-package-engines-version-actions@06d6baf7d8f41934ab630e97d9e6c0bc9c9ac5e4 # v3
         id: versions
         with:
-          path: third_party/astroglobe
+          path: third_party/astrolabe
           fallbackNode: '^20'
           fallbackNpm: '^10'
 
@@ -137,7 +137,7 @@ jobs:
     name: Stylelint
     defaults:
       run:
-        working-directory: third_party/astroglobe
+        working-directory: third_party/astrolabe
     steps:
       - name: Checkout
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
@@ -146,7 +146,7 @@ jobs:
         uses: skjnldsv/read-package-engines-version-actions@06d6baf7d8f41934ab630e97d9e6c0bc9c9ac5e4 # v3
         id: versions
         with:
-          path: third_party/astroglobe
+          path: third_party/astrolabe
           fallbackNode: '^20'
           fallbackNpm: '^10'
 
@@ -175,7 +175,7 @@ jobs:
     name: PHP CS Fixer
     defaults:
       run:
-        working-directory: third_party/astroglobe
+        working-directory: third_party/astrolabe
     steps:
       - name: Checkout
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
@@ -184,7 +184,7 @@ jobs:
         id: versions
         uses: icewind1991/nextcloud-version-matrix@58becf3b4bb6dc6cef677b15e2fd8e7d48c0908f # v1.3.1
         with:
-          filename: third_party/astroglobe/appinfo/info.xml
+          filename: third_party/astrolabe/appinfo/info.xml
 
       - name: Set up php${{ steps.versions.outputs.php-min }}
         uses: shivammathur/setup-php@cf4cade2721270509d5b1c766ab3549210a39a2a # v2.33.0
@@ -212,7 +212,7 @@ jobs:
     name: Psalm
     defaults:
       run:
-        working-directory: third_party/astroglobe
+        working-directory: third_party/astrolabe
     steps:
       - name: Checkout
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
@@ -221,7 +221,7 @@ jobs:
         id: versions
         uses: icewind1991/nextcloud-version-matrix@58becf3b4bb6dc6cef677b15e2fd8e7d48c0908f # v1.3.1
         with:
-          filename: third_party/astroglobe/appinfo/info.xml
+          filename: third_party/astrolabe/appinfo/info.xml
 
       - name: Set up php${{ steps.versions.outputs.php-min }}
         uses: shivammathur/setup-php@cf4cade2721270509d5b1c766ab3549210a39a2a # v2.33.0
@@ -242,7 +242,7 @@ jobs:
         id: ocp-versions
         uses: icewind1991/nextcloud-version-matrix@58becf3b4bb6dc6cef677b15e2fd8e7d48c0908f # v1.3.1
         with:
-          filename: third_party/astroglobe/appinfo/info.xml
+          filename: third_party/astrolabe/appinfo/info.xml
 
       - name: Install OCP for static analysis
         run: |
@@ -253,12 +253,60 @@ jobs:
       - name: Run Psalm
         run: composer run psalm -- --threads=1 --monochrome --no-progress --output-format=github
 
+  # PHPUnit Tests
+  phpunit:
+    runs-on: ubuntu-latest
+    needs: changes
+    if: needs.changes.outputs.php != 'false'
+    defaults:
+      run:
+        working-directory: third_party/astrolabe
+
+    strategy:
+      matrix:
+        php-versions: ['8.1', '8.2', '8.3']
+
+    name: PHPUnit (PHP ${{ matrix.php-versions }})
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Set up PHP ${{ matrix.php-versions }}
+        uses: shivammathur/setup-php@cf4cade2721270509d5b1c766ab3549210a39a2a # v2.33.0
+        with:
+          php-version: ${{ matrix.php-versions }}
+          extensions: ctype, curl, dom, gd, iconv, intl, json, mbstring, openssl, posix, sqlite, xml, zip
+          coverage: none
+          ini-file: development
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install dependencies
+        run: |
+          composer remove nextcloud/ocp --dev || true
+          composer i
+
+      - name: Get OCP version matrix
+        id: ocp-versions
+        uses: icewind1991/nextcloud-version-matrix@58becf3b4bb6dc6cef677b15e2fd8e7d48c0908f # v1.3.1
+        with:
+          filename: third_party/astrolabe/appinfo/info.xml
+
+      - name: Install OCP for testing
+        run: |
+          OCP_VERSION=$(echo '${{ steps.ocp-versions.outputs.ocp-matrix }}' | jq -r '.include[0]."ocp-version"')
+          composer require --dev "nextcloud/ocp:$OCP_VERSION" --ignore-platform-reqs --with-dependencies
+
+      - name: Run PHPUnit
+        run: composer run test:unit
+
   # Summary job
   summary:
     permissions:
       contents: none
     runs-on: ubuntu-latest
-    needs: [changes, node-build, eslint, stylelint, php-cs, psalm]
+    needs: [changes, node-build, eslint, stylelint, php-cs, psalm, phpunit]
     if: always()
     name: astroglobe-ci-summary
     steps:
@@ -268,7 +316,7 @@ jobs:
             echo "Frontend checks failed"
             exit 1
           fi
-          if ${{ needs.changes.outputs.php != 'false' && (needs.php-cs.result != 'success' || needs.psalm.result != 'success') }}; then
+          if ${{ needs.changes.outputs.php != 'false' && (needs.php-cs.result != 'success' || needs.psalm.result != 'success' || needs.phpunit.result != 'success') }}; then
             echo "PHP checks failed"
             exit 1
           fi

docs/configuration.md

@@ -531,6 +531,28 @@ docker-compose up
 
 ---
 
+## Astrolabe Internal URL
+
+The Astrolabe Nextcloud app may need to make internal HTTP requests to the local web server (e.g., for OAuth token refresh). By default, it uses `http://localhost` which works for standard Docker containers where PHP and Apache run together.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `astrolabe_internal_url` | Internal URL for server-to-server requests within container | `http://localhost` |
+
+**When to configure:**
+- Custom container setups where the internal web server is not on `localhost:80`
+- Kubernetes deployments with service discovery
+- Multi-container setups with separate web server containers
+
+**Example (Nextcloud config.php):**
+```php
+'astrolabe_internal_url' => 'http://web-server.internal:8080',
+```
+
+**Note:** This is for internal PHP-to-Apache requests, NOT for external client URLs. The default (`http://localhost`) works for standard Docker containers where PHP and Apache run together.
+
+---
+
 ## Loading Environment Variables
 
 After creating your `.env` file, load the environment variables:

third_party/astrolabe/.gitignore

@@ -12,3 +12,4 @@ build/
 node_modules/
 js/
 css/
+.phpunit.cache/

third_party/astrolabe/composer.json

@@ -14,6 +14,11 @@
 			"OCA\\Astrolabe\\": "lib/"
 		}
 	},
+	"autoload-dev": {
+		"psr-4": {
+			"OCP\\": "vendor/nextcloud/ocp/OCP/"
+		}
+	},
 	"scripts": {
 		"post-install-cmd": [
 			"@composer bin all install --ansi"
@@ -25,7 +30,7 @@
 		"cs:check": "php-cs-fixer fix --dry-run --diff",
 		"cs:fix": "php-cs-fixer fix",
 		"psalm": "psalm --threads=1 --no-cache",
-		"test:unit": "phpunit tests -c tests/phpunit.xml --colors=always --fail-on-warning --fail-on-risky",
+		"test:unit": "./vendor/bin/phpunit -c tests/unit/phpunit.xml --colors=always",
 		"openapi": "generate-spec",
 		"rector": "rector && composer cs:fix"
 	},
@@ -35,6 +40,7 @@
 	},
 	"require-dev": {
 		"nextcloud/ocp": "dev-stable30",
+		"phpunit/phpunit": "^10.0",
 		"roave/security-advisories": "dev-latest"
 	},
 	"config": {

third_party/astrolabe/tests/unit/Controller/ApiTest.php

@@ -1,19 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Controller;
-
-use OCA\Astrolabe\AppInfo\Application;
-use OCA\Astrolabe\Controller\ApiController;
-use OCP\IRequest;
-use PHPUnit\Framework\TestCase;
-
-final class ApiTest extends TestCase {
-	public function testIndex(): void {
-		$request = $this->createMock(IRequest::class);
-		$controller = new ApiController(Application::APP_ID, $request);
-
-		$this->assertEquals($controller->index()->getData()['message'], 'Hello world!');
-	}
-}

third_party/astrolabe/tests/unit/Service/IdpTokenRefresherTest.php

@@ -0,0 +1,79 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Service;
+
+use OCA\Astrolabe\Service\IdpTokenRefresher;
+use OCA\Astrolabe\Service\McpServerClient;
+use OCP\Http\Client\IClient;
+use OCP\Http\Client\IClientService;
+use OCP\IConfig;
+use PHPUnit\Framework\MockObject\MockObject;
+use PHPUnit\Framework\TestCase;
+use Psr\Log\LoggerInterface;
+
+/**
+ * Unit tests for IdpTokenRefresher::getNextcloudBaseUrl().
+ *
+ * Tests the internal URL resolution logic for OAuth token refresh requests.
+ */
+final class IdpTokenRefresherTest extends TestCase {
+	private IConfig&MockObject $config;
+	private IClientService&MockObject $clientService;
+	private LoggerInterface&MockObject $logger;
+	private McpServerClient&MockObject $mcpServerClient;
+	private IdpTokenRefresher $refresher;
+
+	protected function setUp(): void {
+		parent::setUp();
+
+		$this->config = $this->createMock(IConfig::class);
+		$this->clientService = $this->createMock(IClientService::class);
+		$this->logger = $this->createMock(LoggerInterface::class);
+		$this->mcpServerClient = $this->createMock(McpServerClient::class);
+
+		$mockClient = $this->createMock(IClient::class);
+		$this->clientService->method('newClient')->willReturn($mockClient);
+
+		$this->refresher = new IdpTokenRefresher(
+			$this->config,
+			$this->clientService,
+			$this->logger,
+			$this->mcpServerClient
+		);
+	}
+
+	/**
+	 * @dataProvider provideBaseUrlTestCases
+	 */
+	public function testGetNextcloudBaseUrl(string $configValue, string $expected): void {
+		$this->config->method('getSystemValue')
+			->with('astrolabe_internal_url', '')
+			->willReturn($configValue);
+
+		// Use reflection to test private method
+		$reflection = new \ReflectionClass($this->refresher);
+		$method = $reflection->getMethod('getNextcloudBaseUrl');
+		$method->setAccessible(true);
+
+		$result = $method->invoke($this->refresher);
+
+		$this->assertEquals($expected, $result);
+	}
+
+	/**
+	 * Provides test cases for getNextcloudBaseUrl().
+	 *
+	 * @return array<string, array{string, string}>
+	 */
+	public static function provideBaseUrlTestCases(): array {
+		return [
+			'default - no config' => ['', 'http://localhost'],
+			'custom internal url' => ['http://web:8080', 'http://web:8080'],
+			'custom url with trailing slash' => ['http://web:8080/', 'http://web:8080'],
+			'kubernetes service' => ['http://nextcloud.default.svc:80', 'http://nextcloud.default.svc:80'],
+			'https internal url' => ['https://internal.example.com', 'https://internal.example.com'],
+		];
+	}
+}

third_party/astrolabe/tests/unit/bootstrap.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Bootstrap for unit tests.
+ *
+ * Unit tests use mocked dependencies and don't require a full Nextcloud
+ * environment. This bootstrap only loads the composer autoloader which
+ * includes the OCP interface definitions needed for mocking.
+ */
+
+require_once __DIR__ . '/../../vendor/autoload.php';

third_party/astrolabe/tests/unit/phpunit.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="utf-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         bootstrap="bootstrap.php"
+         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.5/phpunit.xsd"
+         colors="true"
+         failOnWarning="true"
+         failOnRisky="true"
+         cacheDirectory=".phpunit.cache">
+    <testsuite name="Astrolabe Unit Tests">
+        <directory suffix="Test.php">.</directory>
+    </testsuite>
+    <source>
+        <include>
+            <directory suffix=".php">../../lib</directory>
+        </include>
+    </source>
+</phpunit>