@shepai/cli 1.119.0 → 1.120.0-pr384.fdb89bb

package/dist/packages/core/src/application/ports/output/services/agent-deployment-service.interface.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Agent Deployment Service Interface
+ *
+ * Higher-level deployment service that uses the DevEnvironmentAgent
+ * to analyze repos before starting deployments. Wraps the low-level
+ * IDeploymentService with AI-driven analysis.
+ *
+ * Flow:
+ * 1. Analyze repo via DevEnvironmentAgent (cached per-repo)
+ * 2. If not deployable → return "not deployable" result
+ * 3. If deployable → run setup commands → start dev server
+ */
+import type { DeploymentState } from '../../../../domain/generated/output.js';
+import type { DevEnvironmentAnalysis } from './dev-environment-agent.interface.js';
+/** Result of an agent-driven deployment attempt. */
+export interface AgentDeployResult {
+    /** Whether the deployment was started successfully. */
+    success: boolean;
+    /** Error message if the deployment failed. */
+    error?: string;
+    /** Current deployment state (Booting on success). */
+    state?: DeploymentState;
+    /** The analysis result from the dev environment agent. */
+    analysis?: DevEnvironmentAnalysis;
+}
+/**
+ * Port interface for agent-driven deployments.
+ *
+ * Uses DevEnvironmentAgent to analyze the repo, then starts the
+ * deployment using the detected command. Handles repos that have
+ * nothing to deploy by returning a descriptive result.
+ */
+export interface IAgentDeploymentService {
+    /**
+     * Analyze a repository and start its dev environment if possible.
+     *
+     * @param targetId - Unique identifier for the deployment (featureId or repositoryPath)
+     * @param targetPath - Absolute filesystem path to the directory to deploy from
+     * @param options - Optional: force re-analysis by skipping cache
+     * @returns Result with success/error and the analysis
+     */
+    deploy(targetId: string, targetPath: string, options?: {
+        skipCache?: boolean;
+    }): Promise<AgentDeployResult>;
+}
+//# sourceMappingURL=agent-deployment-service.interface.d.ts.map

package/dist/packages/core/src/application/ports/output/services/agent-deployment-service.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-deployment-service.interface.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/core/src/application/ports/output/services/agent-deployment-service.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAEnF,oDAAoD;AACpD,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,OAAO,EAAE,OAAO,CAAC;IAEjB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,qDAAqD;IACrD,KAAK,CAAC,EAAE,eAAe,CAAC;IAExB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,sBAAsB,CAAC;CACnC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;;;OAOG;IACH,MAAM,CACJ,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAChC,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC/B"}

package/dist/packages/core/src/application/ports/output/services/agent-deployment-service.interface.js

@@ -0,0 +1,13 @@
+/**
+ * Agent Deployment Service Interface
+ *
+ * Higher-level deployment service that uses the DevEnvironmentAgent
+ * to analyze repos before starting deployments. Wraps the low-level
+ * IDeploymentService with AI-driven analysis.
+ *
+ * Flow:
+ * 1. Analyze repo via DevEnvironmentAgent (cached per-repo)
+ * 2. If not deployable → return "not deployable" result
+ * 3. If deployable → run setup commands → start dev server
+ */
+export {};

package/dist/packages/core/src/application/ports/output/services/deployment-service.interface.d.ts

@@ -28,6 +28,13 @@ export interface DeploymentStatus {
     /** Detected URL when the dev server is Ready, null while Booting. */
     url: string | null;
 }
+/** Options for overriding the default dev script detection. */
+export interface DeploymentStartOptions {
+    /** Shell command to run instead of auto-detecting from package.json. */
+    command?: string;
+    /** Working directory relative to targetPath (defaults to "."). */
+    cwd?: string;
+}
 /**
  * Port interface for managing local dev server deployments.
  *
@@ -45,10 +52,11 @@ export interface IDeploymentService {
      *
      * @param targetId - Unique identifier for the deployment target (featureId or repositoryId)
      * @param targetPath - Absolute filesystem path to the directory to run the dev server in
+     * @param options - Optional: override the auto-detected command
      * @returns The initial deployment state (always Booting on success)
      * @throws Error if no dev script is found in package.json or the process fails to spawn
      */
