jackherd 0.0.0-stage → 1.0.0

package/src/config/detect.ts

@@ -0,0 +1,196 @@
+import { CLI_NAME } from '../version/release'
+import { PROJECT_CONFIG_PATH } from './location'
+
+export const PACKAGE_MANAGER = { bun: 'bun', yarn: 'yarn', pnpm: 'pnpm', npm: 'npm' } as const
+
+export type PackageManager = (typeof PACKAGE_MANAGER)[keyof typeof PACKAGE_MANAGER]
+
+/** What the kit reads from a repository to fill the values its config leaves out. */
+export type RepositoryFacts = {
+  /** The lock files of `LOCK_FILES` present in the repository root. */
+  lockFiles: string[]
+  /** Branch names on `origin`, without the remote prefix. */
+  remoteBranches: string[]
+}
+
+export type PackageManagerDetection =
+  | { kind: 'found'; manager: PackageManager; lockFile: string }
+  | { kind: 'none' }
+  | { kind: 'ambiguous'; lockFiles: string[] }
+
+type DerivedCommands = {
+  test: string
+  typecheck: string
+  lint: string
+  format: string
+  install: string
+  dev: string
+  lintFiles: string
+}
+
+/** In order of preference within one manager: Bun's text lock before its binary one. */
+export const LOCK_FILES: Record<string, PackageManager> = {
+  'bun.lock': PACKAGE_MANAGER.bun,
+  'bun.lockb': PACKAGE_MANAGER.bun,
+  'yarn.lock': PACKAGE_MANAGER.yarn,
+  'pnpm-lock.yaml': PACKAGE_MANAGER.pnpm,
+  'package-lock.json': PACKAGE_MANAGER.npm,
+}
+
+/** The base branches detection chooses between; any other base is set in the config. */
+const BASE_BRANCH_CANDIDATES = ['main', 'master'] as const
+
+/** The base branch when the repository does not decide; the schema's default too. */
+export const DEFAULT_BASE_BRANCH = 'main'
+
+const COMMAND_KEYS = ['test', 'typecheck', 'lint', 'format', 'install', 'dev'] as const
+
+/**
+ * Bun fetches a tool it lacks, so its commands name the package; the others run the repository's own binaries.
+ * Biome runs as `bunx @biomejs/biome <command>`: its package's only binary, started without naming it twice.
+ */
+const DERIVED_COMMANDS: Record<PackageManager, DerivedCommands> = {
+  bun: {
+    test: 'bun test',
+    typecheck: 'bunx -p typescript tsc --noEmit',
+    lint: 'bunx @biomejs/biome check .',
+    format: 'bunx @biomejs/biome format --write .',
+    install: 'bun install',
+    dev: 'bun run dev',
+    lintFiles: 'bunx @biomejs/biome check --no-errors-on-unmatched',
+  },
+  yarn: {
+    test: 'yarn test',
+    typecheck: 'yarn tsc --noEmit',
+    lint: 'yarn biome check .',
+    format: 'yarn biome format --write .',
+    install: 'yarn install',
+    dev: 'yarn dev',
+    lintFiles: 'yarn biome check --no-errors-on-unmatched',
+  },
+  pnpm: {
+    test: 'pnpm test',
+    typecheck: 'pnpm exec tsc --noEmit',
+    lint: 'pnpm exec biome check .',
+    format: 'pnpm exec biome format --write .',
+    install: 'pnpm install',
+    dev: 'pnpm dev',
+    lintFiles: 'pnpm exec biome check --no-errors-on-unmatched',
+  },
+  npm: {
+    test: 'npm test',
+    typecheck: 'npx tsc --noEmit',
+    lint: 'npx @biomejs/biome check .',
+    format: 'npx @biomejs/biome format --write .',
+    install: 'npm install',
+    dev: 'npm run dev',
+    lintFiles: 'npx @biomejs/biome check --no-errors-on-unmatched',
+  },
+}
+
+/** The bun defaults of the schema, so a repository Bun runs and one detection skips agree. */
+export const BUN_COMMANDS = DERIVED_COMMANDS.bun
+
+type ConfigObject = Record<string, unknown>
+
+/** The blocks of a config that detection fills. */
+type ConfigParts = { commands: ConfigObject; lanes: ConfigObject; check: ConfigObject | undefined }
+
+const isObject = (value: unknown): value is ConfigObject =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const has = (object: ConfigObject, key: string): boolean => Object.hasOwn(object, key)
+
+export const detectPackageManager = (lockFiles: readonly string[]): PackageManagerDetection => {
+  const known = Object.keys(LOCK_FILES).filter((file) => lockFiles.includes(file))
+  const managers = new Set(known.map((file) => LOCK_FILES[file]))
+  if (managers.size === 0) return { kind: 'none' }
+  if (managers.size > 1) return { kind: 'ambiguous', lockFiles: known }
+  return { kind: 'found', manager: LOCK_FILES[known[0]], lockFile: known[0] }
+}
+
+/** `main` or `master` when origin has exactly one of them; `origin/HEAD` is not asked, since it can point at a branch long deleted. */
+export const detectBaseBranch = (remoteBranches: readonly string[]): string | null => {
+  const present = BASE_BRANCH_CANDIDATES.filter((branch) => remoteBranches.includes(branch))
+  return present.length === 1 ? present[0] : null
+}
+
+const ambiguousNote = (lockFiles: readonly string[]): string =>
+  `${CLI_NAME}: lock files of several package managers (${lockFiles.join(', ')}); using the bun defaults. Set \`commands\` and \`lanes.lockFile\` in ${PROJECT_CONFIG_PATH}.`
+
+const baseBranchNote = (remoteBranches: readonly string[]): string => {
+  const reason = BASE_BRANCH_CANDIDATES.every((branch) => remoteBranches.includes(branch))
+    ? 'origin has both main and master'
+    : 'origin has neither main nor master'
+  return `${CLI_NAME}: ${reason}; using ${DEFAULT_BASE_BRANCH}. Set \`baseBranch\` in ${PROJECT_CONFIG_PATH}.`
+}
+
+const missingCommandKeys = (commands: ConfigObject): string[] => COMMAND_KEYS.filter((key) => !has(commands, key))
+
+const withManager = (
+  raw: ConfigObject,
+  parts: ConfigParts,
+  found: { manager: PackageManager; lockFile: string },
+): ConfigObject => {
+  const derived = DERIVED_COMMANDS[found.manager]
+  const commands = Object.fromEntries(
+    missingCommandKeys(parts.commands).map((key) => [key, derived[key as keyof DerivedCommands]]),
+  )
+  const check = parts.check ?? {}
+  return {
+    ...raw,
+    commands: { ...commands, ...parts.commands },
+    lanes: { lockFile: found.lockFile, ...parts.lanes },
+    check: { lintFilesCommand: derived.lintFiles, ...check },
+  }
+}
+
+const needsManager = (parts: ConfigParts) =>
+  missingCommandKeys(parts.commands).length > 0 ||
+  !has(parts.lanes, 'lockFile') ||
+  !(parts.check && has(parts.check, 'lintFilesCommand'))
+
+const fillManager = (
+  raw: ConfigObject,
+  parts: ConfigParts,
+  lockFiles: readonly string[],
+): { raw: ConfigObject; notes: string[] } => {
+  if (!needsManager(parts)) return { raw, notes: [] }
+  const detection = detectPackageManager(lockFiles)
+  if (detection.kind === 'found') return { raw: withManager(raw, parts, detection), notes: [] }
+  return { raw, notes: detection.kind === 'ambiguous' ? [ambiguousNote(detection.lockFiles)] : [] }
+}
+
+const fillBaseBranch = (
+  raw: ConfigObject,
+  remoteBranches: readonly string[],
+): { raw: ConfigObject; notes: string[] } => {
+  if (has(raw, 'baseBranch')) return { raw, notes: [] }
+  const detected = detectBaseBranch(remoteBranches)
+  return detected
+    ? { raw: { ...raw, baseBranch: detected }, notes: [] }
+    : { raw, notes: [baseBranchNote(remoteBranches)] }
+}
+
+/** The config's own `commands`, `lanes` and `check` blocks, or null when one is there but no object. */
+const configParts = (raw: ConfigObject): ConfigParts | null => {
+  const { commands = {}, lanes = {}, check } = raw
+  if (!isObject(commands) || !isObject(lanes) || (check !== undefined && !isObject(check))) return null
+  return { commands, lanes, check }
+}
+
+/**
+ * The raw config with every value it leaves out of `commands`, `lanes.lockFile`, `check.lintFilesCommand` and
+ * `baseBranch` filled from the repository: the package manager from the lock file, the base branch from origin.
+ * A value the config sets always wins. Where the repository does not decide (lock files of several managers,
+ * both or neither of `main` and `master`), the schema default holds and a note says so; without a lock file the
+ * defaults hold silently. A config of the wrong shape is passed through untouched for the schema to refuse.
+ */
+export const withDetected = (raw: unknown, facts: RepositoryFacts): { raw: unknown; notes: string[] } => {
+  if (!isObject(raw)) return { raw, notes: [] }
+  const parts = configParts(raw)
+  if (!parts) return { raw, notes: [] }
+  const manager = fillManager(raw, parts, facts.lockFiles)
+  const base = fillBaseBranch(manager.raw, facts.remoteBranches)
+  return { raw: base.raw, notes: [...manager.notes, ...base.notes] }
+}

