jarvis-ci 1.0.0 → 1.0.3

package/README.md

@@ -1,5 +1,235 @@
 # jarvis-ci
-This npm package is light weight nodejs based CI/CD tool. the goal is to achieve simplicity and local machine  or server CI/CD execution. it is configured through YAML for commands.
+
+A lightweight Node.js-based CI/CD tool that executes YAML-defined pipelines on local machines or servers.
+
+jarvis-ci is designed for simplicity, control, and self-hosted automation, similar in concept to GitHub Actions or GitLab CI, but running entirely under user-managed infrastructure.
 
 for local machine , the user needs to configure the proxy URL from https://smee.io
 
+https://www.npmjs.com/package/jarvis-ci
+
+---
+
+# Installation
+
+```bash
+npm install -g jarvis-ci
+```
+
+---
+
+# Overview
+
+jarvis-ci enables developers to define CI/CD workflows using a YAML configuration file and execute them via a webhook-driven system.
+
+It supports:
+
+* GitHub webhook-based triggers
+* YAML-based pipeline definitions
+* Local and server-based execution
+* Working directory isolation per repository
+* Restricted command execution for safety
+
+For local development environments, webhook forwarding can be configured using a proxy service such as smee.io.
+
+---
+
+# Core Features
+
+* YAML-driven pipeline execution
+* GitHub webhook integration
+* Multi-repository support
+* Local and public server deployment modes
+* Working directory isolation per pipeline
+* Whitelisted command execution model
+* Structured logging using Listr2
+
+---
+
+# Security Model
+
+The system enforces a strict command whitelist to prevent arbitrary execution.
+
+Allowed commands:
+
+```ts
+const ALLOWED_COMMANDS = [
+  "node",
+  "npm",
+  "docker",
+  "docker-compose",
+  "ssh",
+  "git"
+];
+```
+
+Each pipeline is executed in an isolated working directory to prevent cross-repository contamination.
+
+---
+
+# Pipeline Configuration (YAML)
+
+Each repository defines its pipeline using a `.jarvis.yml` file.
+
+Example configuration:
+
+```yaml
+steps:
+  - name: Install dependencies
+    run:
+      cmd: npm
+      args: ["install"]
+
+  - name: Run tests
+    run:
+      cmd: npm
+      args: ["test"]
+```
+
+---
+
+# CLI Commands
+
+## Configuration
+
+### Add repository configuration
+
+```bash
+jarvis config add
+```
+
+Adds a new repository configuration for CI execution.
+
+---
+
+### Set webhook port
+
+```bash
+jarvis config port
+```
+
+Defines the port on which the webhook server will run.
+
+---
+
+### Configure server mode
+
+```bash
+jarvis config local
+```
+
+Sets webhook server accessibility mode:
+
+* `yes`: Localhost only
+* `no`: Public IP accessible
+
+---
+
+### Configure proxy mode
+
+```bash
+jarvis config proxy
+```
+
+Enables webhook forwarding through smee.io for local development environments.
+
+---
+
+## Runtime
+
+### Start webhook server
+
+```bash
+jarvis start
+```
+
+Starts the webhook listener and pipeline execution engine.
+
+---
+
+## Pipeline Management
+
+### List pipelines
+
+```bash
+jarvis pipeline list
+```
+
+Displays all configured pipelines.
+
+---
+
+### Delete pipeline
+
+```bash
+jarvis pipeline delete <pipelineName>
+```
+
+Removes an existing pipeline configuration.
+
+---
+
+### Edit pipeline
+
+```bash
+jarvis pipeline edit <pipelineName>
+```
+
+Modifies an existing pipeline configuration.
+
+---
+
+# Execution Flow
+
+The system operates as follows:
+
+1. GitHub push event triggers webhook
+2. Webhook server receives and validates event
+3. Repository configuration is matched
+4. Repository is cloned or updated in isolated directory
+5. `.jarvis.yml` pipeline is loaded
+6. Pipeline is validated against allowed commands
+7. Steps are executed sequentially using Listr2
+8. Each step runs in its isolated working directory using execa
+
+---
+
+# Architecture Components
+
+* YAML parser for pipeline definitions
+* Validation layer enforcing command restrictions
+* Execution engine using execa for process control
+* Task runner using Listr2 for structured output
+* Webhook handler based on @octokit/webhooks
+* Repository workspace isolation layer
+
+---
+
+# Development Mode (Local Setup)
+
+For local environments, webhook events can be forwarded using a proxy such as smee.io.
+
+This allows GitHub webhooks to reach a locally running jarvis-ci instance.
+
+---
+
+# Design Principles
+
+* Minimal configuration overhead
+* Deterministic pipeline execution
+* Secure command execution model
+* Isolation per repository workspace
+* Predictable and traceable CI behavior
+
+---
+
+# Future Improvements
+
+* Containerized execution per pipeline
+* Parallel pipeline execution engine
+* Artifact storage system
+* Retry and failure policy system
+* Plugin-based step extensions
+* Remote dashboard for pipeline monitoring
+
+---

package/configs/.jarvis-ci.json

@@ -3,7 +3,29 @@
     "port": 5050,
     "local": false,
     "proxy": "",
-    "secret": ""
+    "secret": "6e23a467d3acbf3adb29979f1757876d"
   },
