docs:(golden-paths): separate single app from multi apps for GitHub CI

Signed-off-by: Emilien Escalle <emilien.escalle@escemi.com>

Author: hoverkraft-bot[bot]

.devcontainer/devcontainer.json

@@ -1,8 +1,11 @@
 {
-  "name": "Node.js & TypeScript",
-  "image": "mcr.microsoft.com/devcontainers/typescript-node:1-22-bookworm",
+  "name": "public-docs",
+  "image": "mcr.microsoft.com/devcontainers/base:debian",
   "features": {
-    "ghcr.io/devcontainers/features/docker-in-docker:2": {}
+    "ghcr.io/devcontainers/features/node:1": {},
+    "ghcr.io/devcontainers/features/docker-in-docker:2": {
+      "moby": false
+    }
   },
   "forwardPorts": [3000],
   "customizations": {
@@ -29,6 +32,9 @@
             "args": ["lighthouse-mcp"]
           }
         }
+      },
+      "settings": {
+        "terminal.integrated.defaultProfile.linux": "zsh"
       }
     }
   }

.github/actions/prepare-docs/__tests__/documentation-preparer.test.js

@@ -200,6 +200,39 @@ describe("DocumentationPreparer", () => {
     expect(content).toContain("title: Actions");
   });
 
+  it("does not create a fallback _index when the bundle already contains index.md", async () => {
+    mockFs({
+      "/workspace": {
+        artifact: {
+          "README.md": "# Example\n\nMain page",
+          actions: {
+            checkout: {
+              "README.md": "# Checkout\n\nDetails",
+            },
+          },
+        },
+        site: {
+          docs: {},
+          static: {},
+        },
+      },
+    });
+
+    const options = createOptions();
+    const preparer = new DocumentationPreparer(options);
+    const result = await preparer.run();
+
+    expect(result.processedFiles).toContain("index.md");
+    expect(result.processedFiles).not.toContain("_index.md");
+    expect(fs.existsSync(path.join(options.outputPath, "index.md"))).toBe(true);
+    expect(fs.existsSync(path.join(options.outputPath, "_index.md"))).toBe(
+      false,
+    );
+    expect(options.core.info).not.toHaveBeenCalledWith(
+      "Generated default index page for documentation bundle.",
+    );
+  });
+
   it("fails fast when the source repository slug is invalid", async () => {
     mockFs({
       "/workspace": {

.github/actions/prepare-docs/lib/artifact/index-page-writer.js

@@ -5,6 +5,8 @@ const path = require("path");
 const { DEFAULT_INDEX_FILE } = require("../constants");
 const { formatTitleFromSlug } = require("../utils/path-utils");
 
+const ROOT_INDEX_FILE = "index.md";
+
 function ensureIndexPage({
   core,
   outputPath,
@@ -13,7 +15,10 @@ function ensureIndexPage({
   sourceRepository,
   syncTimestamp,
 }) {
-  if (processedFiles.includes(DEFAULT_INDEX_FILE)) {
+  if (
+    processedFiles.includes(DEFAULT_INDEX_FILE) ||
+    processedFiles.includes(ROOT_INDEX_FILE)
+  ) {
     return;
   }
 

.github/actions/resolve-docs-target/README.md

@@ -55,7 +55,7 @@ Responsibilities:
 | **Input**          | **Description**                                       | **Required** | **Default** |
 | ------------------ | ----------------------------------------------------- | ------------ | ----------- |
 | **`github-token`** | GitHub token used to authenticate repository queries. | **true**     | -           |
-| **`repository`**   | Repository slug in the form owner/repo.               | **true**     | -           |
+| **`repository`**   | Repository slug in the form owner/repository.         | **true**     | -           |
 
 <!-- inputs:end -->
 <!-- secrets:start -->

.github/actions/resolve-docs-target/action.yml

@@ -13,7 +13,7 @@ inputs:
     description: GitHub token used to authenticate repository queries.
     required: true
   repository:
-    description: Repository slug in the form owner/repo.
+    description: Repository slug in the form `owner/repo`.
     required: true
 
 outputs:

.github/workflows/sync-docs-dispatcher.md

@@ -59,7 +59,7 @@ your-project/
 
 ### Complete Integration Example
 
-For a full example of integrating this workflow into your CI pipeline, see the [Examples](#examples) section below.
+For a full example of integrating this workflow into your CI pipeline, see the [Usage](#usage) section below.
 
 ### Key Integration Points
 

Makefile

@@ -8,42 +8,36 @@ help: ## Show help message
 
 include .env
 
-prepare: ## Prepare stack to run
-	npm --prefix application install
-	npm --prefix .github/actions/generate-docs install
-	npm --prefix .github/actions/prepare-docs install
-	npm --prefix .github/actions/inject-docs install
-	npm --prefix .github/actions/resolve-docs-target install
+setup: ## Install npm dependencies for all package.json files under actions/
+	@echo "Installing npm dependencies for all packages..."
+	$(call run_npm_for_packages,install)
 
 start: ## Start application in dev mode
 	npm --prefix application run start
 
+npm-audit-fix: ## Execute npm audit fix
+	@echo "Running npm audit fix for all packages..."
+	$(call run_npm_for_packages,audit fix)
+
 lint: ## Run linters
 	npm --prefix application run lint -- $(filter-out $@,$(MAKECMDGOALS))
 	$(call run_linter,)
 
 lint-fix: ## Run linters
 	npm --prefix application run lint:fix
-	npm --prefix application audit fix
-	npm --prefix .github/actions/generate-docs audit fix
-	npm --prefix .github/actions/prepare-docs audit fix
-	npm --prefix .github/actions/inject-docs audit fix
-	npm --prefix .github/actions/resolve-docs-target audit fix
 	$(MAKE) linter-fix
 
 build: ## Build libs and applications
 	npm --prefix application run build
 
 test: ## Run tests
-	npm --prefix application run test:ci
-	npm --prefix .github/actions/generate-docs run test:ci
-	npm --prefix .github/actions/prepare-docs run test:ci
-	npm --prefix .github/actions/inject-docs run test:ci
-	npm --prefix .github/actions/resolve-docs-target run test:ci
+	@echo "Running tests for all packages..."
+	$(call run_npm_for_packages,run test:ci)
 
 ci: ## Run tests in CI mode
-	$(MAKE) prepare
+	$(MAKE) setup
 	$(MAKE) lint-fix
+	$(MAKE) npm-audit-fix || true
 	$(MAKE) build
 	$(MAKE) test
 
@@ -68,22 +62,26 @@ define run_linter
 		-e IGNORE_GITIGNORED_FILES=true \
 		-e VALIDATE_TYPESCRIPT_PRETTIER=false \
 		-e VALIDATE_TYPESCRIPT_ES=false \
-        -e VALIDATE_CSS=false \
+		-e VALIDATE_CSS=false \
 		$(1) \
 		-v $$VOLUME \
 		--rm \
 		$$LINTER_IMAGE
 endef
 
-define docker-compose
-    COMPOSE_DOCKER_CLI_BUILD=1 DOCKER_BUILDKIT=1 docker-compose -f docker-compose.yml -f docker-compose.local.yml -f docker-compose.$(1).yml $(2)
-endef
-
-define open-in-browser
-	@if command -v x-www-browser &> /dev/null ; then x-www-browser $(1); \
-	elif command -v xdg-open &> /dev/null ; then xdg-open $(1); \
-	elif command -v open &> /dev/null ; then open $(1); \
-	elif command -v start &> /dev/null ; then	start $(1);	fi;
+define run_npm_for_packages
+	@set -eu; \
+	overall_status=0; \
+	packages="$$(find application .github/actions -type f -name package.json -not -path '*/node_modules/*' -print | sort)"; \
+	for pkg in $$packages; do \
+		pkg_dir="$$(dirname "$$pkg")"; \
+		echo "---"; \
+		echo "npm $(1) in $$pkg_dir"; \
+		if ! npm --prefix "$$pkg_dir" $(1); then \
+			overall_status=1; \
+		fi; \
+	done; \
+	exit $$overall_status
 endef
 
 #############################

README.md

@@ -14,7 +14,7 @@ The portal aggregates technical guides, project overviews, and methodology notes
 - **Projects** — Directory of open-source projects managed by Hoverkraft (`application/docs/projects/`)
   - Project docs are stored under category folders: `application/docs/projects/<category>/<project>/`.
   - Categories follow the rules in `.github/actions/resolve-docs-target/lib/repository-categorizer.js` (via `RepositoryCategorizer`).
-  - **⚠️ Project documentation must be syncronized from project repositories.** See [Documentation Aggregation System](##documentation-aggregation-system)
+  - **⚠️ Project documentation must be syncronized from project repositories.** See [Documentation Aggregation System](#documentation-aggregation-system)
 - **Internal notes** — Keep internal or implementation-specific documentation concise in this root readme; `application/docs/` is limited to public-facing content.
 
 ## Site Structure

application/.eslintrc.js

@@ -1,4 +1,5 @@
 module.exports = {
+  root: true,
   parser: "@typescript-eslint/parser",
   parserOptions: {
     ecmaVersion: "latest",
@@ -7,5 +8,25 @@ module.exports = {
       jsx: true,
     },
   },
+  plugins: ["n"],
   extends: ["plugin:@docusaurus/recommended"],
+  settings: {
+    react: {
+      version: "detect",
+    },
+  },
+  rules: {
+    "react/react-in-jsx-scope": "off",
+    "n/no-missing-import": [
+      "error",
+      {
+        tryExtensions: [".js", ".jsx", ".ts", ".tsx"],
+        allowModules: [
+          "@docusaurus/useDocusaurusContext",
+          "@theme/Heading",
+          "@theme/Layout",
+        ],
+      },
+    ],
+  },
 };

application/docs/methodology/best-practices/ci-cd/cicd-release-management.md

@@ -14,7 +14,7 @@ Predictable, low-stress deployments. If deployments are scary, you'll do them le
 
 ### Pipeline Stages
 
-```
+```text
 ┌──────────┐   ┌────────┐   ┌──────────┐   ┌────────┐   ┌────────┐
 │  Commit  │──▶│  Lint  │──▶│   Test   │──▶│  Build │──▶│ Deploy │
 └──────────┘   └────────┘   └──────────┘   └────────┘   └────────┘
@@ -57,7 +57,7 @@ Predictable, low-stress deployments. If deployments are scary, you'll do them le
 - **Feature branches**: Short-lived (< 2 days)
 - **No long-lived branches**: Merge daily
 
-```
+```text
 main     ──●────●────●────●────●──▶
              \  /    /    /
 feature1      ●─────┘    /
@@ -87,7 +87,7 @@ feature2           ●────┘
 
 ### Deployment Pipeline
 
-```
+```text
 PR Created
     ↓
 CI Runs (lint, test, build)
@@ -221,7 +221,7 @@ Follow [Semantic Versioning](https://semver.org/): `MAJOR.MINOR.PATCH`
 
 Use conventional commit messages to automate versioning:
 
-```
+```text
 feat: add user profile endpoint      → MINOR bump
 fix: resolve null pointer exception  → PATCH bump
 feat!: remove deprecated API         → MAJOR bump
@@ -246,7 +246,7 @@ feat!: remove deprecated API         → MAJOR bump
 
 ### Environment Progression
 
-```
+```text
 Developer Laptop
     ↓
 CI (ephemeral)
@@ -311,7 +311,7 @@ After deploying to production:
 
 Run two identical production environments:
 
-```
+```text
 ┌─────────┐       ┌─────────┐
 │  Blue   │◀─────▶│  Green  │
 │ (Live)  │       │(Standby)│
@@ -333,7 +333,7 @@ Run two identical production environments:
 
 Gradually shift traffic to new version:
 
-```
+```text
 V1: ███████████ 90%
 V2: ██ 10%
 
@@ -357,7 +357,3 @@ V2: ███████████ 100%
 - [Accelerate - Nicole Forsgren](https://itrevolution.com/product/accelerate/)
 - [Release It! - Michael Nygard](https://pragprog.com/titles/mnee2/release-it-second-edition/)
 - [Site Reliability Engineering - Google](https://sre.google/books/)
-
-```
-
-```