package/src/config/index.ts

@@ -0,0 +1,2 @@
+export * from './json-schema'
+export * from './schema'

package/src/config/json-schema.ts

@@ -0,0 +1,5 @@
+import { z } from 'zod'
+import { jackherdConfigSchema } from './schema'
+
+export const renderConfigJsonSchema = (): string =>
+  `${JSON.stringify(z.toJSONSchema(jackherdConfigSchema, { io: 'input' }), null, 2)}\n`

package/src/config/legacy-names.ts

@@ -0,0 +1,56 @@
+import { join } from 'node:path'
+import { CLI_NAME } from '../version/release'
+import { CONFIG_FILE, CONFIG_SCHEMA_REFERENCE, LEGACY_CONFIG_PATH, MANIFEST_FILE, TOOL_DIRECTORY } from './location'
+
+/** An old file name and the one it moved to, both relative to a project root or the home directory. */
+export type Rename = { from: string; to: string }
+
+/** What moving the old files takes: the renames whose target is free, and the old files a new one shadows. */
+export type RenamePlan = { renames: Rename[]; shadowed: Rename[] }
+
+/** The line a run prints when it moved files of an install before the rename, so the session learns the new command. */
+export const RENAMED_NOTICE = `agent-kit is now jackherd: the command is \`${CLI_NAME}\`.`
+
+/** Read and moved until 2.0.0, never written. */
+export const LEGACY_MANIFEST_PATH = '.claude/agent-kit.lock.json'
+export const LEGACY_UPDATE_STATE_PATH = '.claude/agent-kit-update-check.json'
+export const LEGACY_SCHEMA_REFERENCE = '../node_modules/@crossdelta/agent-kit/schemas/agent-kit.schema.json'
+
+export const PROJECT_LEGACY_FILES: readonly Rename[] = [
+  { from: LEGACY_CONFIG_PATH, to: `${TOOL_DIRECTORY}/${CONFIG_FILE}` },
+  { from: LEGACY_MANIFEST_PATH, to: `${TOOL_DIRECTORY}/${MANIFEST_FILE}` },
+]
+
+export const PUBLIC_CONTENT_PATH = `${TOOL_DIRECTORY}/public-content.json`
+
+/** Where the public-content facts lay before the rename: below `XDG_CONFIG_HOME`, else `~/.config`. */
+export const legacyPublicContentPath = (home: string, configHome: string | undefined): string =>
+  join(configHome || join(home, '.config'), 'agent-kit', 'public-content.json')
+
+/**
+ * The renames `pairs` take in a directory holding `present`: only pairs whose old file is there; one whose new
+ * file is there too is shadowed, since the new file wins and the old one is the user's to delete.
+ */
+export const legacyRenames = (pairs: readonly Rename[], present: readonly string[]): RenamePlan => {
+  const there = new Set(present)
+  const old = pairs.filter(({ from }) => there.has(from))
+  return {
+    renames: old.filter(({ to }) => !there.has(to)),
+    shadowed: old.filter(({ to }) => there.has(to)),
+  }
+}
+
+/** A moved config's `$schema` at the old package points at the new one; any other text stays byte for byte. */
+export const withCurrentSchemaReference = (text: string): string =>
+  text.replace(`"$schema": "${LEGACY_SCHEMA_REFERENCE}"`, `"$schema": "${CONFIG_SCHEMA_REFERENCE}"`)
+
+/**
+ * The line a command prints when it read the config under its old name; null for any other path. The home
+ * directory's file moves with `sync --global`, a project's with `sync`.
+ */
+export const legacyConfigNote = (configPath: string, home: string): string | null => {
+  if (!configPath.endsWith(`/${LEGACY_CONFIG_PATH}`)) return null
+  const directory = configPath.slice(0, -LEGACY_CONFIG_PATH.length - 1)
+  const command = directory === home ? `${CLI_NAME} sync --global` : `${CLI_NAME} sync`
+  return `${configPath} becomes ${join(directory, TOOL_DIRECTORY, CONFIG_FILE)} at the next \`${command}\`.`
+}

