zot-iasset

CLI MIT (zot-iasset sur npm, commande iasset) pour cadrer l’usage des agents (Cursor, Claude Code, OpenCode, CI) via un dossier partageable et auditable iasset/.

0.3.0 — npx [email protected]. Reviews auto et agents distribués sur runners GitLab (voir CHANGELOG).

Architecture · Specification · Security · Evaluation · Tests

Blueprint

Pourquoi iASSET et comment ça fonctionne (schémas + animations) — même style que open-api-importer :

• Local : ouvrir docs/blueprint/index.html
• Publié via GitLab Pages (branche par défaut) : https://zot-lab.gitlab.io/iasset/

Install (npm)

npm i -g zot-iasset
iasset --help

# ou sans install globale
npx zot-iasset --help

Install / dev

pnpm install
pnpm build
pnpm link --global   # optionnel → commande iasset

Sans link :

node dist/cli.js <command>
# ou
pnpm dev -- <command>

Exemple

Un CRM simple cadré avec iASSET est disponible en sous-module :

git submodule update --init --recursive
cd examples/simple-crm
iasset status
iasset validate --gate all

Dépôt : zot-lab/example-iasset-simple-crm

CI GitLab (reviews auto + agents distribués)

Template : templates/gitlab-ci.iasset.yml — ADR 004.

include:
  - local: 'node_modules/zot-iasset/templates/gitlab-ci.iasset.yml'
# ou:
#   - project: 'zot-lab/iasset'
#     file: '/templates/gitlab-ci.iasset.yml'

Sur MR / branche par défaut / trigger API, le job iasset:emit génère une child pipeline : un job GitLab (un runner) par agent de vérification.

| Job child | Commande | Si fail | |---|---|---| | iasset:validate | iasset validate --gate all | pipeline rouge | | iasset:review:architecture-reviewer | iasset agent run architecture-reviewer | pipeline rouge | | iasset:review:security-auditor | iasset agent run security-auditor | pipeline rouge | | iasset:review:spec-compliance | iasset agent run spec-compliance | pipeline rouge | | iasset:comment | iasset ci comment | allow_failure (note MR si GITLAB_TOKEN) |

Artifacts : iasset/reports/ (14 jours). Verdict fail → exit 1.

# Voir le DAG runners sans GitLab
iasset ci list
iasset ci emit --mode review

# Déclencher une pipeline GitLab (GITLAB_TOKEN ou GITLAB_TRIGGER_TOKEN)
iasset ci trigger --mode review --ref main

# Reviews + un job flow par spec (DAG depends_on), driver stub par défaut
iasset ci emit --mode all
iasset ci trigger --mode implement --spec contacts.create

Variables utiles : IASSET_BIN, IASSET_CI_MODE (review | implement | all), IASSET_CI_SPECS, IASSET_DRIVER, IASSET_CI_SKIP_MR.

Le gate architecture vérifie le diff git contre iasset/architecture/boundaries.yaml (must_not_edit, may_edit_with_gate).
Le gate security échoue si un tracking status: gap sur une obligation must n’a pas d’explain (gap_without_explain).

Ce dépôt (zot-lab/iasset) ne lance pas ces reviews : pas de dossier iasset/ métier. Sa CI = smoke du CLI + Pages. Les agents tournent sur le GitLab du projet consommateur qui include le template (celui qui a déjà iasset/).

Flow semi-autonome (jusqu’à la MR)

# Dry-run (pas de push / pas d’API GitLab)
iasset flow --spec contacts.create --driver stub --dry-run --cwd examples/simple-crm

# Boucle repair jusqu’au vert (gates + tests)
iasset flow --spec contacts.create --driver openai --run-tests --max-rounds 5 --skip-mr

# Backlog série (dépendances + queue) — ADR 001
iasset orchestrate --plan --cwd examples/simple-crm
iasset orchestrate --jobs 2 --driver openai --max-rounds 5 --skip-mr --cwd examples/simple-crm

# Étapes unitaires
iasset agent implement --spec contacts.create --driver stub
iasset validate --gate all
iasset agent run architecture-reviewer
iasset mr open --spec contacts.create --dry-run

# Ouvrir une vraie MR (token GitLab ou glab)
export GITLAB_TOKEN=…
iasset flow --spec contacts.create --driver stub

flow --max-rounds N orchestre : implement → validate/agents/(tests) → si rouge, réinjecte les échecs dans le prompt → re-implement, jusqu’à vert ou N tours.

flow n’ouvre une MR (commit/push) que si le dernier round est GREEN. Un flow rouge ne pollue pas GitLab.

iasset orchestrate enchaîne les behaviors selon depends_on. File d’état : iasset/reports/orchestrate-latest.yaml.

• Série (défaut) : ADR 001
• --jobs N : worktrees parallèles + hooks setup/teardown/env des suites — ADR 002
• Escalade : runtime.fallback dans iasset/agents/implementer.yaml (pas d’auto-merge)
• Hooks implement : iasset/implement/hooks.yaml (absent = no-op) — ADR 003
• Tests : plans générés + jobs de suites en child pipeline — ADR 005

