jackherd 0.0.1 → 1.0.1

package/schemas/jackherd.schema.json

@@ -0,0 +1,601 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "responseLanguage": {
+      "default": "en",
+      "type": "string",
+      "enum": [
+        "de",
+        "en"
+      ]
+    },
+    "planLanguage": {
+      "default": "en",
+      "type": "string",
+      "enum": [
+        "de",
+        "en"
+      ]
+    },
+    "planDirectory": {
+      "default": "docs/plans",
+      "type": "string",
+      "minLength": 1
+    },
+    "board": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "pattern": {
+          "default": "board-*",
+          "type": "string",
+          "pattern": "^(?![-.])[A-Za-z0-9._*?-]+$"
+        },
+        "file": {
+          "default": "board.md",
+          "type": "string",
+          "pattern": "^(?![-.])[A-Za-z0-9._-]+\\.md$"
+        },
+        "term": {
+          "default": "board",
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "sprintPattern": {
+      "not": {}
+    },
+    "worktreeDirectory": {
+      "default": ".claude/worktrees",
+      "type": "string",
+      "minLength": 1
+    },
+    "baseBranch": {
+      "default": "main",
+      "type": "string",
+      "pattern": "^(?![-/.])(?!.*(?:\\.\\.|\\/\\/|@\\{|\\.lock(?:\\/|$)))[A-Za-z0-9._/-]+(?<![./])$"
+    },
+    "skillPrefix": {
+      "default": "",
+      "anyOf": [
+        {
+          "type": "string",
+          "const": ""
+        },
+        {
+          "type": "string",
+          "pattern": "^[a-z0-9]+-$"
+        }
+      ]
+    },
+    "commands": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "test": {
+          "default": "bun test",
+          "type": "string",
+          "minLength": 1
+        },
+        "typecheck": {
+          "default": "bunx -p typescript tsc --noEmit",
+          "type": "string",
+          "minLength": 1
+        },
+        "lint": {
+          "default": "bunx @biomejs/biome check .",
+          "type": "string",
+          "minLength": 1
+        },
+        "format": {
+          "default": "bunx @biomejs/biome format --write .",
+          "type": "string",
+          "minLength": 1
+        },
+        "install": {
+          "default": "bun install",
+          "type": "string",
+          "minLength": 1
+        },
+        "dev": {
+          "default": "bun run dev",
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "lanes": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "copy": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^(?![/-])(?!(?:.*\\/)?\\.\\.(?:\\/|$))[^'\\x00-\\x1f\\x7f]+$"
+          }
+        },
+        "lockFile": {
+          "default": "bun.lock",
+          "type": "string",
+          "pattern": "^(?![/-])(?!(?:.*\\/)?\\.\\.(?:\\/|$))[A-Za-z0-9._/-]+$"
+        }
+      },
+      "additionalProperties": false
+    },
+    "models": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string",
+        "enum": [
+          "plan",
+          "implement",
+          "review",
+          "explore",
+          "orchestrate"
+        ]
+      },
+      "additionalProperties": {
+        "type": "string",
+        "pattern": "^claude-[a-z0-9][a-z0-9.-]*$"
+      },
+      "required": [
+        "plan",
+        "implement",
+        "review",
+        "explore",
+        "orchestrate"
+      ]
+    },
+    "terminal": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "adapter": {
+          "default": "none",
+          "type": "string",
+          "enum": [
+            "none",
+            "herdr"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "plans": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "fetchIntervalMinutes": {
+          "default": 5,
+          "type": "number",
+          "minimum": 0
+        },
+        "linkKinds": {
+          "default": [
+            {
+              "pattern": "^https://github\\.com/[^/]+/[^/]+/(pull|issues)/\\d+",
+              "label": "GitHub",
+              "icon": "⑂"
+            },
+            {
+              "pattern": "^https://(www\\.)?figma\\.com/",
+              "label": "Figma",
+              "icon": "◈"
+            },
+            {
+              "pattern": "^https://claude\\.ai/(code/)?artifact/",
+              "label": "Artifact",
+              "icon": "✦"
+            }
+          ],
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "pattern": {
+                "type": "string",
+                "minLength": 1
+              },
+              "label": {
+                "type": "string",
+                "minLength": 1
+              },
+              "icon": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "required": [
+              "pattern",
+              "label",
+              "icon"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "context": {
+          "default": {},
+          "type": "object",
+          "properties": {
+            "warnAt": {
+              "default": 0.6,
+              "type": "number",
+              "exclusiveMinimum": 0,
+              "exclusiveMaximum": 1
+            },
+            "alertAt": {
+              "default": 0.8,
+              "type": "number",
+              "exclusiveMinimum": 0,
+              "exclusiveMaximum": 1
+            },
+            "windows": {
+              "default": {},
+              "type": "object",
+              "propertyNames": {
+                "type": "string",
+                "pattern": "^claude-[a-z0-9][a-z0-9.-]*$"
+              },
+              "additionalProperties": {
+                "type": "integer",
+                "exclusiveMinimum": 0,
+                "maximum": 9007199254740991
+              }
+            },
+            "defaultWindow": {
+              "default": 200000,
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991
+            },
+            "coordinator": {
+              "default": {},
+              "type": "object",
+              "properties": {
+                "warnAt": {
+                  "default": 0.5,
+                  "type": "number",
+                  "exclusiveMinimum": 0,
+                  "exclusiveMaximum": 1
+                },
+                "alertAt": {
+                  "default": 0.7,
+                  "type": "number",
+                  "exclusiveMinimum": 0,
+                  "exclusiveMaximum": 1
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "watch": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "deploy": {
+          "type": "object",
+          "properties": {
+            "workflow": {
+              "type": "string",
+              "pattern": "^(?![-.])[A-Za-z0-9._-]+\\.ya?ml$"
+            },
+            "environments": {
+              "minItems": 1,
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          },
+          "required": [
+            "workflow",
+            "environments"
+          ],
+          "additionalProperties": false
+        },
+        "feedback": {
+          "default": {
+            "ignore": []
+          },
+          "anyOf": [
+            {
+              "type": "boolean",
+              "const": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "ignore": {
+                  "default": [],
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "previews": {
+          "type": "object",
+          "properties": {
+            "deployments": {
+              "default": false,
+              "type": "boolean"
+            },
+            "authors": {
+              "default": [],
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "urlPattern": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "additionalProperties": false
+        },
+        "sources": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string",
+                "pattern": "^[A-Za-z0-9][\\w.-]*$"
+              },
+              "command": {
+                "minItems": 1,
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "every": {
+                "default": 5,
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 9007199254740991
+              },
+              "items": {
+                "type": "string"
+              },
+              "map": {
+                "type": "object",
+                "properties": {
+                  "id": {
+                    "type": "string"
+                  },
+                  "updatedAt": {
+                    "type": "string"
+                  },
+                  "title": {
+                    "type": "string"
+                  },
+                  "url": {
+                    "type": "string"
+                  },
+                  "body": {
+                    "type": "string"
+                  },
+                  "author": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "id",
+                  "updatedAt"
+                ],
+                "additionalProperties": {
+                  "type": "string"
+                }
+              },
+              "ignoreAuthors": {
+                "default": [],
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "reportLimit": {
+                "default": 5,
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 9007199254740991
+              },
+              "lane": {
+                "type": "string",
+                "minLength": 1
+              },
+              "reportOn": {
+                "minItems": 1,
+                "maxItems": 10,
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              }
+            },
+            "required": [
+              "name",
+              "command",
+              "map"
+            ],
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "check": {
+      "type": "object",
+      "properties": {
+        "lintFilesCommand": {
+          "default": "bunx @biomejs/biome check --no-errors-on-unmatched",
+          "type": "string",
+          "minLength": 1
+        },
+        "checks": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string",
+                "minLength": 1
+              },
+              "command": {
+                "type": "string",
+                "minLength": 1
+              },
+              "globs": {
+                "minItems": 1,
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              }
+            },
+            "required": [
+              "name",
+              "command"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "generatorOwned": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "glob": {
+                "type": "string",
+                "minLength": 1
+              },
+              "generator": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "required": [
+              "glob",
+              "generator"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "buildArtifacts": {
+          "default": [
+            "**/tsup.config.bundled_*",
+            "**/dist/**",
+            "**/.turbo/**",
+            "**/node_modules/**",
+            "**/*.tsbuildinfo"
+          ],
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "reviewerRoutes": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "reviewer": {
+                "type": "string",
+                "minLength": 1
+              },
+              "globs": {
+                "minItems": 1,
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "why": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "required": [
+              "reviewer",
+              "globs",
+              "why"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "publicContent": {
+          "type": "object",
+          "properties": {
+            "globs": {
+              "minItems": 1,
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "exclude": {
+              "default": [],
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "reviewer": {
+              "default": "public-content",
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "required": [
+            "globs"
+          ],
+          "additionalProperties": false
+        },
+        "looseTests": {
+          "default": false,
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "required": [
+    "models"
+  ],
+  "additionalProperties": false
+}

package/src/check/changes.ts

@@ -0,0 +1,45 @@
+import { matchesAnyGlob, matchesGlob } from './glob'
+import type { CheckConfig } from './schema'
+
+/** `--untracked-files=all` lists a new directory's files one by one; the default folds it into `dir/`, which names no package root. */
+export const STATUS_COMMAND = ['git', 'status', '--porcelain', '--untracked-files=all'] as const
+
+export type ChangedFile = { path: string; staged: boolean }
+
+const unquote = (path: string): string =>
+  path.startsWith('"') && path.endsWith('"') ? path.slice(1, -1).replace(/\\"/g, '"') : path
+
+/**
+ * `git status --porcelain` rather than `git diff`, because a diff against HEAD lists no untracked
+ * files, so a brand new module and its test would be invisible to the whole check.
+ */
+export const parsePorcelain = (output: string): ChangedFile[] =>
+  output
+    .split('\n')
+    .filter((line) => line.length > 3)
+    // Position 3 is always a space in porcelain v1. If it is not, something trimmed the status
+    // column off the front of the line, and reading it as-is would eat the path's first character.
+    .map((line) => (line[2] === ' ' ? line : ` ${line}`))
+    .flatMap((line) => {
+      const index = line[0]
+      const rest = line.slice(3)
+      // A rename reads `R  old -> new`; the new path is the one that exists now.
+      const path = unquote(rest.includes(' -> ') ? (rest.split(' -> ').at(-1) as string) : rest)
+      if (index === 'D' || line[1] === 'D') return []
+      return [{ path, staged: index !== ' ' && index !== '?' }]
+    })
+
+export const stagedBuildArtifacts = (
+  files: readonly ChangedFile[],
+  artifactGlobs: CheckConfig['buildArtifacts'],
+): string[] => files.filter((file) => file.staged && matchesAnyGlob(file.path, artifactGlobs)).map((file) => file.path)
+
+/** Files a generator owns: a hand edit is lost on the next run, so the commit has to come from the generator. */
+export const generatorOwnedFiles = (
+  paths: readonly string[],
+  owners: CheckConfig['generatorOwned'],
+): { path: string; generator: string }[] =>
+  paths.flatMap((path) => {
+    const owner = owners.find(({ glob }) => matchesGlob(path, glob))
+    return owner ? [{ path, generator: owner.generator }] : []
+  })

package/src/check/command-line.ts

@@ -0,0 +1,12 @@
+const TOKEN = /(?:"[^"]*"|'[^']*'|\S)+/g
+const QUOTED = /"([^"]*)"|'([^']*)'/g
+
+/**
+ * Splits a configured command into arguments without a shell: whitespace separates, single and
+ * double quotes group. No expansion, no pipes; a command that needs them belongs in a script.
+ */
+export const tokenize = (command: string): string[] =>
+  (command.match(TOKEN) ?? []).map((token) => {
+    if (/["']/.test(token.replace(QUOTED, ''))) throw new Error(`Unterminated quote in command: ${command}`)
+    return token.replace(QUOTED, '$1$2')
+  })