package/src/config/link-kinds.ts

@@ -0,0 +1,25 @@
+/** A kind of link a plan can carry, shown as a chip on the sprint page: the URLs it matches, its label and its icon. */
+export type LinkKind = {
+  /** A regular expression source matched against the whole URL. */
+  pattern: string
+  /** The chip's text when the plan gives the link no text of its own. */
+  label: string
+  /** A short text or emoji shown before the label; no external asset. */
+  icon: string
+}
+
+/** The kinds known without configuration: plain URL patterns, no service is called. */
+export const DEFAULT_LINK_KINDS: readonly LinkKind[] = [
+  { 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: '✦' },
+]
+
+export const isRegularExpression = (source: string): boolean => {
+  try {
+    new RegExp(source)
+    return true
+  } catch {
+    return false
+  }
+}

package/src/config/location.ts

@@ -0,0 +1,46 @@
+import { dirname, join, resolve } from 'node:path'
+import { PACKAGE_NAME } from '../version/release'
+
+/** The directory holding the tool's own config and lock, in a project and in the home directory alike. */
+export const TOOL_DIRECTORY = '.jackherd'
+export const CONFIG_FILE = 'config.json'
+export const MANIFEST_FILE = 'lock.json'
+
+/** The `$schema` a new project config gets: from `.jackherd/`, as deep as `node_modules` is from `.claude/`. */
+export const CONFIG_SCHEMA_REFERENCE = `../node_modules/${PACKAGE_NAME}/schemas/${PACKAGE_NAME}.schema.json`
+
+/** The project's config, relative to its root; the same path below the home directory is the global config. */
+export const PROJECT_CONFIG_PATH = `${TOOL_DIRECTORY}/${CONFIG_FILE}`
+
+/** Where the config lay before 0.29, read until 2.0.0 when the new one is missing; never written. */
+export const LEGACY_CONFIG_PATH = '.claude/agent-kit.json'
+
+/** The config files of `root`, the one that wins first. */
+export const configCandidates = (root: string): string[] => [
+  join(root, PROJECT_CONFIG_PATH),
+  join(root, LEGACY_CONFIG_PATH),
+]
+
+export const globalConfigPath = (home: string): string => join(home, PROJECT_CONFIG_PATH)
+
+/**
+ * The nearest ancestor of `start` holding a project config. The home directory is passed over: the file there
+ * is the global config of `jh sync --global`, and `~` is no project.
+ */
+export const findProjectRoot = (start: string, home: string, exists: (path: string) => boolean): string | null => {
+  const homeDirectory = resolve(home)
+  let directory = resolve(start)
+  while (directory === homeDirectory || !configCandidates(directory).some(exists)) {
+    const parent = dirname(directory)
+    if (parent === directory) return null
+    directory = parent
+  }
+  return directory
+}
+
+/**
+ * The project config of the first of `roots` that has one, else `~/.jackherd/config.json`, else null; in each
+ * directory the old `.claude/agent-kit.json` stands in for a missing new file.
+ */
+export const locateConfigFile = (roots: string[], home: string, exists: (path: string) => boolean): string | null =>
+  [...roots, home].flatMap(configCandidates).find(exists) ?? null

