refactor(core): consolidate references (#31539)

packages/opencode/test/server/httpapi-exercise/index.ts

@@ -670,7 +670,7 @@ const scenarios: Scenario[] = [
     .at((ctx) => ({ path: "/api/fs/read?path=hello.txt", headers: ctx.headers() }))
     .json(200, locationData(object)),
   http.protected.get("/api/fs/list", "v2.fs.list").json(200, locationData(array)),
-  http.protected.get("/reference", "reference.list").json(200, array),
+  http.protected.get("/api/reference", "v2.reference.list").json(200, object),
   http.protected
     .get("/api/provider/{providerID}", "v2.provider.get")
     .at((ctx) => ({ path: route("/api/provider/{providerID}", { providerID: "missing" }), headers: ctx.headers() }))

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

@@ -94,17 +94,13 @@ describe("PublicApi OpenAPI v2 errors", () => {
     }
   })
 
-  test("documents optional project reference aliases for filesystem reads and lists", () => {
+  test("documents references separately from filesystem routes", () => {
     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" },
-      })
+      expect(spec.paths[path]?.get?.parameters, path).not.toContainEqual(expect.objectContaining({ name: "reference" }))
     }
+    expect(spec.paths["/api/reference"]?.get).toBeDefined()
   })
 
   test("preserves required request bodies for v2 mutations", () => {

packages/opencode/test/server/httpapi-reference.test.ts

@@ -11,7 +11,7 @@ afterEach(async () => {
 })
 
 describe("reference HttpApi", () => {
-  test("lists presentation-safe references resolved in the server workspace", async () => {
+  test("lists usable references resolved in the server workspace", async () => {
     await using tmp = await tmpdir({
       config: {
         formatter: false,
@@ -24,30 +24,31 @@ describe("reference HttpApi", () => {
       },
     })
 
-    const response = await Server.Default().app.request("/reference", {
+    const response = await Server.Default().app.request("/api/reference", {
       headers: { "x-opencode-directory": tmp.path },
     })
 
     expect(response.status).toBe(200)
-    expect(await response.json()).toEqual([
-      {
-        name: "docs",
-        kind: "local",
-        path: path.join(tmp.path, "docs"),
-      },
-      {
-        name: "effect",
-        kind: "git",
-        repository: "Effect-TS/effect",
-        path: path.join(Global.Path.repos, "github.com", "Effect-TS", "effect"),
-        branch: "main",
-      },
-      {
-        name: "bad",
-        kind: "invalid",
-        repository: "not-a-repo",
-        message: "Repository must be a git URL, host/path reference, or GitHub owner/repo shorthand",
-      },
-    ])
+    const body = await response.json()
+    expect(body).toMatchObject({ location: { directory: tmp.path } })
+    expect(body.data).toEqual([
+        {
+          name: "docs",
+          path: path.join(tmp.path, "docs"),
+          source: {
+            type: "local",
+            path: path.join(tmp.path, "docs"),
+          },
+        },
+        {
+          name: "effect",
+          path: path.join(Global.Path.repos, "github.com", "Effect-TS", "effect"),
+          source: {
+            type: "git",
+            repository: "Effect-TS/effect",
+            branch: "main",
+          },
+        },
+      ])
   })
 })