iasset orchestrate --jobs 2 --driver openai --max-rounds 5 --skip-mr

Drivers d’implémentation :

| Driver | Rôle | |--------|------| | auto (défaut) | openai si base_url configuré → Claude Code → Cursor SDK → IASSET_IMPLEMENT_CMD | | openai | API OpenAI-compatible sur un port dédié (Ollama, LM Studio, vLLM, LiteLLM…) — l’agent code via tools | | claude | Lance claude -p (headless) avec budget + tools Edit/Write | | cursor | @cursor/sdk Agent.prompt local (CURSOR_API_KEY requis) | | stub | Placeholder TS (smoke / CI sans LLM) | | prompt-only | Génère seulement le prompt | | shell | Commande custom (IASSET_IMPLEMENT_CMD, {prompt} {cwd}) |

Modèle custom sur un port local

# Ollama / LM Studio / vLLM (OpenAI-compatible)
export IASSET_LLM_BASE_URL=http://127.0.0.1:11434/v1
export IASSET_LLM_MODEL=qwen2.5-coder
# export IASSET_LLM_API_KEY=local   # défaut: local

node dist/cli.js agent implement --spec contacts.create --cwd examples/simple-crm
# ou explicitement:
node dist/cli.js agent implement --spec contacts.create \
  --driver openai \
  --base-url http://127.0.0.1:11434/v1 \
  --model qwen2.5-coder \
  --cwd examples/simple-crm

Ou dans iasset/agents/implementer.yaml :

runtime:
  driver: openai
  base_url: http://127.0.0.1:11434/v1
  model: qwen2.5-coder
  api_key_env: IASSET_LLM_API_KEY
  max_turns: 24

# Auth Claude Code une fois
claude   # puis /login
# ou: export ANTHROPIC_API_KEY=…

# L’agent implémente la spec (vrai code)
node dist/cli.js agent implement --spec contacts.create --cwd examples/simple-crm

# Flux jusqu’à la MR
node dist/cli.js flow --spec contacts.create --cwd examples/simple-crm

Budget : iasset/agents/implementer.yaml → budget.max_usd (passé à claude --max-budget-usd), surchargeable via --max-budget-usd.

mr open applique iasset/evaluation/behaviors/gate-conduct.yaml (draft si block_merge, label iasset-gate si needs_human).

Tester rapidement

pnpm build
pnpm test:smoke

Ou manuellement dans un dossier vide :

mkdir -p /tmp/iasset-demo && cd /tmp/iasset-demo
node /path/to/iasset/dist/cli.js init --name demo --architecture hexagonal
node /path/to/iasset/dist/cli.js spec add --id auth.login.form --linear ENG-142
node /path/to/iasset/dist/cli.js tests generate --from-spec auth.login.form --kind unit
node /path/to/iasset/dist/cli.js tests generate --from-spec auth.login.form --kind scenario
# ou : iasset tests generate --all --kind unit
node /path/to/iasset/dist/cli.js sync --target cursor
node /path/to/iasset/dist/cli.js validate --gate all
node /path/to/iasset/dist/cli.js agent run security-auditor
node /path/to/iasset/dist/cli.js eval commit-message --behavior auth.login.form

Commandes principales

| Commande | Rôle | |----------|------| | iasset init | Crée iasset/ (A/S/S/E/T + skills + agents) | | iasset validate --gate all | Gates CI | | iasset sync --target cursor\|claude-code\|opencode\|all | Exporte skills IDE | | iasset spec add / find | Behaviors YAML/Gherkin + external keys | | iasset tests generate | Plans unit / scenarios (--from-spec ou --all) ; le job CI les régénère avant tests run (ADR 005) | | iasset eval run / commit-message | Mode d’évaluation + message de commit | | iasset agent run <id> | Agents de vérification déterministes (CI) | | iasset agent implement --spec | Agent d’implémentation (stub/prompt/shell) | | iasset flow --spec | implement → validate → agents → MR si GREEN | | iasset orchestrate | backlog selon depends_on (--jobs = worktrees locaux) | | iasset ci emit / list / trigger / comment | Child pipeline GitLab : un runner par agent, spec ou suite de tests | | iasset mr open --spec | Ouvre/met à jour une MR GitLab + gate-conduct | | iasset tests run | Exécute les suites déclarées (si commande dispo) | | iasset architecture list-presets | hexa, 3-layer, MVC, clean, … |

Licence

MIT — voir LICENSE.

Le package npm zot-iasset est MIT. Le contenu du dossier iasset/ dans un repo client reste la propriété du projet.

Publish

Version actuelle : 0.3.0.

Inclus : CLI (init, validate, implement, flow, orchestrate local, mr GitLab), template CI child-pipeline, iasset ci *, reviews déterministes en runners.

Hors 0.3.0 : auto-merge, GitHub Actions, reviews LLM optionnelles, isolation DB dans le CLI.

pnpm build && pnpm test:smoke
npm publish

(latest sur npm. Ne pas passer --tag beta.)

Consommer :

npx --yes [email protected] --help