@foggy-projects/deepseek-harness-plugin 0.4.0-beta.8 → 0.4.0-rc.1

package/lib/index.js

@@ -1,13 +1,20 @@
 import { execFile } from 'node:child_process'
-import { access, mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises'
 import { constants as fsConstants } from 'node:fs'
 import { dirname, join, delimiter } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { promisify } from 'node:util'
 import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
 import { createFoggySkillProvider } from './skill-provider.js'
+import { writeJsonAtomic } from './atomic-json.js'
 import { ensurePythonRuntime, probePythonRuntime } from './python-runtime.js'
 import { compatible, compatibleNode } from './version.js'
+import { enrichRuntimeStartFailure } from './diagnostics.js'
+import {
+  DEFAULT_RUNTIME_PORT,
+  readRuntimeSettings,
+  writeRuntimeSettings,
+} from './runtime-settings.js'
 
 const execFileAsync = promisify(execFile)
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)))
@@ -128,15 +135,10 @@ async function assertSystemPrerequisites(kind) {
   }
 }
 
-async function writeJsonAtomic(path, payload) {
-  await mkdir(dirname(path), { recursive: true })
-  const temporary = `${path}.${process.pid}.${Date.now()}.tmp`
-  await writeFile(temporary, `${JSON.stringify(payload, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 })
-  await rename(temporary, path)
-}
-
 function createPythonProgressReporter(operation, path) {
   let pending = Promise.resolve()
+  const runtimeStart = operation.kind === 'runtime-start'
+  const totalSteps = runtimeStart ? 6 : 7
   return {
     update(detail) {
       const fraction = Math.max(0, Math.min(1, Number(detail.fraction) || 0))
@@ -145,11 +147,11 @@ function createPythonProgressReporter(operation, path) {
         operationId: operation.id,
         kind: operation.kind,
         state: 'running',
-        phase: 'python',
-        message: detail.message || 'Preparing managed Python',
+        phase: runtimeStart ? 'runtime-preflight' : 'python',
+        message: runtimeStart ? 'Preparing the Foggy Runtime controller' : detail.message || 'Preparing managed Python',
         currentFile: detail.currentFile || null,
-        percent: Math.round(((1 + fraction) / 7) * 100),
-        step: { index: 2, total: 7 },
+        percent: runtimeStart ? Math.round(fraction * 3) : Math.round(((1 + fraction) / totalSteps) * 100),
+        step: { index: runtimeStart ? 1 : 2, total: totalSteps },
         startedAt: operation.startedAt,
         updatedAt: new Date().toISOString(),
       }
@@ -200,13 +202,19 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
     const statePath = join(roots.installRoot, 'install-state.json')
     const runtimeStatePath = join(roots.dataRoot, 'runtime-state.json')
     const progressPath = join(roots.dataRoot, 'operation-progress.json')
+    const portConflictPath = join(roots.dataRoot, 'last-runtime-port-conflict.json')
     const manifest = await readJson(versionsFile)
+    const runtimeSettings = await readRuntimeSettings(roots.dataRoot, {
+      defaultPort: manifest.defaults?.port ?? DEFAULT_RUNTIME_PORT,
+    })
     const python = await probePythonRuntime({ installRoot: roots.installRoot, manifest })
     const java = compatible(await commandVersion(process.env.JAVA_EXE || 'java', ['-version']), '17.0')
     let state = null
     let runtime = null
+    let lastRuntimePortConflict = null
     try { state = await readJson(statePath) } catch {}
     try { runtime = await readJson(runtimeStatePath) } catch {}
+    try { lastRuntimePortConflict = await readJson(portConflictPath) } catch {}
     let onboarding = { success: true, profiles: [], profileCount: 0 }
     let profileMigration = { success: true, entries: [], pendingCount: 0, conflictCount: 0, profileStore: roots.profileStore }
     if (state) {
@@ -253,6 +261,7 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
       && components.analysisSkill.installed
       && components.onboardingSkill.installed
     const running = Boolean(runtime && processRunning(Number(runtime.pid)))
+    const activePort = running && Number.isInteger(Number(runtime?.port)) ? Number(runtime.port) : null
     const progress = await readOptionalJson(progressPath)
     let operation = operationView(this.operation)
     if (operation.state === 'running' && progress?.operationId === operation.id) {
@@ -276,6 +285,14 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
       installed,
       running,
       runtimeUrl: running ? runtime.runtimeUrl ?? null : null,
+      runtimeSettings: {
+        ...runtimeSettings,
+        activePort,
+        activeRuntimeUrl: running ? runtime.runtimeUrl ?? null : null,
+        pendingRestart: Boolean(running && activePort && activePort !== runtimeSettings.port),
+        lastConflict: lastRuntimePortConflict,
+        conflictApplies: Number(lastRuntimePortConflict?.port) === runtimeSettings.port,
+      },
       roots,
       components,
       operation,
@@ -336,6 +353,10 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
   async diagnostics() {
     const roots = defaultRoots()
     const status = await this.status()
+    const lastRuntimeStartFailure = await enrichRuntimeStartFailure(
+      await readOptionalJson(join(roots.dataRoot, 'last-runtime-start-failure.json')),
+      roots.dataRoot,
+    )
     let doctor
     try {
       doctor = await runOnboarding(['doctor', '--no-fail'])
@@ -354,6 +375,8 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
       components: status.components,
       onboarding: status.onboarding,
       profileMigration: status.profileMigration,
+      runtimeSettings: status.runtimeSettings,
+      lastRuntimeStartFailure,
       doctor,
     }
     const directory = join(roots.dataRoot, 'diagnostics')
@@ -364,11 +387,61 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
   }
 
   async runtimeStart() {
-    return this.startOperation('runtime-start', false, ['runtime-start'])
+    const roots = defaultRoots()
+    const manifest = await readJson(versionsFile)
+    const settings = await readRuntimeSettings(roots.dataRoot, {
+      defaultPort: manifest.defaults?.port ?? DEFAULT_RUNTIME_PORT,
+    })
+    if (!settings.valid) {
+      return {
+        success: false,
+        accepted: false,
+        error: {
+          code: 'RUNTIME_SETTINGS_INVALID',
+          message: `Runtime settings are invalid: ${settings.error}. Save a valid port in Foggy plugin settings.`,
+        },
+      }
+    }
+    return this.startOperation('runtime-start', false, [
+      'runtime-start', '--install-root', roots.installRoot, '--data-root', roots.dataRoot,
+      '--port', String(settings.port),
+    ])
   }
 
   async runtimeStop() {
-    return this.startOperation('runtime-stop', false, ['runtime-stop'])
+    const roots = defaultRoots()
+    return this.startOperation('runtime-stop', false, [
+      'runtime-stop', '--install-root', roots.installRoot, '--data-root', roots.dataRoot,
+    ])
+  }
+
+  async saveRuntimeSettings(input) {
+    const roots = defaultRoots()
+    if (this.operation?.state === 'running') {
+      return {
+        success: false,
+        error: { code: 'OPERATION_RUNNING', message: 'Wait for the current Foggy operation to finish before changing the Runtime port.' },
+      }
+    }
+    const runtime = await readOptionalJson(join(roots.dataRoot, 'runtime-state.json'))
+    if (runtime && processRunning(Number(runtime.pid))) {
+      return {
+        success: false,
+        error: { code: 'RUNTIME_RUNNING', message: 'Stop Foggy Runtime before changing its port.' },
+      }
+    }
+    try {
+      const settings = await writeRuntimeSettings(roots.dataRoot, input)
+      if (this.operation?.state === 'failed' && this.operation.result?.error?.code === 'RUNTIME_PORT_UNAVAILABLE') {
+        this.operation = null
+      }
+      return { success: true, settings }
+    } catch (error) {
+      return {
+        success: false,
+        error: { code: 'RUNTIME_PORT_INVALID', message: String(error?.message ?? error) },
+      }
+    }
   }
 
   startOperation(kind, replaceSkill, explicitArgs) {
@@ -377,7 +450,7 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
     }
     const id = `${Date.now()}-${Math.random().toString(16).slice(2, 10)}`
     const args = explicitArgs ?? ['install']
-    const reportsProgress = args[0] === 'install'
+    const reportsProgress = args[0] === 'install' || args[0] === 'runtime-start'
     if (reportsProgress) {
       const roots = defaultRoots()
       args.push('--progress-file', join(roots.dataRoot, 'operation-progress.json'), '--operation-id', id, '--operation-kind', kind)
@@ -386,6 +459,7 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
     for (const cacheDir of (process.env.FOGGY_ASSET_CACHE_DIRS || '').split(delimiter).filter(Boolean)) {
       args.push('--asset-cache-dir', cacheDir)
     }
+    const runtimeStart = kind === 'runtime-start'
     const operation = {
       id,
       kind,
@@ -400,10 +474,10 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
         kind,
         state: 'running',
         phase: 'preflight',
-        message: 'Starting Foggy initialization',
+        message: runtimeStart ? 'Starting Foggy Runtime' : 'Starting Foggy initialization',
         currentFile: null,
         percent: 0,
-        step: { index: 1, total: 7 },
+        step: { index: 1, total: runtimeStart ? 6 : 7 },
       } : null,
       promise: null,
     }
@@ -428,8 +502,10 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
           operation.progress = {
             ...operation.progress,
             state: operation.state,
-            phase: operation.state === 'succeeded' ? 'complete' : operation.progress.phase,
-            message: operation.state === 'succeeded' ? 'Foggy initialization completed' : 'Foggy initialization failed',
+            phase: operation.state === 'succeeded' ? (runtimeStart ? 'runtime-complete' : 'complete') : operation.progress.phase,
+            message: operation.state === 'succeeded'
+              ? (runtimeStart ? 'Foggy Runtime is ready' : 'Foggy initialization completed')
+              : (runtimeStart ? 'Foggy Runtime startup failed' : 'Foggy initialization failed'),
             percent: operation.state === 'succeeded' ? 100 : operation.progress.percent,
           }
         }
@@ -443,7 +519,7 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
           operation.progress = {
             ...operation.progress,
             state: 'failed',
-            message: 'Foggy initialization failed',
+            message: runtimeStart ? 'Foggy Runtime startup failed' : 'Foggy initialization failed',
           }
         }
       })
@@ -456,6 +532,7 @@ const markerInitializers = []
 for (const method of [
   'status', 'plan', 'initialize', 'repair', 'repairPython', 'repairCli', 'repairLauncher', 'repairAnalysisSkill',
   'migrateProfiles', 'diagnostics', 'runtimeStart', 'runtimeStop',
+  'saveRuntimeSettings',
 ]) {
   Remote(method)(FoggyIntegrationGateway.prototype[method], {
     kind: 'method',

package/lib/remote-descriptor.js

@@ -1,15 +1,18 @@
 import { z } from 'zod'
 
 const resultSchema = z.unknown()
+const runtimeSettingsInputSchema = z.object({
+  port: z.number().int().min(1024).max(65535),
+}).strict()
 
-function descriptor(method) {
+function descriptor(method, parameters = []) {
   return {
     id: `@foggy-projects/deepseek-harness-plugin#foggyIntegration/${method}`,
     service: 'foggyIntegration',
     namespace: 'foggyIntegration',
     method,
     invocation: { kind: 'direct' },
-    parameters: [],
+    parameters,
     result: {
       mode: 'strict',
       typeSymbol: '@foggy-projects/deepseek-harness-plugin#FoggyIntegrationResult',
@@ -27,4 +30,14 @@ export const descriptors = [
   descriptor('repairPython'),
   descriptor('runtimeStart'),
   descriptor('runtimeStop'),
+  descriptor('saveRuntimeSettings', [{
+    name: 'input',
+    wire: 'input',
+    source: 'json',
+    codec: {
+      mode: 'strict',
+      typeSymbol: '@foggy-projects/deepseek-harness-plugin#FoggyRuntimeSettingsInput',
+      schema: runtimeSettingsInputSchema,
+    },
+  }]),
 ]

package/lib/runtime-settings.js

@@ -0,0 +1,89 @@
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { writeJsonAtomic } from './atomic-json.js'
+
+export const RUNTIME_SETTINGS_SCHEMA = 'foggy-deepseek-runtime-settings/v1'
+export const DEFAULT_RUNTIME_PORT = 18166
+export const MIN_RUNTIME_PORT = 1024
+export const MAX_RUNTIME_PORT = 65535
+
+export function normalizeRuntimePort(value) {
+  const port = typeof value === 'string' && value.trim() !== '' ? Number(value) : value
+  if (!Number.isInteger(port) || port < MIN_RUNTIME_PORT || port > MAX_RUNTIME_PORT) {
+    throw new Error(`Runtime port must be an integer between ${MIN_RUNTIME_PORT} and ${MAX_RUNTIME_PORT}`)
+  }
+  return port
+}
+
+export function runtimeUrlForPort(port) {
+  return `http://127.0.0.1:${normalizeRuntimePort(port)}`
+}
+
+export function runtimeSettingsPath(dataRoot) {
+  return join(dataRoot, 'runtime-settings.json')
+}
+
+export async function readRuntimeSettings(dataRoot, { defaultPort = DEFAULT_RUNTIME_PORT } = {}) {
+  const path = runtimeSettingsPath(dataRoot)
+  const fallbackPort = normalizeRuntimePort(defaultPort)
+  try {
+    const payload = JSON.parse(await readFile(path, 'utf8'))
+    if (payload?.schemaVersion !== RUNTIME_SETTINGS_SCHEMA) {
+      throw new Error(`expected schemaVersion ${RUNTIME_SETTINGS_SCHEMA}`)
+    }
+    const port = normalizeRuntimePort(payload.runtimePort)
+    return {
+      valid: true,
+      source: 'configured',
+      schemaVersion: RUNTIME_SETTINGS_SCHEMA,
+      port,
+      runtimeUrl: runtimeUrlForPort(port),
+      updatedAt: payload.updatedAt ?? null,
+      path,
+      error: null,
+    }
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return {
+        valid: true,
+        source: 'default',
+        schemaVersion: RUNTIME_SETTINGS_SCHEMA,
+        port: fallbackPort,
+        runtimeUrl: runtimeUrlForPort(fallbackPort),
+        updatedAt: null,
+        path,
+        error: null,
+      }
+    }
+    return {
+      valid: false,
+      source: 'invalid',
+      schemaVersion: RUNTIME_SETTINGS_SCHEMA,
+      port: fallbackPort,
+      runtimeUrl: runtimeUrlForPort(fallbackPort),
+      updatedAt: null,
+      path,
+      error: String(error?.message ?? error),
+    }
+  }
+}
+
+export async function writeRuntimeSettings(dataRoot, input) {
+  const runtimePort = normalizeRuntimePort(input?.port)
+  const payload = {
+    schemaVersion: RUNTIME_SETTINGS_SCHEMA,
+    runtimePort,
+    updatedAt: new Date().toISOString(),
+  }
+  const path = runtimeSettingsPath(dataRoot)
+  await writeJsonAtomic(path, payload)
+  return {
+    valid: true,
+    source: 'configured',
+    ...payload,
+    port: runtimePort,
+    runtimeUrl: runtimeUrlForPort(runtimePort),
+    path,
+    error: null,
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foggy-projects/deepseek-harness-plugin",
-  "version": "0.4.0-beta.8",
+  "version": "0.4.0-rc.1",
   "description": "Foggy Java data analysis engine integration for DeepSeek Harness",
   "type": "module",
   "main": "./lib/index.js",
@@ -20,6 +20,7 @@
     "cordis.patch.yml",
     "experience/linux/**",
     "docs/PUBLIC-BETA-READINESS.md",
+    "docs/RELEASE-CANDIDATE-0.4.0-RC.1.md",
     "docs/WINDOWS-BETA-ACCEPTANCE.md",
     "THIRD-PARTY-RUNTIME-NOTICES.md",
     "README.md"
@@ -48,16 +49,16 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-api-remotes": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-locale": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-runtime": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-settings-plugins": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-skill": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.1-rc.2"
+    "@deepseek-ai/dsh-api-remotes": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-locale": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings-plugins": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-skill": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.2-rc.1"
   },
   "scripts": {
-    "check": "node --check lib/index.js && node --check lib/python-runtime.js && node --check lib/skill-provider.js && node --check lib/client.js && node --check lib/typert.js && node --check lib/remote.js",
-    "test": "node --test test/package.test.js && python test/onboarding_unit.py"
+    "check": "node --check lib/index.js && node --check lib/atomic-json.js && node --check lib/diagnostics.js && node --check lib/python-runtime.js && node --check lib/runtime-settings.js && node --check lib/skill-provider.js && node --check lib/client.js && node --check lib/typert.js && node --check lib/remote.js",
+    "test": "node --test test/package.test.js && node test/run-onboarding-tests.js"
   }
 }