package/src/config/read-config.ts

@@ -0,0 +1,42 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { type RepositoryFacts, withDetected } from './detect'
+import { legacyConfigNote } from './legacy-names'
+import { globalConfigPath, locateConfigFile, PROJECT_CONFIG_PATH } from './location'
+import { readRepositoryFacts } from './repository-facts'
+import { type JackherdConfig, parseConfigFile } from './schema'
+
+/** A config with the values detection filled in, and a line for each value the repository did not decide. */
+export type ResolvedConfig = { config: JackherdConfig; notes: string[] }
+
+/**
+ * Parses a config file's raw JSON, filling what it leaves out from the repository (see `withDetected`); an invalid
+ * file throws with its path and the issues in words.
+ */
+const resolveConfig = (raw: unknown, facts: RepositoryFacts, path: string): ResolvedConfig => {
+  const detected = withDetected(raw ?? {}, facts)
+  return { config: parseConfigFile(detected.raw, path), notes: detected.notes }
+}
+
+/**
+ * The project's config from `.jackherd/config.json` of the first of `roots` that has one, else from
+ * `~/.jackherd/config.json`; throws when there is none or the file is invalid. The checkout a command runs in
+ * comes before the main checkout, so a lane reads the config it is working on, not the one `main` had before
+ * the lane changed it. Values the file leaves out are detected in the first of `roots`.
+ */
+export const readResolvedConfig = (
+  roots: string[],
+  home: string = homedir(),
+  facts: RepositoryFacts = readRepositoryFacts(roots[0]),
+): ResolvedConfig => {
+  const configPath = locateConfigFile(roots, home, existsSync)
+  if (!configPath)
+    throw new Error(`${PROJECT_CONFIG_PATH} not found in ${roots.join(' or ')}, nor ${globalConfigPath(home)}`)
+  const resolved = resolveConfig(JSON.parse(readFileSync(configPath, 'utf8')), facts, configPath)
+  const legacy = legacyConfigNote(configPath, home)
+  return legacy ? { ...resolved, notes: [legacy, ...resolved.notes] } : resolved
+}
+
+/** `readResolvedConfig` without the notes. */
+export const readConfig = (roots: string[], home: string = homedir()): JackherdConfig =>
+  readResolvedConfig(roots, home).config

