@jingyi0605/codingns 0.2.5 → 0.3.5

package/dist/server/modules/client/service-update-task-service.js

@@ -0,0 +1,147 @@
+import { HOST_TASK_TYPES } from "../tasks/task-types.js";
+import { AppError } from "../../shared/errors/app-error.js";
+import { readHostPackageVersion } from "./client-service.js";
+export class ServiceUpdateTaskService {
+    taskManager;
+    npmGlobalPackageService;
+    taskRecordById = new Map();
+    latestTaskIdByPackageName = new Map();
+    constructor(taskManager, npmGlobalPackageService) {
+        this.taskManager = taskManager;
+        this.npmGlobalPackageService = npmGlobalPackageService;
+        this.registerTask();
+    }
+    async installPackage(channel, packageName) {
+        const latestTask = this.getLatestTaskByPackageName(packageName);
+        if (latestTask?.restartRequired) {
+            throw new AppError({
+                statusCode: 409,
+                errorCode: "SERVICE_UPDATE_RESTART_REQUIRED",
+                detail: "新版本已经安装完成，重启 Host 后才会生效"
+            });
+        }
+        const target = await this.npmGlobalPackageService.resolveInstallTarget(channel, readHostPackageVersion(), packageName);
+        const handle = this.taskManager.enqueue(HOST_TASK_TYPES.serviceNpmGlobalUpdateInstall, {
+            key: packageName,
+            source: "client.service_update.install",
+            input: {
+                packageName: target.packageName,
+                channel: target.channel,
+                targetVersion: target.targetVersion,
+                distTag: target.distTag
+            }
+        });
+        this.taskRecordById.set(handle.taskId, {
+            packageName,
+            channel,
+            key: packageName,
+            targetVersion: target.targetVersion
+        });
+        this.latestTaskIdByPackageName.set(packageName, handle.taskId);
+        void handle.promise.catch(() => undefined);
+        return this.getTask(handle.taskId);
+    }
+    getTask(taskId) {
+        const record = this.taskRecordById.get(taskId);
+        if (!record) {
+            throw new AppError({
+                statusCode: 404,
+                errorCode: "SERVICE_UPDATE_TASK_NOT_FOUND",
+                detail: `未找到更新任务 ${taskId}`
+            });
+        }
+        const snapshot = this.taskManager.peek(HOST_TASK_TYPES.serviceNpmGlobalUpdateInstall, record.key);
+        if (!snapshot || snapshot.taskId !== taskId) {
+            throw new AppError({
+                statusCode: 404,
+                errorCode: "SERVICE_UPDATE_TASK_NOT_FOUND",
+                detail: `未找到更新任务 ${taskId}`
+            });
+        }
+        return this.toTaskDto(record, snapshot);
+    }
+    getLatestTaskByPackageName(packageName) {
+        const taskId = this.latestTaskIdByPackageName.get(packageName);
+        if (!taskId) {
+            return null;
+        }
+        try {
+            return this.getTask(taskId);
+        }
+        catch {
+            return null;
+        }
+    }
+    registerTask() {
+        if (this.taskManager.has(HOST_TASK_TYPES.serviceNpmGlobalUpdateInstall)) {
+            return;
+        }
+        this.taskManager.register({
+            taskType: HOST_TASK_TYPES.serviceNpmGlobalUpdateInstall,
+            executionLane: "external_process",
+            timeoutMs: 300_000,
+            concurrency: 1,
+            run: async (input, context) => {
+                await this.npmGlobalPackageService.installGlobalPackage({
+                    packageName: input.packageName,
+                    distTag: input.distTag,
+                    signal: context.signal
+                });
+            }
+        });
+    }
+    toTaskDto(record, snapshot) {
+        return {
+            taskId: snapshot.taskId,
+            packageName: record.packageName,
+            channel: record.channel,
+            targetVersion: record.targetVersion,
+            status: snapshot.status,
+            startedAt: toIsoTime(snapshot.startedAt),
+            finishedAt: toIsoTime(snapshot.finishedAt),
+            errorMessage: snapshot.errorMessage ?? null,
+            restartRequired: snapshot.status === "succeeded"
+                && compareSemver(record.targetVersion, readHostPackageVersion()) > 0
+        };
+    }
+}
+function toIsoTime(timestamp) {
+    if (timestamp === null) {
+        return null;
+    }
+    return new Date(timestamp).toISOString();
+}
+function compareSemver(left, right) {
+    const leftMeta = parseSemver(left);
+    const rightMeta = parseSemver(right);
+    for (let index = 0; index < 3; index += 1) {
+        const diff = (leftMeta.numbers[index] ?? 0) - (rightMeta.numbers[index] ?? 0);
+        if (diff !== 0) {
+            return diff;
+        }
+    }
+    if (leftMeta.prerelease === rightMeta.prerelease) {
+        return 0;
+    }
+    if (!leftMeta.prerelease) {
+        return 1;
+    }
+    if (!rightMeta.prerelease) {
+        return -1;
+    }
+    return leftMeta.prerelease.localeCompare(rightMeta.prerelease);
+}
+function parseSemver(input) {
+    const normalized = input.trim().replace(/^v/i, "");
+    const [versionPart, prerelease = ""] = normalized.split("-", 2);
+    const rawNumbers = versionPart.split(".");
+    return {
+        numbers: [
+            Number.parseInt(rawNumbers[0] ?? "0", 10) || 0,
+            Number.parseInt(rawNumbers[1] ?? "0", 10) || 0,
+            Number.parseInt(rawNumbers[2] ?? "0", 10) || 0
+        ],
+        prerelease
+    };
+}
+//# sourceMappingURL=service-update-task-service.js.map

