npm - @donartcha/openlag - Versions diffs - 0.1.0 - Mend

@donartcha/openlag 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (99) hide show

package/LICENSE +373 -0
package/README.md +82 -0
package/bin/openlag.js +2 -0
package/dist/assets/arc-4YUHkXo3.js +1 -0
package/dist/assets/architectureDiagram-3BPJPVTR-WeGmL7HM.js +36 -0
package/dist/assets/blockDiagram-GPEHLZMM-CtV7ubAx.js +132 -0
package/dist/assets/c4Diagram-AAUBKEIU-DqYDW5c3.js +10 -0
package/dist/assets/channel-Tsel3-MK.js +1 -0
package/dist/assets/chunk-2J33WTMH-BE8P9tjh.js +1 -0
package/dist/assets/chunk-4BX2VUAB-Bi7oLGF5.js +1 -0
package/dist/assets/chunk-55IACEB6-D9Xhxp_r.js +1 -0
package/dist/assets/chunk-727SXJPM-Dz8jKE60.js +206 -0
package/dist/assets/chunk-AQP2D5EJ-BzmM0IeH.js +231 -0
package/dist/assets/chunk-FMBD7UC4-Cvl5dpcx.js +15 -0
package/dist/assets/chunk-ND2GUHAM-Dz2efqnq.js +1 -0
package/dist/assets/chunk-QZHKN3VN-CwblgSnQ.js +1 -0
package/dist/assets/classDiagram-4FO5ZUOK-Bgm-_cW8.js +1 -0
package/dist/assets/classDiagram-v2-Q7XG4LA2-Bgm-_cW8.js +1 -0
package/dist/assets/cose-bilkent-S5V4N54A-h_A3nZUx.js +1 -0
package/dist/assets/cytoscape.esm-D_LviqZs.js +331 -0
package/dist/assets/dagre-BM42HDAG-CN_B2Doz.js +4 -0
package/dist/assets/defaultLocale-DX6XiGOO.js +1 -0
package/dist/assets/diagram-2AECGRRQ-C9TAFwjG.js +43 -0
package/dist/assets/diagram-5GNKFQAL-BThljQLo.js +10 -0
package/dist/assets/diagram-KO2AKTUF-bRPq25Se.js +3 -0
package/dist/assets/diagram-LMA3HP47-BubLCIus.js +24 -0
package/dist/assets/diagram-OG6HWLK6-CJpfhIsS.js +24 -0
package/dist/assets/erDiagram-TEJ5UH35-6Xkza9wL.js +85 -0
package/dist/assets/flowDiagram-I6XJVG4X-Bq_to3hX.js +162 -0
package/dist/assets/ganttDiagram-6RSMTGT7-C3CmvYl7.js +292 -0
package/dist/assets/gitGraphDiagram-PVQCEYII-C93LTfrl.js +106 -0
package/dist/assets/graph-CAnANduQ.js +1 -0
package/dist/assets/index-0RMQQ34p.css +1 -0
package/dist/assets/index-ByxguSZe.js +729 -0
package/dist/assets/infoDiagram-5YYISTIA-CMfuwygl.js +2 -0
package/dist/assets/init-Gi6I4Gst.js +1 -0
package/dist/assets/ishikawaDiagram-YF4QCWOH-CbJ5ojDF.js +70 -0
package/dist/assets/journeyDiagram-JHISSGLW-C_Xz8YyT.js +139 -0
package/dist/assets/kanban-definition-UN3LZRKU-GVv_iRMq.js +89 -0
package/dist/assets/katex-DkKDou_j.js +257 -0
package/dist/assets/layout-DGIYPm2g.js +1 -0
package/dist/assets/linear-BNEtUH2J.js +1 -0
package/dist/assets/mindmap-definition-RKZ34NQL-DIsL0XSF.js +96 -0
package/dist/assets/ordinal-Cboi1Yqb.js +1 -0
package/dist/assets/pieDiagram-4H26LBE5-CSCTSOjk.js +30 -0
package/dist/assets/quadrantDiagram-W4KKPZXB-CQQ9OaFY.js +7 -0
package/dist/assets/requirementDiagram-4Y6WPE33-Cjn3la_S.js +84 -0
package/dist/assets/sankeyDiagram-5OEKKPKP-DoVspvVc.js +40 -0
package/dist/assets/sequenceDiagram-3UESZ5HK-UsoGmL4w.js +162 -0
package/dist/assets/stateDiagram-AJRCARHV-DLmf7Dc8.js +1 -0
package/dist/assets/stateDiagram-v2-BHNVJYJU-jkiDZ_3u.js +1 -0
package/dist/assets/timeline-definition-PNZ67QCA-HfyRxZ8p.js +120 -0
package/dist/assets/vennDiagram-CIIHVFJN-B6pM3L33.js +34 -0
package/dist/assets/wardley-L42UT6IY-B-LdKtrI.js +173 -0
package/dist/assets/wardleyDiagram-YWT4CUSO-BD45zhOu.js +78 -0
package/dist/assets/xychartDiagram-2RQKCTM6-zsDMbUiS.js +7 -0
package/dist/cli/openlag.js +1793 -0
package/dist/index.html +14 -0
package/index.html +13 -0
package/package.json +84 -0
package/scripts/cli/build.ts +34 -0
package/scripts/cli/dev.ts +35 -0
package/scripts/cli/generate.ts +92 -0
package/scripts/cli/init.ts +427 -0
package/scripts/cli/lint.ts +29 -0
package/scripts/cli/openlag.ts +110 -0
package/scripts/cli/vite-bin.ts +8 -0
package/scripts/core/parser/diagnostic.ts +34 -0
package/scripts/core/parser/normalizer.ts +27 -0
package/scripts/core/parser/scanner.ts +30 -0
package/scripts/core/parser/schemas.ts +23 -0
package/scripts/core/parser/types.ts +30 -0
package/scripts/core/parser.ts +127 -0
package/scripts/generate-relations.ts +53 -0
package/scripts/lint/lint-engine.ts +85 -0
package/scripts/lint/lint-profiles.ts +49 -0
package/scripts/lint/lint-rules.ts +174 -0
package/scripts/lint/lint-types.ts +43 -0
package/src/App.tsx +164 -0
package/src/components/DocumentationView.tsx +905 -0
package/src/components/GraphView.tsx +529 -0
package/src/components/GuideView.tsx +535 -0
package/src/components/ImpactView.tsx +365 -0
package/src/components/MarkdownRenderer.tsx +120 -0
package/src/components/OrphansView.tsx +360 -0
package/src/components/SettingsView.tsx +146 -0
package/src/core/generated/relation-definitions.ts +622 -0
package/src/core/graph/GraphQueryLayer.ts +194 -0
package/src/core/registry/ArtifactRegistry.ts +19 -0
package/src/core/registry/RelationRegistry.ts +27 -0
package/src/core/semantic/artifact-layers.ts +43 -0
package/src/core/semantic/ownership-rules.ts +13 -0
package/src/core/semantic/types.ts +11 -0
package/src/index.css +121 -0
package/src/lib/reportUtils.ts +59 -0
package/src/main.tsx +10 -0
package/src/store.ts +146 -0
package/src/types.ts +77 -0
package/vite.config.ts +31 -0