-    start(targetId: string, targetPath: string): void;
+    start(targetId: string, targetPath: string, options?: DeploymentStartOptions): void;
     /**
      * Stop a running deployment gracefully.
      * Sends SIGTERM to the process group, then SIGKILL after a timeout.

package/dist/packages/core/src/application/ports/output/services/deployment-service.interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deployment-service.interface.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/core/src/application/ports/output/services/deployment-service.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAEpE,uEAAuE;AACvE,MAAM,WAAW,QAAQ;IACvB,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC5B,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,iDAAiD;IACjD,KAAK,EAAE,eAAe,CAAC;IACvB,qEAAqE;IACrE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;OAQG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAElD;;;;;;OAMG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtC;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAAC;IAErD;;;OAGG;IACH,OAAO,IAAI,IAAI,CAAC;IAIhB;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,EAAE,GAAG,IAAI,CAAC;IAE7C;;;;;OAKG;IACH,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,IAAI,CAAC;IAE3D;;;;;OAKG;IACH,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,IAAI,CAAC;CAC7D"}
+{"version":3,"file":"deployment-service.interface.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/core/src/application/ports/output/services/deployment-service.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAEpE,uEAAuE;AACvE,MAAM,WAAW,QAAQ;IACvB,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC5B,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,iDAAiD;IACjD,KAAK,EAAE,eAAe,CAAC;IACvB,qEAAqE;IACrE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,+DAA+D;AAC/D,MAAM,WAAW,sBAAsB;IACrC,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;OASG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAEpF;;;;;;OAMG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtC;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAAC;IAErD;;;OAGG;IACH,OAAO,IAAI,IAAI,CAAC;IAIhB;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,EAAE,GAAG,IAAI,CAAC;IAE7C;;;;;OAKG;IACH,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,IAAI,CAAC;IAE3D;;;;;OAKG;IACH,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,IAAI,CAAC;CAC7D"}

package/dist/packages/core/src/application/ports/output/services/dev-environment-agent.interface.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Dev Environment Agent Interface
+ *
+ * Output port for agent-based dev environment analysis.
+ * Uses an AI agent to analyze any repository (language-agnostic) and determine
+ * how to start a local development server. Supports per-repo caching for fast
+ * repeated invocations.
+ *
+ * Key behaviors:
+ * - Analyzes repo structure to detect dev server commands across all languages
+ * - Returns a "not deployable" result for repos with no server/UI to start
+ * - Caches analysis results per-repo for fast subsequent calls
+ */
+/** Result of analyzing a repository for dev environment setup. */
+export interface DevEnvironmentAnalysis {
+    /** Whether this repo has a startable dev environment. */
+    deployable: boolean;
+    /** Human-readable explanation of what was detected or why it's not deployable. */
+    reason: string;
+    /** The shell command to start the dev server (null if not deployable). */
+    command: string | null;
+    /** Working directory relative to repo root (defaults to "."). */
+    cwd: string;
+    /** Expected port the dev server will listen on (null if unknown). */
+    expectedPort: number | null;
+    /** Detected language/framework (e.g., "node", "python", "go", "rust"). */
+    language: string | null;
+    /** Detected framework if any (e.g., "next.js", "django", "flask", "gin"). */
+    framework: string | null;
+    /** Setup commands to run before the dev command (e.g., "npm install"). */
+    setupCommands: string[];
+}
+/** Options for the analyze method. */
+export interface DevEnvironmentAnalyzeOptions {
+    /** Skip the cache and force a fresh analysis. */
+    skipCache?: boolean;
+}
+/**
+ * Port interface for AI-driven dev environment analysis.
+ *
+ * Implementations use a structured agent caller to analyze repositories
+ * and determine how to start a local dev server. Results are cached
+ * per-repo (keyed by absolute path) for fast repeated calls.
+ */
+export interface IDevEnvironmentAgent {
+    /**
+     * Analyze a repository to determine how to start its dev environment.
+     *
+     * @param repositoryPath - Absolute filesystem path to the repository
+     * @param options - Optional configuration (e.g., skip cache)
+     * @returns Analysis result with command, language, and deployability info
+     */
+    analyze(repositoryPath: string, options?: DevEnvironmentAnalyzeOptions): Promise<DevEnvironmentAnalysis>;
+    /**
+     * Clear the cached analysis for a specific repository.
+     *
+     * @param repositoryPath - Absolute filesystem path to the repository
+     */
+    clearCache(repositoryPath: string): void;
+    /**
+     * Clear all cached analyses.
+     */
+    clearAllCaches(): void;
+}
+//# sourceMappingURL=dev-environment-agent.interface.d.ts.map

