feat(core): expose project reference filesystem access (#30423)

packages/opencode/src/server/routes/instance/httpapi/groups/v2/fs.ts

@@ -8,11 +8,13 @@ import { LocationQuery, locationQueryOpenApi, V2LocationMiddleware } from "./loc
 const ReadQuery = Schema.Struct({
   ...LocationQuery.fields,
   path: RelativePath,
+  reference: Schema.String.pipe(Schema.optional),
 })
 
 const ListQuery = Schema.Struct({
   ...LocationQuery.fields,
   path: RelativePath.pipe(Schema.optional),
+  reference: Schema.String.pipe(Schema.optional),
 })
 
 export const FileSystemGroup = HttpApiGroup.make("v2.fs")

packages/opencode/src/server/routes/instance/httpapi/groups/v2/location.ts

@@ -3,6 +3,7 @@ import { Location } from "@opencode-ai/core/location"
 import { LocationServiceMap } from "@opencode-ai/core/location-layer"
 import { LocationFileSystem } from "@opencode-ai/core/location-filesystem"
 import { PermissionV2 } from "@opencode-ai/core/permission"
+import { ProjectReference } from "@opencode-ai/core/project-reference"
 import { AbsolutePath } from "@opencode-ai/core/schema"
 import { PluginBoot } from "@opencode-ai/core/plugin/boot"
 import { Effect, Layer, Schema } from "effect"
@@ -36,7 +37,12 @@ export const locationQueryOpenApi = OpenApi.annotations({
 export class V2LocationMiddleware extends HttpApiMiddleware.Service<
   V2LocationMiddleware,
   {
-    provides: Catalog.Service | PluginBoot.Service | PermissionV2.Service | LocationFileSystem.Service
+    provides:
+      | Catalog.Service
+      | PluginBoot.Service
+      | PermissionV2.Service
+      | ProjectReference.Service
+      | LocationFileSystem.Service
   }
 >()("@opencode/ExperimentalHttpApiV2Location") {}
 

packages/opencode/test/server/httpapi-public-openapi.test.ts

@@ -9,7 +9,12 @@ type OpenApiResponse = {
   readonly content?: Record<string, { readonly schema?: OpenApiSchema }>
 }
 type OpenApiOperation = {
-  readonly parameters?: ReadonlyArray<{ readonly name: string; readonly in: string }>
+  readonly parameters?: ReadonlyArray<{
+    readonly name: string
+    readonly in: string
+    readonly required?: boolean
+    readonly schema?: { readonly type?: string }
+  }>
   readonly responses?: Record<string, OpenApiResponse>
   readonly security?: unknown
 }
@@ -53,6 +58,19 @@ describe("PublicApi OpenAPI v2 errors", () => {
     }
   })
 
+  test("documents optional project reference aliases for filesystem reads and lists", () => {
+    const spec = OpenApi.fromApi(PublicApi) as OpenApiSpec
+
+    for (const path of ["/api/fs/read", "/api/fs/list"]) {
+      expect(spec.paths[path]?.get?.parameters, path).toContainEqual({
+        in: "query",
+        name: "reference",
+        required: false,
+        schema: { type: "string" },
+      })
+    }
+  })
+
   test("does not rewrite /api endpoint errors to legacy error components", () => {
     const spec = OpenApi.fromApi(PublicApi) as OpenApiSpec
     const refs = v2Operations(spec)