package/dist/index.html ADDED Viewed

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>My OpenLAG Project | OpenLAG</title>
+    <script type="module" crossorigin src="/assets/index-ByxguSZe.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-0RMQQ34p.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/index.html ADDED Viewed

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>My OpenLAG Project | OpenLAG</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/package.json ADDED Viewed

@@ -0,0 +1,84 @@
+{
+  "name": "@donartcha/openlag",
+  "version": "0.1.0",
+  "description": "Architecture as Code traceability graph generator",
+  "type": "module",
+  "license": "MPL-2.0",
+  "bin": {
+    "openlag": "./bin/openlag.js"
+  },
+  "files": [
+    "bin",
+    "scripts",
+    "src",
+    "dist",
+    "index.html",
+    "vite.config.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "tsx scripts/cli/openlag.ts dev",
+    "build": "npm run generate-relations && npm run build:web && npm run build:cli",
+    "build:web": "vite build",
+    "build:cli": "tsup scripts/cli/openlag.ts --format esm --platform node --target node18 --out-dir dist/cli --clean false",
+    "check": "npm run typecheck && npm run lint && npm run test && npm run pack:dry-run",
+    "generate": "tsx scripts/cli/openlag.ts generate",
+    "generate-relations": "tsx scripts/generate-relations.ts",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test tests/*.test.ts",
+    "test:watch": "node --import tsx --test --watch tests/*.test.ts",
+    "pack:dry-run": "npm pack --dry-run",
+    "clean": "rimraf dist public/graph-data.json",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@tailwindcss/vite": "^4.1.14",
+    "@vitejs/plugin-react": "^5.0.4",
+    "@xyflow/react": "^12.10.2",
+    "chalk": "^5.4.1",
+    "chokidar": "^5.0.0",
+    "clsx": "^2.1.1",
+    "commander": "^14.0.3",
+    "dagre": "^0.8.5",
+    "gray-matter": "^4.0.3",
+    "html-to-image": "^1.11.13",
+    "html2canvas": "^1.4.1",
+    "js-yaml": "^4.1.1",
+    "jspdf": "^4.2.1",
+    "lucide-react": "^0.546.0",
+    "mermaid": "^11.15.0",
+    "motion": "^12.23.24",
+    "ora": "^8.2.0",
+    "react": "^19.0.1",
+    "react-dom": "^19.0.1",
+    "react-markdown": "^10.1.0",
+    "tailwind-merge": "^3.6.0",
+    "vite": "^6.2.3",
+    "zod": "^4.4.3",
+    "zustand": "^5.0.13"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/dagre": "^0.7.54",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.14.0",
+    "@typescript-eslint/eslint-plugin": "^8.59.3",
+    "@typescript-eslint/parser": "^8.59.3",
+    "autoprefixer": "^10.4.21",
+    "dotenv": "^17.2.3",
+    "esbuild": "^0.25.0",
+    "eslint": "^10.4.0",
+    "globals": "^17.6.0",
+    "rimraf": "^6.1.3",
+    "tailwindcss": "^4.1.14",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "~5.8.2",
+    "vitest": "^4.1.6"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/cli/build.ts ADDED Viewed

@@ -0,0 +1,34 @@
+import { execFileSync } from 'child_process';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import chalk from 'chalk';
+import { generateData } from './generate.js';
+import { resolveViteBin } from './vite-bin.js';
+export function buildPortal() {
+  const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+  const viteBin = resolveViteBin(import.meta.url);
+  const viteConfig = path.join(packageRoot, 'vite.config.ts');
+  const docsDir = path.join(process.cwd(), 'docs');
+  const outputDir = path.join(process.cwd(), 'public');
+  generateData(docsDir, outputDir);
+  console.log(chalk.blue('Building OpenLAG portal...'));
+  try {
+    execFileSync(process.execPath, [viteBin, 'build', '--config', viteConfig], {
+      cwd: packageRoot,
+      env: {
+        ...process.env,
+        OPENLAG_PROJECT_ROOT: process.cwd(),
+      },
+      stdio: 'inherit',
+    });
+    console.log(chalk.green('Portal build complete.'));
+  } catch {
+    console.error(chalk.red('Build failed.'));
+    process.exit(1);
+  }
+}

package/scripts/cli/dev.ts ADDED Viewed

@@ -0,0 +1,35 @@
+import { spawn } from 'child_process';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import chalk from 'chalk';
+import { generateData, watchData } from './generate.js';
+import { resolveViteBin } from './vite-bin.js';
+export function runDevServer() {
+  const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+  const viteBin = resolveViteBin(import.meta.url);
+  const viteConfig = path.join(packageRoot, 'vite.config.ts');
+  const projectRoot = process.cwd();
+  const docsDir = path.join(projectRoot, 'docs');
+  const outputDir = path.join(projectRoot, 'public');
+  generateData(docsDir, outputDir);
+  watchData(docsDir, outputDir);
+  console.log(chalk.blue('Starting OpenLAG portal dev server...'));
+  const vite = spawn(process.execPath, [viteBin, '--config', viteConfig], {
+    cwd: packageRoot,
+    env: {
+      ...process.env,
+      OPENLAG_PROJECT_ROOT: projectRoot,
+    },
+    stdio: 'inherit',
+  });
+  vite.on('close', (code) => {
+    process.exit(code || 0);
+  });
+}

package/scripts/cli/generate.ts ADDED Viewed

@@ -0,0 +1,92 @@
+import fs from "fs";
+import path from "path";
+import { parseOpenLagDocs } from "../core/parser.js";
+import { Version, Change, SystemVersion, GraphSnapshot } from "../../src/types.js";
+import chokidar from "chokidar";
+import chalk from "chalk";
+interface StaticState {
+  versions: Version[];
+  systemVersions: SystemVersion[];
+  graphs: Record<string, GraphSnapshot>;
+  changes: Change[];
+}
+function isDescendant(currentVersionId: string, artifactVersionId: string, versions: Version[]): boolean {
+    const artifactVersion = versions.find(v => v.id === artifactVersionId);
+    if (!artifactVersion) return false;
+    let temp = versions.find(v => v.id === currentVersionId);
+    let depth = 0;
+    while (temp && temp.parentVersion) {
+        depth++;
+        if (depth > 50) return false;
+        if (temp.parentVersion === artifactVersionId) return true;
+        temp = versions.find(v => v.id === temp!.parentVersion);
+    }
+    return false;
+}
+export function generateData(docsDir: string, outputDir: string, silent = false) {
+  if (!silent) console.log(chalk.blue("🚀 Generating OpenLAG Static Data..."));
+  const parsedData = parseOpenLagDocs(docsDir);
+  const state: StaticState = {
+    versions: parsedData.versions,
+    systemVersions: parsedData.systemVersions,
+    graphs: {},
+    changes: parsedData.changes
+  };
+  const allArtifacts = parsedData.artifacts;
+  const allRelations = parsedData.relations;
+  state.versions.forEach(v => {
+    state.graphs[v.id] = {
+      artifacts: allArtifacts.filter(a => a.type === 'SYSTEM_VERSION' || a.type === 'VERSION' || a.version === v.id || isDescendant(v.id, a.version, state.versions)),
+      relations: allRelations.filter(r => {
+        const fromArt = allArtifacts.find(a => a.id === r.from);
+        return fromArt && (fromArt.type === 'SYSTEM_VERSION' || fromArt.type === 'VERSION' || fromArt.version === v.id || isDescendant(v.id, fromArt.version, state.versions));
+      })
+    };
+  });
+  if (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(outputDir, 'graph-data.json'),
+    JSON.stringify(state, null, 2)
+  );
+  if (!silent) console.log(chalk.green("✅ Data generated at"), chalk.cyan(path.join(outputDir, 'graph-data.json')));
+}
+export function watchData(docsDir: string, outputDir: string) {
+  console.log(chalk.yellow("👀 Watching for changes in"), chalk.cyan(docsDir));
+  const watcher = chokidar.watch(docsDir, {
+    ignoreInitial: true,
+    persistent: true
+  });
+  const runCleanly = () => {
+    try {
+      generateData(docsDir, outputDir, true);
+      console.log(chalk.dim(`[${new Date().toLocaleTimeString()}] `) + chalk.green("Regenerated graph-data.json"));
+    } catch (e) {
+      console.error(chalk.red("❌ Error during regeneration:"), e);
+    }
+  };
+  // Debounce to avoid multiple rapid regenerations
+  let timeout: NodeJS.Timeout;
+  const debouncedRun = () => {
+    clearTimeout(timeout);
+    timeout = setTimeout(runCleanly, 300);
+  };
+  watcher.on('all', (event, path) => {
+    debouncedRun();
+  });
+}

package/scripts/cli/init.ts ADDED Viewed

@@ -0,0 +1,427 @@
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+/**
+ * OpenLAG Project Initializer
+ * Purpose: Configures the OpenLAG portal for a specific project.
+ */
+export async function initProject(projectName?: string, projectDesc?: string, includeAllRelations?: boolean) {
+  const name = projectName || process.env.PROJECT_NAME || 'My OpenLAG Project';
+  const desc = projectDesc || process.env.PROJECT_DESCRIPTION || 'Living Architecture documentation for my system.';
+  const ROOT_DIR = process.cwd();
+  console.log(chalk.blue(`🛠️  Initializing OpenLAG for: `) + chalk.bold(name));
+  // 1. Update metadata.json
+  const metadataPath = path.join(ROOT_DIR, 'metadata.json');
+  if (fs.existsSync(metadataPath)) {
+    const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf-8'));
+    metadata.name = name;
+    metadata.description = desc;
+    fs.writeFileSync(metadataPath, JSON.stringify(metadata, null, 2));
+    console.log(chalk.green('✅ Updated metadata.json'));
+  }
+  // 2. Update index.html title
+  const htmlPath = path.join(ROOT_DIR, 'index.html');
+  if (fs.existsSync(htmlPath)) {
+    let html = fs.readFileSync(htmlPath, 'utf-8');
+    html = html.replace(/<title>.*?<\/title>/, `<title>${name} | OpenLAG</title>`);
+    fs.writeFileSync(htmlPath, html);
+    console.log(chalk.green('✅ Updated index.html title'));
+  }
+  // 3. Initialize /docs if empty or missing
+  const docsDir = path.join(ROOT_DIR, 'docs');
+  if (!fs.existsSync(docsDir)) {
+    fs.mkdirSync(docsDir);
+    console.log(chalk.green('✅ Created /docs directory'));
+  }
+  // 3.1 Initialize /docs/relations with Mandatory Core Relations
+  const relationsDir = path.join(docsDir, 'relations');
+  if (!fs.existsSync(relationsDir)) {
+    fs.mkdirSync(relationsDir);
+    console.log(chalk.green('✅ Created /docs/relations directory'));
+  } else {
+    // Purge existing relations to ensure only mandatory ones exist on init
+    const files = fs.readdirSync(relationsDir);
+    for (const file of files) {
+      if (file.endsWith('.yaml')) {
+        fs.unlinkSync(path.join(relationsDir, file));
+      }
+    }
+  }
+  const mandatoryRelations = [
+    {
+      name: 'IMPLEMENTS.yaml',
+      content: `relation: IMPLEMENTS
+description: "Conecta implementación con necesidad funcional/técnica."
+category: TRACEABILITY
+allowedFrom: [CODE_ENTITY, COMPONENT, API, DATABASE_ENTITY, SYSTEM_VERSION]
+allowedTo: [REQUIREMENT, FEATURE, EPIC, DESIGN, USE_CASE, BUSINESS_RULE]
+multiplicity:
+  from: many
+  to: many
+validation:
+  severity: error`
+    },
+    {
+      name: 'TESTS.yaml',
+      content: `relation: TESTS
+description: "Conecta tests con comportamiento validado."
+category: TRACEABILITY
+allowedFrom: [TEST_CASE, TEST]
+allowedTo: [REQUIREMENT, FEATURE, EPIC, CODE_ENTITY, COMPONENT, API, DATABASE_ENTITY, BUG, INCIDENT]
+multiplicity:
+  from: many
+  to: many
+validation:
+  severity: error`
+    },
+    {
+      name: 'REFINES.yaml',
+      content: `relation: REFINES
+description: "Descompone artefactos en otros más concretos."
+category: TRACEABILITY
+allowedFrom: [FEATURE, REQUIREMENT, BUG, RISK, DESIGN]
+allowedTo: [EPIC, FEATURE, PROJECT, BUSINESS_RULE, REQUIREMENT, DESIGN]
+multiplicity:
+  from: many
+  to: many
+validation:
+  severity: warn`
+    },
+    {
+      name: 'FIXES.yaml',
+      content: `relation: FIXES
+description: "Conecta correcciones con bugs o incidentes."
+category: TRACEABILITY
+allowedFrom: [CHANGE, CODE_ENTITY, COMPONENT, SYSTEM_VERSION]
+allowedTo: [BUG, INCIDENT, RISK]
+multiplicity:
+  from: many
+  to: many
+validation:
+  severity: error`
+    },
+    {
+      name: 'DOCUMENTS.yaml',
+      content: `relation: DOCUMENTS
+description: "Conecta documentación con el artefacto descrito."
+category: SEMANTIC
+allowedFrom: [DOCUMENTATION, GLOSSARY_TERM]
+allowedTo: [PROJECT, EPIC, FEATURE, REQUIREMENT, BUSINESS_RULE, USE_CASE, DESIGN, DECISION, CODE_ENTITY, TEST_CASE, CHANGE, BUG, RISK, GLOSSARY_TERM, COMPONENT, API, DATABASE_ENTITY, TEST, DOCUMENTATION, INCIDENT, INFRASTRUCTURE, DEPLOYMENT, MONITORING, MAINTENANCE, SYSTEM_VERSION, VERSION]
+multiplicity:
+  from: many
+  to: many
+validation:
+  severity: info`
+    },
+    {
+      name: 'JUSTIFIES.yaml',
+      content: `relation: JUSTIFIES
+description: "Conecta decisiones con aquello que justifican."
+category: SEMANTIC
+allowedFrom: [DECISION, BUSINESS_RULE, DOCUMENTATION, RISK]
+allowedTo: [DESIGN, REQUIREMENT, FEATURE, EPIC, PROJECT, CODE_ENTITY, COMPONENT, INFRASTRUCTURE, DEPLOYMENT, MAINTENANCE]
+multiplicity:
+  from: many
+  to: many
+validation:
+  severity: warn`
+    }
+  ];
+  mandatoryRelations.forEach(rel => {
+    fs.writeFileSync(path.join(relationsDir, rel.name), rel.content);
+  });
+  console.log(chalk.green('✅ Created Mandatory Core Relations (IMPLEMENTS, TESTS, REFINES, FIXES, DOCUMENTS, JUSTIFIES)'));
+  if (includeAllRelations) {
+    const optionalRelations = [
+      {
+        name: 'DEPENDS_ON.yaml',
+        content: `relation: DEPENDS_ON
+description: "Acoplamiento estático arquitectónico o de empaquetado."
+category: STRUCTURAL
+allowedFrom: [CODE_ENTITY, COMPONENT, API, DATABASE_ENTITY, LIBRARY, VERSION, SYSTEM_VERSION]
+allowedTo: [CODE_ENTITY, COMPONENT, API, DATABASE_ENTITY, LIBRARY, VERSION, SYSTEM_VERSION]
+multiplicity:
+  from: many
+  to: many
+validation:
+  severity: warn`
+      },
+      {
+        name: 'USES.yaml',
+        content: `relation: USES
+description: "Llamada funcional, invocación o flujo en tiempo de ejecución."
+category: OPERATIONAL
+allowedFrom: [CODE_ENTITY, COMPONENT, API, FEATURE, USE_CASE]
+allowedTo: [CODE_ENTITY, COMPONENT, API, SYSTEM_VERSION]
+multiplicity:
+  from: many
+  to: many
+validation:
+  severity: warn`
+      },
+      {
+        name: 'DEPLOYS.yaml',
+        content: `relation: DEPLOYS
+description: "Instanciación de componentes o release en infraestructura."
+category: OPERATIONAL
+allowedFrom: [DEPLOYMENT, PIPELINE, SYSTEM_VERSION]
+allowedTo: [COMPONENT, INFRASTRUCTURE, ENVIRONMENT, DATABASE_ENTITY]
+multiplicity:
+  from: many
+  to: many
+validation:
+  severity: error`
+      },
+      {
+        name: 'MONITORS.yaml',
+        content: `relation: MONITORS
+description: "Relación de observabilidad."
+category: OPERATIONAL
+allowedFrom: [MONITORING, CHECK]
+allowedTo: [COMPONENT, INFRASTRUCTURE, DEPLOYMENT, DATABASE_ENTITY, API]
+multiplicity:
+  from: many
+  to: many
+validation:
+  severity: info`
+      },
+      {
+        name: 'IMPACTS.yaml',
+        content: `relation: IMPACTS
+description: "Descripción de posibles efectos colaterales."
+category: SEMANTIC
+allowedFrom: [CHANGE, RISK, BUG, INCIDENT, DECISION]
+allowedTo: [PROJECT, EPIC, FEATURE, REQUIREMENT, DESIGN, CODE_ENTITY, COMPONENT, API, DATABASE_ENTITY, SYSTEM_VERSION]
+multiplicity:
+  from: many
+  to: many
+validation:
+  severity: warn`
+      },
+      {
+        name: 'BLOCKS.yaml',
+        content: `relation: BLOCKS
+description: "Descripción de impedimentos directos."
+category: DEPENDENCY
+allowedFrom: [BUG, RISK, INCIDENT, CHANGE, DECISION, REQUIREMENT, FEATURE, EPIC]
+allowedTo: [PROJECT, EPIC, FEATURE, REQUIREMENT, BUG, CHANGE, DEPLOYMENT, DEPLOYMENT]
+multiplicity:
+  from: many
+  to: many
+validation:
+  severity: error`
+      },
+      {
+        name: 'BREAKS.yaml',
+        content: `relation: BREAKS
+description: "Averías o rupturas confirmadas."
+category: OPERATIONAL
+allowedFrom: [CHANGE, CODE_ENTITY, COMPONENT, SYSTEM_VERSION]
+allowedTo: [TEST_CASE, TEST, API, COMPONENT, REQUIREMENT, FEATURE]
+multiplicity:
+  from: many
+  to: many
+validation:
+  severity: error`
+      },
+      {
+        name: 'REPLACES.yaml',
+        content: `relation: REPLACES
+description: "Evolución e histórico, deprecando versiones anteriores."
+category: EVOLUTIONARY
+allowedFrom: [COMPONENT, API, SYSTEM_VERSION, VERSION, REQUIREMENT, FEATURE, DESIGN, DECISION]
+allowedTo: [COMPONENT, API, SYSTEM_VERSION, VERSION, REQUIREMENT, FEATURE, DESIGN, DECISION]
+multiplicity:
+  from: many
+  to: one
+validation:
+  severity: info`
+      },
+      {
+        name: 'DERIVES_FROM.yaml',
+        content: `relation: DERIVES_FROM
+description: "Evolución conceptual genérica."
+category: SEMANTIC
+allowedFrom: [REQUIREMENT, FEATURE, DESIGN, BUSINESS_RULE, DECISION, USE_CASE]
+allowedTo: [REQUIREMENT, FEATURE, DESIGN, BUSINESS_RULE, DECISION, USE_CASE]
+multiplicity:
+  from: many
+  to: many
+validation:
+  severity: info`
+      },
+      {
+        name: 'VALIDATES.yaml',
+        content: `relation: VALIDATES
+description: "Validación empírica/humana (QA Manual)."
+category: TRACEABILITY
+allowedFrom: [PROCESS, CHECK, DOCUMENTATION]
+allowedTo: [REQUIREMENT, FEATURE, USE_CASE, DEPLOYMENT]
+multiplicity:
+  from: many
+  to: many
+validation:
+  severity: info`
+      },
+      {
+        name: 'DEFINES.yaml',
+        content: `relation: DEFINES
+description: "Entidades que instauran glosarios o normas."
+category: SEMANTIC
+allowedFrom: [BUSINESS_RULE, DECISION, DOCUMENTATION, GLOSSARY_TERM]
+allowedTo: [REQUIREMENT, FEATURE, DESIGN, PROJECT, COMPONENT, API, DATABASE_ENTITY]
+multiplicity:
+  from: many
+  to: many
+validation:
+  severity: info`
+      },
+      {
+        name: 'CALLS.yaml',
+        content: `relation: CALLS
+description: "Trazabilidad de invocación a nivel código."
+category: STRUCTURAL
+allowedFrom: [CODE_ENTITY]
+allowedTo: [CODE_ENTITY, API]
+multiplicity:
+  from: many
+  to: many
+validation:
+  severity: warn`
+      },
+      {
+        name: 'IMPORTS.yaml',
+        content: `relation: IMPORTS
+description: "Trazabilidad de importación estática a nivel de código."
+category: STRUCTURAL
+allowedFrom: [CODE_ENTITY]
+allowedTo: [CODE_ENTITY, LIBRARY]
+multiplicity:
+  from: many
+  to: many
+validation:
+  severity: warn`
+      },
+      {
+        name: 'RELATES_TO.yaml',
+        content: `relation: RELATES_TO
+description: |
+  Uso genérico propenso a polución semántica. (DISCOURAGED)
+  Para mantener un grafo limpio, solo úsala aportando rationale explícito:
+  relations:
+    - to: mi-otro-artefacto
+      type: RELATES_TO
+      rationale: "No encaja con USES o DEPENDS_ON debido al contexto X."
+category: SEMANTIC
+allowedFrom: [PROJECT, EPIC, FEATURE, REQUIREMENT, BUSINESS_RULE, USE_CASE, DESIGN, DECISION, CODE_ENTITY, TEST_CASE, CHANGE, BUG, RISK, GLOSSARY_TERM, COMPONENT, API, DATABASE_ENTITY, TEST, DOCUMENTATION, INCIDENT, INFRASTRUCTURE, DEPLOYMENT, MONITORING, MAINTENANCE, SYSTEM_VERSION, VERSION]
+allowedTo: [PROJECT, EPIC, FEATURE, REQUIREMENT, BUSINESS_RULE, USE_CASE, DESIGN, DECISION, CODE_ENTITY, TEST_CASE, CHANGE, BUG, RISK, GLOSSARY_TERM, COMPONENT, API, DATABASE_ENTITY, TEST, DOCUMENTATION, INCIDENT, INFRASTRUCTURE, DEPLOYMENT, MONITORING, MAINTENANCE, SYSTEM_VERSION, VERSION]
+multiplicity:
+  from: many
+  to: many
+validation:
+  severity: warn`
+      }
+    ];
+    optionalRelations.forEach(rel => {
+      fs.writeFileSync(path.join(relationsDir, rel.name), rel.content);
+    });
+    console.log(chalk.green('✅ Created Official Optional Relations'));
+  }
+  const versionsDir = path.join(docsDir, 'versions');
+  if (!fs.existsSync(versionsDir)) {
+    fs.mkdirSync(versionsDir);
+    console.log(chalk.green('✅ Created /docs/versions directory'));
+  }
+  const versionPath = path.join(versionsDir, 'v-1.0.0.md');
+  if (!fs.existsSync(versionPath)) {
+    const versionsContent = `---
+id: v-1.0.0
+type: VERSION
+name: "Baseline"
+timestamp: "${new Date().toISOString().split('T')[0]}"
+parentVersion: null
+layer: DOCUMENTATION
+title: "Project Release v1.0.0"
+description: "Initial release"
+ownership:
+  owner: architecture
+  team: architecture
+relations: []
+---
+`;
+    fs.writeFileSync(versionPath, versionsContent);
+    console.log(chalk.green('✅ Created initial docs/versions/v-1.0.0.md'));
+  }
+  const componentsVersionsPath = path.join(versionsDir, 'sys-core-1.0.md');
+  if (!fs.existsSync(componentsVersionsPath)) {
+    const cvContent = `---
+id: sys-core-1.0
+type: SYSTEM_VERSION
+component: "Core System"
+version: "1.0.0"
+releaseDate: "${new Date().toISOString().split('T')[0]}"
+layer: OPERATIONS
+title: "Core System v1.0"
+description: "Base framework."
+ownership:
+  owner: architecture
+  team: architecture
+relations: []
+---
+`;
+    fs.writeFileSync(componentsVersionsPath, cvContent);
+    console.log(chalk.green('✅ Created initial docs/versions/sys-core-1.0.md'));
+  }
+  // 4. Create a sample doc if empty
+  const architectureDir = path.join(docsDir, 'architecture');
+  if (!fs.existsSync(architectureDir)) {
+    fs.mkdirSync(architectureDir);
+    console.log(chalk.green('✅ Created /docs/architecture directory'));
+  }
+  const sampleDocPath = path.join(architectureDir, 'architecture-overview.md');
+  if (!fs.existsSync(sampleDocPath)) {
+    const sampleContent = `---
+id: arch-overview
+type: DOCUMENT
+status: draft
+title: "Architecture Overview"
+description: "High-level description of the system architecture."
+---
+# Architecture Overview
+This document describes the high-level architecture of ${name}.
+## Key Principles
+- Traceability first.
+- Documentation as Code.
+- Graph-based relationships.
+`;
+    fs.writeFileSync(sampleDocPath, sampleContent);
+    console.log(chalk.green('✅ Created initial docs/architecture/architecture-overview.md'));
+  }
+  console.log('\n' + chalk.cyan('🚀 Project initialized successfully!'));
+  console.log('Next steps:');
+  console.log('1. Edit ' + chalk.cyan('docs/') + ' to reflect your architecture.');
+  console.log('2. Run ' + chalk.cyan('openlag dev') + ' to see your portal.');
+}