create-maedow-arch-app 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jean-Marc
+
+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.

package/README.md

@@ -0,0 +1,63 @@
+# create-maedow-arch-app
+
+CLI de scaffolding de [Maedow Arch](https://github.com/maedow-arch/maedow-arch-docs) — un standard d'architecture logicielle modulaire, découplé et agnostique de l'infrastructure, pour TypeScript / React / Next.js.
+
+## Démarrage
+
+```bash
+npx create-maedow-arch-app mon-projet
+cd mon-projet
+npm install
+npm run dev
+```
+
+## Ce qui est généré
+
+```
+mon-projet/
+├── src/
+│   ├── app/            # Routes et orchestration — peut tout importer
+│   ├── features/       # Écrans et logique de vue
+│   │   └── _shared/    # Composants métier transverses
+│   ├── core/           # Domaine métier — zéro dépendance UI
+│   │   └── common/
+│   │       └── result.ts   # Result Pattern + helpers unwrapOr / mapResult / match
+│   ├── components/ui/  # Présentationnel pur
+│   ├── lib/            # Utilitaires sans dépendance
+│   └── tests/          # unit / integration / e2e
+├── scripts/            # Générateurs de domaine et de feature
+├── eslint.config.mjs   # Frontières architecturales appliquées au lint
+├── tsconfig.json       # TypeScript strict (noUncheckedIndexedAccess, exactOptionalPropertyTypes…)
+└── vitest.config.ts
+```
+
+## Générateurs
+
+```bash
+npm run generate:domain billing    # src/core/billing/     — types, validation Zod, service
+npm run generate:feature checkout  # src/features/checkout/ — Screen, hook, types, test
+```
+
+Le domaine généré applique la **Règle de Lazy Abstraction** : accès direct à la donnée, et pas de `contract.ts` ni d'adapters tant qu'une deuxième implémentation réelle n'est pas nécessaire.
+
+## Frontières architecturales
+
+Le flux de dépendance est unidirectionnel — `app → features → core → lib` — et vérifié au lint :
+
+```bash
+npm run lint
+```
+
+```
+Maedow Arch : core ne peut pas importer components. Voir architecture.md §6.
+```
+
+Les règles vivent dans [`eslint-config-maedow-arch`](https://www.npmjs.com/package/eslint-config-maedow-arch), installé par défaut dans le projet généré.
+
+## Documentation
+
+Le corpus complet — les 4 couches, la typologie des modèles, le Result Pattern, les conventions et les modes Light / Full — est sur [github.com/maedow-arch/maedow-arch-docs](https://github.com/maedow-arch/maedow-arch-docs).
+
+## Licence
+
+MIT

package/bin/create-maedow-arch-app.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+import { cpSync, readFileSync, writeFileSync, existsSync, mkdirSync, renameSync, rmSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const DOCS_URL = "https://github.com/maedow-arch/maedow-arch-docs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const templateDir = join(__dirname, "..", "templates", "base");
+
+const projectName = process.argv[2];
+if (!projectName) {
+  console.error("Usage: npx create-maedow-arch-app <nom-du-projet>");
+  process.exit(1);
+}
+
+// Le nom finit dans un package.json : on refuse ce que npm refuserait.
+if (!/^[a-z0-9][a-z0-9._-]*$/.test(projectName)) {
+  console.error(
+    `❌ "${projectName}" n'est pas un nom de package valide.\n` +
+      "   Minuscules, chiffres, tirets, points et underscores ; commence par une lettre ou un chiffre."
+  );
+  process.exit(1);
+}
+
+const targetDir = join(process.cwd(), projectName);
+
+if (existsSync(targetDir)) {
+  console.error(`❌ Le dossier "${projectName}" existe déjà.`);
+  process.exit(1);
+}
+
+console.log(`📦 Création du projet Maedow Arch "${projectName}"...`);
+
+mkdirSync(targetDir, { recursive: true });
+cpSync(templateDir, targetDir, { recursive: true });
+
+// package.json.template -> package.json, avec le vrai nom du projet.
+const pkgTemplatePath = join(targetDir, "package.json.template");
+writeFileSync(
+  join(targetDir, "package.json"),
+  readFileSync(pkgTemplatePath, "utf-8").replaceAll("__PROJECT_NAME__", projectName)
+);
+rmSync(pkgTemplatePath);
+
+// npm exclut les fichiers nommés `.gitignore` des packages publiés :
+// le template le transporte sous le nom `_gitignore`.
+const gitignoreSource = join(targetDir, "_gitignore");
+if (existsSync(gitignoreSource)) {
+  renameSync(gitignoreSource, join(targetDir, ".gitignore"));
+}
+
+// Le nom du projet apparaît aussi dans les fichiers de l'app.
+for (const relativePath of ["src/app/layout.tsx", "src/app/page.tsx"]) {
+  const filePath = join(targetDir, relativePath);
+  if (existsSync(filePath)) {
+    writeFileSync(
+      filePath,
+      readFileSync(filePath, "utf-8").replaceAll("__PROJECT_NAME__", projectName)
+    );
+  }
+}
+
+console.log(`✅ Projet créé dans ./${projectName}`);
+console.log("");
+console.log("Prochaines étapes :");
+console.log(`  cd ${projectName}`);
+console.log("  npm install");
+console.log("  npm run dev");
+console.log("");
+console.log("Générateurs :");
+console.log("  npm run generate:domain <mon-premier-domaine>   # une entité métier dans src/core/");
+console.log("  npm run generate:feature <ma-premiere-feature>  # un écran dans src/features/");
+console.log("");
+console.log("  npm run lint   # vérifie les frontières architecturales");
+console.log("");
+console.log(`📖 Doc complète : ${DOCS_URL}`);

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "create-maedow-arch-app",
+  "version": "0.1.0",
+  "description": "Scaffold un projet suivant Maedow Arch (app/features/core/components/lib, Result Pattern, ESLint boundaries)",
+  "type": "module",
+  "bin": {
+    "create-maedow-arch-app": "./bin/create-maedow-arch-app.mjs"
+  },
+  "files": [
+    "bin",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "maedow-arch",
+    "architecture",
+    "scaffold",
+    "cli",
+    "boilerplate",
+    "nextjs",
+    "clean-architecture",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "Jean-Marc",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maedow-arch/maedow-arch-docs.git",
+    "directory": "packages/create-maedow-arch-app"
+  },
+  "homepage": "https://github.com/maedow-arch/maedow-arch-docs#readme",
+  "bugs": {
+    "url": "https://github.com/maedow-arch/maedow-arch-docs/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/templates/base/_gitignore

@@ -0,0 +1,9 @@
+node_modules
+.next
+out
+build
+*.tsbuildinfo
+next-env.d.ts
+.env*.local
+.vercel
+.DS_Store

package/templates/base/eslint.config.mjs

@@ -0,0 +1,8 @@
+import maedowArchConfig from "eslint-config-maedow-arch";
+import tseslint from "typescript-eslint";
+
+export default [
+  { ignores: [".next/**", "node_modules/**"] },
+  { files: ["**/*.{ts,tsx}"], languageOptions: { parser: tseslint.parser } },
+  ...maedowArchConfig,
+];

package/templates/base/next.config.mjs

@@ -0,0 +1,6 @@
+/** @type {import('next').NextConfig} */
+const config = {
+  reactStrictMode: true,
+};
+
+export default config;

package/templates/base/package.json.template

@@ -0,0 +1,34 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "generate:feature": "node scripts/scaffold-feature.mjs",
+    "generate:domain": "node scripts/scaffold-domain.mjs"
+  },
+  "dependencies": {
+    "next": "^15.5.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "eslint": "^9.39.0",
+    "eslint-config-maedow-arch": "^0.1.0",
+    "eslint-import-resolver-typescript": "^4.4.0",
+    "eslint-plugin-boundaries": "^7.2.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.68.0",
+    "vitest": "^2.1.0"
+  }
+}

package/templates/base/scripts/scaffold-domain.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { mkdirSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+const name = process.argv[2];
+if (!name) {
+  console.error("Usage: npm run generate:domain <nom>");
+  process.exit(1);
+}
+
+const pascal = name.charAt(0).toUpperCase() + name.slice(1);
+const dir = join("src", "core", name);
+
+if (existsSync(dir)) {
+  console.error(`Le domaine "${name}" existe déjà dans ${dir}`);
+  process.exit(1);
+}
+
+mkdirSync(dir, { recursive: true });
+
+writeFileSync(
+  join(dir, "types.ts"),
+  `// Entité métier du domaine "${name}"\n\nexport interface ${pascal} {\n  id: string;\n  // TODO: champs métier\n}\n`
+);
+
+writeFileSync(
+  join(dir, "validation.ts"),
+  `import { z } from "zod";\n\nexport const Create${pascal}Schema = z.object({\n  // TODO: champs à valider\n});\n\nexport type Create${pascal}DTO = z.infer<typeof Create${pascal}Schema>;\n`
+);
+
+writeFileSync(
+  join(dir, "service.ts"),
+  `import type { Result } from "../common/result";\nimport type { ${pascal} } from "./types";\nimport type { Create${pascal}DTO } from "./validation";\n\n// ⚠️ Règle de Lazy Abstraction : n'introduis un contract.ts + adapters\n// que lorsqu'une deuxième implémentation réelle est nécessaire.\n// Tant qu'un seul fournisseur de données existe, accède-y directement ici.\n\nexport async function create${pascal}(input: Create${pascal}DTO): Promise<Result<${pascal}>> {\n  // TODO: logique métier\n  return { ok: false, error: "not_implemented" };\n}\n`
+);
+
+console.log(`✅ Domaine "${name}" généré dans ${dir}/`);
+console.log(`   - types.ts`);
+console.log(`   - validation.ts`);
+console.log(`   - service.ts (accès direct — voir la Règle de Lazy Abstraction)`);
+console.log(`   Rappel : n'ajoute contract.ts + repository.ts que si un 2ème fournisseur devient réel.`);

package/templates/base/scripts/scaffold-feature.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { mkdirSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+const name = process.argv[2];
+if (!name) {
+  console.error("Usage: npm run generate:feature <nom>");
+  process.exit(1);
+}
+
+const pascal = name.charAt(0).toUpperCase() + name.slice(1);
+const dir = join("src", "features", name);
+
+if (existsSync(dir)) {
+  console.error(`La feature "${name}" existe déjà dans ${dir}`);
+  process.exit(1);
+}
+
+mkdirSync(join(dir, "hooks"), { recursive: true });
+mkdirSync(join(dir, "components"), { recursive: true });
+
+writeFileSync(
+  join(dir, "types.ts"),
+  `// Types d'affichage locaux à la feature "${name}"\n\nexport interface ${pascal}View {\n  // TODO\n}\n`
+);
+
+writeFileSync(
+  join(dir, "hooks", `use${pascal}.ts`),
+  `import { useState } from "react";\nimport type { ${pascal}View } from "../types";\n\nexport function use${pascal}() {\n  const [state, setState] = useState<${pascal}View | null>(null);\n  return { state, isLoading: false };\n}\n`
+);
+
+writeFileSync(
+  join(dir, "Screen.tsx"),
+  `import { use${pascal} } from "./hooks/use${pascal}";\n\nexport function ${pascal}Screen() {\n  const { state, isLoading } = use${pascal}();\n\n  if (isLoading) return <p>Chargement...</p>;\n\n  return <div>{/* TODO: rendu de ${pascal} */}</div>;\n}\n`
+);
+
+writeFileSync(
+  join(dir, `${pascal}.test.tsx`),
+  `import { describe, it, expect } from "vitest";\n\ndescribe("${pascal}Screen", () => {\n  it.todo("affiche l'écran ${name}");\n});\n`
+);
+
+console.log(`✅ Feature "${name}" générée dans ${dir}/`);
+console.log(`   - types.ts`);
+console.log(`   - hooks/use${pascal}.ts`);
+console.log(`   - Screen.tsx`);
+console.log(`   - ${pascal}.test.tsx`);

package/templates/base/src/app/layout.tsx

@@ -0,0 +1,14 @@
+import type { ReactNode } from "react";
+
+export const metadata = {
+  title: "__PROJECT_NAME__",
+  description: "Application suivant Maedow Arch",
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="fr">
+      <body>{children}</body>
+    </html>
+  );
+}

package/templates/base/src/app/page.tsx

@@ -0,0 +1,19 @@
+export default function HomePage() {
+  return (
+    <main style={{ fontFamily: "system-ui, sans-serif", padding: "3rem", lineHeight: 1.6 }}>
+      <h1>__PROJECT_NAME__</h1>
+      <p>Projet généré avec Maedow Arch.</p>
+      <ol>
+        <li>
+          <code>npm run generate:domain &lt;nom&gt;</code> — crée un domaine métier dans <code>src/core/</code>
+        </li>
+        <li>
+          <code>npm run generate:feature &lt;nom&gt;</code> — crée une feature dans <code>src/features/</code>
+        </li>
+        <li>
+          <code>npm run lint</code> — vérifie les frontières architecturales
+        </li>
+      </ol>
+    </main>
+  );
+}

package/templates/base/src/core/common/result.ts

@@ -0,0 +1,21 @@
+export type Result<TData, TError = string> =
+  | { ok: true; data: TData }
+  | { ok: false; error: TError };
+
+export function unwrapOr<TData, TError>(result: Result<TData, TError>, fallback: TData): TData {
+  return result.ok ? result.data : fallback;
+}
+
+export function mapResult<TData, TMapped, TError>(
+  result: Result<TData, TError>,
+  fn: (data: TData) => TMapped
+): Result<TMapped, TError> {
+  return result.ok ? { ok: true, data: fn(result.data) } : result;
+}
+
+export function match<TData, TError, TReturn>(
+  result: Result<TData, TError>,
+  handlers: { ok: (data: TData) => TReturn; err: (error: TError) => TReturn }
+): TReturn {
+  return result.ok ? handlers.ok(result.data) : handlers.err(result.error);
+}

package/templates/base/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "exactOptionalPropertyTypes": true,
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "preserve",
+    "allowJs": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "incremental": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    },
+    "plugins": [{ "name": "next" }]
+  },
+  "include": ["src", "next-env.d.ts", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/templates/base/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    // Le domaine (core/) se teste sans monter d'arbre React : c'est tout
+    // l'intérêt de la règle « Zéro Modèle dans le JSX ».
+    include: ["src/**/*.test.{ts,tsx}"],
+  },
+});