<!--
  📄 Proprietary License
  This code is proprietary to FTPROD.
  All rights reserved.
-->

> ## Table of Contents
> - [Used Technologies](#used-technologies)
> - [What is an agent?](#what-is-an-agent)
> - [How to structure an agent?](#how-to-structure-an-agent)
> - [Automatic CLI Exposure](#automatic-cli-exposure)
> - [Pro-tips](#pro-tips)
> - [Collaboration between agents](#collaboration-between-agents)
> - [Examples](#examples)
> - [Advanced Extension](#advanced-extension)
> - [Quality & Security](#quality--security)

### ⚙️ Used Technologies
- Node.js (>=14)
- TypeScript
- pnpm (package manager)
- ESLint (linting)
- Prettier (formatting)
- Jest (testing & coverage)
- Docker
- GitLab CI/CD

# AGENTS — Agent & plugin design guide for `codex-env-tools`
## 👉 What is an agent?

An _agent_ is any module/service that

- encapsulates an infrastructure or workflow capability
- exposes a JavaScript API (via service or controller)
- can interact with a binary, API, cloud resources, cluster, or workflow

## 🏗️ How to structure an agent?

1. Create a file or folder in `src/services` or `src/controllers`
2. Export a properly typed method
3. Allow invocation via CLI or reuse in internal pipelines
4. Example: `src/services/cliExec.ts`, ...

### Automatic CLI Exposure

If your agent should be exposed in the CLI (`codex-env-tools`), simply add an `export const cli` in its service file:

```ts
import { Command } from 'commander';
import { startTaskAgent, StartTaskAgentOptions } from './startTaskAgent';

export const cli = {
  command: 'start-task',
  description: 'Start a new Git task from a GitLab issue',
  builder: (cmd: Command) =>
    cmd
      .argument('<id>', 'GitLab issue IID (task number)')
      .option('--repoPath <path>', 'Repository path (default: cwd)')
      .option('--baseBranch <branch>', 'Base branch (default: main)')
      .option('--gitlabToken <token>', 'GitLab token (default: GITLAB_TOKEN env)')
      .option(
        '--gitlabUrl <url>',
        'GitLab URL (default: https://gitlab.teleport.ftprod.fr/)'
      )
      .option(
        '--workDir <path>',
        "Working directory for 'data' and 'dest'"
      )
      .option(
        '--teleportToken <token>',
        'TeleportBot join token (for TLS generation via TeleportBot)'
      ),
  handler: async (id: string, opts: Omit<StartTaskAgentOptions, 'id'>) => {
    await startTaskAgent({ id, ...opts });
  },
};
```

The CLI will automatically detect all `export const cli` under `src/services` and register them as commands.

## 💡 Pro-tips

- Prefix agent names by scope (e.g. `ssh*`, `deploy*`, `health*`)
- Always explicitly type your exports for better autocomplete and validation
- Allow configuration (environment variables or config files)
- Always provide logs, verbosity flags, dry-run options
- Add basic unit tests for the agent from day one (see `tests/`)

## 🔒 Quality & Security

- **Required tests**: every code change must be covered by tests (unit, integration, or E2E) and **all tests must pass** before merging.
- **Clean code**: code must be linted and formatted (`ESLint`, `Prettier`) with no errors or warnings.
- **No security flaws**: do not introduce vulnerabilities, fix dependency alerts, and perform security-focused code reviews.
- **English comments**: all code comments must be written in English.

## 🔄 Collaboration between agents

- Agents invoke each other via controllers (`src/controllers/`)
- Add options for composition: hooks, callbacks, events.

<!-- SSH Check Agent removed -->
## ✍️ Examples

### Teleport Bot Agent

CLI command:
```sh
codex-env-tools start-app --app myApp --token yourJoinToken --workDir /var/lib/teleport
```

```ts
    import { teleportBotAgent, TeleportBotAgentOptions } from '../src/services/teleportBotAgent';
    await teleportBotAgent({
      appName: 'myApp',
      joinToken: 'yourJoinToken',
      workDir: '/var/lib/teleport',
    });
    ```  

### 📊 Qualimetry Agents

You can orchestrate the project quality via 4 specialized agents:

```sh
codex-env-tools qualimetrie:test      # run tests and generate a coverage report
codex-env-tools qualimetrie:lint      # analyze code with ESLint
codex-env-tools qualimetrie:security  # detect vulnerabilities (pnpm audit)
codex-env-tools qualimetrie:bom       # generate BOM (packages & licenses)
```

In TypeScript, import and use them as follows:
```ts
import {
  testAgent,
  lintAgent,
  securityAgent,
  bomAgent,
} from '../src/services';

async function runChecks() {
  const t = await testAgent();
  const l = await lintAgent();
  const s = await securityAgent();
  const b = await bomAgent();
  console.log({ t, l, s, b });
}
```

## ↗️ Advanced Extension

- Plugin system: auto-register agents via metadata
- Common interface for orchestrators, integrated tests
- Coming soon: recipes & blueprints for agent-controller-service

---

Adopt a modular approach — an _agent_ = a reusable & orchestratable capability!

---
© FTPROD - All rights reserved.