jackherd 0.0.0-stage → 1.0.0

package/src/sync/init-command.ts

@@ -0,0 +1,239 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { CLAUDE_DIRECTORY, SETTINGS_FILE } from '../claude/paths'
+import { configCandidates, globalConfigPath, PROJECT_CONFIG_PATH } from '../config/location'
+import { CLI_NAME, PACKAGE_NAME } from '../version/release'
+import {
+  type CommandContext,
+  defaultContext,
+  GLOBAL_FLAG,
+  globalTargetNote,
+  runWithKit,
+  usageError,
+} from './command-context'
+import { collidingNames, DEFAULT_SKILL_PREFIX, type InitResult, runGlobalInit, runInit } from './init'
+import type { KitSource } from './kit'
+import { nextSteps } from './next-steps'
+import { SYNC_EXIT } from './report'
+import { GLOBAL_STATUS_LINE_COMMAND, migrateGlobalSettings } from './settings-migration'
+import {
+  applySettingsOffer,
+  readSettingsOffer,
+  SESSION_HOOK_COMMAND,
+  SESSION_HOOK_OFFER,
+  type SettingsOffer,
+  type SettingsRead,
+  statusLineOffer,
+} from './settings-offer'
+import type { SetupOutcome } from './setup'
+import { chooseSetup } from './setup-questions'
+
+/** The answer to init's questions (prefix, hook, status line), for runs without a terminal. */
+const ANSWER_FLAG = { yes: '--yes', no: '--no' } as const
+
+/** Where a project's status line runs from: the copy `sync` writes into its `.claude/`. */
+const PROJECT_STATUS_LINE = `${CLAUDE_DIRECTORY}/statusline.sh`
+
+const INIT_USAGE = `Usage: ${CLI_NAME} init [--global] [${ANSWER_FLAG.yes} | ${ANSWER_FLAG.no}]`
+
+/** How the user runs the CLI after each kind of install, for the next steps. */
+const GLOBAL_CLI = CLI_NAME
+const PROJECT_CLI = `bunx ${PACKAGE_NAME}`
+
+const NO_PREFIX = { skillPrefix: undefined, notes: [] }
+
+/** What a successful init leaves for its next steps: the config's names and the kit's version. */
+type FinishedInit = { init: InitResult; version: string }
+
+type InitArgs = { ok: true; global: boolean; answer: boolean | undefined } | { ok: false; message: string }
+
+/** `--yes` → true, `--no` → false, neither → undefined (ask). */
+const answerOf = (yes: boolean, no: boolean): boolean | undefined => {
+  if (yes) return true
+  if (no) return false
+  return undefined
+}
+
+const parseInitArgs = (args: string[]): InitArgs => {
+  const unknown = args.find((arg) => arg !== GLOBAL_FLAG && arg !== ANSWER_FLAG.yes && arg !== ANSWER_FLAG.no)
+  if (unknown !== undefined) return { ok: false, message: `Unknown argument: ${unknown}\n${INIT_USAGE}` }
+  const [yes, no, global] = [ANSWER_FLAG.yes, ANSWER_FLAG.no, GLOBAL_FLAG].map((flag) => args.includes(flag))
+  if (yes && no)
+    return { ok: false, message: `${ANSWER_FLAG.yes} and ${ANSWER_FLAG.no} exclude each other\n${INIT_USAGE}` }
+  return { ok: true, global, answer: answerOf(yes, no) }
+}
+
+const configNote = (configCreated: boolean, path: string): string =>
+  configCreated ? `Created ${path}.` : `Found ${path}, kept it as it is.`
+
+/** The lines about the config: created or kept, and for a new one the defaults taken without asking. */
+const configNotes = (configCreated: boolean, path: string, setup: SetupOutcome | null): string[] => [
+  configNote(configCreated, path),
+  ...(configCreated && setup?.note ? [setup.note] : []),
+]
+
+const HOOK_QUESTION = `Add a SessionStart hook that runs \`${SESSION_HOOK_COMMAND}\`, so every new session brings the global kit up to date after an update?`
+
+const STATUS_LINE_QUESTION = "Show the kit's status line (model, context fill, session cost)?"
+
+/** One setting `init` offers: what it writes, where, and how it asks. */
+type Offer = { offer: SettingsOffer; path: string; shownPath: string; label: string; question: string }
+
+const sessionHookOffer = (home: string): Offer => ({
+  offer: SESSION_HOOK_OFFER,
+  path: join(home, CLAUDE_DIRECTORY, SETTINGS_FILE),
+  shownPath: `~/${CLAUDE_DIRECTORY}/${SETTINGS_FILE}`,
+  label: 'the SessionStart hook',
+  question: HOOK_QUESTION,
+})
+
+const statusLineOfferAt = (root: string, shownRoot: string, command: string): Offer => ({
+  offer: statusLineOffer(command),
+  path: join(root, CLAUDE_DIRECTORY, SETTINGS_FILE),
+  shownPath: `${shownRoot}${CLAUDE_DIRECTORY}/${SETTINGS_FILE}`,
+  label: 'the status line',
+  question: STATUS_LINE_QUESTION,
+})
+
+const notWritten = (offer: Offer, reason: string): string =>
+  `Did not add ${offer.label} to ${offer.shownPath} (${reason}). It stays as it was; the README shows the entry to add by hand.`
+
+const notAsked = (offer: Offer): string =>
+  `Not asked about ${offer.label} without a terminal: \`${ANSWER_FLAG.yes}\` adds it to ${offer.shownPath}, \`${ANSWER_FLAG.no}\` leaves it out.`
+
+/**
+ * A status line of the user's own is replaced only after a yes to the question that names it: `--yes` does not
+ * answer it, `--no` does, and without a terminal it is not asked.
+ */
+const foreignAnswer = async (
+  context: CommandContext,
+  offer: Offer,
+  current: string,
+  answer: boolean | undefined,
+): Promise<boolean | null> => {
+  if (answer === false) return false
+  return context.ask(`${offer.shownPath} already runs \`${current}\`. Replace it with ${offer.label} of the kit?`)
+}
+
+/** The answer for one offer: from the command line, else from the user, null when nobody can be asked. */
+const answerFor = async (context: CommandContext, offer: Offer, read: SettingsRead, answer: boolean | undefined) => {
+  if (read.plan.kind === 'foreign') return foreignAnswer(context, offer, read.plan.current, answer)
+  return (
+    answer ??
+    (await context.ask(`${offer.question} It goes into ${offer.shownPath}; everything else there stays as it is.`))
+  )
+}
+
+/** Asks once per offer unless it is there already or the command line answered; never fails the init. */
+const offerSetting = async (context: CommandContext, offer: Offer, answer: boolean | undefined): Promise<void> => {
+  const read = await readSettingsOffer(offer.path, offer.offer)
+  if (read.plan.kind === 'present') return context.log(`${offer.shownPath} already has ${offer.label}.`)
+  if (read.plan.kind === 'unreadable') return context.log(notWritten(offer, read.plan.reason))
+  const choice = await answerFor(context, offer, read, answer)
+  if (choice === null) return context.log(notAsked(offer))
+  if (!choice) {
+    const kept = read.plan.kind === 'foreign' ? `, kept \`${read.plan.current}\`` : ''
+    return context.log(`Left ${offer.label} out of ${offer.shownPath}${kept}.`)
+  }
+  const written = await applySettingsOffer(offer.path, read)
+  context.log(
+    written.kind === 'written' ? `Added ${offer.label} to ${offer.shownPath}.` : notWritten(offer, written.reason),
+  )
+}
+
+const offerSettings = async (context: CommandContext, offers: Offer[], answer: boolean | undefined) => {
+  for (const offer of offers) await offerSetting(context, offer, answer)
+}
+
+const prefixQuestion = (names: string[]): string =>
+  `This project already has ${names.join(', ')}. Install the kit's skills and agents with the prefix ${DEFAULT_SKILL_PREFIX} (/${DEFAULT_SKILL_PREFIX}implement, …), so yours stay as they are and the kit's skills call each other, not yours?`
+
+const prefixNotAsked = (names: string[]): string =>
+  `Not asked about a prefix without a terminal although the project has ${names.join(', ')}: those became conflicts (.kit-new). \`${CLI_NAME} init ${ANSWER_FLAG.yes}\` on a fresh config installs the kit as ${DEFAULT_SKILL_PREFIX}…; or set "skillPrefix" in ${PROJECT_CONFIG_PATH} and run sync.`
+
+/** The prefix for a new config: asked when the project already has skills or agents of kit names. */
+const chooseSkillPrefix = async (context: CommandContext, kit: KitSource, answer: boolean | undefined) => {
+  const claudeDirectory = join(context.projectRoot, CLAUDE_DIRECTORY)
+  const names = collidingNames(kit, (path) => existsSync(join(claudeDirectory, path)))
+  if (names.length === 0) return { skillPrefix: undefined, notes: [] }
+  const choice = answer ?? (await context.ask(prefixQuestion(names)))
+  if (choice === null) return { skillPrefix: undefined, notes: [prefixNotAsked(names)] }
+  return { skillPrefix: choice ? DEFAULT_SKILL_PREFIX : undefined, notes: [] }
+}
+
+/** Prints what to do next, after everything else init said; tools are detected again, since setup may have installed herdr. */
+const printNextSteps = (context: CommandContext, finished: FinishedInit, cli: string): void => {
+  const steps = nextSteps({
+    skillPrefix: finished.init.skillPrefix,
+    adapter: finished.init.terminalAdapter,
+    tools: context.detectTools(),
+    version: finished.version,
+    cli,
+  })
+  for (const line of steps) context.log(line)
+}
+
+/** After the sync: the settings offers, then the next steps; nothing of it when init failed. */
+const finishInit = async (
+  context: CommandContext,
+  exitCode: number,
+  finished: FinishedInit | undefined,
+  after: { offers: Offer[]; cli: string; answer: boolean | undefined },
+): Promise<number> => {
+  if (exitCode === SYNC_EXIT.error || !finished) return exitCode
+  await offerSettings(context, after.offers, after.answer)
+  printNextSteps(context, finished, after.cli)
+  return exitCode
+}
+
+const initProjectCommand = async (context: CommandContext, answer: boolean | undefined): Promise<number> => {
+  const configExists = configCandidates(context.projectRoot).some(existsSync)
+  let finished: FinishedInit | undefined
+  const exitCode = await runWithKit(context, 'init', async (kit) => {
+    const { skillPrefix, notes } = configExists ? NO_PREFIX : await chooseSkillPrefix(context, kit, answer)
+    const setup = configExists ? null : await chooseSetup(context, answer)
+    const init = await runInit({
+      projectRoot: context.projectRoot,
+      home: context.home,
+      kit,
+      skillPrefix,
+      setup: setup?.values,
+    })
+    finished = { init, version: kit.version }
+    return {
+      notes: [...configNotes(init.configCreated, PROJECT_CONFIG_PATH, setup), ...notes],
+      result: init.sync,
+    }
+  })
+  const offers = [statusLineOfferAt(context.projectRoot, '', PROJECT_STATUS_LINE)]
+  return finishInit(context, exitCode, finished, { offers, cli: PROJECT_CLI, answer })
+}
+
+const initGlobalCommand = async (context: CommandContext, answer: boolean | undefined): Promise<number> => {
+  const configExists = configCandidates(context.home).some(existsSync)
+  let finished: FinishedInit | undefined
+  const exitCode = await runWithKit(context, 'init', async (kit) => {
+    const setup = configExists ? null : await chooseSetup(context, answer)
+    const init = await runGlobalInit({ home: context.home, kit, setup: setup?.values, configHome: context.configHome })
+    finished = { init, version: kit.version }
+    const settings = await migrateGlobalSettings(context.home, context.cliOnPath())
+    return {
+      notes: [
+        ...configNotes(init.configCreated, globalConfigPath(context.home), setup),
+        globalTargetNote(context.home),
+        ...settings,
+      ],
+      result: init.sync,
+    }
+  })
+  const offers = [sessionHookOffer(context.home), statusLineOfferAt(context.home, '~/', GLOBAL_STATUS_LINE_COMMAND)]
+  return finishInit(context, exitCode, finished, { offers, cli: GLOBAL_CLI, answer })
+}
+
+export const runInitCommand = async (args: string[], context: CommandContext = defaultContext()): Promise<number> => {
+  const parsed = parseInitArgs(args)
+  if (!parsed.ok) return usageError(context, parsed.message)
+  return parsed.global ? initGlobalCommand(context, parsed.answer) : initProjectCommand(context, parsed.answer)
+}
+
+export const run = (args: string[]): Promise<number> => runInitCommand(args)

