git-daemon 0.1.9 → 0.1.11

package/healthchecks/example-suite/about-description/run.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const start = Date.now();
+
+const emit = ({
+  status,
+  summary,
+  explanation,
+  details = [],
+  metrics = {},
+  artifacts = [],
+}) => {
+  const payload = {
+    status,
+    summary,
+    explanation,
+    details,
+    metrics,
+    artifacts,
+    durationMs: Date.now() - start,
+  };
+  process.stdout.write(JSON.stringify(payload));
+};
+
+const parseJsonEnv = (name) => {
+  const raw = process.env[name];
+  if (!raw) {
+    return { value: null };
+  }
+  try {
+    return { value: JSON.parse(raw) };
+  } catch (err) {
+    return { error: err instanceof Error ? err.message : "Invalid JSON" };
+  }
+};
+
+const findReadme = (repoPath) => {
+  const candidates = [
+    "README.md",
+    "README.MD",
+    "README.markdown",
+    "README.txt",
+  ];
+  for (const name of candidates) {
+    const target = path.join(repoPath, name);
+    if (fs.existsSync(target)) {
+      return target;
+    }
+  }
+  return null;
+};
+
+const isBadgeLine = (line) =>
+  /^\s*\[!\[.*\]\(.*\)\]\(.*\)\s*$/.test(line) ||
+  /^\s*!\[.*\]\(.*\)\s*$/.test(line) ||
+  /^\s*<img\b/i.test(line);
+
+const stripMarkdown = (text) =>
+  text
+    .replace(/!\[([^\]]*)\]\([^)]+\)/g, "$1")
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+    .replace(/`([^`]*)`/g, "$1")
+    .replace(/[*_~]/g, "")
+    .replace(/<[^>]+>/g, "");
+
+const normalize = (text) =>
+  stripMarkdown(text)
+    .replace(/\s+/g, " ")
+    .trim()
+    .replace(/[.!?]+$/, "")
+    .toLowerCase();
+
+const extractFirstSentence = (readme) => {
+  const lines = readme.split(/\r?\n/);
+  const paragraph = [];
+  let inCodeBlock = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("```")) {
+      inCodeBlock = !inCodeBlock;
+      continue;
+    }
+    if (inCodeBlock) {
+      continue;
+    }
+    if (!trimmed) {
+      if (paragraph.length > 0) {
+        break;
+      }
+      continue;
+    }
+    if (trimmed.startsWith("#") || trimmed.startsWith(">")) {
+      continue;
+    }
+    if (isBadgeLine(trimmed)) {
+      continue;
+    }
+    if (trimmed.startsWith("<!--")) {
+      continue;
+    }
+    paragraph.push(trimmed);
+  }
+
+  if (paragraph.length === 0) {
+    return null;
+  }
+  const text = paragraph.join(" ");
+  const match = text.match(/^(.+?[.!?])(?:\s|$)/);
+  return match ? match[1] : text;
+};
+
+const repoPath = process.env.REPO_PATH;
+if (!repoPath) {
+  emit({
+    status: "failed",
+    summary: "Missing repo path",
+    explanation: "REPO_PATH environment variable is required.",
+    details: [
+      {
+        code: "MISSING_REPO_PATH",
+        severity: "high",
+        message: "REPO_PATH environment variable was not provided.",
+      },
+    ],
+  });
+  process.exit(0);
+}
+
+const repoInfo = parseJsonEnv("REPO_INFO");
+if (repoInfo.error) {
+  emit({
+    status: "failed",
+    summary: "Invalid repo info",
+    explanation: "REPO_INFO must be valid JSON.",
+    details: [
+      {
+        code: "INVALID_REPO_INFO",
+        severity: "high",
+        message: repoInfo.error,
+      },
+    ],
+  });
+  process.exit(0);
+}
+
+const description =
+  repoInfo.value && typeof repoInfo.value.description === "string"
+    ? repoInfo.value.description.trim()
+    : "";
+
+if (!description) {
+  emit({
+    status: "na",
+    summary: "Missing repo description",
+    explanation:
+      "REPO_INFO.description is missing, so there is nothing to compare.",
+  });
+  process.exit(0);
+}
+
+const readmePath = findReadme(repoPath);
+if (!readmePath) {
+  emit({
+    status: "na",
+    summary: "README not found",
+    explanation: "No README file was found in the repo root.",
+  });
+  process.exit(0);
+}
+
+let readmeText = "";
+try {
+  readmeText = fs.readFileSync(readmePath, "utf8");
+} catch (err) {
+  emit({
+    status: "failed",
+    summary: "Failed to read README",
+    explanation: "Unable to read README file.",
+    details: [
+      {
+        code: "README_READ_FAILED",
+        severity: "high",
+        message: err instanceof Error ? err.message : "Read failed.",
+      },
+    ],
+  });
+  process.exit(0);
+}
+
+const firstSentence = extractFirstSentence(readmeText);
+if (!firstSentence) {
+  emit({
+    status: "na",
+    summary: "README has no readable paragraph",
+    explanation:
+      "Could not locate non-title text to compare against the description.",
+  });
+  process.exit(0);
+}
+
+const normalizedDescription = normalize(description);
+const normalizedSentence = normalize(firstSentence);
+
+if (normalizedDescription === normalizedSentence) {
+  emit({
+    status: "pass-full",
+    summary: "Description matches README",
+    explanation:
+      "The GitHub repo description matches the first README sentence.",
+  });
+  process.exit(0);
+}
+
+emit({
+  status: "failed",
+  summary: "Description does not match README",
+  explanation:
+    "The GitHub repo description does not match the first README sentence.",
+  details: [
+    {
+      code: "ABOUT_MISMATCH",
+      severity: "medium",
+      message: `README sentence: "${firstSentence}"`,
+      remediation: `Update the GitHub description to match: "${firstSentence}"`,
+    },
+    {
+      code: "ABOUT_MISMATCH",
+      severity: "medium",
+      message: `Repo description: "${description}"`,
+    },
+  ],
+  metrics: {
+    readmeSentence: firstSentence,
+    description,
+  },
+});

