Create Project Environment

Instructions

Implementation Reference

• tools/createEnvironment.ts:11-51 (registration)

  Tool factory that builds the 'create_environment' Tool object with name, title, description, and inputSchema (name/url required, description/projectUuid optional).

  export function buildCreateEnvironmentTool(): Tool {
    return {
      name: 'create_environment',
      title: 'Create Project Environment',
      description: DESCRIPTION,
      inputSchema: {
        type: 'object',
        properties: {
          name: {
            type: 'string',
            description: 'Short label for the environment (e.g. "staging", "production"). Required.',
            minLength: 1,
          },
          url: {
            type: 'string',
            description: 'Base URL for the environment (e.g. https://staging.example.com). Required.',
          },
          description: {
            type: 'string',
            description: 'Optional: free-text description.',
          },
          projectUuid: {
            type: 'string',
            description: 'Optional: UUID of the target project. Defaults to the project resolved from the current git repo.',
          },
        },
        required: ['name', 'url'],
        additionalProperties: false,
      },
    };
  }
  
  export function buildValidatedCreateEnvironmentTool(): ValidatedTool {
    const tool = buildCreateEnvironmentTool();
    return {
      ...tool,
      inputSchema: CreateEnvironmentInputSchema,
      handler: createEnvironmentHandler,
    };
  }

• handlers/createEnvironmentHandler.ts:14-100 (handler)

  Main handler that creates a DebuggAI environment: resolves projectUuid from input or git repo, calls client.createEnvironment, optionally seeds credentials, and returns the result.

  export async function createEnvironmentHandler(
    input: CreateEnvironmentInput,
    _context: ToolContext,
  ): Promise<ToolResponse> {
    const start = Date.now();
    logger.toolStart('create_environment', {
      name: input.name,
      hasUrl: !!input.url,
      projectUuid: input.projectUuid,
    });
  
    try {
      const client = new DebuggAIServerClient(config.api.key);
      await client.init();
  
      let projectUuid = input.projectUuid;
      if (!projectUuid) {
        const repoName = detectRepoName();
        if (!repoName) {
          const payload = {
            error: 'NoProjectResolved',
            message: 'No git repo detected and no projectUuid provided. Pass projectUuid (get it from search_projects) or invoke from a directory with a git origin.',
          };
          return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
        }
        const project = await client.findProjectByRepoName(repoName);
        if (!project) {
          const payload = {
            error: 'NoProjectResolved',
            message: `No DebuggAI project found for repo "${repoName}". Pass projectUuid explicitly.`,
          };
          return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
        }
        projectUuid = project.uuid;
      }
  
      const env = await client.createEnvironment(projectUuid, {
        name: input.name,
        url: input.url,
        description: input.description,
      });
  
      const payload: Record<string, any> = {
        created: true,
        projectUuid,
        environment: env,
      };
  
      // Optional credentials seed: best-effort per-cred. Success goes to
      // credentials[]; failure goes to credentialWarnings[] (never blocks env creation).
      if (input.credentials && input.credentials.length > 0) {
        const created: Array<{ uuid: string; label: string; username: string; role: string | null; environmentUuid: string }> = [];
        const warnings: Array<{ label: string; error: string }> = [];
        for (const seed of input.credentials) {
          try {
            const cred = await client.createCredential(projectUuid, env.uuid, {
              label: seed.label,
              username: seed.username,
              password: seed.password,
              role: seed.role,
            });
            // Defensive: drop any stray password from the response shape
            created.push({
              uuid: cred.uuid,
              label: cred.label,
              username: cred.username,
              role: cred.role ?? null,
              environmentUuid: cred.environmentUuid,
            });
          } catch (err: any) {
            warnings.push({
              label: seed.label,
              error: err?.message ?? String(err),
            });
          }
        }
        payload.credentials = created;
        if (warnings.length > 0) payload.credentialWarnings = warnings;
      }
  
      logger.toolComplete('create_environment', Date.now() - start);
      return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
    } catch (error) {
      logger.toolError('create_environment', error as Error, Date.now() - start);
      throw handleExternalServiceError(error, 'DebuggAI', 'create_environment');
    }
  }

• types/index.ts:95-102 (schema)

  Zod schema and TypeScript type for CreateEnvironmentInput, including optional credentials array with CredentialSeedSchema.

  export const CreateEnvironmentInputSchema = z.object({
    name: z.string().min(1, 'name is required'),
    url: z.string().url('url is required for standard environments'),
    description: z.string().optional(),
    projectUuid: z.string().uuid().optional(),
    credentials: z.array(CredentialSeedSchema).optional(),
  }).strict();
  export type CreateEnvironmentInput = z.infer<typeof CreateEnvironmentInputSchema>;

• tools/createEnvironment.ts:43-50 (registration)

  Factory that wraps the base tool with the Zod-validated schema and wires it to the handler.

  export function buildValidatedCreateEnvironmentTool(): ValidatedTool {
    const tool = buildCreateEnvironmentTool();
    return {
      ...tool,
      inputSchema: CreateEnvironmentInputSchema,
      handler: createEnvironmentHandler,
    };
  }

• services/index.ts:284-302 (helper)

  Service-layer method that POSTs to the DebuggAI API to create an environment under a project.

  public async createEnvironment(
    projectUuid: string,
    input: { name: string; url?: string; description?: string },
  ): Promise<{ uuid: string; name: string; url: string; isActive: boolean }> {
    if (!this.tx) throw new Error('Client not initialized — call init() first');
    const body: Record<string, any> = { name: input.name };
    if (input.url) body.url = input.url;
    if (input.description) body.description = input.description;
    const response = await this.tx.post<any>(
      `api/v1/projects/${projectUuid}/environments/`,
      body,
    );
    return {
      uuid: response.uuid,
      name: response.name,
      url: response.url || response.activeUrl || '',
      isActive: response.isActive,
    };
  }