From 45a9a6cdc39bb5893e5b3276be0106202b8d9a96 Mon Sep 17 00:00:00 2001 From: harsh mahajan Date: Thu, 23 Jul 2026 12:55:50 +0530 Subject: [PATCH 01/10] [TEMP/TESTING] Point utopia-php/vcs at unreleased feat/gitlab-list-namespaces Testing GitLab::listNamespaces() (utopia-php/vcs#122) on staging before it's released. Do not merge -- revert to the pinned release version once the vcs PR merges and a real release is cut. --- composer.json | 6 +++++- composer.lock | 39 +++++++++++++++++++++++++++++---------- 2 files changed, 34 insertions(+), 11 deletions(-) diff --git a/composer.json b/composer.json index c598d5ec66..b29cb6dfa8 100644 --- a/composer.json +++ b/composer.json @@ -41,6 +41,10 @@ { "type": "vcs", "url": "https://github.com/utopia-php/auth" + }, + { + "type": "vcs", + "url": "https://github.com/utopia-php/vcs" } ], "require": { @@ -96,7 +100,7 @@ "utopia-php/telemetry": "^0.4", "utopia-php/user-agent": "0.1.*", "mustangostang/spyc": "0.6.*", - "utopia-php/vcs": "^4.4.2", + "utopia-php/vcs": "dev-feat/gitlab-list-namespaces", "utopia-php/websocket": "1.0.*", "dragonmantank/cron-expression": "3.4.*", "phpmailer/phpmailer": "6.9.*", diff --git a/composer.lock b/composer.lock index b5e0346c26..1ddbaad483 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "7a2821539fc6e6063587e38e3eca19c4", + "content-hash": "54c4b8e9607f4b8b1ce387ad27d2726c", "packages": [ { "name": "adhocore/jwt", @@ -5165,16 +5165,16 @@ }, { "name": "utopia-php/vcs", - "version": "4.4.4", + "version": "dev-feat/gitlab-list-namespaces", "source": { "type": "git", "url": "https://github.com/utopia-php/vcs.git", - "reference": "37580b1a459c6b51f567b1720c118a8a0213f314" + "reference": "8bd586e9eae0f622b1a728c5b0269369b3efdde2" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/vcs/zipball/37580b1a459c6b51f567b1720c118a8a0213f314", - "reference": "37580b1a459c6b51f567b1720c118a8a0213f314", + "url": "https://api.github.com/repos/utopia-php/vcs/zipball/8bd586e9eae0f622b1a728c5b0269369b3efdde2", + "reference": "8bd586e9eae0f622b1a728c5b0269369b3efdde2", "shasum": "" }, "require": { @@ -5195,7 +5195,25 @@ "Utopia\\VCS\\": "src/VCS" } }, - "notification-url": "https://packagist.org/downloads/", + "autoload-dev": { + "psr-4": { + "Utopia\\Tests\\": "tests/VCS" + } + }, + "scripts": { + "lint": [ + "./vendor/bin/pint --test --config pint.json" + ], + "format": [ + "./vendor/bin/pint --config pint.json" + ], + "check": [ + "./vendor/bin/phpstan analyse --level 8 --memory-limit 512M -c phpstan.neon src tests" + ], + "test": [ + "./vendor/bin/phpunit --configuration phpunit.xml --debug" + ] + }, "license": [ "MIT" ], @@ -5207,10 +5225,10 @@ "vcs" ], "support": { - "issues": "https://github.com/utopia-php/vcs/issues", - "source": "https://github.com/utopia-php/vcs/tree/4.4.4" + "source": "https://github.com/utopia-php/vcs/tree/feat/gitlab-list-namespaces", + "issues": "https://github.com/utopia-php/vcs/issues" }, - "time": "2026-07-22T10:18:04+00:00" + "time": "2026-07-23T07:17:43+00:00" }, { "name": "utopia-php/websocket", @@ -8398,7 +8416,8 @@ "minimum-stability": "dev", "stability-flags": { "utopia-php/http": 5, - "utopia-php/platform": 5 + "utopia-php/platform": 5, + "utopia-php/vcs": 20 }, "prefer-stable": true, "prefer-lowest": false, From 90c7f02ad191f0110617c604d325a11736d64ea1 Mon Sep 17 00:00:00 2001 From: harsh mahajan Date: Thu, 23 Jul 2026 14:13:53 +0530 Subject: [PATCH 02/10] Add GET /v1/vcs/installations/:installationId/namespaces endpoint Exposes GitLab::listNamespaces() (utopia-php/vcs#122) so the console can build a group/namespace picker after OAuth connect -- GitLab has no per-installation org scoping like GitHub's App flow, so there's nowhere else in the stack that knows about a user's groups. For providers without listNamespaces() (currently everything but GitLab), falls back to a single-item list wrapping the installation's own organization, so the response shape stays uniform for callers. --- app/init/models.php | 3 + .../Http/Installations/Namespaces/XList.php | 119 ++++++++++++++++++ .../Platform/Modules/VCS/Services/Http.php | 2 + src/Appwrite/Utopia/Response.php | 2 + .../Utopia/Response/Model/VcsNamespace.php | 64 ++++++++++ 5 files changed, 190 insertions(+) create mode 100644 src/Appwrite/Platform/Modules/VCS/Http/Installations/Namespaces/XList.php create mode 100644 src/Appwrite/Utopia/Response/Model/VcsNamespace.php diff --git a/app/init/models.php b/app/init/models.php index 55101a27b8..d3b776b2bd 100644 --- a/app/init/models.php +++ b/app/init/models.php @@ -224,6 +224,7 @@ use Appwrite\Utopia\Response\Model\UsageVectorsDBs; use Appwrite\Utopia\Response\Model\User; use Appwrite\Utopia\Response\Model\Variable; use Appwrite\Utopia\Response\Model\VcsContent; +use Appwrite\Utopia\Response\Model\VcsNamespace; use Appwrite\Utopia\Response\Model\VectorsDBCollection; use Appwrite\Utopia\Response\Model\Webhook; @@ -259,6 +260,8 @@ Response::setModel(new BaseList('Function Templates List', Response::MODEL_TEMPL Response::setModel(new BaseList('Installations List', Response::MODEL_INSTALLATION_LIST, 'installations', Response::MODEL_INSTALLATION)); Response::setModel(new ProviderRepositoryFrameworkList()); Response::setModel(new ProviderRepositoryRuntimeList()); +Response::setModel(new VcsNamespace()); +Response::setModel(new BaseList('VCS Namespaces List', Response::MODEL_VCS_NAMESPACE_LIST, 'namespaces', Response::MODEL_VCS_NAMESPACE)); Response::setModel(new BaseList('Branches List', Response::MODEL_BRANCH_LIST, 'branches', Response::MODEL_BRANCH)); Response::setModel(new BaseList('Frameworks List', Response::MODEL_FRAMEWORK_LIST, 'frameworks', Response::MODEL_FRAMEWORK)); Response::setModel(new BaseList('Runtimes List', Response::MODEL_RUNTIME_LIST, 'runtimes', Response::MODEL_RUNTIME)); diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Installations/Namespaces/XList.php b/src/Appwrite/Platform/Modules/VCS/Http/Installations/Namespaces/XList.php new file mode 100644 index 0000000000..ef3fc3acbb --- /dev/null +++ b/src/Appwrite/Platform/Modules/VCS/Http/Installations/Namespaces/XList.php @@ -0,0 +1,119 @@ +setHttpMethod(Action::HTTP_REQUEST_METHOD_GET) + ->setHttpPath('/v1/vcs/installations/:installationId/namespaces') + ->desc('List namespaces') + ->groups(['api', 'vcs']) + ->label('scope', 'vcs.read') + ->label('resourceType', RESOURCE_TYPE_VCS) + ->label('sdk', new Method( + namespace: 'vcs', + group: 'installations', + name: 'listNamespaces', + description: '/docs/references/vcs/list-namespaces.md', + auth: [AuthType::ADMIN], + responses: [ + new SDKResponse( + code: Response::STATUS_CODE_OK, + model: Response::MODEL_VCS_NAMESPACE_LIST, + ) + ] + )) + ->param('installationId', '', new Text(256), 'Installation Id') + ->param('search', '', new Text(256), 'Search term to filter your list results. Max length: 256 chars.', true) + ->param('queries', [], new Queries([new Limit(), new Offset()]), 'Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Only supported methods are limit and offset', true) + ->inject('vcsFactory') + ->inject('installationTokens') + ->inject('response') + ->inject('dbForPlatform') + ->callback($this->action(...)); + } + + public function action( + string $installationId, + string $search, + array $queries, + VcsFactory $vcsFactory, + InstallationTokens $installationTokens, + Response $response, + Database $dbForPlatform + ) { + $installation = $dbForPlatform->getDocument('installations', $installationId); + + if ($installation->isEmpty()) { + throw new Exception(Exception::INSTALLATION_NOT_FOUND); + } + + $installation = $installationTokens->refreshForInstallation($installation, $dbForPlatform, $vcsFactory); + $vcs = $vcsFactory->fromInstallation($installation); + + $queries = Query::parseQueries($queries); + $limitQuery = current(array_filter($queries, fn ($query) => $query->getMethod() === Query::TYPE_LIMIT)); + $offsetQuery = current(array_filter($queries, fn ($query) => $query->getMethod() === Query::TYPE_OFFSET)); + + $limit = !empty($limitQuery) ? $limitQuery->getValue() : 20; + $offset = !empty($offsetQuery) ? $offsetQuery->getValue() : 0; + + if ($offset % $limit !== 0) { + throw new Exception(Exception::GENERAL_ARGUMENT_INVALID, 'offset must be a multiple of the limit'); + } + + $page = ($offset / $limit) + 1; + + // Only GitLab has more than one namespace per installation: GitHub's + // OAuth App flow already scopes an installation to a single org/user + // during authorization, so there's nothing else to list here. + if (\method_exists($vcs, 'listNamespaces')) { + ['items' => $namespaces, 'total' => $total] = $vcs->listNamespaces($page, $limit, $search); + } else { + $organization = $installation->getAttribute('organization', ''); + $matches = empty($search) || \stripos($organization, $search) !== false; + $namespaces = $matches ? [[ + 'id' => $installation->getAttribute('providerInstallationId', ''), + 'name' => $organization, + 'path' => $organization, + 'kind' => 'org', + 'avatarUrl' => '', + ]] : []; + $total = \count($namespaces); + } + + $namespaces = \array_map(fn ($namespace) => new Document($namespace), $namespaces); + + $response->dynamic(new Document([ + 'namespaces' => $namespaces, + 'total' => $total, + ]), Response::MODEL_VCS_NAMESPACE_LIST); + } +} diff --git a/src/Appwrite/Platform/Modules/VCS/Services/Http.php b/src/Appwrite/Platform/Modules/VCS/Services/Http.php index a9cedf40f6..063be6bd9d 100644 --- a/src/Appwrite/Platform/Modules/VCS/Services/Http.php +++ b/src/Appwrite/Platform/Modules/VCS/Services/Http.php @@ -14,6 +14,7 @@ use Appwrite\Platform\Modules\VCS\Http\Gitlab\Callback\Get as GetGitlabCallback; use Appwrite\Platform\Modules\VCS\Http\Gitlab\Events\Create as CreateGitlabEvent; use Appwrite\Platform\Modules\VCS\Http\Installations\Delete as DeleteInstallation; use Appwrite\Platform\Modules\VCS\Http\Installations\Get as GetInstallation; +use Appwrite\Platform\Modules\VCS\Http\Installations\Namespaces\XList as ListNamespaces; use Appwrite\Platform\Modules\VCS\Http\Installations\Repositories\Branches\XList as ListRepositoryBranches; use Appwrite\Platform\Modules\VCS\Http\Installations\Repositories\Contents\Get as GetRepositoryContents; use Appwrite\Platform\Modules\VCS\Http\Installations\Repositories\Create as CreateRepository; @@ -46,6 +47,7 @@ class Http extends Service $this->addAction(GetInstallation::getName(), new GetInstallation()); $this->addAction(ListInstallations::getName(), new ListInstallations()); $this->addAction(DeleteInstallation::getName(), new DeleteInstallation()); + $this->addAction(ListNamespaces::getName(), new ListNamespaces()); // Repositories $this->addAction(CreateRepository::getName(), new CreateRepository()); diff --git a/src/Appwrite/Utopia/Response.php b/src/Appwrite/Utopia/Response.php index 156ebe532c..b5d85efc9e 100644 --- a/src/Appwrite/Utopia/Response.php +++ b/src/Appwrite/Utopia/Response.php @@ -195,6 +195,8 @@ class Response extends SwooleResponse public const MODEL_PROVIDER_REPOSITORY_FRAMEWORK_LIST = 'providerRepositoryFrameworkList'; public const MODEL_PROVIDER_REPOSITORY_RUNTIME = 'providerRepositoryRuntime'; public const MODEL_PROVIDER_REPOSITORY_RUNTIME_LIST = 'providerRepositoryRuntimeList'; + public const MODEL_VCS_NAMESPACE = 'vcsNamespace'; + public const MODEL_VCS_NAMESPACE_LIST = 'vcsNamespaceList'; public const MODEL_BRANCH = 'branch'; public const MODEL_BRANCH_LIST = 'branchList'; public const MODEL_DETECTION_FRAMEWORK = 'detectionFramework'; diff --git a/src/Appwrite/Utopia/Response/Model/VcsNamespace.php b/src/Appwrite/Utopia/Response/Model/VcsNamespace.php new file mode 100644 index 0000000000..dc0f38b07c --- /dev/null +++ b/src/Appwrite/Utopia/Response/Model/VcsNamespace.php @@ -0,0 +1,64 @@ +addRule('id', [ + 'type' => self::TYPE_STRING, + 'description' => 'VCS (Version Control System) namespace ID.', + 'default' => '', + 'example' => '5e5ea5c16897e', + ]) + ->addRule('name', [ + 'type' => self::TYPE_STRING, + 'description' => 'VCS (Version Control System) namespace display name.', + 'default' => '', + 'example' => 'Appwrite', + ]) + ->addRule('path', [ + 'type' => self::TYPE_STRING, + 'description' => 'VCS (Version Control System) namespace path, used as the owner when listing repositories.', + 'default' => '', + 'example' => 'appwrite', + ]) + ->addRule('kind', [ + 'type' => self::TYPE_STRING, + 'description' => 'Namespace kind. Either the user\'s personal namespace or a group/organization.', + 'default' => '', + 'example' => 'user', + ]) + ->addRule('avatarUrl', [ + 'type' => self::TYPE_STRING, + 'description' => 'Namespace avatar URL.', + 'default' => '', + 'example' => 'https://example.com/avatar.png', + ]); + } + + /** + * Get Name + * + * @return string + */ + public function getName(): string + { + return 'VcsNamespace'; + } + + /** + * Get Type + * + * @return string + */ + public function getType(): string + { + return Response::MODEL_VCS_NAMESPACE; + } +} From 2a107511a0b04fdc22336683a72e9c23d3d06921 Mon Sep 17 00:00:00 2001 From: harsh mahajan Date: Thu, 23 Jul 2026 14:19:23 +0530 Subject: [PATCH 03/10] Add docs for listNamespaces SDK method (required for spec generation) --- docs/references/vcs/list-namespaces.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/references/vcs/list-namespaces.md diff --git a/docs/references/vcs/list-namespaces.md b/docs/references/vcs/list-namespaces.md new file mode 100644 index 0000000000..51b09caaea --- /dev/null +++ b/docs/references/vcs/list-namespaces.md @@ -0,0 +1 @@ +Get a list of namespaces a VCS (Version Control System) installation can browse, such as the user's personal namespace and any groups they belong to. This is primarily useful for providers like GitLab, where a single OAuth authorization grants access to multiple namespaces with no per-installation selection step. For providers that already scope one installation to a single organization, this returns that organization as the only namespace. You can optionally filter namespaces using a search term. From dd6560447f617f3e9eab7933979986b872e09a41 Mon Sep 17 00:00:00 2001 From: harsh mahajan Date: Thu, 23 Jul 2026 14:29:26 +0530 Subject: [PATCH 04/10] Accept providerNamespace on listRepositories to browse other namespaces Without this, the new namespaces/groups picker would be cosmetic -- this endpoint always resolved the owner via getOwnerName(), which for GitLab only ever returns the personal namespace. Optional param, so existing callers that don't pass it keep the current behavior. --- .../Modules/VCS/Http/Installations/Repositories/XList.php | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/XList.php b/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/XList.php index 75e7dfab7a..1be88e514a 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/XList.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/XList.php @@ -97,6 +97,7 @@ class XList extends Action ->param('installationId', '', new Text(256), 'Installation Id') ->param('type', '', new WhiteList(['runtime', 'framework']), 'Detector type. Must be one of the following: runtime, framework', enum: new Enum(name: 'VCSDetectionType')) ->param('search', '', new Text(256), 'Search term to filter your list results. Max length: 256 chars.', true) + ->param('providerNamespace', '', new Text(256), 'Namespace (personal account or group) to list repositories from, as returned by listNamespaces\' `path` field. Defaults to the installation\'s own namespace.', true) ->param('queries', [], new Queries([new Limit(), new Offset()]), 'Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Only supported methods are limit and offset', true) ->inject('vcsFactory') ->inject('installationTokens') @@ -109,6 +110,7 @@ class XList extends Action string $installationId, string $type, string $search, + string $providerNamespace, array $queries, VcsFactory $vcsFactory, InstallationTokens $installationTokens, @@ -141,7 +143,7 @@ class XList extends Action } $page = ($offset / $limit) + 1; - $owner = $vcs->getOwnerName($providerInstallationId); + $owner = !empty($providerNamespace) ? $providerNamespace : $vcs->getOwnerName($providerInstallationId); ['items' => $repos, 'total' => $total] = $vcs->searchRepositories($owner, $page, $limit, $search); $repos = \array_map(function ($repo) use ($installation) { From 78c3c6b4cd4b9489fd998646c9ba7b2ec20a83b4 Mon Sep 17 00:00:00 2001 From: harsh mahajan Date: Thu, 23 Jul 2026 17:57:56 +0530 Subject: [PATCH 05/10] Bump utopia-php/vcs to pick up native /namespaces endpoint fix --- composer.lock | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/composer.lock b/composer.lock index 1ddbaad483..7ce9721b91 100644 --- a/composer.lock +++ b/composer.lock @@ -5169,12 +5169,12 @@ "source": { "type": "git", "url": "https://github.com/utopia-php/vcs.git", - "reference": "8bd586e9eae0f622b1a728c5b0269369b3efdde2" + "reference": "2423618e32a1b3d0dd3e8e4327b5f85561d90cf3" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/vcs/zipball/8bd586e9eae0f622b1a728c5b0269369b3efdde2", - "reference": "8bd586e9eae0f622b1a728c5b0269369b3efdde2", + "url": "https://api.github.com/repos/utopia-php/vcs/zipball/2423618e32a1b3d0dd3e8e4327b5f85561d90cf3", + "reference": "2423618e32a1b3d0dd3e8e4327b5f85561d90cf3", "shasum": "" }, "require": { @@ -5228,7 +5228,7 @@ "source": "https://github.com/utopia-php/vcs/tree/feat/gitlab-list-namespaces", "issues": "https://github.com/utopia-php/vcs/issues" }, - "time": "2026-07-23T07:17:43+00:00" + "time": "2026-07-23T12:23:30+00:00" }, { "name": "utopia-php/websocket", From 19f9a8824afed0d27c94ace98681baa31281bb79 Mon Sep 17 00:00:00 2001 From: harsh mahajan Date: Thu, 23 Jul 2026 19:02:49 +0530 Subject: [PATCH 06/10] Address VCS namespace review feedback --- docs/references/vcs/list-namespaces.md | 1 - .../Http/Installations/Namespaces/XList.php | 2 +- .../Http/Installations/Repositories/XList.php | 13 +++--- .../Queries/ProviderRepositories.php | 20 +++++++++ .../Validator/Query/ProviderOwner.php | 45 +++++++++++++++++++ 5 files changed, 72 insertions(+), 9 deletions(-) delete mode 100644 docs/references/vcs/list-namespaces.md create mode 100644 src/Appwrite/Utopia/Database/Validator/Queries/ProviderRepositories.php create mode 100644 src/Appwrite/Utopia/Database/Validator/Query/ProviderOwner.php diff --git a/docs/references/vcs/list-namespaces.md b/docs/references/vcs/list-namespaces.md deleted file mode 100644 index 51b09caaea..0000000000 --- a/docs/references/vcs/list-namespaces.md +++ /dev/null @@ -1 +0,0 @@ -Get a list of namespaces a VCS (Version Control System) installation can browse, such as the user's personal namespace and any groups they belong to. This is primarily useful for providers like GitLab, where a single OAuth authorization grants access to multiple namespaces with no per-installation selection step. For providers that already scope one installation to a single organization, this returns that organization as the only namespace. You can optionally filter namespaces using a search term. diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Installations/Namespaces/XList.php b/src/Appwrite/Platform/Modules/VCS/Http/Installations/Namespaces/XList.php index c01bf3c676..9849fcd451 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Installations/Namespaces/XList.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Installations/Namespaces/XList.php @@ -41,7 +41,7 @@ class XList extends Action namespace: 'vcs', group: 'namespaces', name: 'list', - description: '/docs/references/vcs/list-namespaces.md', + description: 'List provider namespaces available to a VCS installation. This can include the user personal namespace and any groups or organizations the installation can browse.', auth: [AuthType::ADMIN], responses: [ new SDKResponse( diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/XList.php b/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/XList.php index c8769c728c..2eabb6dd88 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/XList.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/XList.php @@ -7,6 +7,7 @@ use Appwrite\Platform\Action; use Appwrite\SDK\AuthType; use Appwrite\SDK\Method; use Appwrite\SDK\Response as SDKResponse; +use Appwrite\Utopia\Database\Validator\Queries\ProviderRepositories; use Appwrite\Utopia\Response; use Appwrite\Vcs\Factory as VcsFactory; use Appwrite\Vcs\InstallationTokens; @@ -17,9 +18,6 @@ use Utopia\Config\Exceptions\Parse; use Utopia\Database\Database; use Utopia\Database\Document; use Utopia\Database\Query; -use Utopia\Database\Validator\Queries; -use Utopia\Database\Validator\Query\Limit; -use Utopia\Database\Validator\Query\Offset; use Utopia\Detector\Detection\Framework\Analog; use Utopia\Detector\Detection\Framework\Angular; use Utopia\Detector\Detection\Framework\Astro; @@ -97,8 +95,7 @@ class XList extends Action ->param('installationId', '', new Text(256), 'Installation Id') ->param('type', '', new WhiteList(['runtime', 'framework']), 'Detector type. Must be one of the following: runtime, framework', enum: new Enum(name: 'VCSDetectionType')) ->param('search', '', new Text(256), 'Search term to filter your list results. Max length: 256 chars.', true) - ->param('providerNamespace', '', new Text(256), 'Namespace (personal account or group) to list repositories from, as returned by the namespaces endpoint\'s `path` field. Defaults to the installation\'s own namespace.', true) - ->param('queries', [], new Queries([new Limit(), new Offset()]), 'Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Only supported methods are limit and offset', true) + ->param('queries', [], new ProviderRepositories(), 'Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Only supported methods are limit, offset, and equal on owner.', true) ->inject('vcsFactory') ->inject('installationTokens') ->inject('response') @@ -110,7 +107,6 @@ class XList extends Action string $installationId, string $type, string $search, - string $providerNamespace, array $queries, VcsFactory $vcsFactory, InstallationTokens $installationTokens, @@ -134,16 +130,19 @@ class XList extends Action $queries = Query::parseQueries($queries); $limitQuery = current(array_filter($queries, fn ($query) => $query->getMethod() === Query::TYPE_LIMIT)); $offsetQuery = current(array_filter($queries, fn ($query) => $query->getMethod() === Query::TYPE_OFFSET)); + $ownerQueries = array_filter($queries, fn ($query) => $query->getMethod() === Query::TYPE_EQUAL && $query->getAttribute() === 'owner'); $limit = !empty($limitQuery) ? $limitQuery->getValue() : 4; $offset = !empty($offsetQuery) ? $offsetQuery->getValue() : 0; + $ownerQuery = current($ownerQueries); + $providerOwner = !empty($ownerQuery) ? $ownerQuery->getValue('') : ''; if ($offset % $limit !== 0) { throw new Exception(Exception::GENERAL_ARGUMENT_INVALID, 'offset must be a multiple of the limit'); } $page = ($offset / $limit) + 1; - $owner = !empty($providerNamespace) ? $providerNamespace : $vcs->getOwnerName($providerInstallationId); + $owner = !empty($providerOwner) ? $providerOwner : $vcs->getOwnerName($providerInstallationId); ['items' => $repos, 'total' => $total] = $vcs->searchRepositories($owner, $page, $limit, $search); $repos = \array_map(function ($repo) use ($installation) { diff --git a/src/Appwrite/Utopia/Database/Validator/Queries/ProviderRepositories.php b/src/Appwrite/Utopia/Database/Validator/Queries/ProviderRepositories.php new file mode 100644 index 0000000000..4713bd25e8 --- /dev/null +++ b/src/Appwrite/Utopia/Database/Validator/Queries/ProviderRepositories.php @@ -0,0 +1,20 @@ +message = 'Query must be an instance of Query'; + return false; + } + + if ($value->getMethod() !== Query::TYPE_EQUAL) { + $this->message = 'Only equal queries are supported for owner'; + return false; + } + + if ($value->getAttribute() !== 'owner') { + $this->message = 'Only owner can be queried'; + return false; + } + + if (\count($value->getValues()) !== 1) { + $this->message = 'Owner query must have exactly one value'; + return false; + } + + if (!(new Text(256))->isValid($value->getValue())) { + $this->message = 'Owner query value must be a string with a maximum length of 256 characters'; + return false; + } + + return true; + } +} From bcfdbc829ed4346862dcb1ed0ac33a45200d325a Mon Sep 17 00:00:00 2001 From: harsh mahajan Date: Thu, 23 Jul 2026 19:17:42 +0530 Subject: [PATCH 07/10] Address VCS namespace review feedback Rename owner terminology to namespace across the repositories listing endpoint, rename ProviderOwner/ProviderRepositories validators to VcsNamespace/VcsRepositories, rename VcsNamespace model's kind/id fields to type/$id, and relax the utopia-php/vcs composer constraint. --- composer.json | 2 +- .../Http/Installations/Namespaces/XList.php | 11 +++- .../Http/Installations/Repositories/XList.php | 14 ++--- ...erRepositories.php => VcsRepositories.php} | 6 +-- .../{ProviderOwner.php => VcsNamespace.php} | 12 ++--- .../Utopia/Response/Model/VcsNamespace.php | 8 +-- .../Validator/Queries/VcsRepositoriesTest.php | 41 ++++++++++++++ .../Validator/Query/VcsNamespaceTest.php | 54 +++++++++++++++++++ 8 files changed, 125 insertions(+), 23 deletions(-) rename src/Appwrite/Utopia/Database/Validator/Queries/{ProviderRepositories.php => VcsRepositories.php} (70%) rename src/Appwrite/Utopia/Database/Validator/Query/{ProviderOwner.php => VcsNamespace.php} (71%) create mode 100644 tests/unit/Utopia/Database/Validator/Queries/VcsRepositoriesTest.php create mode 100644 tests/unit/Utopia/Database/Validator/Query/VcsNamespaceTest.php diff --git a/composer.json b/composer.json index 6baa6b6123..c0c528c006 100644 --- a/composer.json +++ b/composer.json @@ -100,7 +100,7 @@ "utopia-php/telemetry": "^0.4", "utopia-php/user-agent": "0.1.*", "mustangostang/spyc": "0.6.*", - "utopia-php/vcs": "^4.4.5", + "utopia-php/vcs": "4.*.*", "utopia-php/websocket": "1.0.*", "dragonmantank/cron-expression": "3.4.*", "phpmailer/phpmailer": "6.9.*", diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Installations/Namespaces/XList.php b/src/Appwrite/Platform/Modules/VCS/Http/Installations/Namespaces/XList.php index 9849fcd451..b5c409ebc7 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Installations/Namespaces/XList.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Installations/Namespaces/XList.php @@ -99,15 +99,22 @@ class XList extends Action if (\method_exists($vcs, 'listNamespaces')) { ['items' => $namespaces, 'total' => $total] = $vcs->listNamespaces($page, $limit, $search); + $namespaces = \array_map(fn ($namespace) => [ + '$id' => $namespace['id'] ?? '', + 'name' => $namespace['name'] ?? '', + 'path' => $namespace['path'] ?? '', + 'type' => ($namespace['kind'] ?? '') === 'user' ? 'user' : 'organization', + 'avatarUrl' => $namespace['avatarUrl'] ?? '', + ], $namespaces); } else { $providerInstallationId = $installation->getAttribute('providerInstallationId', ''); $owner = $vcs->getOwnerName($providerInstallationId); $matches = empty($search) || \stripos($owner, $search) !== false; $namespaces = $matches ? [[ - 'id' => $providerInstallationId, + '$id' => $providerInstallationId, 'name' => $owner, 'path' => $owner, - 'kind' => $installation->getAttribute('personal', false) ? 'user' : 'organization', + 'type' => $installation->getAttribute('personal', false) ? 'user' : 'organization', 'avatarUrl' => '', ]] : []; $total = \count($namespaces); diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/XList.php b/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/XList.php index 2eabb6dd88..fc7059ccb0 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/XList.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/XList.php @@ -7,7 +7,7 @@ use Appwrite\Platform\Action; use Appwrite\SDK\AuthType; use Appwrite\SDK\Method; use Appwrite\SDK\Response as SDKResponse; -use Appwrite\Utopia\Database\Validator\Queries\ProviderRepositories; +use Appwrite\Utopia\Database\Validator\Queries\VcsRepositories; use Appwrite\Utopia\Response; use Appwrite\Vcs\Factory as VcsFactory; use Appwrite\Vcs\InstallationTokens; @@ -95,7 +95,7 @@ class XList extends Action ->param('installationId', '', new Text(256), 'Installation Id') ->param('type', '', new WhiteList(['runtime', 'framework']), 'Detector type. Must be one of the following: runtime, framework', enum: new Enum(name: 'VCSDetectionType')) ->param('search', '', new Text(256), 'Search term to filter your list results. Max length: 256 chars.', true) - ->param('queries', [], new ProviderRepositories(), 'Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Only supported methods are limit, offset, and equal on owner.', true) + ->param('queries', [], new VcsRepositories(), 'Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Only supported methods are limit, offset, and equal on namespace.', true) ->inject('vcsFactory') ->inject('installationTokens') ->inject('response') @@ -130,20 +130,20 @@ class XList extends Action $queries = Query::parseQueries($queries); $limitQuery = current(array_filter($queries, fn ($query) => $query->getMethod() === Query::TYPE_LIMIT)); $offsetQuery = current(array_filter($queries, fn ($query) => $query->getMethod() === Query::TYPE_OFFSET)); - $ownerQueries = array_filter($queries, fn ($query) => $query->getMethod() === Query::TYPE_EQUAL && $query->getAttribute() === 'owner'); + $namespaceQueries = array_filter($queries, fn ($query) => $query->getMethod() === Query::TYPE_EQUAL && $query->getAttribute() === 'namespace'); $limit = !empty($limitQuery) ? $limitQuery->getValue() : 4; $offset = !empty($offsetQuery) ? $offsetQuery->getValue() : 0; - $ownerQuery = current($ownerQueries); - $providerOwner = !empty($ownerQuery) ? $ownerQuery->getValue('') : ''; + $namespaceQuery = current($namespaceQueries); + $providerNamespace = !empty($namespaceQuery) ? $namespaceQuery->getValue('') : ''; if ($offset % $limit !== 0) { throw new Exception(Exception::GENERAL_ARGUMENT_INVALID, 'offset must be a multiple of the limit'); } $page = ($offset / $limit) + 1; - $owner = !empty($providerOwner) ? $providerOwner : $vcs->getOwnerName($providerInstallationId); - ['items' => $repos, 'total' => $total] = $vcs->searchRepositories($owner, $page, $limit, $search); + $namespace = !empty($providerNamespace) ? $providerNamespace : $vcs->getOwnerName($providerInstallationId); + ['items' => $repos, 'total' => $total] = $vcs->searchRepositories($namespace, $page, $limit, $search); $repos = \array_map(function ($repo) use ($installation) { $repo['id'] = \strval($repo['id'] ?? ''); diff --git a/src/Appwrite/Utopia/Database/Validator/Queries/ProviderRepositories.php b/src/Appwrite/Utopia/Database/Validator/Queries/VcsRepositories.php similarity index 70% rename from src/Appwrite/Utopia/Database/Validator/Queries/ProviderRepositories.php rename to src/Appwrite/Utopia/Database/Validator/Queries/VcsRepositories.php index 4713bd25e8..ada47ff42e 100644 --- a/src/Appwrite/Utopia/Database/Validator/Queries/ProviderRepositories.php +++ b/src/Appwrite/Utopia/Database/Validator/Queries/VcsRepositories.php @@ -2,19 +2,19 @@ namespace Appwrite\Utopia\Database\Validator\Queries; -use Appwrite\Utopia\Database\Validator\Query\ProviderOwner; +use Appwrite\Utopia\Database\Validator\Query\VcsNamespace; use Utopia\Database\Validator\Queries; use Utopia\Database\Validator\Query\Limit; use Utopia\Database\Validator\Query\Offset; -class ProviderRepositories extends Queries +class VcsRepositories extends Queries { public function __construct() { parent::__construct([ new Limit(), new Offset(), - new ProviderOwner(), + new VcsNamespace(), ]); } } diff --git a/src/Appwrite/Utopia/Database/Validator/Query/ProviderOwner.php b/src/Appwrite/Utopia/Database/Validator/Query/VcsNamespace.php similarity index 71% rename from src/Appwrite/Utopia/Database/Validator/Query/ProviderOwner.php rename to src/Appwrite/Utopia/Database/Validator/Query/VcsNamespace.php index 6a61b8972d..87486bd758 100644 --- a/src/Appwrite/Utopia/Database/Validator/Query/ProviderOwner.php +++ b/src/Appwrite/Utopia/Database/Validator/Query/VcsNamespace.php @@ -6,7 +6,7 @@ use Utopia\Database\Query; use Utopia\Database\Validator\Query\Base; use Utopia\Validator\Text; -class ProviderOwner extends Base +class VcsNamespace extends Base { public function getMethodType(): string { @@ -21,22 +21,22 @@ class ProviderOwner extends Base } if ($value->getMethod() !== Query::TYPE_EQUAL) { - $this->message = 'Only equal queries are supported for owner'; + $this->message = 'Only equal queries are supported for namespace'; return false; } - if ($value->getAttribute() !== 'owner') { - $this->message = 'Only owner can be queried'; + if ($value->getAttribute() !== 'namespace') { + $this->message = 'Only namespace can be queried'; return false; } if (\count($value->getValues()) !== 1) { - $this->message = 'Owner query must have exactly one value'; + $this->message = 'Namespace query must have exactly one value'; return false; } if (!(new Text(256))->isValid($value->getValue())) { - $this->message = 'Owner query value must be a string with a maximum length of 256 characters'; + $this->message = 'Namespace query value must be a string with a maximum length of 256 characters'; return false; } diff --git a/src/Appwrite/Utopia/Response/Model/VcsNamespace.php b/src/Appwrite/Utopia/Response/Model/VcsNamespace.php index dc0f38b07c..2903552668 100644 --- a/src/Appwrite/Utopia/Response/Model/VcsNamespace.php +++ b/src/Appwrite/Utopia/Response/Model/VcsNamespace.php @@ -10,7 +10,7 @@ class VcsNamespace extends Model public function __construct() { $this - ->addRule('id', [ + ->addRule('$id', [ 'type' => self::TYPE_STRING, 'description' => 'VCS (Version Control System) namespace ID.', 'default' => '', @@ -24,13 +24,13 @@ class VcsNamespace extends Model ]) ->addRule('path', [ 'type' => self::TYPE_STRING, - 'description' => 'VCS (Version Control System) namespace path, used as the owner when listing repositories.', + 'description' => 'VCS (Version Control System) namespace path, used to filter repositories by namespace.', 'default' => '', 'example' => 'appwrite', ]) - ->addRule('kind', [ + ->addRule('type', [ 'type' => self::TYPE_STRING, - 'description' => 'Namespace kind. Either the user\'s personal namespace or a group/organization.', + 'description' => 'Namespace type. Either the user\'s personal namespace or a group/organization.', 'default' => '', 'example' => 'user', ]) diff --git a/tests/unit/Utopia/Database/Validator/Queries/VcsRepositoriesTest.php b/tests/unit/Utopia/Database/Validator/Queries/VcsRepositoriesTest.php new file mode 100644 index 0000000000..c59ecc35ee --- /dev/null +++ b/tests/unit/Utopia/Database/Validator/Queries/VcsRepositoriesTest.php @@ -0,0 +1,41 @@ +assertTrue($validator->isValid([]), $validator->getDescription()); + } + + public function testValidQueries(): void + { + $validator = new VcsRepositories(); + + $this->assertTrue($validator->isValid([Query::limit(25)]), $validator->getDescription()); + $this->assertTrue($validator->isValid([Query::offset(0)]), $validator->getDescription()); + $this->assertTrue($validator->isValid([Query::equal('namespace', ['appwrite'])]), $validator->getDescription()); + $this->assertTrue($validator->isValid([ + Query::limit(25), + Query::offset(0), + Query::equal('namespace', ['appwrite']), + ]), $validator->getDescription()); + } + + public function testInvalidQueries(): void + { + $validator = new VcsRepositories(); + + $this->assertFalse($validator->isValid([Query::equal('name', ['appwrite'])])); + $this->assertFalse($validator->isValid([Query::greaterThan('namespace', 'appwrite')])); + } +} diff --git a/tests/unit/Utopia/Database/Validator/Query/VcsNamespaceTest.php b/tests/unit/Utopia/Database/Validator/Query/VcsNamespaceTest.php new file mode 100644 index 0000000000..4f3f01a07b --- /dev/null +++ b/tests/unit/Utopia/Database/Validator/Query/VcsNamespaceTest.php @@ -0,0 +1,54 @@ +assertTrue($validator->isValid(Query::equal('namespace', ['appwrite'])), $validator->getDescription()); + } + + public function testInvalidNotQuery(): void + { + $validator = new VcsNamespace(); + + $this->assertFalse($validator->isValid('namespace')); + } + + public function testInvalidMethod(): void + { + $validator = new VcsNamespace(); + + $this->assertFalse($validator->isValid(Query::greaterThan('namespace', 'appwrite'))); + } + + public function testInvalidAttribute(): void + { + $validator = new VcsNamespace(); + + $this->assertFalse($validator->isValid(Query::equal('name', ['appwrite']))); + } + + public function testInvalidMultipleValues(): void + { + $validator = new VcsNamespace(); + + $this->assertFalse($validator->isValid(Query::equal('namespace', ['appwrite', 'utopia']))); + } + + public function testInvalidValueTooLong(): void + { + $validator = new VcsNamespace(); + + $this->assertFalse($validator->isValid(Query::equal('namespace', [\str_repeat('a', 257)]))); + } +} From 4bec2a30885406e80e0a2a8611c3595eeddaf371 Mon Sep 17 00:00:00 2001 From: harsh mahajan Date: Thu, 23 Jul 2026 19:20:47 +0530 Subject: [PATCH 08/10] Remove VCS query validator unit tests, no established coverage pattern for these classes --- .../Validator/Queries/VcsRepositoriesTest.php | 41 -------------- .../Validator/Query/VcsNamespaceTest.php | 54 ------------------- 2 files changed, 95 deletions(-) delete mode 100644 tests/unit/Utopia/Database/Validator/Queries/VcsRepositoriesTest.php delete mode 100644 tests/unit/Utopia/Database/Validator/Query/VcsNamespaceTest.php diff --git a/tests/unit/Utopia/Database/Validator/Queries/VcsRepositoriesTest.php b/tests/unit/Utopia/Database/Validator/Queries/VcsRepositoriesTest.php deleted file mode 100644 index c59ecc35ee..0000000000 --- a/tests/unit/Utopia/Database/Validator/Queries/VcsRepositoriesTest.php +++ /dev/null @@ -1,41 +0,0 @@ -assertTrue($validator->isValid([]), $validator->getDescription()); - } - - public function testValidQueries(): void - { - $validator = new VcsRepositories(); - - $this->assertTrue($validator->isValid([Query::limit(25)]), $validator->getDescription()); - $this->assertTrue($validator->isValid([Query::offset(0)]), $validator->getDescription()); - $this->assertTrue($validator->isValid([Query::equal('namespace', ['appwrite'])]), $validator->getDescription()); - $this->assertTrue($validator->isValid([ - Query::limit(25), - Query::offset(0), - Query::equal('namespace', ['appwrite']), - ]), $validator->getDescription()); - } - - public function testInvalidQueries(): void - { - $validator = new VcsRepositories(); - - $this->assertFalse($validator->isValid([Query::equal('name', ['appwrite'])])); - $this->assertFalse($validator->isValid([Query::greaterThan('namespace', 'appwrite')])); - } -} diff --git a/tests/unit/Utopia/Database/Validator/Query/VcsNamespaceTest.php b/tests/unit/Utopia/Database/Validator/Query/VcsNamespaceTest.php deleted file mode 100644 index 4f3f01a07b..0000000000 --- a/tests/unit/Utopia/Database/Validator/Query/VcsNamespaceTest.php +++ /dev/null @@ -1,54 +0,0 @@ -assertTrue($validator->isValid(Query::equal('namespace', ['appwrite'])), $validator->getDescription()); - } - - public function testInvalidNotQuery(): void - { - $validator = new VcsNamespace(); - - $this->assertFalse($validator->isValid('namespace')); - } - - public function testInvalidMethod(): void - { - $validator = new VcsNamespace(); - - $this->assertFalse($validator->isValid(Query::greaterThan('namespace', 'appwrite'))); - } - - public function testInvalidAttribute(): void - { - $validator = new VcsNamespace(); - - $this->assertFalse($validator->isValid(Query::equal('name', ['appwrite']))); - } - - public function testInvalidMultipleValues(): void - { - $validator = new VcsNamespace(); - - $this->assertFalse($validator->isValid(Query::equal('namespace', ['appwrite', 'utopia']))); - } - - public function testInvalidValueTooLong(): void - { - $validator = new VcsNamespace(); - - $this->assertFalse($validator->isValid(Query::equal('namespace', [\str_repeat('a', 257)]))); - } -} From 563c70db9562e9baa4d9b4c08fe18e859f75017d Mon Sep 17 00:00:00 2001 From: harsh mahajan Date: Thu, 23 Jul 2026 19:24:27 +0530 Subject: [PATCH 09/10] Regenerate composer.lock content-hash for relaxed utopia-php/vcs constraint --- composer.lock | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/composer.lock b/composer.lock index 2e4f08c36e..fa94a2fb54 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "e1219809bb21a3a8dc73aeb0d6107641", + "content-hash": "a811ab43bece6d9d01be1caab8a08a75", "packages": [ { "name": "adhocore/jwt", From 393bb7b8f71f568736e7b1960126575a8377480c Mon Sep 17 00:00:00 2001 From: Harsh Mahajan <127186841+HarshMN2345@users.noreply.github.com> Date: Thu, 23 Jul 2026 19:27:26 +0530 Subject: [PATCH 10/10] Update src/Appwrite/Platform/Modules/VCS/Http/Installations/Namespaces/XList.php MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Matej Bačo --- .../Modules/VCS/Http/Installations/Namespaces/XList.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Installations/Namespaces/XList.php b/src/Appwrite/Platform/Modules/VCS/Http/Installations/Namespaces/XList.php index b5c409ebc7..62b9172bc0 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Installations/Namespaces/XList.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Installations/Namespaces/XList.php @@ -40,7 +40,7 @@ class XList extends Action ->label('sdk', new Method( namespace: 'vcs', group: 'namespaces', - name: 'list', + name: 'listNamespaces', description: 'List provider namespaces available to a VCS installation. This can include the user personal namespace and any groups or organizations the installation can browse.', auth: [AuthType::ADMIN], responses: [