package/healthchecks/example-suite/package-manager/healthcheck.json

@@ -0,0 +1,17 @@
+{
+  "id": "package-manager",
+  "name": "packageManager is defined",
+  "version": "1.0.0",
+  "description": "Ensures package.json declares a package manager.",
+  "entrypoint": "./run.js",
+  "args": [],
+  "timeoutSeconds": 30,
+  "permissions": {
+    "repoRead": true,
+    "network": false,
+    "secrets": []
+  },
+  "cacheable": true,
+  "cacheMaxAgeSeconds": 3600,
+  "outputSchemaVersion": 1
+}

package/healthchecks/example-suite/package-manager/run.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const start = Date.now();
+
+const emit = ({
+  status,
+  summary,
+  explanation,
+  details = [],
+  metrics = {},
+  artifacts = [],
+}) => {
+  const payload = {
+    status,
+    summary,
+    explanation,
+    details,
+    metrics,
+    artifacts,
+    durationMs: Date.now() - start,
+  };
+  process.stdout.write(JSON.stringify(payload));
+};
+
+const repoPath = process.env.REPO_PATH;
+if (!repoPath) {
+  emit({
+    status: "failed",
+    summary: "Missing repo path",
+    explanation: "REPO_PATH environment variable is required.",
+    details: [
+      {
+        code: "MISSING_REPO_PATH",
+        severity: "high",
+        message: "REPO_PATH environment variable was not provided.",
+      },
+    ],
+  });
+  process.exit(0);
+}
+
+const packageJsonPath = path.join(repoPath, "package.json");
+if (!fs.existsSync(packageJsonPath)) {
+  emit({
+    status: "na",
+    summary: "No package.json",
+    explanation: "This repository does not use package.json.",
+  });
+  process.exit(0);
+}
+
+let parsed;
+try {
+  const raw = fs.readFileSync(packageJsonPath, "utf8");
+  parsed = JSON.parse(raw);
+} catch (err) {
+  emit({
+    status: "failed",
+    summary: "Invalid package.json",
+    explanation: "package.json could not be parsed.",
+    details: [
+      {
+        code: "PACKAGE_JSON_INVALID",
+        severity: "high",
+        message: err instanceof Error ? err.message : "Parse failed.",
+      },
+    ],
+  });
+  process.exit(0);
+}
+
+const packageManager =
+  parsed && typeof parsed.packageManager === "string"
+    ? parsed.packageManager.trim()
+    : "";
+
+if (!packageManager) {
+  emit({
+    status: "failed",
+    summary: "packageManager missing",
+    explanation:
+      "Define packageManager in package.json to lock the package manager toolchain.",
+    details: [
+      {
+        code: "PACKAGE_MANAGER_MISSING",
+        severity: "medium",
+        message:
+          "Set packageManager (example: \"pnpm@8.15.4\") to enable corepack.",
+      },
+    ],
+  });
+  process.exit(0);
+}
+
+emit({
+  status: "pass-full",
+  summary: "packageManager is set",
+  explanation: `package.json declares "${packageManager}".`,
+  metrics: {
+    packageManager,
+  },
+});