-  "repos": []
+  "repos": [
+    {
+      "name": "backend",
+      "repo": "asdf/sdf",
+      "branch": "main",
+      "yamlPath": "/home/muqeet-ahmad/Desktop/jarvis-ci/pipelines/backend/backend.jarvis.yaml",
+      "tempDir": "/home/muqeet-ahmad/Desktop/jarvis-ci/tmp/asdf-sdf"
+    },
+    {
+      "name": "n",
+      "repo": "sdf/sdf",
+      "branch": "main",
+      "yamlPath": "/home/muqeet-ahmad/Desktop/jarvis-ci/pipelines/n/n.jarvis.yaml",
+      "tempDir": "/home/muqeet-ahmad/Desktop/jarvis-ci/tmp/sdf-sdf"
+    },
+    {
+      "name": "asdf",
+      "repo": "sd/d",
+      "branch": "main",
+      "yamlPath": "/home/muqeet-ahmad/Desktop/jarvis-ci/pipelines/asdf/asdf.jarvis.yaml",
+      "tempDir": "/home/muqeet-ahmad/Desktop/jarvis-ci/tmp/sd-d"
+    }
+  ]
 }

package/dist/bin/cli.js

@@ -1,14 +1,30 @@
 #!/usr/bin/env node
+import path from "path";
 import { ConfigCommand } from "../commands/config/config.command.js";
 import { PipelineCommand } from "../commands/pipeline/pipeline.command.js";
 import { ServerCommand } from "../commands/server/server.command.js";
 import { Server } from "../server.js";
+import fs from 'fs';
 export class JarvisCLI {
     static instance;
     configCommand;
     serverCommand;
     PipelineCommand;
+    CONFIG_PATH = path.join(process.cwd(), 'configs');
+    baseConfiguration = {
+        "server": {
+            "port": 5050,
+            "local": false,
+            "proxy": "",
+            "secret": ""
+        },
+        "repos": []
+    };
     constructor() {
+        if (!fs.existsSync(this.CONFIG_PATH)) {
+            fs.mkdirSync(this.CONFIG_PATH, { recursive: true });
+            fs.writeFileSync(path.join(this.CONFIG_PATH, '.jarvis-ci.json'), JSON.stringify(this.baseConfiguration));
+        }
         this.configCommand = new ConfigCommand();
         this.serverCommand = new ServerCommand();
         this.PipelineCommand = new PipelineCommand();
@@ -61,7 +77,6 @@ export class JarvisCLI {
             return;
         }
         switch (subcommand) {
-            case 'add':
             case 'edit':
                 this.PipelineCommand.editPipeline(pipelineName);
                 break;
@@ -83,6 +98,8 @@ Jarvis CLI
 Commands:
   jarvis config add         Add repository configuration
   jarvis config port        Set webhook server port
+  jarvis config local       Set webhook server to listen on localhost(yes) or public ip enabled server (no)
+  jarvis config proxy       Set webhook server to listen on interfaces (proxy mode) from smee.io
   jarvis start              Start webhook server
   jarvis pipeline list      List all pipelines
   jarvis pipeline delete <pipelineName>   Delete a pipeline configuration

package/dist/commands/config/config.command.js

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import { ConfigService } from './config.service.js';
+import crypto from 'crypto';
 export class ConfigCommand {
     CONFIG_PATH = path.join(process.cwd(), 'configs', '.jarvis-ci.json');
     configService;
@@ -12,7 +13,7 @@ export class ConfigCommand {
         const proxyURL = local ? (await this.configService.getProxyURL()).proxy : '';
         const { githubRepoURL } = await this.configService.getGithubRepo();
         const { branchName } = await this.configService.getBranchName();
-        const { webhookSecret } = await this.configService.getWebhookSecret();
+        // const { webhookSecret } = await this.configService.getWebhookSecret()
         const { pipelineName } = await this.configService.getPipelineName();
         const tempDirPath = this.configService.createTempPipelineDirectory(githubRepoURL);
         if (!tempDirPath) {
@@ -33,13 +34,19 @@ export class ConfigCommand {
         };
         const configFile = fs.readFileSync(this.CONFIG_PATH);
         let configArray = JSON.parse(configFile.toString());
-        configArray.server.secret = webhookSecret;
+        const webhookSecret = configArray.server.secret !== "" ? configArray.server.secret : crypto.randomBytes(16).toString('hex');
+        if (configArray.server.secret !== "") {
+            configArray.server.secret = webhookSecret;
+        }
         configArray.server.local = local;
         if (local) {
             configArray.server.proxy = proxyURL;
         }
         configArray.repos.push(config);
         fs.writeFileSync(this.CONFIG_PATH, JSON.stringify(configArray, null, 2));
+        console.info(`
+            The webhook secret is this:  ${webhookSecret}
+            `);
         console.log('✅ configuration has been added successfully to .jarvis-ci.json');
     }
     loadConfig() {

package/dist/commands/pipeline/pipeline.command.js

@@ -13,6 +13,7 @@ export class PipelineCommand {
         "docker-compose",
         "ssh",
         "git",
+        "cd",
     ];
     configService;
     CONFIG_PATH = path.join(process.cwd(), 'configs', '.jarvis-ci.json');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jarvis-ci",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "description": "This npm package is light weight CI/CD tool. the goal is to achieve simplicity and local machine CI/CD execution. it is configured through YAML for commands.",
   "main": "./dist/index.js",
   "type": "module",
@@ -51,4 +51,4 @@
     "esbuild": "^0.27.4",
     "typescript": "^6.0.2"
   }
-}
+}

package/pipelines/asdf/asdf.jarvis.yaml

@@ -0,0 +1 @@
+sdfg

package/pipelines/backend/backend.jarvis.yaml

@@ -0,0 +1 @@
+asdfsdf

package/pipelines/n/n.jarvis.yaml

@@ -0,0 +1 @@
+ljk