package/dist/packages/core/src/application/ports/output/services/dev-environment-agent.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-environment-agent.interface.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/core/src/application/ports/output/services/dev-environment-agent.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,kEAAkE;AAClE,MAAM,WAAW,sBAAsB;IACrC,yDAAyD;IACzD,UAAU,EAAE,OAAO,CAAC;IAEpB,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IAEf,0EAA0E;IAC1E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAEvB,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAC;IAEZ,qEAAqE;IACrE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAExB,6EAA6E;IAC7E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB,0EAA0E;IAC1E,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,sCAAsC;AACtC,MAAM,WAAW,4BAA4B;IAC3C,iDAAiD;IACjD,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,OAAO,CACL,cAAc,EAAE,MAAM,EACtB,OAAO,CAAC,EAAE,4BAA4B,GACrC,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAEnC;;;;OAIG;IACH,UAAU,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzC;;OAEG;IACH,cAAc,IAAI,IAAI,CAAC;CACxB"}

package/dist/packages/core/src/application/ports/output/services/dev-environment-agent.interface.js

@@ -0,0 +1,14 @@
+/**
+ * Dev Environment Agent Interface
+ *
+ * Output port for agent-based dev environment analysis.
+ * Uses an AI agent to analyze any repository (language-agnostic) and determine
+ * how to start a local development server. Supports per-repo caching for fast
+ * repeated invocations.
+ *
+ * Key behaviors:
+ * - Analyzes repo structure to detect dev server commands across all languages
+ * - Returns a "not deployable" result for repos with no server/UI to start
+ * - Caches analysis results per-repo for fast subsequent calls
+ */
+export {};

package/dist/packages/core/src/infrastructure/di/container.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/src/infrastructure/di/container.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAoHrC;;;;;;GAMG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,OAAO,SAAS,CAAC,CAiUrE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED;;;GAGG;AACH,OAAO,EAAE,SAAS,EAAE,CAAC"}
+{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/src/infrastructure/di/container.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAwHrC;;;;;;GAMG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,OAAO,SAAS,CAAC,CAoVrE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED;;;GAGG;AACH,OAAO,EAAE,SAAS,EAAE,CAAC"}

package/dist/packages/core/src/infrastructure/di/container.js

@@ -26,6 +26,8 @@ import { GitPrService } from '../services/git/git-pr.service.js';
 import { JsonDrivenIdeLauncherService } from '../services/ide-launchers/json-driven-ide-launcher.service.js';
 import { DaemonPidService } from '../services/daemon/daemon-pid.service.js';
 import { DeploymentService } from '../services/deployment/deployment.service.js';
+import { DevEnvironmentAgentService } from '../services/deployment/dev-environment-agent.service.js';
+import { AgentDeploymentService } from '../services/deployment/agent-deployment.service.js';
 import { AttachmentStorageService } from '../services/attachment-storage.service.js';
 import { AgentExecutorFactory } from '../services/agents/common/agent-executor-factory.service.js';
 import { AgentExecutorProvider } from '../services/agents/common/agent-executor-provider.service.js';
@@ -238,6 +240,23 @@ export async function initializeContainer() {
             return new FeatureAgentProcessService(runRepository);
         },
     });
+    // Register agent-based deployment services
+    container.register('IDevEnvironmentAgent', {
+        useFactory: (c) => {
+            const caller = c.resolve('IStructuredAgentCaller');
+            return new DevEnvironmentAgentService({ structuredAgentCaller: caller });
+        },
+    });
+    container.register('IAgentDeploymentService', {
+        useFactory: (c) => {
+            const devEnvAgent = c.resolve('IDevEnvironmentAgent');
+            const deploySvc = c.resolve('IDeploymentService');
+            return new AgentDeploymentService({
+                devEnvironmentAgent: devEnvAgent,
+                deploymentService: deploySvc,
+            });
+        },
+    });
     container.register('ISpecInitializerService', {
         useFactory: () => new SpecInitializerService(),
     });

