@cmflow/agents 3.4.0-alpha.1 → 3.4.0-beta.31

package/README.md

@@ -1,403 +1,225 @@
-<div style="text-align: center" align="center">
- <img src="https://ns.clubmed.com/fbs/RWD/branding2023/Logo/MicrosoftTeams-image%20(9).png" width="200" alt="Club Med"/>
-</div>
+# @cmflow/agents
 
-<div align="center">
-   <h1>@cmflow/atlas</h1>
-   <hr />
+CLI for installing and configuring AI tools for Club Med developers (Codex, Claude, MCPs).
 
-[![npm version](https://badge.fury.io/js/%40cmflow%2Fatlas.svg)](https://badge.fury.io/js/%40cmflow%2Fatlas)
-[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
-[![code style: oxfmt](https://img.shields.io/badge/code_style-oxfmt-ef4444.svg?style=flat-square)](https://oxc.rs/docs/guide/usage/formatter)
+## Quick start
 
-</div>
-
-Atlas builds an API-to-backend mapping catalogue from an OpenAPI contract and static TypeScript analysis. It generates a reviewable YAML document per route, can optionally infer unresolved mappings, and synchronizes confirmed mappings with Directus.
-
-## What Atlas produces
-
-For each API route, Atlas writes a route-centric YAML document and a companion `.graph.yaml` file. The graph records the resolved path from the API handler to its backends; the YAML records inputs, outputs, mapping evidence and fields that require review.
-
-## Install
-
-```bash
-npm install --save-dev @cmflow/atlas
-```
+### macOS / Linux
 
 ```bash
-yarn add -D @cmflow/atlas
-```
+# 1. Install mise
+curl https://mise.run | sh
 
-```bash
-pnpm add -D @cmflow/atlas
-```
+# 2. Activate mise in the current shell
+eval "$(~/.local/bin/mise activate bash)"   # or: zsh
 
-## Initialize a target API project
+# 3. Install Node.js 24
+mise use -g node@24
 
-Create `atlas.config.ts` at the root of the API project; it does not belong in the Atlas package.
-
-```bash
-atlas init
-# or create it at an explicit location
-atlas --config /path/to/api/atlas.config.ts init
+# 4. Run the Club Med setup
+npx -p @cmflow/agents cm-agents install
 ```
 
-By default, Atlas loads `atlas.config.ts` from the directory where the command is launched. Use `--config` (or `-c`) to reference another configuration file. Use `--analysis-dir` only to override the API source directory to analyze.
-
-The configuration imports `defineConfig` from Atlas:
-
-```ts
-import { defineConfig } from "@cmflow/atlas";
-
-export default defineConfig({
-  outputDir: "./tmp/atlas",
-  envs: {
-    XM_API_URL: "https://xm.example/openapi.json"
-  },
-  openapiUrl: "https://api.example.com/openapi.json",
-  openapiTimeoutMs: 60_000,
-  directusUrl: "https://cms.api.clubmed",
-  analysis: {
-    rootDir: "./app",
-    backends: ["ICC", "CMS", "CMS_B2C"]
-  }
-});
-```
+### Windows (PowerShell, no admin rights required)
 
-`process.cwd()` is always the project root: `outputDir`, `tsconfig.json`, Git paths and serialized source paths are resolved from it. `analysis.rootDir` only defines the source tree to analyze and may therefore point to a subdirectory such as `./app`. Atlas reads `compilerOptions.paths` from the root `tsconfig.json` and uses them as module aliases. Add `resolver.alias` only to override or complement those aliases.
+```powershell
+# 1. Install mise via winget
+winget install --id jdx.mise --accept-source-agreements --accept-package-agreements --silent
 
-`outputDir` is resolved from the project root, not from `analysis.rootDir`. With the configuration above, artifacts are written to `<project-root>/tmp/atlas`, never to `<project-root>/app/tmp/atlas`.
+# 2. Activate mise in PowerShell
+(&mise activate pwsh) | Out-String | Invoke-Expression
 
-Use `analysis.excluded` for project-root-relative technical files that must not enter dependency traversal or `analysis_files`:
+# 3. Install Node.js 24
+mise use -g node@24
 
-```ts
-analysis: {
-  rootDir: "./app",
-  excluded: ["tools/build/*-reference.json"],
-  backends: [/* ... */]
-}
+# 4. Run the Club Med setup
+npx -p @cmflow/agents cm-agents install
 ```
 
-## Backend sources
-
-Atlas starts from accesses actually detected in code on a backend reached by the route graph. It then consolidates those code candidates against the canonical properties returned by the matching `BackendSource`. Atlas never creates a confirmed mapping from API field-name similarity alone.
+## Commands
 
-For a backend with no configured source, Atlas preserves code candidates for optional AI inference. A configured source is authoritative: only its resolved properties can validate the code access.
+### `cm-agents install [--reinstall]`
 
-A backend can be either a string or a `BackendSource` created with `defineBackendSource`:
+Interactive full workstation setup:
 
-- a string (for example `"ICC"`) has no field reference; Atlas keeps the current code-analysis and optional inference flow;
-- a `BackendSource` provides a `resolve` function that returns the backend's known properties. Atlas assigns its `name` as `backend` on every resolved property.
+1. Checks Git is available
+2. Collects secrets and preferences via interactive prompts:
+   - `LITELLM_API_KEY`, `ANTHROPIC_API_KEY`, MCP keys…
+   - **"Configure Codex with Club Med LiteLLM?"** — yes fetches the model catalog and writes the LiteLLM provider config; no keeps the personal OpenAI account untouched
+3. Clones / updates the `digital-api-team-skills` repository
+4. Writes environment variables to the shell rc (Unix) or user scope (Windows)
+5. Installs and configures **Codex CLI** (MCPs; LiteLLM config if chosen)
+6. Installs and configures **Claude CLI** (HTTP MCPs, Atlassian marketplace plugin)
+7. Optionally installs Python 3.12 via mise
 
-Any backend source can persist its resolved properties in a YAML cache. When the cache exists, Atlas uses it and does not call the remote source. Refresh it explicitly with `atlas backend-source --refresh` (or the compatible `atlas backend-sources --refresh`). Use `atlas backend-sources --refresh --all` to refresh every configured source without an interactive prompt.
-
-```ts
-export const xm = defineBackendSource({
-  name: "XM",
-  cache: `${__dirname}/cache.yaml`,
-  resolve: () => openapiSource({ url: "https://xm.example/openapi.json" })
-});
+```bash
+npx -p @cmflow/agents cm-agents install
+npx -p @cmflow/agents cm-agents install --reinstall   # force reinstall of every tool
 ```
 
-When a string and a source share the same name, the last declaration wins. This lets a source enrich a list of backend names, for example `[..., Object.values(BackendTypes), quableBackendSource]`.
-
-The resolver returns one of the following shapes. Document-oriented backends have no route; REST backends have no document.
-
-```ts
-type BackendProperty =
-  | {
-      document: string;
-      field: string;
-      description?: string;
-    }
-  | {
-      route: string;
-      method: string;
-      field: string;
-      description?: string;
-    };
-```
+### `cm-agents check`
 
-The generated mapping preserves this shape. In particular, `document` is a separate property: Atlas does not turn a Quable field into an artificial path such as `products.product_geographical_area`.
+Checks the workstation installation state and prints a pass / warn / fail report:
 
-## Resolved backend metadata artifacts
+- **Node.js version** ≥ 20 (via `process.version`)
+- **git**, **codex**, **claude** present in PATH
+- **python** present in PATH (optional — warn only)
+- Required environment variables
+- Codex config (`~/.codex/config.toml` + standard MCPs)
+- **Codex LiteLLM provider**: `model_provider = "litellm"`, correct `base_url`, `model_catalog_json` exists, active `model` is in the catalog
+- **Kibana MCPs**: warns if no `kibana_*` profile is configured in Codex
+- Claude MCPs configured
+- Repository cloned
 
-At the start of `generate:graph` and `generate:catalog`, Atlas resolves every configured backend source and writes its metadata for inspection:
+> `mise` and `node` are not checked for presence — they are prerequisites to run this CLI at all.
 
-```text
-<outputDir>/backends/<backend>.yaml
+```bash
+npx -p @cmflow/agents cm-agents check
 ```
 
-For example, `<outputDir>/backends/quable_rest.yaml` contains the source name, generation date and canonical properties returned by Quable. Backends declared as strings still receive an artifact with `resolved: false`; this makes missing metadata sources visible during analysis.
+### `cm-agents codex use openai [--model <model>]`
 
-### Quable
+Switches Codex back to the personal OpenAI account:
+- Removes `model_provider`, `model_catalog_json`, `model_providers`, `openai_base_url`
+- Lists available models via the OpenAI SDK (`openai.models.list()`) and shows an interactive select prompt
+- Falls back to `gpt-5.6-luna` if `OPENAI_API_KEY` is not set or the API is unreachable
 
-Attach rules that are specific to Quable directly to its source. They inherit the source backend automatically and their candidates are validated by the Quable property list.
-
-```ts
-import { defineBackendSource, httpClient } from "@cmflow/atlas";
-import { quableI18nFieldRule } from "./atlas-rules";
-
-export const quable = defineBackendSource({
-  name: "QUABLE",
-  rules: [quableI18nFieldRule],
-  resolve: async () => {
-    const documentTypes = await httpClient.get<QuableDocumentType[]>("https://quable.example/document-types");
-
-    return documentTypes.flatMap((document) =>
-      document.properties.map((property) => ({
-        document: document.code,
-        field: property.code,
-        description: "récupéré via le backend resolver"
-      }))
-    );
-  }
-});
+```bash
+cm-agents codex use openai                          # interactive model selection
+cm-agents codex use openai --model gpt-5.6-luna     # skip selection
 ```
 
-For example, the resolver above may return:
+### `cm-agents codex use litellm`
 
-```ts
-{
-  backend: "QUABLE",
-  document: "products",
-  field: "product_geographical_area",
-  description: "récupéré via le backend resolver"
-}
-```
+Switches Codex to the Club Med LiteLLM provider:
+- If `model_providers.litellm` is not yet configured, prompts for `LITELLM_API_KEY` and `base_url` (default: `https://litellm-aiplatform.ai.clubmed.com`)
+- Fetches the Club Med model catalog from the LiteLLM API → writes `~/.codex/clubmed-models.json`
+- Sets `model_provider = "litellm"`, `model_catalog_json`, and `model_providers.litellm`
 
-### CMS Directus
+```bash
+cm-agents codex use litellm
+```
 
-CMS Directus follows the same document-oriented contract. Its `cmsI18nFieldRule` is owned by the CMS source rather than registered as a global expression rule.
+Expected result in `~/.codex/config.toml`:
 
-```ts
-import { defineBackendSource } from "@cmflow/atlas";
-import { cmsI18nFieldRule } from "./atlas-rules";
+```toml
+model = "<default-model-from-catalog>"
+model_provider = "litellm"
+model_catalog_json = "~/.codex/clubmed-models.json"
 
-export const cmsDirectus = defineBackendSource({
-  name: "CMS",
-  rules: [cmsI18nFieldRule],
-  resolve: async () => directusResolver.listProperties()
-});
+[model_providers.litellm]
+name = "LiteLLM"
+base_url = "<litellm-base-url>"
+env_key = "LITELLM_API_KEY"
+wire_api = "responses"
 ```
 
-`directusResolver.listProperties()` returns items such as `{ document: "offers", field: "title", description: "…" }`.
+### `cm-agents codex models`
 
-### CMS Legacy
+Displays the active Codex configuration and the list of models available in the local catalog.
 
-CMS Legacy is configured identically, with its own resolver and backend identifier. It may reuse `cmsI18nFieldRule` when the backend uses `CmsI18n` helpers.
-
-```ts
-import { defineBackendSource } from "@cmflow/atlas";
-import { cmsI18nFieldRule } from "./atlas-rules";
-
-export const cmsLegacy = defineBackendSource({
-  name: "CMS_LEGACY",
-  rules: [cmsI18nFieldRule],
-  resolve: async () => cmsLegacyResolver.listProperties()
-});
+```bash
+cm-agents codex models
 ```
 
-### Custom REST backend with OpenAPI
+### `cm-agents codex models --refresh`
 
-`openapiSource` reuses Atlas's OpenAPI parsing utilities: downloading the document, resolving references, traversing operations, and extracting field descriptions. A project therefore only supplies the URL.
+Refreshes `~/.codex/clubmed-models.json` by querying the LiteLLM API.
+Requires `LITELLM_API_KEY` to be set in the environment.
 
-```ts
-import { constant, defineBackendSource, openapiSource } from "@cmflow/atlas";
-
-export const xm = defineBackendSource({
-  name: "XM",
-  cache: `${__dirname}/xm-openapi.yaml`,
-  resolve: () =>
-    openapiSource({
-      url: constant<string>("XM_API_URL", "https://xm.example/openapi.json")
-    })
-});
+```bash
+cm-agents codex models --refresh
 ```
 
-`constant` resolves a value declared in `envs`, falling back to its second argument. No resolver context is required.
+### `cm-agents kibana setup <profile>`
 
-### Environment constants
+Runs the interactive Kibana MCP profile setup wizard for the given profile name (`prod`, `staging`, or any custom name).
 
-Use `constant` when a backend source needs a configurable value such as a URL or an access token. Declare injected values at the root of `atlas.config.ts`; the value is resolved when the source runs:
+- Streams `npx @havesomecode/kibana-mcp-server setup` with full stdin/stdout relay.
+- After a successful setup, registers `kibana_<profile>` as a **stdio MCP** in both Codex and Claude.
 
-1. Atlas uses `envs[name]` when it is set.
-2. Otherwise, it returns the supplied default value.
-
-```ts
-import { constant, defineBackendSource, openapiSource } from "@cmflow/atlas";
-
-export const xmBackendSource = defineBackendSource({
-  name: "XM",
-  resolve: () =>
-    openapiSource({
-      url: constant<string>("XM_API_URL", "https://xm.example/openapi.json")
-    })
-});
+```bash
+cm-agents kibana setup prod
+cm-agents kibana setup staging
+cm-agents kibana setup prod --reinstall   # re-register even if already present
 ```
 
-For example, configure the endpoint used by the source:
+Once a profile is configured, the MCP server is started on demand:
 
-```ts
-export default defineConfig({
-  envs: {
-    XM_API_URL: "https://xm.internal/openapi.json"
-  }
-  // …other Atlas options
-});
+```bash
+KIBANA_PROFILE=prod    npx -y @havesomecode/kibana-mcp-server serve
+KIBANA_PROFILE=staging npx -y @havesomecode/kibana-mcp-server serve
 ```
 
-`envs` can itself be populated from `process.env` when appropriate for the project.
+The registered MCP JSON (used for both Codex and Claude):
 
-This returns entries such as:
-
-```ts
+```json
 {
-  backend: "XM",
-  route: "/path/to",
-  method: "GET",
-  field: "path.to.field",
-  description: "Description extraite du Swagger"
+  "type": "stdio",
+  "command": "npx",
+  "args": ["-y", "@havesomecode/kibana-mcp-server", "serve"],
+  "env": { "KIBANA_PROFILE": "prod" }
 }
 ```
 
-Register strings and sources together:
-
-```ts
-import { defineConfig } from "@cmflow/atlas";
-import { cmsDirectus, cmsLegacy, quable, xm } from "./backend-sources";
-
-export default defineConfig({
-  // …other Atlas options
-  analysis: {
-    backends: ["ICC", quable, cmsDirectus, cmsLegacy, xm]
-  }
-});
-```
-
-## Custom expression rules
-
-Use `defineExpressionRule` when a project-specific helper hides a backend field or wraps an expression that Atlas should follow. Define those rules in the analyzed project, add a cross-backend rule to `analysis.rules` in `atlas.config.ts`, and attach backend-specific rules to `defineBackendSource({ rules: [...] })` instead.
-
-`match` is a cheap predicate that selects the `ts-morph` expression. `parse` returns the information Atlas should use: a backend field, a transparent wrapper, or both.
-
-```ts
-import { defineConfig, defineExpressionRule } from "@cmflow/atlas";
-import { Node } from "ts-morph";
-
-const localizedFieldRule = defineExpressionRule({
-  name: "localized-field",
-  match: (expression) => Node.isCallExpression(expression) && expression.getExpression().getText() === "localizedField",
-  parse: (expression) => {
-    if (!Node.isCallExpression(expression)) return undefined;
-
-    const [source, field] = expression.getArguments();
-    if (!source || !Node.isExpression(source) || !Node.isStringLiteral(field)) return undefined;
-
-    return { backendField: `${source.getText()}.${field.getLiteralValue()}` };
-  }
-});
-
-export default defineConfig({
-  // …other Atlas options
-  analysis: {
-    // …other analysis options
-    rules: [localizedFieldRule]
-  }
-});
-```
-
-For a wrapper that does not change the field path, return `transparent: true`:
-
-```ts
-const unwrapRule = defineExpressionRule({
-  name: "unwrap-api-value",
-  match: (expression) => Node.isCallExpression(expression) && expression.getExpression().getText() === "unwrap",
-  parse: () => ({ transparent: true })
-});
-```
-
-`parse` may also set `mapperType` to annotate the generated mapping, or `apiMapping: true` when the helper maps an API value rather than a backend value.
-
-Create a `.env.local` in the target API project when pushing to Directus:
-
-```dotenv
-DIRECTUS_URL=https://****
-DIRECTUS_TOKEN=replace-with-a-static-token
-```
-
-## Workflow
+### `cm-agents kibana serve <profile>`
 
-Generate the topology first, then the route catalogue:
+Starts the Kibana MCP server for a given profile — a thin proxy for:
 
 ```bash
-atlas --analysis-dir /path/to/api generate:graph
-atlas --analysis-dir /path/to/api generate:catalog --output .tmp/datasource-catalogue
+KIBANA_PROFILE=<profile> npx -y @havesomecode/kibana-mcp-server serve
 ```
 
-Each route produces a YAML document and a `.graph.yaml` topology artifact. The catalogue requires a valid graph and leaves ambiguous fields marked `needs_review`.
-
-When changing `analysis.rootDir`, backend sources or exclusions, regenerate the graph before the catalogue so the route graph and metadata artifacts use the same configuration:
-
-```bash
-atlas generate:graph "GET /v2/products"
-atlas generate:catalog "GET /v2/products"
-```
-
-Check configured coverage baselines:
-
 ```bash
-atlas --analysis-dir /path/to/api generate:test
+cm-agents kibana serve prod
+cm-agents kibana serve staging
 ```
 
-Review unresolved mappings or run optional AI inference:
+## Environment variables
 
-```bash
-atlas --analysis-dir /path/to/api needs-review --sort percentage --limit 25
-atlas --analysis-dir /path/to/api infer .tmp/datasource-catalogue
-```
+| Variable                         | Purpose                                          |
+|----------------------------------|--------------------------------------------------|
+| `LITELLM_API_KEY`                | LiteLLM key (AI portal — VPN required)           |
+| `ANTHROPIC_API_KEY`              | Anthropic key (same portal)                      |
+| `ANTHROPIC_BASE_URL`             | LiteLLM proxy base URL                           |
+| `ANTHROPIC_DEFAULT_SONNET_MODEL` | Default Claude model                             |
+| `ANTHROPIC_DEFAULT_FABLE_MODEL`  | Fable model                                      |
+| `ANTHROPIC_DEFAULT_OPUS_MODEL`   | Opus model                                       |
+| `ANTHROPIC_DEFAULT_HAIKU_MODEL`  | Haiku model                                      |
+| `CLUBMED_API_MCP_KEY`            | Club Med API portal MCP key                      |
+| `CMS_API_MCP_TOKEN`              | CMS Directus MCP token (optional)                |
+| `CLUBMED_REPO_DIR`               | Path to the `digital-api-team-skills` repository |
 
-The inference pass only reads analysis files referenced by each route graph. Accepted suggestions remain marked `inferred`; suggestions below the configured confidence threshold are retained for manual review.
+## Configured MCPs
 
-Push route artifacts to Directus with an explicit write flag:
+### Codex (`~/.codex/config.toml`)
 
-```bash
-atlas --analysis-dir /path/to/api push .tmp/datasource-catalogue --update
-```
+| Name          | URL                                       |
+|---------------|-------------------------------------------|
+| `clubmed_api` | `https://portal.api.clubmed/mcp`          |
+| `cms_api`     | `https://cms.api.clubmed/mcp`             |
+| `atlassian`   | `https://mcp.atlassian.com/v1/mcp/authv2` |
 
-Without `--update`, the command performs a dry run. Use `clean-orphans` to inspect Directus links that no longer reference an API or backend property.
-
-## Command reference
-
-```text
-atlas init                         Create atlas.config.ts
-atlas backend-source [--refresh]         Display backend metadata; refresh configured source caches when requested
-atlas backend-sources [--refresh] [--all] Compatible plural alias; --all skips the source picker
-atlas generate:graph               Trace API routes to backends
-atlas generate:catalog [route]     Generate route review documents
-atlas generate:test                Check configured coverage baselines
-atlas needs-review                 Rank unresolved routes
-atlas infer [route|directory]      Optionally enrich unresolved mappings
-atlas push [directory|route]       Preview or push mappings to Directus
-atlas clean-orphans                Inspect or delete orphaned Directus links
-atlas report:changed               Report coverage for changed routes
-```
+### Claude (user scope)
 
-## CI
+| Name          | URL                                                    |
+|---------------|--------------------------------------------------------|
+| `clubmed_api` | `https://portal.api.clubmed/mcp`                       |
+| `cms_api`     | `https://cms.api.clubmed/mcp`                          |
+| `atlassian`   | Marketplace plugin `atlassian@claude-plugins-official` |
 
-The recommended static CI flow is `generate:graph`, `generate:catalog`, then `push`. Do not run optional inference in CI. Supply `DIRECTUS_URL` and `DIRECTUS_TOKEN` through the CI secret context; skip the push if either value is absent.
+## Post-install manual steps
 
-## Development
+1. Restart the terminal to load environment variables
+2. Authenticate Atlassian for Codex: `codex mcp login atlassian`
+3. Install the ChatGPT app (Codex UI): <https://chatgpt.com/download>
+4. Install Claude Desktop: <https://claude.ai/download>
 
-From the monorepo root:
-
-```bash
-yarn workspace @cmflow/atlas build
-yarn workspace @cmflow/atlas test
-```
 
 ## License
 
-LicenseThe MIT License (MIT)Copyright (c) 2016 - Today ClubMed
+The MIT License (MIT)
+
+Copyright (c) 2016 - Today ClubMed
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.