package/dist/server/modules/client/service-update-task-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-update-task-service.js","sourceRoot":"","sources":["../../../../src/modules/client/service-update-task-service.ts"],"names":[],"mappings":"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"}

package/dist/server/modules/client/service-update-types.d.ts

@@ -0,0 +1,30 @@
+import type { TaskStatus } from "../tasks/task-types.js";
+export interface ServiceUpdateTaskDto {
+    taskId: string;
+    packageName: string;
+    channel: "stable" | "beta";
+    targetVersion: string | null;
+    status: TaskStatus;
+    startedAt: string | null;
+    finishedAt: string | null;
+    errorMessage: string | null;
+    restartRequired: boolean;
+}
+export interface ManagedServicePackageDto {
+    channel: "stable" | "beta";
+    packageName: string;
+    registryUrl: string;
+    packagePageUrl: string;
+    currentVersion: string;
+    latestVersion: string | null;
+    hasUpdate: boolean;
+    checkStatus: "ready" | "up_to_date" | "check_failed";
+    checkError: string | null;
+    restartRequired: boolean;
+    installTask: ServiceUpdateTaskDto | null;
+}
+export interface ServiceUpdateListDto {
+    channel: "stable" | "beta";
+    checkedAt: string;
+    packages: ManagedServicePackageDto[];
+}

package/dist/server/modules/client/service-update-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=service-update-types.js.map

package/dist/server/modules/client/service-update-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-update-types.js","sourceRoot":"","sources":["../../../../src/modules/client/service-update-types.ts"],"names":[],"mappings":""}

package/dist/server/modules/debug-target/debug-target-service.d.ts

@@ -7,7 +7,7 @@ import type { FrameworkAnalysisResultRepository } from "../../storage/repositori
 import type { PortLeaseRepository } from "../../storage/repositories/port-lease-repository.js";
 import type { RuntimeBindingRepository } from "../../storage/repositories/runtime-binding-repository.js";
 import type { WorkspaceWorktreeRepository } from "../../storage/repositories/workspace-worktree-repository.js";
-import type { AiFallbackEditRecord, DebugLaunchPlan, DebugRuntimeHistoryEnvelope, DebugRuntimeDetail, DebugRuntimeSession, DebugServiceSpec, DebugTargetProfile, FrameworkAnalysisResult, TerminalInstance, TerminalRuntimeType } from "../../types/domain.js";
+import type { AiFallbackEditRecord, DebugLaunchPlan, DebugRuntimeHistoryEnvelope, DebugRuntimeDetail, DebugRuntimeSession, DebugServiceSpec, DebugTargetProfile, FrameworkAnalysisResult, TerminalCommandTemplate, TerminalInstance, TerminalRuntimeType } from "../../types/domain.js";
 import type { TerminalService } from "../terminal/terminal-service.js";
 import { TaskManager } from "../tasks/task-manager.js";
 import type { WorkspaceService } from "../workspace/workspace-service.js";