package/dist/packages/core/src/infrastructure/services/deployment/agent-deployment.service.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Agent Deployment Service
+ *
+ * Higher-level deployment orchestrator that uses the DevEnvironmentAgent
+ * to analyze repos before starting deployments. Replaces the simple
+ * "detect package.json scripts" approach with AI-driven analysis that
+ * supports any language/framework.
+ *
+ * Flow:
+ * 1. Analyze repo via DevEnvironmentAgent (cached per-repo for speed)
+ * 2. If not deployable → return descriptive reason
+ * 3. If deployable → run setup commands → start dev server via DeploymentService
+ */
+import type { IAgentDeploymentService, AgentDeployResult } from '../../../application/ports/output/services/agent-deployment-service.interface.js';
+import type { IDevEnvironmentAgent } from '../../../application/ports/output/services/dev-environment-agent.interface.js';
+import type { IDeploymentService } from '../../../application/ports/output/services/deployment-service.interface.js';
+/** Dependencies injectable for testing. */
+export interface AgentDeploymentServiceDeps {
+    devEnvironmentAgent: IDevEnvironmentAgent;
+    deploymentService: IDeploymentService;
+    execCommand?: (command: string, cwd: string) => Promise<void>;
+}
+export declare class AgentDeploymentService implements IAgentDeploymentService {
+    private readonly deps;
+    constructor(deps: AgentDeploymentServiceDeps);
+    deploy(targetId: string, targetPath: string, options?: {
+        skipCache?: boolean;
+    }): Promise<AgentDeployResult>;
+}
+//# sourceMappingURL=agent-deployment.service.d.ts.map

package/dist/packages/core/src/infrastructure/services/deployment/agent-deployment.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-deployment.service.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/infrastructure/services/deployment/agent-deployment.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EACV,uBAAuB,EACvB,iBAAiB,EAClB,MAAM,2EAA2E,CAAC;AACnF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wEAAwE,CAAC;AACnH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qEAAqE,CAAC;AAM9G,2CAA2C;AAC3C,MAAM,WAAW,0BAA0B;IACzC,mBAAmB,EAAE,oBAAoB,CAAC;IAC1C,iBAAiB,EAAE,kBAAkB,CAAC;IACtC,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/D;AAaD,qBAAa,sBAAuB,YAAW,uBAAuB;IACpE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;gBAExB,IAAI,EAAE,0BAA0B;IAOtC,MAAM,CACV,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAChC,OAAO,CAAC,iBAAiB,CAAC;CA+E9B"}

package/dist/packages/core/src/infrastructure/services/deployment/agent-deployment.service.js

