@kabran-tecnologia/kabran-config 2.1.1 → 2.3.0

package/README.md

@@ -368,8 +368,9 @@ echo "npx lint-staged" > .husky/pre-commit
 # Add commit-msg hook
 echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg
 
-# Add pre-push hook (optional)
-echo "npm run type-check && npm test" > .husky/pre-push
+# Add pre-push hook (optional - kept lightweight by design)
+# Full validation runs in CI. Uncomment type-check if desired:
+# echo "npm run type-check" > .husky/pre-push
 ```
 
 ---
@@ -476,21 +477,14 @@ node node_modules/@kabran-tecnologia/kabran-config/src/scripts/license-check.mjs
 }
 ```
 
-**Usage in CI/CD:**
+**Usage in CI (recommended):**
 
 ```yaml
-# .github/workflows/quality.yml
+# .github/workflows/ci.yml
 - name: License Check
   run: npm run license:check
 ```
 
-**Usage in Husky:**
-
-```bash
-# .husky/pre-push
-npm run license:check
-```
-
 **Blocked licenses:** GPL, AGPL, LGPL, EUPL (viral copyleft)
 **Exit code:** 1 if prohibited licenses found, 0 otherwise
 
@@ -607,14 +601,7 @@ node node_modules/@kabran-tecnologia/kabran-config/src/scripts/env-validator.mjs
 3. If env vars detected, validates `.env.example` exists
 4. Warns if vars in `.env.example` lack comments/documentation
 
-**Usage in Husky:**
-
-```bash
-# .husky/pre-push
-npm run env:validate
-```
-
-**Usage in CI/CD:**
+**Usage in CI (recommended):**
 
 ```yaml
 # .github/workflows/security.yml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kabran-tecnologia/kabran-config",
-  "version": "2.1.1",
+  "version": "2.3.0",
   "description": "Shared quality configurations, enforcement scripts, and CI/CD tooling for Kabran projects",
   "author": "Kabran",
   "license": "MIT",

package/src/scripts/setup.mjs

@@ -11,6 +11,7 @@
  *
  * Options:
  *   --type=<node|react|base>  Project type (default: node)
+ *   --runner=<github|self-hosted>  Runner type (default: github)
  *   --skip-husky              Don't copy husky hooks
  *   --skip-workflows          Don't copy workflow files
  *   --sync-workflows          Overwrite existing workflow files
@@ -74,6 +75,7 @@ export function logDry(message) {
 export function parseArgs(args) {
   const options = {
     type: 'node',
+    runner: 'github',
     skipHusky: false,
     skipWorkflows: false,
     skipQualityStandard: false,
@@ -112,6 +114,14 @@ export function parseArgs(args) {
         logError(`Invalid type: ${type}. Valid options: node, react, base`);
         process.exit(1);
       }
+    } else if (arg.startsWith('--runner=')) {
+      const runner = arg.split('=')[1];
+      if (['github', 'self-hosted'].includes(runner)) {
+        options.runner = runner;
+      } else {
+        logError(`Invalid runner: ${runner}. Valid options: github, self-hosted`);
+        process.exit(1);
+      }
     }
   }
 
@@ -130,6 +140,7 @@ ${colors.yellow}USAGE:${colors.reset}
 
 ${colors.yellow}OPTIONS:${colors.reset}
   --type=<type>           Project type: node, react, base (default: node)
+  --runner=<runner>       Runner type: github, self-hosted (default: github)
   --skip-husky            Don't copy husky hooks
   --skip-workflows        Don't copy GitHub workflow files
   --skip-quality-standard Don't create quality-standard.md
@@ -147,9 +158,15 @@ ${colors.yellow}EXAMPLES:${colors.reset}
   # Setup React project
   npx kabran-setup --type=react
 
+  # Setup with self-hosted runners (Kosmos CI)
+  npx kabran-setup --runner=self-hosted
+
   # Update workflows only
   npx kabran-setup --sync-workflows
 
+  # Update to self-hosted workflows
+  npx kabran-setup --sync-workflows --runner=self-hosted
+
   # Generate telemetry .env.example
   npx kabran-setup --telemetry-env
 
@@ -160,6 +177,10 @@ ${colors.yellow}UPDATE STRATEGY:${colors.reset}
   - Config files:   Re-export from kabran-config (auto-update via npm update)
   - Workflows:      Copied once, update with --sync-workflows
   - Husky hooks:    Copied once, update with --sync-husky
+
+${colors.yellow}RUNNER TYPES:${colors.reset}
+  - github:       Standard GitHub-hosted runners (ubuntu-latest)
+  - self-hosted:  Kosmos self-hosted runners [self-hosted, linux, x64, docker]
 `);
 }
 