package/healthchecks/example-suite/suite.json

@@ -0,0 +1,6 @@
+{
+  "id": "example-suite",
+  "name": "Example Healthchecks",
+  "version": "1.0.0",
+  "description": "Sample healthchecks for git-daemon."
+}

package/openapi.yaml

@@ -93,6 +93,8 @@ paths:
                   data: {"type":"log","stream":"stdout","line":"Cloning into..."}
 
                   data: {"type":"progress","kind":"git","percent":42,"detail":"receiving objects"}
+
+                  data: {"type":"progress","kind":"healthcheck","detail":"lint: running"}
         '401':
           $ref: '#/components/responses/Unauthorized'
         '403':
@@ -314,6 +316,77 @@ paths:
           $ref: '#/components/responses/UnprocessableEntity'
         '500':
           $ref: '#/components/responses/InternalError'
+  /v1/healthchecks:
+    get:
+      summary: List available healthchecks
+      parameters:
+        - $ref: '#/components/parameters/OriginHeader'
+      responses:
+        '200':
+          description: Healthcheck catalog
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HealthcheckCatalogResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '500':
+          $ref: '#/components/responses/InternalError'
+  /v1/healthchecks/run:
+    post:
+      summary: Run healthchecks for a repository
+      parameters:
+        - $ref: '#/components/parameters/OriginHeader'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/HealthcheckRunRequest'
+      responses:
+        '202':
+          description: Job created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/JobResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          $ref: '#/components/responses/Conflict'
+        '422':
+          $ref: '#/components/responses/UnprocessableEntity'
+        '500':
+          $ref: '#/components/responses/InternalError'
+  /v1/healthchecks/jobs/{id}/result:
+    get:
+      summary: Get healthcheck results for a job
+      parameters:
+        - $ref: '#/components/parameters/OriginHeader'
+        - $ref: '#/components/parameters/JobId'
+      responses:
+        '200':
+          description: Healthcheck results
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HealthcheckRunResult'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          $ref: '#/components/responses/Conflict'
+        '500':
+          $ref: '#/components/responses/InternalError'
   /v1/diagnostics:
     get:
       summary: Get diagnostics bundle metadata
@@ -708,6 +781,210 @@ components:
         safer:
           type: boolean
           default: true