package/src/config/repository-facts.ts

@@ -0,0 +1,19 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { LOCK_FILES, type RepositoryFacts } from './detect'
+
+const REMOTE_BRANCHES = ['for-each-ref', '--format=%(refname:lstrip=3)', 'refs/remotes/origin/']
+
+/** Branch names on origin as the last fetch left them; none outside a git repository or without origin. */
+const remoteBranchesOf = (root: string): string[] => {
+  const result = spawnSync('git', REMOTE_BRANCHES, { cwd: root, encoding: 'utf8' })
+  if (result.status !== 0) return []
+  return result.stdout.split('\n').filter((branch) => branch !== '' && branch !== 'HEAD')
+}
+
+/** The lock files and origin branches of the repository at `root`; reads only, never fetches. */
+export const readRepositoryFacts = (root: string): RepositoryFacts => ({
+  lockFiles: Object.keys(LOCK_FILES).filter((file) => existsSync(join(root, file))),
+  remoteBranches: remoteBranchesOf(root),
+})

package/src/config/repository-values.ts

@@ -0,0 +1,46 @@
+import type { JackherdConfig } from './schema'
+
+/** The values each repository decides for itself, by the short name `jh config` and global skills use. */
+export const REPOSITORY_VALUE = {
+  test: 'test',
+  typecheck: 'typecheck',
+  lint: 'lint',
+  format: 'format',
+  install: 'install',
+  dev: 'dev',
+  lockFile: 'lockFile',
+  baseBranch: 'baseBranch',
+} as const
+
+export type RepositoryValue = (typeof REPOSITORY_VALUE)[keyof typeof REPOSITORY_VALUE]
+
+const PLACEHOLDER: Record<RepositoryValue, string> = {
+  test: 'kit.command.test',
+  typecheck: 'kit.command.typecheck',
+  lint: 'kit.command.lint',
+  format: 'kit.command.format',
+  install: 'kit.command.install',
+  dev: 'kit.command.dev',
+  lockFile: 'kit.lanes.lockFile',
+  baseBranch: 'kit.baseBranch',
+}
+
+const NAMES = Object.values(REPOSITORY_VALUE)
+
+export const isRepositoryValue = (value: string): value is RepositoryValue => (NAMES as string[]).includes(value)
+
+/** How a global kit renders the placeholders a repository decides: `<install>`, `<lockFile>`, `<baseBranch>`, … */
+export const REPOSITORY_TOKENS: ReadonlyMap<string, string> = new Map(
+  NAMES.map((name) => [PLACEHOLDER[name], `<${name}>`]),
+)
+
+export const repositoryValuesOf = (config: JackherdConfig): Record<RepositoryValue, string> => ({
+  ...config.commands,
+  lockFile: config.lanes.lockFile,
+  baseBranch: config.baseBranch,
+})
+
+export const formatRepositoryValues = (values: Record<RepositoryValue, string>): string[] => {
+  const width = Math.max(...NAMES.map((name) => name.length)) + 2
+  return NAMES.map((name) => `${name.padEnd(width)}${values[name]}`)
+}