@sentinelqa/uploader 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SentinelQA
+
+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,96 @@
+# @sentinelqa/uploader
+
+Sentinel uploader CLI for Playwright CI artifacts.
+
+## Install
+
+```bash
+npm i -D @sentinelqa/uploader
+```
+
+Or run directly:
+
+```bash
+npx @sentinelqa/uploader playwright
+```
+
+## Usage
+
+```bash
+sentinelqa playwright
+```
+
+If you want to run without installing, use:
+
+```bash
+npx @sentinelqa/uploader playwright
+```
+
+### Minimal GitLab CI
+
+```yaml
+e2e:
+  image: node:20
+  script:
+    - npm ci
+    - npx playwright install --with-deps
+    - npm run test:e2e || true
+    - npx @sentinelqa/uploader playwright
+  artifacts:
+    when: always
+    paths:
+      - playwright-report/
+      - test-results/
+```
+
+### Minimal GitHub Actions
+
+```yaml
+name: E2E
+on: [push]
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - run: npm ci
+      - run: npx playwright install --with-deps
+      - run: npm run test:e2e || true
+      - run: npx @sentinelqa/uploader playwright
+```
+
+## Required Environment Variables
+
+- `SENTINEL_TOKEN` (project ingest token)
+- `SENTINEL_URL` (optional; defaults to `https://app.sentinelqa.com`)
+
+## Optional: BYO S3 (Advanced)
+
+Set these to upload directly to your own bucket:
+
+- `SENTINEL_S3_ENDPOINT` (optional for AWS)
+- `SENTINEL_S3_REGION`
+- `SENTINEL_S3_BUCKET`
+- `SENTINEL_S3_PREFIX` (optional)
+- `SENTINEL_S3_ACCESS_KEY_ID`
+- `SENTINEL_S3_SECRET_ACCESS_KEY`
+
+## Troubleshooting
+
+**Missing artifacts**
+- Ensure Playwright outputs are present:
+  - `playwright-report/report.json`
+  - `playwright-report/`
+  - `test-results/`
+
+**401 Unauthorized**
+- Check `SENTINEL_TOKEN` and project permissions.
+
+**No CI metadata**
+- The uploader detects GitLab or GitHub. If running locally, set the CI env vars or run in CI.
+
+**BYO uploads failing**
+- Verify `SENTINEL_S3_*` values and permissions.

package/dist/cli.js

