@ontologie/cli 0.1.0-preview.1

package/README.md

@@ -0,0 +1,492 @@
+# @dataforge/cli
+
+[![Version](https://img.shields.io/badge/version-3.4.0-blue)](./) [![License](https://img.shields.io/badge/license-MIT-green)](./)
+
+> **`dataforge` -- SDK CLI for DataForge Platform**
+> Project scaffolding, type generation, login, and context engineering for AI agents.
+> Also available as `ontologie` (legacy alias).
+
+---
+
+## Pourquoi un CLI en plus des APIs et MCP ?
+
+Le CLI appelle le meme backend que l'API REST — il n'est pas "plus rapide". Sa valeur est ailleurs :
+
+- **Moins de friction** : 1 commande = aggregation multi-source (ontologie + knowledge + graphe). Remplace 3+ appels API sequentiels.
+- **Composabilite shell** : pipes, jq, scripts — `ontologie nodes search "X" --ids-only | ontologie graph neighbors --stdin`
+- **Integration pipeline agent** : stdout alimente directement les prompts LLM — `ontologie context pack "sujet" --format markdown | claude`
+- **Simplicite E2E** : `ontologie context pack` compile un context pack complet en une seule invocation
+
+**Cas d'usage** :
+- Pre-prompt context injection (`ontologie context pack "sujet" | claude`)
+- Scripts d'automatisation batch
+- CI/CD (validation schemas, health checks)
+- Composition Unix : `ontologie nodes search "X" --ids-only | ontologie graph neighbors --stdin`
+
+---
+
+## Installation
+
+```bash
+# Depuis le monorepo SDK
+pnpm install
+pnpm --filter @dataforge/cli build
+
+# Link global
+cd packages/cli && npm link
+
+# Verification
+dataforge --version   # -> 3.4.0
+dataforge --help
+```
+
+> **Migration** : Les binaires `ontologie` et `df` restent disponibles comme alias mais affichent un avertissement de deprecation. Utilisez `dataforge` pour tous les nouveaux projets.
+
+---
+
+## Configuration
+
+### Ordre de resolution
+
+```
+CLI flags (--api-key, --workspace)
+  |-> Variables d'environnement (ONTOLOGIE_API_KEY, ONTOLOGIE_WORKSPACE_ID)
+       |-> Variables legacy (DF_API_KEY, DF_WORKSPACE_ID) -- deprecated
+            |-> Fichier ~/.ontologierc (YAML, multi-profil)
+                 |-> Fichier ~/.dfrc (deprecated)
+                      |-> Defaut (api.dataforge.io)
+```
+
+### Fichier `~/.ontologierc`
+
+```yaml
+default:
+  api_url: https://api.dataforge.io
+  workspace_id: <uuid>
+  api_key: df_...
+
+staging:
+  api_url: https://api.dev-growthsystemes.com
+  workspace_id: <uuid>
+  api_key: df_...
+```
+
+> **Migration** : Si vous aviez un `~/.dfrc`, lancez `ontologie config migrate` pour le copier vers `~/.ontologierc`.
+
+### Variables d'environnement
+
+| Variable | Description | Legacy (deprecated) |
+|----------|-------------|---------------------|
+| `ONTOLOGIE_API_URL` | URL de base de l'API | `DF_API_URL` |
+| `ONTOLOGIE_API_KEY` | Cle API (prefixe `df_`) | `DF_API_KEY` |
+| `ONTOLOGIE_WORKSPACE_ID` | UUID du workspace | `DF_WORKSPACE_ID` |
+| `ONTOLOGIE_SPACE_ID` | UUID de l'espace (optionnel) | `DF_ESPACE_ID` |
+| `ONTOLOGIE_PROFILE` | Nom du profil ~/.ontologierc | `DF_PROFILE` |
+
+---
+
+## Commandes
+
+### `ontologie context pack <query>` -- Killer Feature
+
+Assemble un context pack LLM-ready avec budget tokens, en une seule requete.
+
+```bash
+# Basique
+ontologie context pack "politique RGPD"
+
+# Avec budget et profondeur custom
+ontologie context pack "gestion clients" --budget 4000 --depth 1
+
+# Sections specifiques
+ontologie context pack "pipeline ETL" --include ontology,knowledge
+
+# Format agent-optimized (Markdown)
+ontologie context pack "architecture microservices" --format markdown
+
+# JSON pour pipeline
+ontologie context pack "analyse RH" --format json | jq '.sections.knowledge.results'
+```
+
+**Options** :
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--budget <tokens>` | 8000 | Budget tokens total |
+| `--depth <n>` | 2 | Profondeur traversee graphe (1-3) |
+| `--include <sections>` | ontology,knowledge,graph | Sections a inclure |
+
+**Budget allocation** :
+- Ontology : 20% -- resume contextuel de l'ontologie
+- Knowledge : 40% -- resultats hybrid search (vector + lexical + graph)
+- Graph : 30% -- voisins graphe des entites trouvees
+- Reserve : 10% -- metadata, headers
+
+**Backend** : `POST /api/v1/context/pack` | Feature flag : `FEATURE_CONTEXT_PACK` | Auth : API key (no RBAC scope required)
+
+---
+
+### `ontologie nodes` -- Operations ontologie
+
+```bash
+# Lister les noeuds
+ontologie nodes list
+ontologie nodes list --type ObjectType --status active
+ontologie nodes list --ids-only                         # IDs seulement (pipe-friendly)
+ontologie nodes list --all                              # Auto-pagination
+
+# Recuperer un noeud
+ontologie nodes get <uuid>
+
+# Recherche hybride
+ontologie nodes search "Client"
+ontologie nodes search "employe RH" --types ObjectType --explain
+ontologie nodes search "facturation" --ids-only | ontologie graph neighbors --stdin
+```
+
+---
+
+### `ontologie knowledge search` -- Knowledge Library
+
+```bash
+ontologie knowledge search "politique de securite"
+ontologie knowledge search "RGPD conformite" --limit 5
+ontologie knowledge list
+ontologie knowledge get <id>
+```
+
+---
+
+### `dataforge query <type>` -- Query instances
+
+```bash
+# Basique
+dataforge query Contract --limit 20
+dataforge query Contract --where status=active --order-by created_at --order desc
+
+# Filtre JSON avance
+dataforge query Invoice --filter-json '{"status":"pending","amount_gt":1000}'
+
+# Estimation de cout (sans executer)
+dataforge query Contract --explain-cost --format json
+
+# IDs ou count seuls
+dataforge query Contract --ids-only
+dataforge query Contract --count
+```
+
+**Options** :
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--filter-json <json>` | — | JSON filter expression |
+| `--where <expr>` | — | Simple key=value filter |
+| `--order-by <field>` | — | Sort field |
+| `--order <dir>` | asc | Sort direction: asc\|desc |
+| `--select <fields>` | — | Comma-separated field list |
+| `--ids-only` | — | Output only IDs |
+| `--count` | — | Return only count |
+| `--cursor <cursor>` | — | Pagination cursor |
+| `--explain-cost` | — | Show estimated cost without executing |
+
+> **Limit**: Max `--limit` is 10,000. Use `--cursor` for larger datasets.
+
+---
+
+### `dataforge search <query>` -- Search entities
+
+```bash
+dataforge search "Acme" --types Company,Contract --limit 20
+dataforge search "facturation" --mode deterministic --explain
+dataforge search "Client" --ids-only
+```
+
+**Options** :
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--types <types>` | — | Comma-separated entity types |
+| `--limit <n>` | 10 | Max results |
+| `--explain` | — | Include score breakdown |
+| `--ids-only` | — | Output only IDs |
+| `--mode <mode>` | auto | Search mode: `auto` or `deterministic` (exact/fuzzy only, no semantic) |
+
+---
+
+### `ontologie graph` -- Traversee graphe
+
+```bash
+# Voisins directs (depth capped at 3)
+ontologie graph neighbors <node-id>
+ontologie graph neighbors <node-id> --depth 2 --direction outbound
+ontologie graph neighbors <node-id> --edge-types "manages,owns" --ids-only
+
+# N-hop traversal (depth capped at 5)
+ontologie graph traverse <node-id> --depth 3 --direction outbound
+
+# Shortest path (max-hops capped at 10)
+ontologie graph path <from> <to> --max-hops 5
+
+# Pipe composition
+ontologie nodes search "Client" --ids-only | ontologie graph neighbors --stdin --depth 2
+```
+
+**Depth limits (V1 stable)** :
+
+| Subcommand | Max depth | Default |
+|------------|-----------|---------|
+| `neighbors` | 3 | 1 |
+| `traverse` | 5 | 2 |
+| `path` (max-hops) | 10 | 5 |
+
+---
+
+### `dataforge schema` -- Schema operations
+
+```bash
+# Export full schema (raw JSON/YAML dump)
+dataforge schema export
+dataforge schema export --format yaml
+
+# Compare local dataforge.schema.ts vs remote ontology
+dataforge schema diff
+dataforge schema diff --schema ./custom-schema.ts
+
+# Push local schema changes to remote
+dataforge schema push --dry-run          # preview plan
+dataforge schema push --yes              # apply changes
+
+# Generate dataforge.schema.ts from remote ontology
+dataforge schema pull
+dataforge schema pull --output ./src/schema.ts
+
+# Compile schema + verify lockfile integrity
+dataforge schema check
+```
+
+**Schema workflow** :
+
+```
+dataforge init         ->  Edit dataforge.schema.ts  ->  dataforge schema diff
+                                                          |
+                                              dataforge schema push --yes
+                                                          |
+                                              dataforge generate
+```
+
+---
+
+### `ontologie whoami` -- Connection info
+
+```bash
+ontologie whoami
+# -> Workspace: xxx | API: https://api... | Health: OK
+```
+
+---
+
+### `ontologie doctor` -- Diagnostics
+
+```bash
+ontologie doctor
+# Checks: config, rc file, env vars, API connectivity, cache, Node.js version
+```
+
+---
+
+### `ontologie config` -- Configuration
+
+```bash
+ontologie config list
+# -> Affiche la config resolue (profil, URL, workspace, key masquee)
+
+ontologie config set api_key df_xxx
+ontologie config get workspace_id
+ontologie config migrate           # ~/.dfrc -> ~/.ontologierc
+```
+
+---
+
+## Options globales
+
+| Flag | Description |
+|------|-------------|
+| `-w, --workspace <id>` | Override workspace ID |
+| `-s, --space <id>` | Override space ID |
+| `--api-url <url>` | Override API URL |
+| `--api-key <key>` | Override API key |
+| `--profile <name>` | Profil ~/.ontologierc (defaut: "default") |
+| `-f, --format <fmt>` | Format: json, table, csv, yaml, markdown, jsonl, raw |
+| `--raw` | Alias pour `--format raw` (sans envelope _meta) |
+| `-n, --limit <n>` | Nombre max de resultats |
+| `-q, --quiet` | Supprimer les diagnostics stderr |
+| `-v, --verbose` | Diagnostics detailles sur stderr |
+| `--no-cache` | Bypass cache local |
+| `--cache <ttl>` | TTL cache (ex: 60s, 5m, 1h) |
+| `--keychain` | Force keychain credential resolution |
+
+---
+
+## Formats de sortie
+
+| Format | Usage | Destination |
+|--------|-------|-------------|
+| `json` | Default (pipe) | Machine, jq, scripts |
+| `table` | Default (TTY) | Humain, terminal |
+| `markdown` | Agent-optimized | LLM, context injection |
+| `csv` | Import | Tableurs, analyse |
+| `yaml` | Config | Documentation, IaC |
+| `jsonl` | Streaming | Logs, traitement ligne par ligne |
+| `raw` | Sans envelope | Quand `_meta` n'est pas voulu |
+
+> `--format plain` est un alias de `--format markdown` pour la retrocompatibilite.
+
+**Auto-detection** : si stdout est un TTY -> `table`, sinon -> `json`.
+
+---
+
+## Pipe composition
+
+Le CLI est concu pour la composition Unix :
+
+```bash
+# Rechercher -> explorer le graphe
+ontologie nodes search "Client" --ids-only | ontologie graph neighbors --stdin --depth 2
+
+# Context pack -> injection prompt
+ontologie context pack "architecture" --format markdown | pbcopy
+
+# Schema -> analyse jq
+ontologie schema export --format json | jq '.objectTypes | length'
+
+# Batch node details
+cat node-ids.txt | ontologie graph neighbors --stdin --ids-only | sort -u
+```
+
+---
+
+## Architecture
+
+```
++---------------------------------------------------------+
+|  $ ontologie context pack "query" --budget 4000          |
+|                                                         |
+|  CLI (Commander.js)                                     |
+|  +-- config.ts     -- Resolution chaine (flag>env>file) |
+|  +-- client.ts     -- Factory @dataforge/sdk-client     |
+|  +-- stdin.ts      -- Support pipe Unix                 |
+|  +-- cache/        -- Cache local SHA256 + TTL          |
+|  +-- output/       -- 7 formatters (json,table,csv,...) |
+|  +-- commands/     -- 9 commandes enregistrees          |
+|         |                                               |
+|         v HTTP                                          |
+|  @dataforge/sdk-client                                  |
+|  +-- ContextOperations.pack()                           |
+|         |                                               |
+|         v POST /api/v1/context/pack                     |
+|  Backend                                                |
+|  +-- Route: context-pack.ts (Zod validation)            |
+|  +-- Service: ContextPackService.ts                     |
+|       +-- OntologyContextService (20% budget)           |
+|       +-- HybridSearchService    (40% budget)           |
+|       +-- ArangoDBService        (30% budget)           |
++---------------------------------------------------------+
+```
+
+---
+
+## Contrat JSON (`dataforge.cli.v1`)
+
+Quand `--format json` est utilise, toutes les commandes retournent une enveloppe stable :
+
+```jsonc
+{
+  "ok": true,                    // boolean
+  "data": [...],                 // resultat (null si erreur)
+  "error": null,                 // CliError (null si succes)
+  "page": null,                  // pagination cursor-based (si applicable)
+  "meta": {
+    "schemaVersion": "dataforge.cli.v1",
+    "command": "nodes.list",
+    "requestId": "local_req_...",
+    "workspaceId": "...",
+    "environment": "staging",    // detecte depuis apiUrl
+    "warnings": []
+  }
+}
+```
+
+Specification complete : [`produit/02-cli/cli-contract.md`](../../../produit/02-cli/cli-contract.md)
+
+---
+
+## Codes de sortie
+
+| Code | Error Code | Signification |
+|------|-----------|--------------|
+| 0 | *(succes)* | Commande reussie |
+| 1 | `NOT_FOUND`, `UNAVAILABLE`, `INTERNAL_ERROR` | Ressource introuvable / erreur serveur |
+| 2 | `INVALID_USAGE` | Arguments CLI invalides |
+| 3 | `AUTHENTICATION_ERROR` | Credentials invalides ou manquants |
+| 4 | `AUTHORIZATION_ERROR` | Permissions insuffisantes |
+| 5 | `VALIDATION_ERROR` | Validation schema/payload echouee |
+| 6 | `SCHEMA_DRIFT_ERROR` | Manifeste local != schema distant |
+| 7 | `QUOTA_EXCEEDED` | Quota workspace epuise |
+| 8 | `RATE_LIMITED` | Trop de requetes (retryable) |
+| 9 | `CONFLICT_ERROR` | Conflit OCC (retryable) |
+| 10 | `PRECONDITION_FAILED`, `CONFIRMATION_REQUIRED` | Precondition non remplie / `--yes` requis |
+| 11 | `NETWORK_ERROR` | Connexion refusee / DNS (retryable) |
+| 12 | `TIMEOUT_ERROR` | Timeout (retryable) |
+
+---
+
+## Developpement
+
+```bash
+# Mode dev (sans build)
+cd sdk/packages/cli
+npx tsx src/cli.ts whoami --api-key df_... --workspace <uuid>
+
+# Build
+pnpm build
+
+# Tests
+pnpm test
+```
+
+---
+
+## Dependances
+
+| Package | Role |
+|---------|------|
+| `@dataforge/schema` | Schema DSL, compiler, diff, push/pull |
+| `@dataforge/sdk-client` | Client HTTP type-safe |
+| `@dataforge/sdk-types` | Types runtime |
+| `commander` | Framework CLI |
+| `yaml` | Parsing ~/.ontologierc |
+| `keytar` | (optional) Keychain credential storage |
+
+---
+
+## Migration depuis v0.1.0
+
+| v0.1.0 | v0.2.0 | Notes |
+|--------|--------|-------|
+| `df` | `ontologie` | Binaire `df` est un shim deprece |
+| `~/.dfrc` | `~/.ontologierc` | `ontologie config migrate` |
+| `DF_API_KEY` | `ONTOLOGIE_API_KEY` | Legacy vars still work (with warning) |
+| `DF_WORKSPACE_ID` | `ONTOLOGIE_WORKSPACE_ID` | Legacy vars still work (with warning) |
+| `-e, --espace` | `-s, --space` | `--espace` still works (hidden) |
+| `docs search` | `knowledge search` | `docs` still works (hidden alias) |
+| `--format plain` | `--format markdown` | `plain` still works (alias) |
+| `~/.df/cache/` | `~/.ontologie/cache/` | Old cache auto-detected |
+
+---
+
+## Voir aussi
+
+- [SDK README](../../README.md) -- Vue d'ensemble du SDK
+- [ContextPackService](../../../backend/src/services/ContextPackService.ts) -- Service backend
+- [Route API](../../../backend/src/routes/v1/context-pack.ts) -- Endpoint REST
+- [ContextCompiler](../../../backend/src/services/agent/memory/context/ContextCompiler.ts) -- Compilateur contexte agent avance

package/dist/cache/keys.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Cache key generation — deterministic SHA256 of request params
+ */
+export interface CacheKeyParams {
+    workspace: string;
+    espace?: string;
+    command: string;
+    params: Record<string, unknown>;
+}
+export declare function cacheKey(p: CacheKeyParams): string;
+//# sourceMappingURL=keys.d.ts.map

package/dist/cache/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../src/cache/keys.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,CAQlD"}

package/dist/cache/keys.js

@@ -0,0 +1,14 @@
+/**
+ * Cache key generation — deterministic SHA256 of request params
+ */
+import * as crypto from 'node:crypto';
+export function cacheKey(p) {
+    const payload = JSON.stringify({
+        w: p.workspace,
+        e: p.espace || '',
+        c: p.command,
+        p: p.params,
+    });
+    return crypto.createHash('sha256').update(payload).digest('hex').slice(0, 16);
+}
+//# sourceMappingURL=keys.js.map

package/dist/cache/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../src/cache/keys.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AAStC,MAAM,UAAU,QAAQ,CAAC,CAAiB;IACxC,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC;QAC7B,CAAC,EAAE,CAAC,CAAC,SAAS;QACd,CAAC,EAAE,CAAC,CAAC,MAAM,IAAI,EAAE;QACjB,CAAC,EAAE,CAAC,CAAC,OAAO;QACZ,CAAC,EAAE,CAAC,CAAC,MAAM;KACZ,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAChF,CAAC"}

package/dist/cache/store.d.ts

@@ -0,0 +1,23 @@
+/**
+ * File-based cache -- ~/.ontologie/cache/
+ *
+ * Key: SHA256 of { workspace, space, command, params }
+ * Layout: ~/.ontologie/cache/{workspace_prefix_8chars}/{hash}.json
+ * Default TTL: 60s, configurable per command
+ */
+import { type CacheKeyParams } from './keys.js';
+/** Parse TTL string like "60s", "5m", "1h" to seconds */
+export declare function parseTtl(ttl: string): number;
+export declare function cacheGet(params: CacheKeyParams): unknown | null;
+export declare function cacheSet(params: CacheKeyParams, data: unknown, ttlSeconds?: number): void;
+export declare function cacheClear(): {
+    count: number;
+    size: number;
+};
+export declare function cacheStats(): {
+    count: number;
+    size: number;
+    oldest?: Date;
+    newest?: Date;
+};
+//# sourceMappingURL=store.d.ts.map

package/dist/cache/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/cache/store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,EAAY,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AA4C1D,yDAAyD;AACzD,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAU5C;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,GAAG,IAAI,CA8B/D;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,SAAK,GAAG,IAAI,CAerF;AAED,wBAAgB,UAAU,IAAI;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAyB5D;AAED,wBAAgB,UAAU,IAAI;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,IAAI,CAAC;IAAC,MAAM,CAAC,EAAE,IAAI,CAAA;CAAE,CAiC1F"}