feat(skiller): support external web service

skulidropek · skulidropek · commit 1dc2272f02f8 · 2026-06-06T10:17:13.000Z
diff --git a/packages/api/src/http.ts b/packages/api/src/http.ts
@@ -163,8 +163,10 @@ import {
   openSkillerForTerminalSession,
   parseSkillerRoute,
   proxySkillerTrpc,
+  readSkillerProjectContext,
   serveSkillerApp
 } from "./services/skiller.js"
+import { resolveDockerGitSkillerBackendUrl } from "./services/skiller-core.js"
 import {
   commitStateFromRequest,
   initStateFromRequest,
@@ -596,6 +598,9 @@ const resolveRequestOrigin = (request: HttpServerRequest.HttpServerRequest): str
   return `${proto}://${host}`
 }
 
+const resolveSkillerBackendUrl = (request: HttpServerRequest.HttpServerRequest): string =>
+  resolveDockerGitSkillerBackendUrl(process.env, resolveRequestOrigin(request))
+
 const resolveFederationContext = (
   request: HttpServerRequest.HttpServerRequest,
   requestedDomain?: string | undefined
@@ -812,24 +817,43 @@ export const makeRouter = () => {
     ),
     HttpRouter.post(
       "/skiller/open",
-      openSkiller().pipe(
-        Effect.flatMap((launch) => jsonResponse({ ok: true, ...launch }, 202)),
-        Effect.catchAll(errorResponse)
-      )
+      Effect.gen(function*(_) {
+        const request = yield* _(HttpServerRequest.HttpServerRequest)
+        const launch = yield* _(openSkiller(undefined, undefined, resolveSkillerBackendUrl(request)))
+        return yield* _(jsonResponse({ ok: true, ...launch }, 202))
+      }).pipe(Effect.catchAll(errorResponse))
     ),
     HttpRouter.post(
       "/projects/by-key/:projectKey/skiller/open",
+      Effect.gen(function*(_) {
+        const request = yield* _(HttpServerRequest.HttpServerRequest)
+        const { projectKey } = yield* _(projectKeyParams)
+        const launch = yield* _(openSkiller(projectKey, undefined, resolveSkillerBackendUrl(request)))
+        return yield* _(jsonResponse({ ok: true, ...launch }, 202))
+      }).pipe(Effect.catchAll(errorResponse))
+    ),
+    HttpRouter.post(
+      "/projects/by-key/:projectKey/terminal-sessions/:sessionId/skiller/open",
+      Effect.gen(function*(_) {
+        const request = yield* _(HttpServerRequest.HttpServerRequest)
+        const { projectKey, sessionId } = yield* _(terminalSessionByProjectKeyParams)
+        const launch = yield* _(openSkillerForTerminalSession(projectKey, sessionId, resolveSkillerBackendUrl(request)))
+        return yield* _(jsonResponse({ ok: true, ...launch }, 202))
+      }).pipe(Effect.catchAll(errorResponse))
+    ),
+    HttpRouter.get(
+      "/projects/by-key/:projectKey/skiller/context",
       projectKeyParams.pipe(
-        Effect.flatMap(({ projectKey }) => openSkiller(projectKey)),
-        Effect.flatMap((launch) => jsonResponse({ ok: true, ...launch }, 202)),
+        Effect.flatMap(({ projectKey }) => readSkillerProjectContext(projectKey, null)),
+        Effect.flatMap((context) => jsonResponse({ ok: true, ...context }, 200)),
         Effect.catchAll(errorResponse)
       )
     ),
-    HttpRouter.post(
-      "/projects/by-key/:projectKey/terminal-sessions/:sessionId/skiller/open",
+    HttpRouter.get(
+      "/projects/by-key/:projectKey/terminal-sessions/:sessionId/skiller/context",
       terminalSessionByProjectKeyParams.pipe(
-        Effect.flatMap(({ projectKey, sessionId }) => openSkillerForTerminalSession(projectKey, sessionId)),
-        Effect.flatMap((launch) => jsonResponse({ ok: true, ...launch }, 202)),
+        Effect.flatMap(({ projectKey, sessionId }) => readSkillerProjectContext(projectKey, sessionId)),
+        Effect.flatMap((context) => jsonResponse({ ok: true, ...context }, 200)),
         Effect.catchAll(errorResponse)
       )
     ),
diff --git a/packages/api/src/services/skiller-core.ts b/packages/api/src/services/skiller-core.ts
@@ -35,6 +35,65 @@ export type SkillerBrowserScope = {
   readonly sessionId: string | null
 }
 
+export type ConfiguredSkillerWebUrl =
+  | { readonly _tag: "Disabled" }
+  | { readonly _tag: "Enabled"; readonly baseUrl: string }
+  | { readonly _tag: "Invalid"; readonly message: string }
+
+export type ExternalSkillerLaunchUrlInput = {
+  readonly backendUrl: string
+  readonly projectKey: string | undefined
+  readonly sessionId: string | undefined
+  readonly skillerWebUrl: string
+}
+
+const trimTrailingSlashes = (value: string): string =>
+  value.replace(/\/+$/u, "")
+
+export const resolveConfiguredSkillerWebUrl = (
+  env: Record<string, string | undefined>
+): ConfiguredSkillerWebUrl => {
+  const raw = env["DOCKER_GIT_SKILLER_WEB_URL"]?.trim()
+  if (raw === undefined || raw.length === 0) {
+    return { _tag: "Disabled" }
+  }
+  if (!URL.canParse(raw)) {
+    return { _tag: "Invalid", message: `Invalid DOCKER_GIT_SKILLER_WEB_URL: ${raw}` }
+  }
+  const parsed = new URL(raw)
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    return { _tag: "Invalid", message: "DOCKER_GIT_SKILLER_WEB_URL must use http or https." }
+  }
+  parsed.hash = ""
+  parsed.search = ""
+  return { _tag: "Enabled", baseUrl: trimTrailingSlashes(parsed.toString()) }
+}
+
+export const resolveDockerGitSkillerBackendUrl = (
+  env: Record<string, string | undefined>,
+  requestOrigin: string
+): string => {
+  const configured = [
+    env["DOCKER_GIT_SKILLER_BACKEND_URL"],
+    env["DOCKER_GIT_API_PUBLIC_URL"]
+  ]
+    .map((value) => value?.trim())
+    .find((value) => value !== undefined && value.length > 0)
+  return configured ?? requestOrigin
+}
+
+export const externalSkillerLaunchUrl = (input: ExternalSkillerLaunchUrlInput): string => {
+  const url = new URL(`${trimTrailingSlashes(input.skillerWebUrl)}/launch`)
+  url.searchParams.set("backendUrl", input.backendUrl)
+  if (input.projectKey !== undefined) {
+    url.searchParams.set("projectKey", input.projectKey)
+  }
+  if (input.sessionId !== undefined) {
+    url.searchParams.set("sessionId", input.sessionId)
+  }
+  return url.toString()
+}
+
 export const parseDockerMountLines = (output: string): ReadonlyArray<DockerContainerMount> =>
   output
     .split(/\r?\n/u)
diff --git a/packages/api/src/services/skiller.ts b/packages/api/src/services/skiller.ts
@@ -19,10 +19,13 @@ import * as Stream from "effect/Stream"
 import { ApiConflictError, ApiInternalError, ApiNotFoundError } from "../api/errors.js"
 import {
   containerCodexSkillsPath,
+  externalSkillerLaunchUrl,
   parseDockerMountLines,
   remapContainerPathToMountedHost,
+  resolveConfiguredSkillerWebUrl,
   sameSkillerScope,
   skillerBrowserScopeForContainer,
+  type SkillerBrowserScope,
   type SkillerContainerScope
 } from "./skiller-core.js"
 import { getProjectItemByKey } from "./projects.js"
@@ -31,14 +34,21 @@ import { getProjectTerminalSession } from "./terminal-sessions.js"
 export type SkillerLaunch = {
   readonly alreadyRunning: boolean
   readonly appPath: string
+  readonly backendUrl: string | null
   readonly logPath: string
+  readonly mode: "bundled" | "external"
   readonly pid: number | null
   readonly scope: SkillerContainerScope | null
   readonly startedAtIso: string
   readonly trpcBasePath: string
   readonly trpcPort: number
 }
 
+export type SkillerProjectContext = {
+  readonly browserScope: SkillerBrowserScope
+  readonly scope: SkillerContainerScope
+}
+
 type SkillerProcess = {
   readonly appPath: string
   readonly logPath: string
@@ -133,7 +143,9 @@ const toLaunch = (
 ): SkillerLaunch => ({
   alreadyRunning,
   appPath: sessionId === undefined ? process.appPath : sessionSkillerAppPath(sessionId),
+  backendUrl: null,
   logPath: process.logPath,
+  mode: "bundled",
   pid: process.process.pid ?? null,
   scope: process.scope,
   startedAtIso: process.startedAtIso,
@@ -369,6 +381,27 @@ const resolveRequestedSkillerScope = (
       Effect.flatMap((project) => resolveSkillerScope(projectKey, project))
     )
 
+export const readSkillerProjectContext = (
+  projectKey: string,
+  sessionId: string | null
+): Effect.Effect<
+  SkillerProjectContext,
+  ApiConflictError | ApiInternalError | ApiNotFoundError | PlatformError,
+  ListProjectsContext
+> =>
+  getProjectItemByKey(projectKey).pipe(
+    Effect.flatMap((project) =>
+      sessionId === null
+        ? Effect.succeed(project)
+        : getProjectTerminalSession(project.projectDir, sessionId).pipe(Effect.as(project))
+    ),
+    Effect.flatMap((project) => resolveSkillerScope(projectKey, project)),
+    Effect.map((scope) => ({
+      browserScope: skillerBrowserScopeForContainer(scope, sessionId),
+      scope
+    }))
+  )
+
 const waitForSkillerReady = (trpcPort: number): Effect.Effect<void, ApiInternalError> =>
   Effect.tryPromise({
     catch: (cause) => new ApiInternalError({
@@ -794,9 +827,43 @@ const touchSkillerActivity = (
       )
     )
 
+const externalSkillerLaunch = (
+  scope: SkillerContainerScope | null,
+  projectKey: string | undefined,
+  sessionId: string | undefined,
+  backendUrl: string
+): Effect.Effect<SkillerLaunch | null, ApiInternalError> => {
+  const config = resolveConfiguredSkillerWebUrl(process.env)
+  if (config._tag === "Disabled") {
+    return Effect.succeed(null)
+  }
+  if (config._tag === "Invalid") {
+    return Effect.fail(new ApiInternalError({ message: config.message }))
+  }
+  const appPath = externalSkillerLaunchUrl({
+    backendUrl,
+    projectKey,
+    sessionId,
+    skillerWebUrl: config.baseUrl
+  })
+  return Effect.succeed({
+    alreadyRunning: true,
+    appPath,
+    backendUrl,
+    logPath: "",
+    mode: "external",
+    pid: null,
+    scope,
+    startedAtIso: new Date().toISOString(),
+    trpcBasePath: `${config.baseUrl}/trpc`,
+    trpcPort: 0
+  })
+}
+
 export const openSkiller = (
   projectKey?: string,
-  sessionId?: string
+  sessionId?: string,
+  backendUrl = "http://localhost:3334"
 ): Effect.Effect<
   SkillerLaunch,
   ApiConflictError | ApiInternalError | ApiNotFoundError | PlatformError,
@@ -806,6 +873,10 @@ export const openSkiller = (
     const scope = yield* _(resolveRequestedSkillerScope(projectKey))
     yield* _(touchSkillerActivity(scope))
     rememberSessionScope(sessionId, scope)
+    const externalLaunch = yield* _(externalSkillerLaunch(scope, projectKey, sessionId, backendUrl))
+    if (externalLaunch !== null) {
+      return externalLaunch
+    }
     if (currentProcess !== null && isRunning(currentProcess.process)) {
       if (sameSkillerScope(currentProcess.scope, scope)) {
         yield* _(Effect.try({
@@ -851,7 +922,8 @@ export const hasLiveProjectSkillerSession = (projectId: string): boolean =>
 
 export const openSkillerForTerminalSession = (
   projectKey: string,
-  sessionId: string
+  sessionId: string,
+  backendUrl = "http://localhost:3334"
 ): Effect.Effect<
   SkillerLaunch,
   ApiConflictError | ApiInternalError | ApiNotFoundError | PlatformError,
@@ -863,7 +935,7 @@ export const openSkillerForTerminalSession = (
         Effect.as(projectKey)
       )
     ),
-    Effect.flatMap((resolvedProjectKey) => openSkiller(resolvedProjectKey, sessionId))
+    Effect.flatMap((resolvedProjectKey) => openSkiller(resolvedProjectKey, sessionId, backendUrl))
   )
 
 export const parseSkillerRoute = (pathname: string): SkillerRoute | null => {
diff --git a/packages/api/tests/skiller-core.test.ts b/packages/api/tests/skiller-core.test.ts
@@ -2,15 +2,58 @@ import { describe, expect, it } from "@effect/vitest"
 
 import {
   containerCodexSkillsPath,
+  externalSkillerLaunchUrl,
   parseDockerMountLines,
   remapContainerPathToMountedHost,
   remapSkillerBrowserContainerPath,
   remapSkillerBrowserHostPath,
+  resolveConfiguredSkillerWebUrl,
+  resolveDockerGitSkillerBackendUrl,
   sameSkillerScope,
   skillerBrowserScopeForContainer
 } from "../src/services/skiller-core.js"
 
 describe("skiller container filesystem mapping", () => {
+  it("resolves external Skiller web URLs from docker-git environment", () => {
+    expect(resolveConfiguredSkillerWebUrl({})).toEqual({ _tag: "Disabled" })
+    expect(resolveConfiguredSkillerWebUrl({ DOCKER_GIT_SKILLER_WEB_URL: "  " })).toEqual({ _tag: "Disabled" })
+    expect(resolveConfiguredSkillerWebUrl({
+      DOCKER_GIT_SKILLER_WEB_URL: "https://skiller.example/app/?ignored=1#hash"
+    })).toEqual({
+      _tag: "Enabled",
+      baseUrl: "https://skiller.example/app"
+    })
+    expect(resolveConfiguredSkillerWebUrl({ DOCKER_GIT_SKILLER_WEB_URL: "file:///tmp/skiller" })._tag).toBe("Invalid")
+  })
+
+  it("builds external Skiller launch URLs with docker-git context parameters", () => {
+    const launchUrl = new URL(externalSkillerLaunchUrl({
+      backendUrl: "https://docker-git.example/api",
+      projectKey: "project one",
+      sessionId: "session/1",
+      skillerWebUrl: "https://skiller.example/ui/"
+    }))
+
+    expect(launchUrl.origin).toBe("https://skiller.example")
+    expect(launchUrl.pathname).toBe("/ui/launch")
+    expect(launchUrl.searchParams.get("backendUrl")).toBe("https://docker-git.example/api")
+    expect(launchUrl.searchParams.get("projectKey")).toBe("project one")
+    expect(launchUrl.searchParams.get("sessionId")).toBe("session/1")
+  })
+
+  it("prefers explicit Skiller backend URLs before request origin", () => {
+    expect(resolveDockerGitSkillerBackendUrl({
+      DOCKER_GIT_API_PUBLIC_URL: "https://public-api.example",
+      DOCKER_GIT_SKILLER_BACKEND_URL: "https://skiller-backend.example"
+    }, "http://localhost:3334")).toBe("https://skiller-backend.example")
+
+    expect(resolveDockerGitSkillerBackendUrl({
+      DOCKER_GIT_API_PUBLIC_URL: " https://public-api.example "
+    }, "http://localhost:3334")).toBe("https://public-api.example")
+
+    expect(resolveDockerGitSkillerBackendUrl({}, "http://localhost:3334")).toBe("http://localhost:3334")
+  })
+
   it("maps a project container path through the most specific writable Docker mount", () => {
     const mounts = parseDockerMountLines([
       "/var/lib/docker/volumes/project-home/_data\t/home/dev\ttrue",
diff --git a/packages/api/tests/skiller-routes.test.ts b/packages/api/tests/skiller-routes.test.ts
@@ -1,6 +1,9 @@
 import { describe, expect, it } from "@effect/vitest"
+import { NodeContext } from "@effect/platform-node"
+import { Effect } from "effect"
 
 import {
+  openSkiller,
   parseSkillerRoute,
   resolveSkillerBrowserScopeSelection,
   resolveSkillerRouteScopeSelection,
@@ -76,6 +79,33 @@ describe("skiller routes", () => {
     expect(launch.userName).toBe("dg-skiller-u2147483001")
   })
 
+  it("returns an external Skiller Web launch when DOCKER_GIT_SKILLER_WEB_URL is configured", async () => {
+    const previous = process.env["DOCKER_GIT_SKILLER_WEB_URL"]
+    process.env["DOCKER_GIT_SKILLER_WEB_URL"] = "https://skiller.example/ui"
+    try {
+      const launch = await Effect.runPromise(
+        openSkiller(undefined, undefined, "https://docker-git.example").pipe(Effect.provide(NodeContext.layer))
+      )
+      const launchUrl = new URL(launch.appPath)
+
+      expect(launch.mode).toBe("external")
+      expect(launch.alreadyRunning).toBe(true)
+      expect(launch.backendUrl).toBe("https://docker-git.example")
+      expect(launch.pid).toBeNull()
+      expect(launch.trpcPort).toBe(0)
+      expect(launchUrl.pathname).toBe("/ui/launch")
+      expect(launchUrl.searchParams.get("backendUrl")).toBe("https://docker-git.example")
+      expect(launchUrl.searchParams.has("projectKey")).toBe(false)
+      expect(launchUrl.searchParams.has("sessionId")).toBe(false)
+    } finally {
+      if (previous === undefined) {
+        delete process.env["DOCKER_GIT_SKILLER_WEB_URL"]
+      } else {
+        process.env["DOCKER_GIT_SKILLER_WEB_URL"] = previous
+      }
+    }
+  })
+
   it("fails stalled child processes with a distinct timeout error", () =>
     expect(runProcess(
       process.execPath,
diff --git a/packages/app/src/web/actions-skiller.ts b/packages/app/src/web/actions-skiller.ts
diff --git a/packages/app/src/web/api-skiller-schema.ts b/packages/app/src/web/api-skiller-schema.ts