@@ -0,0 +1,466 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const client_s3_1 = require("@aws-sdk/client-s3");
+const DEFAULT_APP_URL = "https://app.sentinelqa.com";
+const DEFAULT_JSON_PATH = "playwright-report/report.json";
+const DEFAULT_PLAYWRIGHT_REPORT_DIR = "playwright-report";
+const DEFAULT_TEST_RESULTS_DIR = "test-results";
+const readEnv = (key) => {
+    const value = process.env[key];
+    return value && value.trim().length > 0 ? value.trim() : null;
+};
+const fail = (message) => {
+    console.error(`Error: ${message}`);
+    process.exit(1);
+};
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const withRetry = async (fn, label) => {
+    const maxAttempts = 3;
+    let attempt = 0;
+    let delay = 500;
+    while (attempt < maxAttempts) {
+        try {
+            return await fn(attempt + 1);
+        }
+        catch (err) {
+            attempt += 1;
+            if (attempt >= maxAttempts)
+                throw err;
+            await sleep(delay);
+            delay *= 2;
+        }
+    }
+    throw new Error(`${label} failed after ${maxAttempts} attempts`);
+};
+const getArgValue = (args, name) => {
+    const idx = args.indexOf(name);
+    if (idx === -1)
+        return null;
+    return args[idx + 1] ?? null;
+};
+const ensureFile = (filePath, label) => {
+    if (!filePath)
+        fail(`${label} is required.`);
+    if (!fs_1.default.existsSync(filePath))
+        fail(`${label} not found at ${filePath}.`);
+    if (!fs_1.default.statSync(filePath).isFile())
+        fail(`${label} is not a file: ${filePath}.`);
+};
+const ensureDir = (dirPath, label) => {
+    if (!dirPath)
+        fail(`${label} is required.`);
+    if (!fs_1.default.existsSync(dirPath))
+        fail(`${label} not found at ${dirPath}.`);
+    if (!fs_1.default.statSync(dirPath).isDirectory()) {
+        fail(`${label} is not a directory: ${dirPath}.`);
+    }
+};
+const listFilesRecursive = (dirPath) => {
+    const results = [];
+    const entries = fs_1.default.readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path_1.default.join(dirPath, entry.name);
+        if (entry.isDirectory())
+            results.push(...listFilesRecursive(fullPath));
+        else if (entry.isFile())
+            results.push(fullPath);
+    }
+    return results;
+};
+const normalizeError = (value) => {
+    if (!value)
+        return null;
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "object" && value && "message" in value) {
+        return String(value.message);
+    }
+    return JSON.stringify(value);
+};
+const buildFullTitle = (suiteTitles, testTitle) => {
+    const parts = [...suiteTitles, testTitle].filter(Boolean);
+    return parts.join(" > ");
+};
+const statusRank = (status) => {
+    if (status === "failed")
+        return 3;
+    if (status === "timedOut")
+        return 2;
+    if (status === "passed")
+        return 1;
+    if (status === "skipped")
+        return 0;
+    return 0;
+};
+const normalizeStatus = (status) => {
+    if (status === "failed" || status === "timedOut")
+        return "failed";
+    if (status === "passed")
+        return "passed";
+    if (status === "skipped")
+        return "skipped";
+    return "skipped";
+};
+const extractTestsFromReport = (reportJson) => {
+    const tests = [];
+    const suites = Array.isArray(reportJson?.suites) ? reportJson.suites : [];
+    const visitSuite = (suite, ancestors) => {
+        const title = suite?.title || "";
+        const nextAncestors = title ? [...ancestors, title] : [...ancestors];
+        const childSuites = Array.isArray(suite?.suites) ? suite.suites : [];
+        for (const child of childSuites)
+            visitSuite(child, nextAncestors);
+        const suiteTests = Array.isArray(suite?.tests) ? suite.tests : [];
+        for (const test of suiteTests) {
+            const results = Array.isArray(test?.results) ? test.results : [];
+            let topStatus = normalizeStatus(test?.status) || "skipped";
+            let durationMs = 0;
+            let error = null;
+            for (const result of results) {
+                const resultStatus = normalizeStatus(result?.status);
+                if (statusRank(resultStatus) > statusRank(topStatus))
+                    topStatus = resultStatus;
+                if (typeof result?.duration === "number")
+                    durationMs += result.duration;
+                if (!error && Array.isArray(result?.errors) && result.errors.length > 0) {
+                    error = normalizeError(result.errors[0]?.message || result.errors[0]);
+                }
+            }
+            if (!error && test?.error)
+                error = normalizeError(test.error);
+            const file = test?.location?.file || suite?.location?.file || null;
+            const projectName = test?.projectName || results[0]?.projectName || null;
+            const testTitle = test?.title || "";
+            const fullTitle = buildFullTitle(nextAncestors, testTitle);
+            const displayTitle = fullTitle || testTitle;
+            const testKey = `${file || "unknown"}::${projectName || "default"}::${fullTitle || testTitle}`;
+            tests.push({
+                testKey,
+                title: displayTitle,
+                file: file || "",
+                projectName: projectName || "",
+                status: topStatus,
+                durationMs,
+                error
+            });
+        }
+    };
+    for (const suite of suites)
+        visitSuite(suite, []);
+    return tests;
+};
+const computeRunStatus = (tests) => {
+    return tests.some((t) => t.status === "failed") ? "failed" : "passed";
+};
+const detectGitLabEnv = () => {
+    const isGitLab = readEnv("GITLAB_CI") === "true" || !!readEnv("CI_PROJECT_ID");
+    if (!isGitLab)
+        return null;
+    return {
+        provider: "gitlab",
+        commit: {
+            sha: readEnv("CI_COMMIT_SHA"),
+            branch: readEnv("CI_COMMIT_BRANCH") || readEnv("CI_COMMIT_REF_NAME")
+        },
+        ci: {
+            url: readEnv("CI_JOB_URL") || readEnv("CI_PIPELINE_URL")
+        }
+    };
+};
+const detectGitHubEnv = () => {
+    const isGitHub = readEnv("GITHUB_ACTIONS") === "true";
+    if (!isGitHub)
+        return null;
+    const sha = readEnv("GITHUB_SHA");
+    const branch = readEnv("GITHUB_REF_NAME") ||
+        (readEnv("GITHUB_REF") || "").replace("refs/heads/", "");
+    const serverUrl = readEnv("GITHUB_SERVER_URL");
+    const repo = readEnv("GITHUB_REPOSITORY");
+    const runId = readEnv("GITHUB_RUN_ID");
+    const url = serverUrl && repo && runId ? `${serverUrl}/${repo}/actions/runs/${runId}` : null;
+    return {
+        provider: "github",
+        commit: { sha, branch },
+        ci: { url }
+    };
+};
+const getArtifacts = (rootDir, typeOverride, runId, s3Prefix) => {
+    const files = listFilesRecursive(rootDir);
+    return files.map((filePath) => {
+        const rel = path_1.default.relative(rootDir, filePath).replace(/\\/g, "/");
+        const keyParts = [s3Prefix, runId, rel].filter(Boolean);
+        const objectKey = keyParts.join("/");
+        let type = typeOverride || null;
+        if (!type) {
+            const ext = path_1.default.extname(filePath).toLowerCase();
+            if (ext === ".zip")
+                type = "trace";
+            else if (ext === ".webm" || ext === ".mp4")
+                type = "video";
+            else if (ext === ".png" || ext === ".jpg" || ext === ".jpeg")
+                type = "screenshot";
+            else if (ext === ".log" || ext === ".txt")
+                type = "log";
+            else
+                type = "other";
+        }
+        return { type, filePath, objectKey };
+    });
+};
+const uploadArtifacts = async (s3Client, bucket, artifacts) => {
+    for (const artifact of artifacts) {
+        await withRetry(async () => {
+            const body = fs_1.default.createReadStream(artifact.filePath);
+            await s3Client.send(new client_s3_1.PutObjectCommand({
+                Bucket: bucket,
+                Key: artifact.objectKey,
+                Body: body
+            }));
+        }, `upload ${artifact.objectKey}`);
+    }
+};
+const printHelp = () => {
+    console.log([
+        "Sentinel Uploader CLI",
+        "",
+        "Usage:",
+        "  sentinelqa playwright [options]",
+        "  sentinelqa upload [options]",
+        "",
+        "Options:",
+        "  --playwright-json-path <path>   Path to Playwright JSON report",
+        "  --playwright-report-dir <dir>   Path to Playwright HTML report directory",
+        "  --test-results-dir <dir>        Path to Playwright test-results directory",
+        "  -h, --help                      Show help",
+        "",
+        "Env:",
+        "  SENTINEL_TOKEN   Ingest token for your project (required)",
+        "  SENTINEL_URL     Optional override for app URL",
+        "",
+        "Examples:",
+        "  sentinelqa playwright",
+        "  sentinelqa upload --playwright-json-path playwright-report/report.json"
+    ].join("\n"));
+};
+const main = async () => {
+    const args = process.argv.slice(2);
+    const command = args[0];
+    if (!command || command === "-h" || command === "--help" || command === "help") {
+        printHelp();
+        process.exit(0);
+    }
+    if (command !== "playwright" && command !== "upload") {
+        fail(`Unknown command "${command}". Run with --help for usage.`);
+    }
+    const ingestToken = readEnv("SENTINEL_TOKEN") || readEnv("PROJECT_INGEST_TOKEN");
+    if (!ingestToken)
+        fail("SENTINEL_TOKEN is required.");
+    const playwrightJsonPath = getArgValue(args, "--playwright-json-path") ||
+        readEnv("PLAYWRIGHT_JSON_PATH") ||
+        DEFAULT_JSON_PATH;
+    const playwrightReportDir = getArgValue(args, "--playwright-report-dir") ||
+        readEnv("PLAYWRIGHT_REPORT_DIR") ||
+        DEFAULT_PLAYWRIGHT_REPORT_DIR;
+    const testResultsDir = getArgValue(args, "--test-results-dir") ||
+        readEnv("TEST_RESULTS_DIR") ||
+        DEFAULT_TEST_RESULTS_DIR;
+    ensureFile(playwrightJsonPath, "PLAYWRIGHT_JSON_PATH");
+    ensureDir(playwrightReportDir, "PLAYWRIGHT_REPORT_DIR");
+    ensureDir(testResultsDir, "TEST_RESULTS_DIR");
+    const reportJson = JSON.parse(fs_1.default.readFileSync(playwrightJsonPath, "utf8"));
+    const tests = extractTestsFromReport(reportJson);
+    const status = computeRunStatus(tests);
+    const gitlab = detectGitLabEnv();
+    const github = detectGitHubEnv();
+    const ci = gitlab || github;
+    if (!ci)
+        fail("CI environment not detected (GitLab or GitHub).");
+    if (!ci.commit.sha)
+        fail("Commit SHA is required.");
+    if (!ci.commit.branch)
+        fail("Commit branch is required.");
+    if (!ci.ci.url)
+        fail("CI run URL is required.");
+    const appUrl = readEnv("SENTINEL_URL") || readEnv("APP_URL") || DEFAULT_APP_URL;
+    const createRes = await withRetry(() => fetch(`${appUrl}/api/runs`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${ingestToken}`
+        },
+        body: JSON.stringify({
+            provider: ci.provider,
+            commit: ci.commit,
+            ci: ci.ci
+        })
+    }), "POST /api/runs");
+    if (!createRes.ok) {
+        const body = await createRes.text();
+        fail(`POST /api/runs failed (${createRes.status}): ${body}`);
+    }
+    const { runId } = await createRes.json();
+    if (!runId)
+        fail("Missing runId from /api/runs response.");
+    const uploadStart = Date.now();
+    const byoBucket = readEnv("SENTINEL_S3_BUCKET") || readEnv("S3_BUCKET");
+    const byoPrefix = readEnv("SENTINEL_S3_PREFIX") || readEnv("S3_PREFIX") || "";
+    const artifacts = [
+        ...getArtifacts(playwrightReportDir, null, runId, byoBucket ? byoPrefix : ""),
+        ...getArtifacts(testResultsDir, null, runId, byoBucket ? byoPrefix : "")
+    ].filter((artifact) => path_1.default.resolve(artifact.filePath) !== path_1.default.resolve(playwrightJsonPath));
+    const artifactsWithMeta = artifacts.map((artifact) => {
+        const stat = fs_1.default.statSync(artifact.filePath);
+        const ext = path_1.default.extname(artifact.filePath).toLowerCase();
+        const contentType = ext === ".zip"
+            ? "application/zip"
+            : ext === ".webm"
+                ? "video/webm"
+                : ext === ".mp4"
+                    ? "video/mp4"
+                    : ext === ".png"
+                        ? "image/png"
+                        : ext === ".jpg" || ext === ".jpeg"
+                            ? "image/jpeg"
+                            : ext === ".txt" || ext === ".log"
+                                ? "text/plain"
+                                : "application/octet-stream";
+        return { ...artifact, sizeBytes: stat.size, contentType };
+    });
+    let finalArtifacts = artifactsWithMeta;
+    if (byoBucket) {
+        const s3Region = readEnv("SENTINEL_S3_REGION") || readEnv("AWS_REGION") || readEnv("S3_REGION");
+        if (!s3Region)
+            fail("SENTINEL_S3_REGION is required for BYO S3.");
+        const s3Endpoint = readEnv("SENTINEL_S3_ENDPOINT") || readEnv("S3_ENDPOINT");
+        const accessKeyId = readEnv("SENTINEL_S3_ACCESS_KEY_ID") || readEnv("AWS_ACCESS_KEY_ID");
+        const secretAccessKey = readEnv("SENTINEL_S3_SECRET_ACCESS_KEY") || readEnv("AWS_SECRET_ACCESS_KEY");
+        if (!accessKeyId || !secretAccessKey) {
+            fail("SENTINEL_S3_ACCESS_KEY_ID and SENTINEL_S3_SECRET_ACCESS_KEY are required.");
+        }
+        const s3Client = new client_s3_1.S3Client({
+            region: s3Region,
+            ...(s3Endpoint ? { endpoint: s3Endpoint } : {}),
+            credentials: { accessKeyId, secretAccessKey }
+        });
+        await withRetry(async () => {
+            await uploadArtifacts(s3Client, byoBucket, finalArtifacts);
+        }, "upload artifacts");
+        finalArtifacts = finalArtifacts.map((artifact) => ({
+            ...artifact,
+            bucket: byoBucket
+        }));
+    }
+    else {
+        const presignRes = await withRetry(() => fetch(`${appUrl}/api/uploads/presign`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${ingestToken}`
+            },
+            body: JSON.stringify({
+                items: finalArtifacts.map((artifact) => ({
+                    relPath: artifact.objectKey,
+                    contentType: artifact.contentType,
+                    sizeBytes: artifact.sizeBytes,
+                    kind: artifact.type
+                }))
+            })
+        }), "POST /api/uploads/presign");
+        if (!presignRes.ok) {
+            const body = await presignRes.text();
+            fail(`POST /api/uploads/presign failed (${presignRes.status}): ${body}`);
+        }
+        const presignData = await presignRes.json();
+        const uploadMap = new Map((presignData.items || []).map((item) => [item.relPath, item]));
+        await withRetry(async () => {
+            for (const artifact of finalArtifacts) {
+                const item = uploadMap.get(artifact.objectKey);
+                if (!item?.uploadUrl || !item?.objectKey) {
+                    throw new Error(`Missing upload URL for ${artifact.objectKey}`);
+                }
+                await withRetry(async () => {
+                    const body = fs_1.default.createReadStream(artifact.filePath);
+                    const res = await fetch(item.uploadUrl, {
+                        method: "PUT",
+                        headers: {
+                            "content-type": artifact.contentType
+                        },
+                        body
+                    });
+                    if (!res.ok) {
+                        throw new Error(`Upload failed (${res.status}) for ${artifact.objectKey}`);
+                    }
+                }, `upload ${artifact.objectKey}`);
+                artifact.objectKey = item.objectKey;
+            }
+        }, "upload artifacts");
+        finalArtifacts = finalArtifacts.map((artifact) => ({
+            ...artifact,
+            bucket: presignData.bucket
+        }));
+    }
+    const uploadDurationMs = Date.now() - uploadStart;
+    const completeRes = await withRetry(() => fetch(`${appUrl}/api/runs/${runId}/complete`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${ingestToken}`
+        },
+        body: JSON.stringify({
+            status,
+            finishedAt: new Date().toISOString(),
+            tests,
+            artifacts: finalArtifacts.map((artifact) => ({
+                type: artifact.type,
+                bucket: artifact.bucket,
+                objectKey: artifact.objectKey,
+                sizeBytes: artifact.sizeBytes,
+                contentType: artifact.contentType,
+                testKey: null
+            }))
+        })
+    }), "POST /api/runs/:runId/complete");
+    if (!completeRes.ok) {
+        const body = await completeRes.text();
+        fail(`POST /api/runs/:runId/complete failed (${completeRes.status}): ${body}`);
+    }
+    let shareUrl = null;
+    try {
+        const data = await completeRes.json();
+        shareUrl = data.shareUrl || null;
+    }
+    catch {
+        shareUrl = null;
+    }
+    const internalUrl = `${appUrl}/runs/${runId}`;
+    console.log(JSON.stringify({
+        event: "uploader_summary",
+        runId,
+        tests: tests.length,
+        artifacts: artifacts.length,
+        uploadDurationMs
+    }));
+    console.log(`Uploaded ${artifacts.length} artifacts and completed run ${runId}.`);
+    console.log(internalUrl);
+    if (shareUrl)
+        console.log(shareUrl);
+    if (status === "failed") {
+        const total = tests.length;
+        const failed = tests.filter((t) => t.status === "failed").length;
+        const useColor = !process.env.NO_COLOR;
+        const bold = useColor ? "\u001b[1m" : "";
+        const red = useColor ? "\u001b[31m" : "";
+        const reset = useColor ? "\u001b[0m" : "";
+        console.log(`${bold}${red}CI Debug Report${reset}`);
+        console.log(`${bold}${failed} failed / ${total} total${reset}`);
+    }
+};
+main().catch((err) => {
+    fail(err?.message || String(err));
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@sentinelqa/uploader",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Sentinel uploader CLI for CI/CD debugging artifacts",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sentinelqa/sentinel"
+  },
+  "keywords": [
+    "sentinel",
+    "ci",
+    "cicd",
+    "playwright",
+    "debugging",
+    "artifacts",
+    "uploader"
+  ],
+  "bin": {
+    "sentinelqa": "dist/cli.js"
+  },
+  "type": "commonjs",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "dist/cli.js",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "publish:dry": "npm run build && npm pack --dry-run"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.600.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.32",
+    "typescript": "^5.9.3"
+  }
+}