package/src/sync/init.ts

@@ -0,0 +1,136 @@
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { AGENTS_DIRECTORY, SKILLS_DIRECTORY } from '../claude/paths'
+import { type JackherdConfig, MODEL_ROLE, type ModelRole, parseJackherdConfig, type TerminalAdapter } from '../config'
+import { type RepositoryFacts, withDetected } from '../config/detect'
+import { CONFIG_FILE, CONFIG_SCHEMA_REFERENCE, TOOL_DIRECTORY } from '../config/location'
+import { readRepositoryFacts } from '../config/repository-facts'
+import type { KitSource } from './kit'
+import { moveGlobalLegacyFiles, moveProjectLegacyFiles } from './legacy-files'
+import { assertNotHomeDirectory, assertOwnDirectoriesInProject, createFileExclusively } from './project-fs'
+import type { SetupConfig } from './setup'
+import { syncGlobalWithConfig, syncProjectWithConfig } from './sync'
+import type { SyncResult } from './sync-result'
+
+/** `home` defaults to the real home directory, which is never a project; `facts` to the project root's. */
+export type InitRequest = {
+  projectRoot: string
+  home?: string
+  kit: KitSource
+  facts?: RepositoryFacts
+  /** Written into a new config, so the kit's skills and agents stay apart from the project's own. */
+  skillPrefix?: string
+  /** The languages and the terminal adapter for a new config; the schema's defaults without it. */
+  setup?: SetupConfig
+}
+
+/** `configHome` is `XDG_CONFIG_HOME` as the command read it; undefined for `~/.config`. */
+export type GlobalInitRequest = { home: string; kit: KitSource; setup?: SetupConfig; configHome?: string }
+
+/** `skillPrefix` and `terminalAdapter` are the config's as read, so an existing config yields its own names. */
+export type InitResult = {
+  configCreated: boolean
+  sync: SyncResult
+  skillPrefix: string
+  terminalAdapter: TerminalAdapter
+}
+
+// TODO: default model per role for a fresh project; the role list
+// itself is still a draft in config/schema.ts.
+export const DEFAULT_MODELS: Record<ModelRole, string> = {
+  [MODEL_ROLE.plan]: 'claude-opus-5-5',
+  [MODEL_ROLE.implement]: 'claude-sonnet-5-5',
+  [MODEL_ROLE.review]: 'claude-sonnet-5-5',
+  [MODEL_ROLE.explore]: 'claude-sonnet-5-5',
+  [MODEL_ROLE.orchestrate]: 'claude-opus-5-5',
+}
+
+/** What a global install, and a project that already has skills of kit names, puts before every kit name. */
+export const DEFAULT_SKILL_PREFIX = 'jh-'
+
+const SKILL_ENTRY = new RegExp(`^${SKILLS_DIRECTORY}/([^/]+)/SKILL\\.md$`)
+const AGENT_ENTRY = new RegExp(`^${AGENTS_DIRECTORY}/([^/]+)\\.md$`)
+
+/**
+ * The kit's skills (`/name`) and agents (`name agent`) the project's `.claude/` already holds under the same
+ * name; `exists` answers for a path relative to `.claude/`.
+ */
+export const collidingNames = (kit: KitSource, exists: (path: string) => boolean): string[] =>
+  kit.files.flatMap(({ path }) => {
+    const skill = SKILL_ENTRY.exec(path)
+    const agent = AGENT_ENTRY.exec(path)
+    if (!exists(path)) return []
+    if (skill) return [`/${skill[1]}`]
+    return agent ? [`${agent[1]} agent`] : []
+  })
+
+/**
+ * The default config with every default spelled out, so the project sees what it can change; commands, lock file
+ * and base branch as detected in the project.
+ */
+const defaultConfigText = (facts: RepositoryFacts, skillPrefix: string, setup: SetupConfig | undefined): string => {
+  const config = parseJackherdConfig(withDetected({ models: DEFAULT_MODELS, skillPrefix, ...setup }, facts).raw)
+  return `${JSON.stringify({ $schema: CONFIG_SCHEMA_REFERENCE, ...config }, null, 2)}\n`
+}
+
+/** What each repository decides for itself; a global config that spelled them out would set them for all. */
+const withoutRepositoryValues = ({ baseBranch: _base, commands: _commands, lanes, ...rest }: JackherdConfig) => {
+  const { lockFile: _lockFile, ...ownLanes } = lanes
+  return { ...rest, lanes: ownLanes }
+}
+
+/**
+ * The global default config: no `$schema`, since `~/.jackherd` has no `node_modules` beside it, and no commands,
+ * lock file or base branch, so every repository gets its own detected ones.
+ */
+const defaultGlobalConfigText = (setup: SetupConfig | undefined): string => {
+  const config = parseJackherdConfig({ models: DEFAULT_MODELS, skillPrefix: DEFAULT_SKILL_PREFIX, ...setup })
+  return `${JSON.stringify(withoutRepositoryValues(config), null, 2)}\n`
+}
+
+/** Init moves the old files before it writes a config, so the sync after it has nothing to name: the lines come first. */
+const withMoves = (result: SyncResult, moved: string[]): SyncResult => ({
+  ...result,
+  notes: [...moved, ...(result.notes ?? [])],
+})
+
+const initResult = (configCreated: boolean, sync: SyncResult, config: JackherdConfig): InitResult => ({
+  configCreated,
+  sync,
+  skillPrefix: config.skillPrefix,
+  terminalAdapter: config.terminal.adapter,
+})
+
+/** Writes `.jackherd/config.json` with the setup and defaults unless one exists, then runs sync. */
+export const runInit = async ({
+  projectRoot,
+  home = homedir(),
+  kit,
+  facts = readRepositoryFacts(projectRoot),
+  skillPrefix = '',
+  setup,
+}: InitRequest): Promise<InitResult> => {
+  await assertNotHomeDirectory(projectRoot, home)
+  await assertOwnDirectoriesInProject(projectRoot)
+  const moved = await moveProjectLegacyFiles(projectRoot)
+  const configCreated = await createFileExclusively(
+    join(projectRoot, TOOL_DIRECTORY),
+    CONFIG_FILE,
+    defaultConfigText(facts, skillPrefix, setup),
+  )
+  const { result, config } = await syncProjectWithConfig({ projectRoot, home, kit, accept: [], facts })
+  return initResult(configCreated, withMoves(result, moved), config)
+}
+
+/** Writes `~/.jackherd/config.json` with the setup, defaults and the `jh-` prefix unless one exists, then runs the global sync. */
+export const runGlobalInit = async ({ home, kit, setup, configHome }: GlobalInitRequest): Promise<InitResult> => {
+  await assertOwnDirectoriesInProject(home)
+  const moved = await moveGlobalLegacyFiles(home, configHome)
+  const configCreated = await createFileExclusively(
+    join(home, TOOL_DIRECTORY),
+    CONFIG_FILE,
+    defaultGlobalConfigText(setup),
+  )
+  const { result, config } = await syncGlobalWithConfig({ home, kit, accept: [], configHome })
+  return initResult(configCreated, withMoves(result, moved), config)
+}