@@ -282,7 +303,7 @@ export function writeFile(dest, content, options = {}) {
  * @returns {object} Results
  */
 export function setupWorkflows(projectDir, templatesDir, options) {
-  const {force = false, dryRun = false, syncWorkflows = false} = options;
+  const {force = false, dryRun = false, syncWorkflows = false, runner = 'github'} = options;
   const overwrite = force || syncWorkflows;
 
   const results = {
@@ -291,13 +312,22 @@ export function setupWorkflows(projectDir, templatesDir, options) {
     skipped: 0,
   };
 
-  const workflowFiles = ['ci.yml', 'commitlint.yml', 'validate-pr-source.yml'];
+  // Determine CI workflow file based on runner type
+  const ciWorkflowSrc = runner === 'self-hosted' ? 'ci-self-hosted.yml' : 'ci.yml';
+
+  // Map of source file -> destination file
+  const workflowFiles = [
+    {src: ciWorkflowSrc, dest: 'ci.yml'},
+    {src: 'commitlint.yml', dest: 'commitlint.yml'},
+    {src: 'validate-pr-source.yml', dest: 'validate-pr-source.yml'},
+  ];
 
-  logInfo('Setting up GitHub workflows...');
+  const runnerLabel = runner === 'self-hosted' ? 'self-hosted' : 'GitHub-hosted';
+  logInfo(`Setting up GitHub workflows (${runnerLabel} runners)...`);
 
   for (const file of workflowFiles) {
-    const src = join(templatesDir, '.github', 'workflows', file);
-    const dest = join(projectDir, '.github', 'workflows', file);
+    const src = join(templatesDir, '.github', 'workflows', file.src);
+    const dest = join(projectDir, '.github', 'workflows', file.dest);
 
     const status = copyFile(src, dest, {overwrite, dryRun});
 
@@ -648,6 +678,7 @@ export function runSetup(projectDir, options) {
   console.log('');
   logInfo(`Setting up project at: ${projectDir}`);
   logInfo(`Project type: ${options.type}`);
+  logInfo(`Runner type: ${options.runner}`);
   if (options.dryRun) {
     logWarn('DRY-RUN MODE - No files will be modified');
   }

package/templates/.github/workflows/ci-quality-self-hosted.yml

@@ -0,0 +1,108 @@
+# Kabran CI Quality Workflow (Self-Hosted Runners)
+#
+# This workflow runs the Kabran CI pipeline on self-hosted runners
+# and posts quality reports to PRs.
+#
+# Runner Labels: [self-hosted, linux, x64, docker]
+#
+# For GitHub-hosted runners, use ci-quality.yml instead.
+#
+# Requirements:
+#   - scripts/ci-config.sh with PROJECT_NAME, PM, and ci_steps() defined
+#   - @kabran-tecnologia/kabran-config installed as dev dependency
+#   - Kosmos CI runners configured for this repository
+
+name: CI Quality
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  ci:
+    name: CI Pipeline
+    runs-on: [self-hosted, linux, x64, docker]
+    timeout-minutes: 15
+
+    permissions:
+      contents: read
+      pull-requests: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run CI Pipeline
+        id: ci
+        env:
+          CI_USE_V2: "true"
+          CI_OUTPUT_FILE_V2: "docs/quality/ci-result.json"
+        run: |
+          npx kabran-ci || exit_code=$?
+
+          if [ -f "docs/quality/ci-result.json" ]; then
+            echo "ci_result_exists=true" >> $GITHUB_OUTPUT
+          else
+            echo "ci_result_exists=false" >> $GITHUB_OUTPUT
+          fi
+
+          exit ${exit_code:-0}
+
+      - name: Generate PR Comment
+        if: github.event_name == 'pull_request' && steps.ci.outputs.ci_result_exists == 'true'
+        id: comment
+        run: |
+          npx kabran-pr-comment \
+            --current docs/quality/ci-result.json \
+            --baseline-branch ${{ github.base_ref }} \
+            --output /tmp/pr-comment.md || true
+
+          if [ -f "/tmp/pr-comment.md" ]; then
+            echo "comment_exists=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Post PR Comment
+        if: github.event_name == 'pull_request' && steps.comment.outputs.comment_exists == 'true'
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: kabran-quality
+          path: /tmp/pr-comment.md
+
+      - name: Upload CI Result
+        if: always() && steps.ci.outputs.ci_result_exists == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: ci-result
+          path: docs/quality/ci-result.json
+          retention-days: 30
+
+      - name: Commit CI Result (main only)
+        if: github.ref == 'refs/heads/main' && github.event_name == 'push' && steps.ci.outputs.ci_result_exists == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          if git diff --quiet docs/quality/ci-result.json; then
+            echo "No changes to ci-result.json"
+          else
+            git add docs/quality/ci-result.json
+            git commit -m "chore(ci): update ci-result.json [skip ci]"
+            git push
+          fi

package/templates/.github/workflows/ci-self-hosted.yml

@@ -0,0 +1,53 @@
+# Kabran CI Workflow (Self-Hosted Runners)
+#
+# This workflow runs CI on self-hosted runners with Docker support.
+# Use this when you have Kosmos CI runners configured.
+#
+# Runner Labels: [self-hosted, linux, x64, docker]
+#
+# For GitHub-hosted runners, use ci.yml instead.
+
+name: CI
+
+on:
+  pull_request:
+    branches: [main, staging]
+  push:
+    branches: [main, staging]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  ci:
+    name: CI Pipeline
+    runs-on: [self-hosted, linux, x64, docker]
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Type Check
+        run: npm run type-check
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test
+        env:
+          CI: true

package/templates/.husky/pre-push

@@ -1,4 +1,5 @@
-npm run lint
-npm run type-check
-npm test
-npm run build
+# Pre-push hook - kept lightweight by design
+# Full validation (lint, tests, build) runs in CI asynchronously
+#
+# Uncomment below if you want local type-check before push:
+# npm run type-check