+    HealthcheckCatalogResponse:
+      type: object
+      required:
+        - suites
+      properties:
+        suites:
+          type: array
+          items:
+            $ref: '#/components/schemas/HealthcheckSuite'
+    HealthcheckSuite:
+      type: object
+      required:
+        - id
+        - name
+        - checks
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        version:
+          type: string
+        description:
+          type: string
+        checks:
+          type: array
+          items:
+            $ref: '#/components/schemas/HealthcheckDefinition'
+    HealthcheckDefinition:
+      type: object
+      required:
+        - id
+        - name
+        - version
+        - description
+        - timeoutSeconds
+        - cacheable
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        version:
+          type: string
+        description:
+          type: string
+        timeoutSeconds:
+          type: integer
+          minimum: 1
+        cacheable:
+          type: boolean
+        cacheMaxAgeSeconds:
+          type: integer
+          minimum: 1
+        permissions:
+          $ref: '#/components/schemas/HealthcheckPermissions'
+        configSchema:
+          type: object
+          description: JSON schema for check config.
+          additionalProperties: true
+        outputSchemaVersion:
+          type: integer
+    HealthcheckPermissions:
+      type: object
+      properties:
+        repoRead:
+          type: boolean
+        network:
+          type: boolean
+        secrets:
+          type: array
+          items:
+            type: string
+    HealthcheckRunRequest:
+      type: object
+      required:
+        - repoPath
+      properties:
+        repoPath:
+          type: string
+        repoInfo:
+          type: object
+          description: UI-supplied repo metadata passed through to checks.
+          additionalProperties: true
+        suiteId:
+          type: string
+        checks:
+          type: array
+          items:
+            $ref: '#/components/schemas/HealthcheckSelection'
+    HealthcheckSelection:
+      type: object
+      required:
+        - checkId
+      properties:
+        suiteId:
+          type: string
+        checkId:
+          type: string
+        config:
+          type: object
+          additionalProperties: true
+        cacheMode:
+          type: string
+          enum: [prefer, refresh, bypass]
+          default: prefer
+    HealthcheckRunResult:
+      type: object
+      required:
+        - jobId
+        - repoPath
+        - status
+        - checks
+      properties:
+        jobId:
+          type: string
+        repoPath:
+          type: string
+        status:
+          $ref: '#/components/schemas/HealthcheckStatus'
+        summary:
+          type: string
+        checks:
+          type: array
+          items:
+            $ref: '#/components/schemas/HealthcheckResult'
+        startedAt:
+          type: string
+          format: date-time
+        finishedAt:
+          type: string
+          format: date-time
+    HealthcheckResult:
+      type: object
+      required:
+        - checkId
+        - status
+        - summary
+        - explanation
+      properties:
+        suiteId:
+          type: string
+        checkId:
+          type: string
+        status:
+          $ref: '#/components/schemas/HealthcheckStatus'
+        summary:
+          type: string
+        explanation:
+          type: string
+        details:
+          type: array
+          items:
+            $ref: '#/components/schemas/HealthcheckDetail'
+        metrics:
+          type: object
+          additionalProperties: true
+        artifacts:
+          type: array
+          items:
+            $ref: '#/components/schemas/HealthcheckArtifact'
+        durationMs:
+          type: integer
+          minimum: 0
+        cached:
+          type: boolean
+    HealthcheckDetail:
+      type: object
+      required:
+        - severity
+        - message
+      properties:
+        code:
+          type: string
+        severity:
+          type: string
+          enum: [info, low, medium, high, critical]
+        message:
+          type: string
+        path:
+          type: string
+        line:
+          type: integer
+          minimum: 1
+        column:
+          type: integer
+          minimum: 1
+        remediation:
+          type: string
+    HealthcheckArtifact:
+      type: object
+      required:
+        - name
+        - path
+      properties:
+        name:
+          type: string
+        path:
+          type: string
+        contentType:
+          type: string
+    HealthcheckStatus:
+      type: string
+      enum: [na, failed, pass-partial, pass-full]
     CancelResponse:
       type: object
       required:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "git-daemon",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "private": false,
   "type": "commonjs",
   "main": "dist/daemon.js",
@@ -8,6 +8,8 @@
     "build": "tsc",
     "daemon": "tsx src/daemon.ts",
     "daemon:setup": "tsx src/setup.ts",
+    "typecheck": "tsc --noEmit",
+    "verify": "npm run lint && npm run typecheck && npm test",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:clone": "bash scripts/test-clone.sh",