feat: launch Skiller from terminal header

Author: skulidropek

docs/integrations/skiller.md

@@ -38,6 +38,12 @@ Run Skiller checks:
 bun run skiller:check
 ```
 
+## docker-git Web Launch
+
+The docker-git web terminal header includes a `Skiller` button next to `Open browser`. The button calls `POST /skiller/open`, which launches the pinned submodule Electron app as a separate process and writes launcher output to `~/.docker-git/logs/skiller.log`.
+
+When the API process has no `$DISPLAY`, the launcher uses `xvfb-run` if it is available so Skiller can still start in a headless controller environment.
+
 ## Updating the Pin
 
 Update Skiller only as an explicit dependency change:
@@ -58,4 +64,4 @@ bun run skiller:check
 
 ## Integration Boundary
 
-This integration makes Skiller part of the docker-git checkout and developer workflow. It does not embed Skiller's Electron UI into the docker-git web UI yet. Any future bridge should adapt Skiller's skills registry, scanner, and marketplace behavior through docker-git API services instead of importing the Electron app into the existing web bundle.
+This integration makes Skiller part of the docker-git checkout and developer workflow. It launches Skiller from docker-git, but it does not embed Skiller's Electron UI into the docker-git web UI. Any future deeper bridge should adapt Skiller's skills registry, scanner, and marketplace behavior through docker-git API services instead of importing the Electron app into the existing web bundle.

docs/screenshots/issue-237/proof/pr238-proof-11-skiller-terminal-header-button.png

@@ -132,6 +132,7 @@ import {
   readProjectTerminalImage,
   startTerminalSession
 } from "./services/terminal-sessions.js"
+import { openSkiller } from "./services/skiller.js"
 import {
   commitStateFromRequest,
   initStateFromRequest,
@@ -570,6 +571,13 @@ export const makeRouter = () => {
         const projectsRoot = defaultProjectsRoot(cwd)
         return yield* _(jsonResponse({ ok: true, revision: controllerRevision, cwd, projectsRoot }, 200))
       }).pipe(Effect.catchAll(errorResponse))
+    ),
+    HttpRouter.post(
+      "/skiller/open",
+      openSkiller().pipe(
+        Effect.flatMap((launch) => jsonResponse({ ok: true, ...launch }, 202)),
+        Effect.catchAll(errorResponse)
+      )
     )
   )
 

docs/screenshots/issue-237/proof/pr238-proof-12-skiller-button-launch-action.png

@@ -0,0 +1,122 @@
+import { spawn, type ChildProcess } from "node:child_process"
+import { closeSync, existsSync, mkdirSync, openSync } from "node:fs"
+import { homedir } from "node:os"
+import { dirname, join, resolve } from "node:path"
+import { Effect } from "effect"
+
+import { ApiInternalError, ApiNotFoundError } from "../api/errors.js"
+
+export type SkillerLaunch = {
+  readonly alreadyRunning: boolean
+  readonly logPath: string
+  readonly pid: number | null
+  readonly startedAtIso: string
+}
+
+type SkillerProcess = {
+  readonly logPath: string
+  readonly process: ChildProcess
+  readonly startedAtIso: string
+}
+
+const submoduleRelativePath = join("third_party", "skiller-desktop-skills-manager")
+const launchLogPath = join(homedir(), ".docker-git", "logs", "skiller.log")
+
+let currentProcess: SkillerProcess | null = null
+
+const isRunning = (process: ChildProcess): boolean =>
+  process.exitCode === null && process.signalCode === null && !process.killed
+
+const findWorkspaceRoot = (startDir: string): string | null => {
+  let current = resolve(startDir)
+  for (;;) {
+    if (existsSync(join(current, ".gitmodules")) && existsSync(join(current, submoduleRelativePath))) {
+      return current
+    }
+    const parent = dirname(current)
+    if (parent === current) {
+      return null
+    }
+    current = parent
+  }
+}
+
+const resolveSkillerDir = (): Effect.Effect<string, ApiNotFoundError> =>
+  Effect.gen(function*(_) {
+    const root = findWorkspaceRoot(process.cwd())
+    if (root === null) {
+      return yield* _(Effect.fail(new ApiNotFoundError({
+        message: "docker-git workspace root with Skiller submodule was not found."
+      })))
+    }
+    const skillerDir = join(root, submoduleRelativePath)
+    if (!existsSync(join(skillerDir, "package.json"))) {
+      return yield* _(Effect.fail(new ApiNotFoundError({
+        message: `Skiller submodule is not initialized at ${skillerDir}. Run bun run skiller:init first.`
+      })))
+    }
+    return skillerDir
+  })
+
+const launchScript = [
+  "set -euo pipefail",
+  "if [ ! -d node_modules ]; then bun install --frozen-lockfile; fi",
+  "bun run build",
+  "ln -sf index.mjs out/preload/index.js",
+  "if [ -z \"${DISPLAY:-}\" ] && command -v xvfb-run >/dev/null 2>&1; then",
+  "  exec xvfb-run -a ./node_modules/electron/dist/electron --no-sandbox out/main/index.js",
+  "fi",
+  "exec ./node_modules/electron/dist/electron --no-sandbox out/main/index.js"
+].join("\n")
+
+const launchSkillerProcess = (skillerDir: string): SkillerLaunch => {
+  mkdirSync(dirname(launchLogPath), { recursive: true })
+  const logFd = openSync(launchLogPath, "a")
+  try {
+    const child = spawn("bash", ["-lc", launchScript], {
+      cwd: skillerDir,
+      detached: true,
+      env: {
+        ...process.env,
+        ELECTRON_ENABLE_LOGGING: "1"
+      },
+      stdio: ["ignore", logFd, logFd]
+    })
+    const startedAtIso = new Date().toISOString()
+    currentProcess = { logPath: launchLogPath, process: child, startedAtIso }
+    child.once("exit", () => {
+      if (currentProcess?.process.pid === child.pid) {
+        currentProcess = null
+      }
+    })
+    child.unref()
+    return {
+      alreadyRunning: false,
+      logPath: launchLogPath,
+      pid: child.pid ?? null,
+      startedAtIso
+    }
+  } finally {
+    closeSync(logFd)
+  }
+}
+
+export const openSkiller = (): Effect.Effect<SkillerLaunch, ApiInternalError | ApiNotFoundError> =>
+  Effect.gen(function*(_) {
+    if (currentProcess !== null && isRunning(currentProcess.process)) {
+      return {
+        alreadyRunning: true,
+        logPath: currentProcess.logPath,
+        pid: currentProcess.process.pid ?? null,
+        startedAtIso: currentProcess.startedAtIso
+      }
+    }
+    const skillerDir = yield* _(resolveSkillerDir())
+    return yield* _(Effect.try({
+      catch: (cause) => new ApiInternalError({
+        message: "Failed to launch Skiller.",
+        cause
+      }),
+      try: () => launchSkillerProcess(skillerDir)
+    }))
+  })

docs/screenshots/issue-237/proof/pr238-proof-13-skiller-opened-from-terminal-button.png

@@ -0,0 +1,26 @@
+import { type BrowserActionContext, withBusy } from "./actions-shared.js"
+import { openSkiller } from "./api.js"
+
+type SkillerLaunch = {
+  readonly alreadyRunning: boolean
+  readonly logPath: string
+  readonly pid: number | null
+}
+
+const skillerLaunchMessage = (launch: SkillerLaunch): string => {
+  const pid = launch.pid === null ? "unknown pid" : `pid ${launch.pid}`
+  return launch.alreadyRunning
+    ? `Skiller is already running (${pid}). Log: ${launch.logPath}`
+    : `Skiller launch started (${pid}). Log: ${launch.logPath}`
+}
+
+export const openSkillerApp = (context: BrowserActionContext): void => {
+  withBusy({
+    context,
+    effect: openSkiller(),
+    label: "Opening Skiller",
+    onSuccess: (launch) => {
+      context.setMessage(skillerLaunchMessage(launch))
+    }
+  })
+}

packages/api/src/http.ts

@@ -43,6 +43,7 @@ export {
   loadSelectedProjectPrompts,
   saveSelectedProjectPrompt
 } from "./actions-prompts.js"
+export { openSkillerApp } from "./actions-skiller.js"
 export { deleteSelectedProjectSkill, loadSelectedProjectSkills, saveSelectedProjectSkill } from "./actions-skills.js"
 export {
   loadProjectTasksById,

packages/api/src/services/skiller.ts

@@ -10,6 +10,7 @@ export {
   ProjectPromptsSnapshotSchema,
   ProjectPromptUpdateResponseSchema
 } from "./api-prompts-schema.js"
+export { SkillerLaunchResponseSchema } from "./api-skiller-schema.js"
 export {
   ProjectSkillFileSchema,
   ProjectSkillScopeInfoSchema,

packages/app/src/web/actions-skiller.ts

@@ -0,0 +1,9 @@
+import * as Schema from "@effect/schema/Schema"
+
+export const SkillerLaunchResponseSchema = Schema.Struct({
+  alreadyRunning: Schema.Boolean,
+  logPath: Schema.String,
+  ok: Schema.Boolean,
+  pid: Schema.NullOr(Schema.Number),
+  startedAtIso: Schema.String
+})