package/src/sync/kit-hooks.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod'
+import { errorMessage } from './error-message'
+import { HOOK_NAME, type HookDefinition, hookDefinitionSchema } from './settings-hooks'
+
+export type KitHooksResult = { ok: true; hooks: Record<string, HookDefinition> } | { ok: false; reason: string }
+
+const kitHooksSchema = z.record(z.string().regex(HOOK_NAME), hookDefinitionSchema)
+
+/** Parses the rendered `kit/hooks.json`: `{ "<name>": { event, matcher?, handler } }`. */
+export const parseKitHooks = (rendered: string): KitHooksResult => {
+  try {
+    const parsed = kitHooksSchema.safeParse(JSON.parse(rendered))
+    if (!parsed.success) return { ok: false, reason: z.prettifyError(parsed.error) }
+    return { ok: true, hooks: parsed.data }
+  } catch (err) {
+    return { ok: false, reason: errorMessage(err) }
+  }
+}

package/src/sync/kit-path.ts

@@ -0,0 +1,77 @@
+import { posix } from 'node:path'
+import { CLAUDE_DIRECTORY, LOCAL_SETTINGS_FILE, SETTINGS_FILE } from '../claude/paths'
+import { TOOL_DIRECTORY } from '../config/location'
+
+export type KitPathResult = { ok: true; path: string } | { ok: false; reason: string }
+
+const KIT_NEW_SUFFIX = '.kit-new'
+
+/** The names config and lock had in `.claude/` before they moved to `.jackherd/`; no kit file may claim them. */
+const LEGACY_CONFIG_FILE = 'agent-kit.json'
+const LEGACY_MANIFEST_FILE = 'agent-kit.lock.json'
+
+/** Files under `.claude/` sync owns itself or must never treat as a kit file; compared lower-case. */
+const RESERVED_PATHS: readonly string[] = [LEGACY_CONFIG_FILE, LEGACY_MANIFEST_FILE, SETTINGS_FILE, LOCAL_SETTINGS_FILE]
+
+/**
+ * Plain ASCII names that do not start or end with a dot. Anything else (a dot-directory such as
+ * `.git`, Unicode a case-insensitive file system folds onto a reserved name, a trailing dot or
+ * space Windows drops, `:` streams, `~` short names) could alias another file.
+ */
+const SEGMENT = /^[A-Za-z0-9_][A-Za-z0-9._-]*$/
+
+const ABSOLUTE = /^(\/|[A-Za-z]:)/
+
+const reject = (reason: string): KitPathResult => ({ ok: false, reason })
+
+const isReserved = (path: string): boolean => {
+  const lowerPath = path.toLowerCase()
+  return RESERVED_PATHS.includes(lowerPath) || lowerPath.endsWith(KIT_NEW_SUFFIX)
+}
+
+/** The only lock paths a global install may own in the tool directory; its config, lock and state stay out of reach. */
+const TOOL_ROOT_FILES = /^_jackherd\/(rules\/.+|statusline\.sh)$/
+
+const isForbiddenToolPath = (path: string): boolean =>
+  path.toLowerCase().startsWith('_jackherd/') && !TOOL_ROOT_FILES.test(path)
+
+const isPlainSegment = (segment: string): boolean => SEGMENT.test(segment) && !segment.endsWith('.')
+
+/**
+ * Validates a path relative to `.claude/` that comes from the kit, the manifest or `--accept`.
+ * A leading `.claude/` is stripped so a path can be passed the way the report prints it. Anything
+ * that could resolve outside `.claude/` is refused; symlinks are checked where the disk is read.
+ * Reserved names are compared case-insensitively, since macOS and Windows file systems are.
+ */
+export const parseKitPath = (raw: string): KitPathResult => {
+  if (raw.includes('\0')) return reject('contains NUL')
+  if (raw.includes('\\')) return reject('contains a backslash')
+  if (ABSOLUTE.test(raw)) return reject('is absolute')
+  if (raw.split('/').includes('..')) return reject('leaves .claude/')
+  const segments = posix.normalize(raw).split('/')
+  const relative = segments[0] === CLAUDE_DIRECTORY ? segments.slice(1) : segments
+  const path = relative.filter((segment) => segment !== '.' && segment !== '').join('/')
+  if (path === '') return reject('is empty')
+  if (!path.split('/').every(isPlainSegment)) return reject(`has a segment that is not a plain file name: ${path}`)
+  if (isReserved(path)) return reject(`is reserved: ${path}`)
+  if (isForbiddenToolPath(path)) return reject(`is reserved: ${path}`)
+  return { ok: true, path }
+}
+
+/**
+ * A lock path below this segment lives in the tool directory (`~/.jackherd/`), not in `.claude/`: the rules and the
+ * status line of a global install, which Claude Code must not load on its own. Only a global sync writes them.
+ */
+export const TOOL_ROOT = '_jackherd'
+
+/** The path inside the tool directory for a lock path below `TOOL_ROOT`, else null. */
+export const toolRootPath = (path: string): string | null =>
+  path.startsWith(`${TOOL_ROOT}/`) ? path.slice(TOOL_ROOT.length + 1) : null
+
+/** A lock path as the user finds it on disk: `~/.jackherd/…` for the tool root, else `.claude/…`. */
+export const shownPath = (path: string): string => {
+  const inTool = toolRootPath(path)
+  return inTool === null ? `${CLAUDE_DIRECTORY}/${path}` : `~/${TOOL_DIRECTORY}/${inTool}`
+}
+
+export const kitNewPath = (path: string): string => `${path}${KIT_NEW_SUFFIX}`