@@ -49,10 +49,13 @@ export declare class DebugTargetService {
     private readonly portLeaseRepository;
     private readonly runtimeBindingRepository;
     private readonly aiFallbackEditRepository;
+    private readonly terminalCommandTemplateRepository;
     private readonly terminalService;
     private readonly terminalInstanceRepository;
     private readonly taskManager;
-    constructor(db: Database.Database, workspaceService: WorkspaceService, workspaceWorktreeRepository: Pick<WorkspaceWorktreeRepository, "findByWorkspaceId">, debugTargetRepository: DebugTargetRepository, debugServiceRepository: DebugServiceRepository, frameworkAnalysisResultRepository: FrameworkAnalysisResultRepository, debugRuntimeSessionRepository: DebugRuntimeSessionRepository, portLeaseRepository: PortLeaseRepository, runtimeBindingRepository: RuntimeBindingRepository, aiFallbackEditRepository: AiFallbackEditRepository, terminalService: Pick<TerminalService, "createTerminal" | "writeInput" | "closeTerminal" | "getTerminalOrThrow">, terminalInstanceRepository: {
+    constructor(db: Database.Database, workspaceService: WorkspaceService, workspaceWorktreeRepository: Pick<WorkspaceWorktreeRepository, "findByWorkspaceId">, debugTargetRepository: DebugTargetRepository, debugServiceRepository: DebugServiceRepository, frameworkAnalysisResultRepository: FrameworkAnalysisResultRepository, debugRuntimeSessionRepository: DebugRuntimeSessionRepository, portLeaseRepository: PortLeaseRepository, runtimeBindingRepository: RuntimeBindingRepository, aiFallbackEditRepository: AiFallbackEditRepository, terminalCommandTemplateRepository: {
+        listByWorkspace(workspaceId: string): TerminalCommandTemplate[];
+    }, terminalService: Pick<TerminalService, "createTerminal" | "writeInput" | "closeTerminal" | "getTerminalOrThrow">, terminalInstanceRepository: {
         findById(id: string): TerminalInstance | null;
     }, taskManager?: TaskManager);
     analyze(input: AnalyzeDebugTargetInput): AnalyzeDebugTargetResult;

package/dist/server/modules/debug-target/debug-target-service.js

@@ -20,10 +20,11 @@ export class DebugTargetService {
     portLeaseRepository;
     runtimeBindingRepository;
     aiFallbackEditRepository;
+    terminalCommandTemplateRepository;
     terminalService;
     terminalInstanceRepository;
     taskManager;
-    constructor(db, workspaceService, workspaceWorktreeRepository, debugTargetRepository, debugServiceRepository, frameworkAnalysisResultRepository, debugRuntimeSessionRepository, portLeaseRepository, runtimeBindingRepository, aiFallbackEditRepository, terminalService, terminalInstanceRepository, taskManager = createTaskManager()) {
+    constructor(db, workspaceService, workspaceWorktreeRepository, debugTargetRepository, debugServiceRepository, frameworkAnalysisResultRepository, debugRuntimeSessionRepository, portLeaseRepository, runtimeBindingRepository, aiFallbackEditRepository, terminalCommandTemplateRepository, terminalService, terminalInstanceRepository, taskManager = createTaskManager()) {
         this.db = db;
         this.workspaceService = workspaceService;
         this.workspaceWorktreeRepository = workspaceWorktreeRepository;
@@ -34,6 +35,7 @@ export class DebugTargetService {
         this.portLeaseRepository = portLeaseRepository;
         this.runtimeBindingRepository = runtimeBindingRepository;
         this.aiFallbackEditRepository = aiFallbackEditRepository;
+        this.terminalCommandTemplateRepository = terminalCommandTemplateRepository;
         this.terminalService = terminalService;
         this.terminalInstanceRepository = terminalInstanceRepository;
         this.taskManager = taskManager;
@@ -44,7 +46,13 @@ export class DebugTargetService {
         const rootPath = this.resolveRootPath(workspace.path, input.rootPath);
         const sourceMeta = this.resolveSourceMeta(workspace.id);
         const timestamp = nowIso();
-        const discoveredServices = discoverServiceCandidates(rootPath, input.commandHints);
+        const commandHints = resolveAnalyzeCommandHints({
+            workspaceId: workspace.id,
+            rootPath,
+            explicitCommandHints: input.commandHints,
+            terminalCommandTemplateRepository: this.terminalCommandTemplateRepository
+        });
+        const discoveredServices = discoverServiceCandidates(rootPath, commandHints);
         const analyzedServices = discoveredServices.map((candidate) => ({
             candidate,
             framework: pickFramework(collectFrameworkEvidence(candidate.cwd))
@@ -754,12 +762,20 @@ function discoverServiceCandidates(rootPath, commandHints) {
     const rootScripts = extractPackageScripts(rootPackageJson);
     const workspacePackages = discoverWorkspacePackages(rootPath, rootPackageJson);
     const candidatesFromRootScripts = discoverWorkspaceServiceCandidatesFromRootScripts(rootPath, workspacePackages, rootScripts);
-    if (candidatesFromRootScripts.length > 0) {
-        return applyCommandHintFallback(candidatesFromRootScripts, commandHints);
-    }
     const candidatesFromWorkspacePackages = discoverWorkspaceServiceCandidatesFromPackages(rootPath, workspacePackages);
-    if (candidatesFromWorkspacePackages.length > 0) {
-        return applyCommandHintFallback(candidatesFromWorkspacePackages, commandHints);
+    const candidatesFromAppsPythonServices = discoverAppsPythonServiceCandidates(rootPath);
+    const discoveredByCwd = new Map();
+    for (const candidate of [
+        ...candidatesFromRootScripts,
+        ...candidatesFromWorkspacePackages,
+        ...candidatesFromAppsPythonServices
+    ]) {
+        if (!discoveredByCwd.has(candidate.cwd)) {
+            discoveredByCwd.set(candidate.cwd, candidate);
+        }
+    }
+    if (discoveredByCwd.size > 0) {
+        return applyCommandHintFallback(sortDiscoveredServiceCandidates([...discoveredByCwd.values()]), commandHints);
     }
     return applyCommandHintFallback([
         {
@@ -908,6 +924,37 @@ function discoverWorkspaceServiceCandidatesFromPackages(rootPath, workspacePacka
     }));
     return sortDiscoveredServiceCandidates(discovered);
 }
+function discoverAppsPythonServiceCandidates(rootPath) {
+    const appsDir = path.join(rootPath, "apps");
+    if (!fs.existsSync(appsDir) || !fs.statSync(appsDir).isDirectory()) {
+        return [];
+    }
+    let appEntries = [];
+    try {
+        appEntries = fs.readdirSync(appsDir);
+    }
+    catch {
+        return [];
+    }
+    const discovered = [];
+    for (const entry of appEntries) {
+        const serviceDir = path.join(appsDir, entry);
+        if (!fs.existsSync(serviceDir) || !fs.statSync(serviceDir).isDirectory()) {
+            continue;
+        }
+        const framework = pickFramework(collectFrameworkEvidence(serviceDir));
+        if (!isPythonFramework(framework.primaryFramework)) {
+            continue;
+        }
+        discovered.push({
+            name: path.basename(serviceDir) || "service",
+            cwd: serviceDir,
+            commandHint: null,
+            roleHint: "backend"
+        });
+    }
+    return sortDiscoveredServiceCandidates(discovered);
+}
 function hasRunnableDevScript(scripts) {
     return Object.keys(scripts).some((name) => name === "dev" || name.startsWith("dev:"));
 }
@@ -976,7 +1023,7 @@ function extractPackageName(packageJson) {
     return typeof packageName === "string" && packageName.trim().length > 0 ? packageName.trim() : null;
 }
 function buildServiceRecord(target, candidate, framework, timestamp, frameworkAnalysisId) {
-    const parsedCommand = parseCommandHint(candidate.commandHint ?? defaultCommandHintForFramework(framework.primaryFramework));
+    const parsedCommand = parseCommandHint(candidate.commandHint ?? defaultCommandHintForFramework(framework.primaryFramework, candidate.cwd));
     return {
         id: createId(),
         targetId: target.id,
@@ -1010,12 +1057,12 @@ function parseCommandHint(commandHint) {
         args: tokens.slice(1)
     };
 }
-function defaultCommandHintForFramework(framework) {
+function defaultCommandHintForFramework(framework, rootPath) {
     switch (framework) {
         case "spring-boot":
             return "./mvnw spring-boot:run";
         case "uvicorn":
-            return "uvicorn main:app --reload";
+            return `uvicorn ${inferUvicornAppSpec(rootPath)} --reload`;
         case "flask":
             return "flask run";
         case "django":
@@ -1057,6 +1104,35 @@ function resolveServiceRole(framework) {
             return "custom";
     }
 }
+function inferUvicornAppSpec(rootPath) {
+    if (!rootPath) {
+        return "main:app";
+    }
+    const candidates = [
+        {
+            relativePath: "app/main.py",
+            moduleSpec: "app.main:app"
+        },
+        {
+            relativePath: "main.py",
+            moduleSpec: "main:app"
+        },
+        {
+            relativePath: "src/main.py",
+            moduleSpec: "src.main:app"
+        },
+        {
+            relativePath: "app.py",
+            moduleSpec: "app:app"
+        }
+    ];
+    for (const candidate of candidates) {
+        if (fs.existsSync(path.join(rootPath, candidate.relativePath))) {
+            return candidate.moduleSpec;
+        }
+    }
+    return "main:app";
+}
 function normalizeAdapterKind(framework) {
     const item = getFrameworkCompatibilityItem(framework);
     if (item.recommendedInjectionMode === "none") {
@@ -1366,6 +1442,90 @@ function safeListFiles(rootPath) {
 function pickFramework(result) {
     return result;
 }
+function isPythonFramework(framework) {
+    return framework === "uvicorn" || framework === "flask" || framework === "django";
+}
+function resolveAnalyzeCommandHints(input) {
+    const templateHints = collectTemplateCommandHints(input.terminalCommandTemplateRepository.listByWorkspace(input.workspaceId), input.rootPath);
+    const explicitHints = (input.explicitCommandHints ?? []).map((item) => item.trim()).filter(Boolean);
+    const mergedHints = [...templateHints, ...explicitHints];
+    return mergedHints.length > 0 ? [...new Set(mergedHints)] : undefined;
+}
+function collectTemplateCommandHints(templates, rootPath) {
+    return templates
+        .filter((template) => isTemplateRelevantToRootPath(template, rootPath))
+        .sort((left, right) => compareTemplatePriority(left, right, rootPath))
+        .map((template) => buildTemplateCommandHint(template))
+        .filter((item) => Boolean(item));
+}
+function isTemplateRelevantToRootPath(template, rootPath) {
+    const templateCwd = path.resolve(template.cwd);
+    const normalizedRootPath = path.resolve(rootPath);
+    return isPathWithin(normalizedRootPath, templateCwd) || isPathWithin(templateCwd, normalizedRootPath);
+}
+function compareTemplatePriority(left, right, rootPath) {
+    const backendDelta = Number(isLikelyBackendTemplate(right)) - Number(isLikelyBackendTemplate(left));
+    if (backendDelta !== 0) {
+        return backendDelta;
+    }
+    const sourceDelta = resolveTemplateSourcePriority(left) - resolveTemplateSourcePriority(right);
+    if (sourceDelta !== 0) {
+        return sourceDelta;
+    }
+    const distanceDelta = resolveTemplateDistance(left, rootPath) - resolveTemplateDistance(right, rootPath);
+    if (distanceDelta !== 0) {
+        return distanceDelta;
+    }
+    return left.cwd.localeCompare(right.cwd);
+}
+function resolveTemplateSourcePriority(template) {
+    return template.sourceType === "debug_service" ? 1 : 0;
+}
+function resolveTemplateDistance(template, rootPath) {
+    const templateCwd = path.resolve(template.cwd);
+    const normalizedRootPath = path.resolve(rootPath);
+    if (templateCwd === normalizedRootPath) {
+        return 0;
+    }
+    if (isPathWithin(normalizedRootPath, templateCwd)) {
+        return 1;
+    }
+    if (isPathWithin(templateCwd, normalizedRootPath)) {
+        return 2;
+    }
+    return 3;
+}
+function buildTemplateCommandHint(template) {
+    const command = template.command.trim();
+    const args = template.args.map((item) => item.trim()).filter(Boolean);
+    if (!command) {
+        return null;
+    }
+    return [command, ...args].join(" ");
+}
+function isLikelyBackendTemplate(template) {
+    const signal = [
+        template.name,
+        template.cwd,
+        template.command,
+        ...template.args
+    ].join(" ").toLowerCase();
+    return (signal.includes("backend")
+        || signal.includes("server")
+        || signal.includes("api")
+        || signal.includes("host")
+        || signal.includes("python")
+        || signal.includes("uvicorn")
+        || signal.includes("gunicorn")
+        || signal.includes("flask")
+        || signal.includes("django")
+        || signal.includes("manage.py"));
+}
+function isPathWithin(parentPath, childPath) {
+    const normalizedParent = withTrailingSeparator(path.resolve(parentPath));
+    const normalizedChild = path.resolve(childPath);
+    return normalizedChild === path.resolve(parentPath) || normalizedChild.startsWith(normalizedParent);
+}
 function selectFrameworkCandidate(candidates) {
     return Array.from(candidates.values())
         .sort((left, right) => {