git-daemon 0.1.10 → 0.1.12

package/README.md

@@ -19,7 +19,9 @@ Git Daemon is a local Node.js service that exposes a small, authenticated HTTP A
 Healthchecks are user-supplied executables/scripts stored in local suites (which can be
 private repos). The daemon runs them as jobs, streams logs over SSE, and returns a
 normalized status (`na`, `failed`, `pass-partial`, `pass-full`) plus details. Suites are
-configured via local paths, and each check has a `healthcheck.json` manifest.
+configured via local paths, and each check has a `healthcheck.json` manifest. For a
+quick demo, set `healthchecks.demo: true` in config to auto-enable the bundled example
+suite (when present).
 
 ## Security model (high level)
 
@@ -197,6 +199,14 @@ curl -H "Origin: https://app.example.com" \
   http://127.0.0.1:8790/v1/healthchecks/jobs/<JOB_ID>/result
 ```
 
+List healthchecks (flat):
+
+```bash
+curl -H "Origin: https://app.example.com" \
+  -H "Authorization: Bearer <TOKEN>" \
+  "http://127.0.0.1:8790/v1/healthchecks?flat=true"
+```
+
 ## Configuration
 
 Config is stored in OS-specific directories:
@@ -218,6 +228,7 @@ Key settings live in `config.json`:
 - `deps.defaultSafer`: defaults to `true` for `--ignore-scripts`
 - `jobs.maxConcurrent` and `jobs.timeoutSeconds`
 - `healthchecks.suites`: array of absolute or config-relative suite paths
+- `healthchecks.demo`: enable bundled example healthchecks if present
 
 Tokens are stored (hashed) in `tokens.json`. Logs are written under the configured `logging.directory` with rotation.
 

package/config.schema.json

@@ -140,6 +140,11 @@
         },
         "defaultSuiteId": {
           "type": "string"
+        },
+        "demo": {
+          "type": "boolean",
+          "default": false,
+          "description": "When true, auto-enables the bundled example healthchecks if present."
         }
       }
     },

package/design.md

@@ -430,7 +430,7 @@ Recommendations:
 
 ### Healthcheck endpoints
 
-* `GET /v1/healthchecks` → list installed suites and checks.
+* `GET /v1/healthchecks` → list installed suites and checks (use `?flat=true` for a flattened list).
 * `POST /v1/healthchecks/run` → job
 
   * body: `{ repoPath, repoInfo?, suiteId?, checks?: [{ suiteId?, checkId, config?, cacheMode? }] }`

package/dist/config.js

@@ -47,6 +47,7 @@ const defaultConfig = () => ({
     },
     healthchecks: {
         suites: [],
+        demo: false,
     },
     logging: {
         directory: "logs",
@@ -68,7 +69,7 @@ const loadConfig = async (configDir) => {
     try {
         const raw = await fs_1.promises.readFile(configPath, "utf8");
         const data = JSON.parse(raw);
-        return {
+        const merged = {
             ...(0, exports.defaultConfig)(),
             ...data,
             server: {
@@ -107,6 +108,22 @@ const loadConfig = async (configDir) => {
                 entries: data.approvals?.entries ?? [],
             },
         };
+        if (merged.healthchecks?.demo) {
+            const demoSuitePath = path_1.default.resolve(__dirname, "..", "healthchecks", "example-suite");
+            try {
+                await fs_1.promises.access(demoSuitePath);
+                if (!merged.healthchecks.suites.includes(demoSuitePath)) {
+                    merged.healthchecks.suites = [
+                        ...merged.healthchecks.suites,
+                        demoSuitePath,
+                    ];
+                }
+            }
+            catch {
+                // Ignore missing demo suite; config can still load.
+            }
+        }
+        return merged;
     }
     catch (err) {
         if (err.code !== "ENOENT") {

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

@@ -155,10 +155,16 @@ const description =
 
 if (!description) {
   emit({
-    status: "na",
+    status: "failed",
     summary: "Missing repo description",
-    explanation:
-      "REPO_INFO.description is missing, so there is nothing to compare.",
+    explanation: "REPO_INFO.description is required for this healthcheck.",
+    details: [
+      {
+        code: "ABOUT_MISSING",
+        severity: "high",
+        message: "Provide a GitHub repo description to match the README.",
+      },
+    ],
   });
   process.exit(0);
 }
@@ -166,9 +172,16 @@ if (!description) {
 const readmePath = findReadme(repoPath);
 if (!readmePath) {
   emit({
-    status: "na",
+    status: "failed",
     summary: "README not found",
-    explanation: "No README file was found in the repo root.",
+    explanation: "A README is required to compare against the description.",
+    details: [
+      {
+        code: "README_MISSING",
+        severity: "high",
+        message: "Add a README with a clear first sentence.",
+      },
+    ],
   });
   process.exit(0);
 }
@@ -195,10 +208,18 @@ try {
 const firstSentence = extractFirstSentence(readmeText);
 if (!firstSentence) {
   emit({
-    status: "na",
-    summary: "README has no readable paragraph",
+    status: "failed",
+    summary: "README missing a first sentence",
     explanation:
       "Could not locate non-title text to compare against the description.",
+    details: [
+      {
+        code: "README_SENTENCE_MISSING",
+        severity: "high",
+        message:
+          "Add a first paragraph with a clear first sentence after the title.",
+      },
+    ],
   });
   process.exit(0);
 }

package/openapi.yaml

@@ -321,13 +321,16 @@ paths:
       summary: List available healthchecks
       parameters:
         - $ref: '#/components/parameters/OriginHeader'
+        - $ref: '#/components/parameters/HealthcheckFlat'
       responses:
         '200':
           description: Healthcheck catalog
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/HealthcheckCatalogResponse'
+                oneOf:
+                  - $ref: '#/components/schemas/HealthcheckCatalogResponse'
+                  - $ref: '#/components/schemas/HealthcheckFlatResponse'
         '401':
           $ref: '#/components/responses/Unauthorized'
         '403':
@@ -438,6 +441,14 @@ components:
       schema:
         type: boolean
         default: true
+    HealthcheckFlat:
+      name: flat
+      in: query
+      required: false
+      schema:
+        type: boolean
+        default: false
+      description: Return a flattened list of checks instead of suites.
   schemas:
     MetaResponse:
       type: object
@@ -790,6 +801,15 @@ components:
           type: array
           items:
             $ref: '#/components/schemas/HealthcheckSuite'
+    HealthcheckFlatResponse:
+      type: object
+      required:
+        - checks
+      properties:
+        checks:
+          type: array
+          items:
+            $ref: '#/components/schemas/HealthcheckFlatCheck'
     HealthcheckSuite:
       type: object
       required:
@@ -843,6 +863,43 @@ components:
           additionalProperties: true
         outputSchemaVersion:
           type: integer
+    HealthcheckFlatCheck:
+      type: object
+      required:
+        - suiteId
+        - checkId
+        - name
+        - version
+        - description
+        - timeoutSeconds
+        - cacheable
+      properties:
+        suiteId:
+          type: string
+        checkId:
+          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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "git-daemon",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "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",

package/src/app.ts

@@ -54,6 +54,7 @@ import { installDeps } from "./deps";
 import { openTarget } from "./os";
 import {
   HealthcheckResultStore,
+  flattenHealthchecks,
   listHealthcheckSuites,
   loadHealthcheckSuites,
   resolveSelections,
@@ -530,6 +531,11 @@ export const createApp = (ctx: DaemonContext) => {
           ctx.configDir,
           ctx.config.healthchecks?.suites ?? [],
         );
+        const flat = _req.query.flat === "true";
+        if (flat) {
+          res.json({ checks: flattenHealthchecks(suites) });
+          return;
+        }
         res.json({ suites: listHealthcheckSuites(suites) });
       } catch (err) {
         next(err);

package/src/config.ts

@@ -46,6 +46,7 @@ export const defaultConfig = (): AppConfig => ({
   },
   healthchecks: {
     suites: [],
+    demo: false,
   },
   logging: {
     directory: "logs",
@@ -67,7 +68,7 @@ export const loadConfig = async (configDir: string): Promise<AppConfig> => {
   try {
     const raw = await fs.readFile(configPath, "utf8");
     const data = JSON.parse(raw) as AppConfig;
-    return {
+    const merged: AppConfig = {
       ...defaultConfig(),
       ...data,
       server: {
@@ -106,6 +107,28 @@ export const loadConfig = async (configDir: string): Promise<AppConfig> => {
         entries: data.approvals?.entries ?? [],
       },
     };
+
+    if (merged.healthchecks?.demo) {
+      const demoSuitePath = path.resolve(
+        __dirname,
+        "..",
+        "healthchecks",
+        "example-suite",
+      );
+      try {
+        await fs.access(demoSuitePath);
+        if (!merged.healthchecks.suites.includes(demoSuitePath)) {
+          merged.healthchecks.suites = [
+            ...merged.healthchecks.suites,
+            demoSuitePath,
+          ];
+        }
+      } catch {
+        // Ignore missing demo suite; config can still load.
+      }
+    }
+
+    return merged;
   } catch (err) {
     if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
       throw err;

package/src/daemon.ts

@@ -15,6 +15,7 @@ const start = async () => {
     port: ctx.config.server.port,
     workspaceRoot: ctx.config.workspaceRoot ?? "not configured",
     originAllowlist: ctx.config.originAllowlist,
+    healthchecksDemo: ctx.config.healthchecks?.demo ?? false,
   };
   ctx.logger.info(startupSummary, "Git Daemon starting");
   if (process.env.GIT_DAEMON_LOG_STDOUT !== "1") {
@@ -26,6 +27,9 @@ const start = async () => {
     console.log(
       `  allowlist: ${startupSummary.originAllowlist.join(", ") || "none"}`,
     );
+    if (startupSummary.healthchecksDemo) {
+      console.log("  healthchecks: demo mode enabled");
+    }
     const httpsConfig = ctx.config.server.https;
     if (httpsConfig?.enabled) {
       console.log(

package/src/healthchecks.ts

@@ -279,6 +279,23 @@ export const listHealthcheckSuites = (suites: HealthcheckSuite[]) =>
     })),
   }));
 
+export const flattenHealthchecks = (suites: HealthcheckSuite[]) =>
+  suites.flatMap((suite) =>
+    suite.checks.map((check) => ({
+      suiteId: suite.id,
+      checkId: check.id,
+      name: check.name,
+      version: check.version,
+      description: check.description,
+      timeoutSeconds: check.timeoutSeconds,
+      cacheable: check.cacheable,
+      cacheMaxAgeSeconds: check.cacheMaxAgeSeconds,
+      permissions: check.permissions,
+      configSchema: check.configSchema,
+      outputSchemaVersion: check.outputSchemaVersion,
+    })),
+  );
+
 export const resolveSelections = (
   suites: HealthcheckSuite[],
   request: HealthcheckRunRequest,

package/src/types.ts

@@ -34,6 +34,7 @@ export type AppConfig = {
   healthchecks?: {
     suites: string[];
     defaultSuiteId?: string;
+    demo?: boolean;
   };
   logging: {
     directory: string;