package/src/sync/kit-source.ts

@@ -0,0 +1,169 @@
+import { existsSync } from 'node:fs'
+import { lstat, readdir, readFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { z } from 'zod'
+import { PACKAGE_NAME } from '../version/release'
+import type { KitFile, KitSource } from './kit'
+import { parseKitPath } from './kit-path'
+
+export type KitLocation = { kitDirectory: string; version: string; packageRoot: string }
+
+/** What one kit module ships: its files and the text of its `hooks.json`, if any. */
+type KitModule = { name: string; files: KitFile[]; hooksText: string | undefined }
+
+const MODULE_HOOKS_FILE = 'hooks.json'
+
+/** A test beside a kit script runs in this package and never ships into a project. */
+const TEST_FILE = /\.test\.ts$/
+
+/** A module directory name: plain ASCII, no leading dot, so `.cache` or `.git` never ship. */
+const MODULE_NAME = /^[A-Za-z0-9_][A-Za-z0-9_-]*$/
+
+const ANY_EXECUTE_BIT = 0o111
+
+const packageJsonSchema = z.looseObject({ name: z.string().optional(), version: z.string().min(1).optional() })
+
+const hookObjectSchema = z.record(z.string(), z.unknown())
+
+const parseJsonOr = (text: string, failure: Error): unknown => {
+  try {
+    return JSON.parse(text)
+  } catch {
+    throw failure
+  }
+}
+
+const assertUniquePaths = (modules: KitModule[]): void => {
+  const owner = new Map<string, string>()
+  for (const { name, files } of modules) {
+    for (const { path } of files) {
+      const other = owner.get(path)
+      if (other) throw new Error(`Kit file ${path} ships in modules ${other} and ${name}`)
+      owner.set(path, name)
+    }
+  }
+}
+
+const parseModuleHooks = ({ name, hooksText }: KitModule): Record<string, unknown> => {
+  if (hooksText === undefined) return {}
+  const notAnObject = new Error(`Kit ${name}/${MODULE_HOOKS_FILE} is not a JSON object of hooks`)
+  const parsed = hookObjectSchema.safeParse(parseJsonOr(hooksText, notAnObject))
+  if (!parsed.success) throw notAnObject
+  return parsed.data
+}
+
+/**
+ * Merges the modules' hooks into one unrendered template. Placeholders sit inside JSON strings,
+ * so the text parses before rendering; a hook name shipped twice is an error.
+ */
+const mergeModuleHooks = (modules: KitModule[]): string | undefined => {
+  const merged: Record<string, unknown> = {}
+  for (const module of modules) {
+    for (const [hookName, hook] of Object.entries(parseModuleHooks(module))) {
+      if (Object.hasOwn(merged, hookName)) throw new Error(`Kit hook ${hookName} ships in more than one module`)
+      merged[hookName] = hook
+    }
+  }
+  return Object.keys(merged).length > 0 ? JSON.stringify(merged, null, 2) : undefined
+}
+
+const listFiles = async (directory: string, prefix = ''): Promise<string[]> => {
+  const entries = await readdir(join(directory, prefix), { withFileTypes: true })
+  const nested = await Promise.all(
+    entries.map(async (entry) => {
+      const relative = prefix ? `${prefix}/${entry.name}` : entry.name
+      if (entry.isDirectory()) return listFiles(directory, relative)
+      if (entry.isFile()) return [relative]
+      throw new Error(`Kit entry ${relative} is neither a file nor a directory`)
+    }),
+  )
+  return nested.flat()
+}
+
+const readKitFile = async (moduleDirectory: string, relative: string): Promise<KitFile> => {
+  const parsed = parseKitPath(relative)
+  if (!parsed.ok || parsed.path !== relative) {
+    throw new Error(`Kit file ${relative} ${parsed.ok ? 'is not normalised' : parsed.reason}`)
+  }
+  const absolute = join(moduleDirectory, relative)
+  const [template, entry] = await Promise.all([readFile(absolute, 'utf8'), lstat(absolute)])
+  return { path: relative, template, executable: (entry.mode & ANY_EXECUTE_BIT) !== 0 }
+}
+
+const readModule = async (kitDirectory: string, name: string): Promise<KitModule> => {
+  const moduleDirectory = join(kitDirectory, name)
+  const relatives = (await listFiles(moduleDirectory)).sort()
+  const filePaths = relatives.filter((relative) => relative !== MODULE_HOOKS_FILE && !TEST_FILE.test(relative))
+  const files = await Promise.all(filePaths.map((relative) => readKitFile(moduleDirectory, relative)))
+  const hooksText = relatives.includes(MODULE_HOOKS_FILE)
+    ? await readFile(join(moduleDirectory, MODULE_HOOKS_FILE), 'utf8')
+    : undefined
+  return { name, files, hooksText }
+}
+
+const listModuleNames = async (kitDirectory: string): Promise<string[]> => {
+  const entries = await readdir(kitDirectory, { withFileTypes: true })
+  const symlinked = entries.find((entry) => entry.isSymbolicLink())
+  if (symlinked) throw new Error(`Kit module ${symlinked.name} is a symlink`)
+  const names = entries
+    .filter((entry) => entry.isDirectory())
+    .map(({ name }) => name)
+    .sort()
+  const invalid = names.find((name) => !MODULE_NAME.test(name))
+  if (invalid) throw new Error(`Kit module ${invalid} is not a plain directory name`)
+  if (names.length === 0) throw new Error(`Kit directory ${kitDirectory} holds no modules`)
+  return names
+}
+
+/**
+ * Reads the kit shipped with the package. Every directory under `kit/` is a module that mirrors
+ * `.claude/` (`kit/workflow/skills/plan/SKILL.md` → `.claude/skills/plan/SKILL.md`); a module's
+ * `hooks.json` holds its hooks by name, `{ "<name>": { event, matcher?, handler } }`, and is not
+ * copied, nor is a `*.test.ts`. Files at the kit root, such as a README, belong to no module.
+ *
+ * A missing kit directory, or one without modules, is an error, never an empty kit: an empty kit
+ * would make sync remove every untouched kit file from the project.
+ */
+export const readKitSource = async ({
+  kitDirectory,
+  version,
+}: Pick<KitLocation, 'kitDirectory' | 'version'>): Promise<KitSource> => {
+  if (!existsSync(kitDirectory)) throw new Error(`Kit directory not found: ${kitDirectory}`)
+  const names = await listModuleNames(kitDirectory)
+  const modules = await Promise.all(names.map((name) => readModule(kitDirectory, name)))
+  assertUniquePaths(modules)
+  const files = modules.flatMap((module) => module.files).sort((left, right) => (left.path < right.path ? -1 : 1))
+  return { version, files, hooksTemplate: mergeModuleHooks(modules) }
+}
+
+const readPackageJson = async (path: string) => packageJsonSchema.parse(JSON.parse(await readFile(path, 'utf8')))
+
+const KIT_DIRECTORY = 'kit'
+
+const kitDirectoryIn = (packageRoot: string): string => {
+  const found = join(packageRoot, KIT_DIRECTORY)
+  if (!existsSync(found)) throw new Error(`No kit directory in ${packageRoot} (looked for ${KIT_DIRECTORY})`)
+  return found
+}
+
+/**
+ * Finds the package root by walking up from this module in `src/`, then resolves the `kit/`
+ * directory below it. The repository and the published package both ship `kit/`, so there is one
+ * place to look.
+ */
+export const locateKit = async (from: string = fileURLToPath(import.meta.url)): Promise<KitLocation> => {
+  let directory = dirname(from)
+  while (directory !== dirname(directory)) {
+    const packageJsonPath = join(directory, 'package.json')
+    if (existsSync(packageJsonPath)) {
+      const packageJson = await readPackageJson(packageJsonPath)
+      if (packageJson.name === PACKAGE_NAME) {
+        if (!packageJson.version) throw new Error(`${packageJsonPath} has no version`)
+        return { kitDirectory: kitDirectoryIn(directory), version: packageJson.version, packageRoot: directory }
+      }
+    }
+    directory = dirname(directory)
+  }
+  throw new Error(`Could not find the ${PACKAGE_NAME} package root above ${from}`)
+}

package/src/sync/kit.ts

@@ -0,0 +1,9 @@
+/** A file the kit ships, by its path relative to `.claude/`, still unrendered. */
+export type KitFile = { path: string; template: string; executable: boolean }
+
+export type KitSource = {
+  version: string
+  files: KitFile[]
+  /** The unrendered text of `kit/hooks.json`, if the kit ships hooks. */
+  hooksTemplate: string | undefined
+}