@@ -0,0 +1,110 @@
+/**
+ * Agent Deployment Service
+ *
+ * Higher-level deployment orchestrator that uses the DevEnvironmentAgent
+ * to analyze repos before starting deployments. Replaces the simple
+ * "detect package.json scripts" approach with AI-driven analysis that
+ * supports any language/framework.
+ *
+ * Flow:
+ * 1. Analyze repo via DevEnvironmentAgent (cached per-repo for speed)
+ * 2. If not deployable → return descriptive reason
+ * 3. If deployable → run setup commands → start dev server via DeploymentService
+ */
+import { exec } from 'node:child_process';
+import { join } from 'node:path';
+import { DeploymentState } from '../../../domain/generated/output.js';
+import { createDeploymentLogger } from './deployment-logger.js';
+const log = createDeploymentLogger('[AgentDeploymentService]');
+function defaultExecCommand(command, cwd) {
+    return new Promise((resolve, reject) => {
+        exec(command, { cwd }, (error) => {
+            if (error)
+                reject(error);
+            else
+                resolve();
+        });
+    });
+}
+export class AgentDeploymentService {
+    deps;
+    constructor(deps) {
+        this.deps = {
+            execCommand: defaultExecCommand,
+            ...deps,
+        };
+    }
+    async deploy(targetId, targetPath, options) {
+        log.info(`deploy() called — targetId="${targetId}", targetPath="${targetPath}"`);
+        // Step 1: Analyze via agent
+        let analysis;
+        try {
+            analysis = await this.deps.devEnvironmentAgent.analyze(targetPath, {
+                skipCache: options?.skipCache,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Analysis failed';
+            log.error(`agent analysis failed: ${message}`);
+            return { success: false, error: message };
+        }
+        log.info(`analysis result — deployable=${analysis.deployable}, command=${analysis.command}`);
+        // Step 2: Handle not-deployable repos
+        if (!analysis.deployable) {
+            log.info(`repo is not deployable: ${analysis.reason}`);
+            return {
+                success: false,
+                error: analysis.reason,
+                analysis,
+            };
+        }
+        // Validate: deployable but no command is an error
+        if (!analysis.command) {
+            log.error('analysis marked repo as deployable but provided no command');
+            return {
+                success: false,
+                error: 'Analysis marked repo as deployable but provided no command',
+                analysis,
+            };
+        }
+        // Step 3: Run setup commands
+        const resolvedCwd = analysis.cwd && analysis.cwd !== '.' ? join(targetPath, analysis.cwd) : targetPath;
+        for (const setupCmd of analysis.setupCommands) {
+            log.info(`running setup command: "${setupCmd}" in "${resolvedCwd}"`);
+            try {
+                await this.deps.execCommand(setupCmd, resolvedCwd);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : 'Setup failed';
+                log.error(`setup command failed: ${message}`);
+                return {
+                    success: false,
+                    error: `Setup command failed: ${message}`,
+                    analysis,
+                };
+            }
+        }
+        // Step 4: Start the dev server
+        try {
+            this.deps.deploymentService.start(targetId, targetPath, {
+                command: analysis.command,
+                cwd: analysis.cwd,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Failed to start deployment';
+            log.error(`deployment start failed: ${message}`);
+            return {
+                success: false,
+                error: message,
+                analysis,
+            };
+        }
+        log.info('deployment started successfully');
+        return {
+            success: true,
+            state: DeploymentState.Booting,
+            analysis,
+        };
+    }
+}

package/dist/packages/core/src/infrastructure/services/deployment/deployment.service.d.ts

@@ -7,7 +7,7 @@
  * shutdown (SIGTERM → poll → SIGKILL).
  */
 import { spawn } from 'node:child_process';
-import type { IDeploymentService, DeploymentStatus, LogEntry } from '../../../application/ports/output/services/deployment-service.interface.js';
+import type { IDeploymentService, DeploymentStatus, DeploymentStartOptions, LogEntry } from '../../../application/ports/output/services/deployment-service.interface.js';
 import { detectDevScript } from './detect-dev-script.js';
 export interface DeploymentServiceDeps {
     spawn: typeof spawn;
@@ -23,8 +23,12 @@ export declare class DeploymentService implements IDeploymentService {
     /**
      * Start a deployment for the given target.
      * If a deployment already exists for this target, it is stopped first.
+     *
+     * When options.command is provided, the command is executed directly via shell
+     * instead of auto-detecting from package.json. This enables agent-based
+     * deployment for any language/framework.
      */
-    start(targetId: string, targetPath: string): void;
+    start(targetId: string, targetPath: string, options?: DeploymentStartOptions): void;
     /**
      * Get the current deployment status for a target.
      * Returns null if no deployment exists for this target.

package/dist/packages/core/src/infrastructure/services/deployment/deployment.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deployment.service.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/infrastructure/services/deployment/deployment.service.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,KAAK,EAAqB,MAAM,oBAAoB,CAAC;AAI9D,OAAO,KAAK,EACV,kBAAkB,EAClB,gBAAgB,EAChB,QAAQ,EACT,MAAM,qEAAqE,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAoBzD,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,eAAe,EAAE,OAAO,eAAe,CAAC;IACxC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,MAAM,KAAK,IAAI,CAAC;IAC7D,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;CACnC;AAgBD,qBAAa,iBAAkB,YAAW,kBAAkB;IAC1D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsC;IAClE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAwB;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;gBAElC,IAAI,GAAE,OAAO,CAAC,qBAAqB,CAAM;IAIrD;;;OAGG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IA+EjD;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI;IAYpD;;OAEG;IACG,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyC3C;;OAEG;IACH,OAAO,IAAI,IAAI;IAOf;;OAEG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,EAAE,GAAG,IAAI;IAM5C;;OAEG;IACH,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,IAAI;IAI1D;;OAEG;IACH,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,IAAI;IAI3D;;OAEG;IACH,OAAO,CAAC,WAAW;IAQnB;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IA+D5B;;OAEG;YACW,aAAa;IAW3B;;OAEG;IACH,OAAO,CAAC,WAAW;CASpB"}
+{"version":3,"file":"deployment.service.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/infrastructure/services/deployment/deployment.service.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,KAAK,EAAqB,MAAM,oBAAoB,CAAC;AAI9D,OAAO,KAAK,EACV,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,QAAQ,EACT,MAAM,qEAAqE,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAoBzD,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,eAAe,EAAE,OAAO,eAAe,CAAC;IACxC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,MAAM,KAAK,IAAI,CAAC;IAC7D,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;CACnC;AAgBD,qBAAa,iBAAkB,YAAW,kBAAkB;IAC1D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsC;IAClE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAwB;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;gBAElC,IAAI,GAAE,OAAO,CAAC,qBAAqB,CAAM;IAIrD;;;;;;;OAOG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,IAAI;IA8FnF;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI;IAYpD;;OAEG;IACG,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyC3C;;OAEG;IACH,OAAO,IAAI,IAAI;IAOf;;OAEG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,EAAE,GAAG,IAAI;IAM5C;;OAEG;IACH,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,IAAI;IAI1D;;OAEG;IACH,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,IAAI;IAI3D;;OAEG;IACH,OAAO,CAAC,WAAW;IAQnB;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IA+D5B;;OAEG;YACW,aAAa;IAW3B;;OAEG;IACH,OAAO,CAAC,WAAW;CASpB"}

package/dist/packages/core/src/infrastructure/services/deployment/deployment.service.js

@@ -41,9 +41,13 @@ export class DeploymentService {
     /**
      * Start a deployment for the given target.
      * If a deployment already exists for this target, it is stopped first.
+     *
+     * When options.command is provided, the command is executed directly via shell
+     * instead of auto-detecting from package.json. This enables agent-based
+     * deployment for any language/framework.
      */
-    start(targetId, targetPath) {
-        log.info(`start() called — targetId="${targetId}", targetPath="${targetPath}"`);
+    start(targetId, targetPath, options) {
+        log.info(`start() called — targetId="${targetId}", targetPath="${targetPath}", command=${options?.command ?? 'auto-detect'}`);
         // Stop any existing deployment for this target
         const existing = this.deployments.get(targetId);
         if (existing) {
@@ -51,19 +55,32 @@ export class DeploymentService {
             this.killProcess(existing);
             this.deployments.delete(targetId);
         }
-        // Detect the dev script
-        const detection = this.deps.detectDevScript(targetPath);
-        if (!detection.success) {
-            log.error(`Dev script detection failed: ${detection.error}`);
-            throw new Error(detection.error);
+        // Resolve the working directory
+        const cwd = options?.cwd && options.cwd !== '.' ? `${targetPath}/${options.cwd}` : targetPath;
+        let spawnCommand;
+        let spawnArgs;
+        if (options?.command) {
+            // Agent-provided command — run directly via shell
+            const parts = options.command.split(/\s+/);
+            spawnCommand = parts[0];
+            spawnArgs = parts.slice(1);
+            log.info(`Using agent-provided command: "${options.command}", cwd="${cwd}"`);
         }
-        // Build spawn args based on package manager
-        const { packageManager, scriptName, command } = detection;
-        const args = packageManager === 'npm' ? ['run', scriptName] : [scriptName];
-        log.info(`Spawning dev server: command="${command}", packageManager="${packageManager}", scriptName="${scriptName}", cwd="${targetPath}"`);
-        const child = this.deps.spawn(packageManager, args, {
+        else {
+            // Legacy auto-detection from package.json
+            const detection = this.deps.detectDevScript(targetPath);
+            if (!detection.success) {
+                log.error(`Dev script detection failed: ${detection.error}`);
+                throw new Error(detection.error);
+            }
+            const { packageManager, scriptName, command } = detection;
+            spawnCommand = packageManager;
+            spawnArgs = packageManager === 'npm' ? ['run', scriptName] : [scriptName];
+            log.info(`Spawning dev server: command="${command}", packageManager="${packageManager}", scriptName="${scriptName}", cwd="${cwd}"`);
+        }
+        const child = this.deps.spawn(spawnCommand, spawnArgs, {
             shell: true,
-            cwd: targetPath,
+            cwd,
             detached: true,
             stdio: ['ignore', 'pipe', 'pipe'],
         });

package/dist/packages/core/src/infrastructure/services/deployment/dev-environment-agent.service.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Dev Environment Agent Service
+ *
+ * AI-driven service that analyzes any repository to determine how to start
+ * a local dev environment. Language-agnostic — supports Node.js, Python,
+ * Go, Rust, Java, Ruby, and more. Uses structured agent calls to get
+ * typed analysis results.
+ *
+ * Features:
+ * - In-memory per-repo caching for fast repeated calls
+ * - Reads key config files (package.json, Cargo.toml, etc.) for context
+ * - Handles "not deployable" repos gracefully
+ * - Truncates large files to prevent prompt overflow
+ */
+import type { IDevEnvironmentAgent, DevEnvironmentAnalysis, DevEnvironmentAnalyzeOptions } from '../../../application/ports/output/services/dev-environment-agent.interface.js';
+import type { IStructuredAgentCaller } from '../../../application/ports/output/agents/structured-agent-caller.interface.js';
+/** Dependencies injectable for testing. */
+export interface DevEnvironmentAgentDeps {
+    structuredAgentCaller: Pick<IStructuredAgentCaller, 'call'>;
+    readdir: (path: string) => string[];
+    readFile: (path: string) => string;
+    existsSync: (path: string) => boolean;
+}
+export declare class DevEnvironmentAgentService implements IDevEnvironmentAgent {
+    private readonly cache;
+    private readonly deps;
+    constructor(deps: Partial<DevEnvironmentAgentDeps> & Pick<DevEnvironmentAgentDeps, 'structuredAgentCaller'>);
+    analyze(repositoryPath: string, options?: DevEnvironmentAnalyzeOptions): Promise<DevEnvironmentAnalysis>;
+    clearCache(repositoryPath: string): void;
+    clearAllCaches(): void;
+    private buildPrompt;
+    private getDirListing;
+    private readConfigFiles;
+}
+//# sourceMappingURL=dev-environment-agent.service.d.ts.map

package/dist/packages/core/src/infrastructure/services/deployment/dev-environment-agent.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-environment-agent.service.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/infrastructure/services/deployment/dev-environment-agent.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EACV,oBAAoB,EACpB,sBAAsB,EACtB,4BAA4B,EAC7B,MAAM,wEAAwE,CAAC;AAChF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,wEAAwE,CAAC;AAqFrH,2CAA2C;AAC3C,MAAM,WAAW,uBAAuB;IACtC,qBAAqB,EAAE,IAAI,CAAC,sBAAsB,EAAE,MAAM,CAAC,CAAC;IAC5D,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC;IACpC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CACvC;AASD,qBAAa,0BAA2B,YAAW,oBAAoB;IACrE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6C;IACnE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA0B;gBAG7C,IAAI,EAAE,OAAO,CAAC,uBAAuB,CAAC,GAAG,IAAI,CAAC,uBAAuB,EAAE,uBAAuB,CAAC;IAK3F,OAAO,CACX,cAAc,EAAE,MAAM,EACtB,OAAO,CAAC,EAAE,4BAA4B,GACrC,OAAO,CAAC,sBAAsB,CAAC;IAyClC,UAAU,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI;IAKxC,cAAc,IAAI,IAAI;IAKtB,OAAO,CAAC,WAAW;IA2CnB,OAAO,CAAC,aAAa;IASrB,OAAO,CAAC,eAAe;CA2BxB"}