@dmension-software/agentinstall-spec

Source canonique unique de l'architecture AgentInstall. Lu par les générateurs (CLI, cloud-bootstrap) et le validator runtime chez chaque client.

Structure

spec/
├── architecture-v5.2.yaml    ← la spec (source de vérité)
├── schemas/
│   └── architecture.schema.json  ← JSON Schema (validation)
└── src/
    ├── loader.ts             ← loadSpec() + validation AJV
    ├── types.ts              ← types TS miroir du schema
    ├── validate.ts           ← CLI de validation (npm run validate)
    └── index.ts              ← exports publics

Usage

Depuis un consommateur (CLI, Worker, cloud-bootstrap)

import { loadSpec } from "@dmension-software/agentinstall-spec";

const { spec, version, hash } = loadSpec();
console.log(spec.gateway.port);        // 18789
console.log(spec.agents_defaults.model.primary);  // google-vertex/gemini-2.5-flash
console.log(spec.required_agents.length);  // 2 (fusion v5.2)

Validation manuelle

npm run validate

Exit 0 si OK, 1 sinon. À intégrer dans CI/CD.

Extension de la spec

1. Éditer architecture-v5.2.yaml
2. Si nouveau champ obligatoire → mettre à jour schemas/architecture.schema.json et src/types.ts
3. Bump spec_version :
   • PATCH (5.2.0 → 5.2.1) : valeur par défaut ajustée
   • MINOR (5.2.0 → 5.3.0) : nouveau champ optionnel ou nouvelle section
   • MAJOR (5.2.0 → 6.0.0) : breaking change (champ renommé, enum supprimé)
4. npm run validate pour confirmer
5. Commit

Versioning

Semver strict. Les validators runtime chez les clients refusent une spec major différente de celle à leur installation — migration opt-in via commande agentinstall upgrade.

Hash SHA-256

Chaque loadSpec() retourne un hash du YAML source. Il est :

• posté dans le #systeme channel du client à chaque démarrage
• affiché dans /api/admin/fleet-health (Worker Cloudflare)
• utilisé pour détecter qu'un client tourne sur une spec obsolète

Fichiers consommés par

| Consommateur | Usage | |---|---| | cli/src/generators/openclaw-config.ts | Génération du openclaw.json client | | cli/src/generators/cron.ts | Génération des crons (triggers + maintenance) | | cli/src/generators/shared-drive.ts | Création de l'arborescence shared drive (dynamique) | | cli/src/generators/scripts.ts | Copie des scripts maintenance | | cloud/cloud-bootstrap.mjs | Bootstrap container Cloud | | api/src/validator/runtime.ts (à créer P5) | Validator runtime + auto-repair | | api/src/admin/fleet-health.ts (à créer P7) | Dashboard conformité |