jackherd 0.0.1 → 1.0.1

package/src/sync/legacy-files.ts

@@ -0,0 +1,116 @@
+import { lstat, mkdir, readdir, readFile, rename, rm, rmdir, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import {
+  LEGACY_UPDATE_STATE_PATH,
+  legacyPublicContentPath,
+  legacyRenames,
+  PROJECT_LEGACY_FILES,
+  PUBLIC_CONTENT_PATH,
+  RENAMED_NOTICE,
+  type Rename,
+  withCurrentSchemaReference,
+} from '../config/legacy-names'
+import { PROJECT_CONFIG_PATH } from '../config/location'
+
+/** Where earlier global installs put rules and status line below `~/.claude/`: before the rename, and 0.28 on main. */
+const LEGACY_GLOBAL_DIRECTORIES = ['agent-kit', 'jackherd']
+
+const isThere = async (path: string): Promise<boolean> => {
+  try {
+    await lstat(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+const presentPaths = async (root: string, pairs: readonly Rename[]): Promise<string[]> => {
+  const paths = pairs.flatMap(({ from, to }) => [from, to])
+  const found = await Promise.all(paths.map(async (path) => ((await isThere(join(root, path))) ? [path] : [])))
+  return found.flat()
+}
+
+/** A moved regular config gets the new `$schema`; a link is moved as it is and never read through. */
+const updateSchemaReference = async (path: string): Promise<void> => {
+  if (!(await lstat(path)).isFile()) return
+  const text = await readFile(path, 'utf8')
+  const next = withCurrentSchemaReference(text)
+  if (next !== text) await writeFile(path, next)
+}
+
+const moveOne = async (root: string, { from, to }: Rename): Promise<string> => {
+  await mkdir(dirname(join(root, to)), { recursive: true })
+  await rename(join(root, from), join(root, to))
+  if (to === PROJECT_CONFIG_PATH) await updateSchemaReference(join(root, to))
+  return `Moved ${from} to ${to}.`
+}
+
+const shadowedNote = ({ from, to }: Rename): string =>
+  `${from} stays: ${to} is there and wins. Delete the old file once nothing reads it.`
+
+/**
+ * Moves the old files of `pairs` below `root` to their new names before anything reads them, and returns a line
+ * per move or per old file a new one shadows. A file is renamed, never copied, so a link stays a link.
+ */
+export const moveLegacyFiles = async (root: string, pairs: readonly Rename[]): Promise<string[]> => {
+  const plan = legacyRenames(pairs, await presentPaths(root, pairs))
+  const moved: string[] = []
+  for (const rename of plan.renames) moved.push(await moveOne(root, rename))
+  const notice = moved.length > 0 ? [RENAMED_NOTICE] : []
+  return [...notice, ...moved, ...plan.shadowed.map(shadowedNote)]
+}
+
+/** The project's old config and lock. */
+export const moveProjectLegacyFiles = (projectRoot: string): Promise<string[]> =>
+  moveLegacyFiles(projectRoot, PROJECT_LEGACY_FILES)
+
+/** The old public-content facts, below `XDG_CONFIG_HOME` as the reader finds them, move into `~/.jackherd/`. */
+const movePublicContent = async (home: string, configHome: string | undefined): Promise<string[]> => {
+  const from = legacyPublicContentPath(home, configHome)
+  const to = join(home, PUBLIC_CONTENT_PATH)
+  if (!(await isThere(from))) return []
+  if (await isThere(to)) return [shadowedNote({ from, to: PUBLIC_CONTENT_PATH })]
+  await mkdir(dirname(to), { recursive: true })
+  try {
+    await rename(from, to)
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'EXDEV') throw err
+    return [`${from} stays where it is (another file system); it is still read there.`]
+  }
+  return [`Moved ${from} to ${PUBLIC_CONTENT_PATH}.`]
+}
+
+/** The old update check is deleted, not read; only a file or a link at its path, never a directory. */
+const removeLegacyUpdateState = async (home: string): Promise<void> => {
+  const path = join(home, LEGACY_UPDATE_STATE_PATH)
+  const entry = await lstat(path).catch(() => null)
+  if (entry && (entry.isFile() || entry.isSymbolicLink())) await rm(path)
+}
+
+/**
+ * The home directory's old config, lock and public-content facts move; the old update check goes. `configHome` is
+ * `XDG_CONFIG_HOME` as the command read it, undefined for `~/.config`; never read from the environment here, so a
+ * test home cannot reach the real one.
+ */
+export const moveGlobalLegacyFiles = async (home: string, configHome: string | undefined): Promise<string[]> => {
+  const notes = await moveLegacyFiles(home, PROJECT_LEGACY_FILES)
+  const publicContent = await movePublicContent(home, configHome)
+  await removeLegacyUpdateState(home)
+  return [...notes, ...publicContent]
+}
+
+/** Removes `directory` and the directories below it that hold nothing; a file or a link keeps its directories. */
+const removeEmptyDirectories = async (directory: string): Promise<void> => {
+  const entry = await lstat(directory).catch(() => null)
+  if (!entry?.isDirectory()) return
+  for (const name of await readdir(directory)) await removeEmptyDirectories(join(directory, name))
+  if ((await readdir(directory)).length === 0) await rmdir(directory)
+}
+
+/**
+ * After a global sync removed the kit's files from the old places in `~/.claude/`, the directories they leave empty
+ * go too; a file of the user's own keeps its directory and everything above it.
+ */
+export const removeEmptyLegacyDirectories = async (claudeDirectory: string): Promise<void> => {
+  for (const name of LEGACY_GLOBAL_DIRECTORIES) await removeEmptyDirectories(join(claudeDirectory, name))
+}

package/src/sync/manifest.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod'
+import { parseKitPath } from './kit-path'
+import { HOOK_NAME, hookDefinitionSchema } from './settings-hooks'
+
+const sha256 = z.string().regex(/^[0-9a-f]{64}$/)
+
+/** Only the normalised form is accepted: a manifest path must be exactly what sync itself wrote. */
+const kitPath = z.string().refine((raw) => {
+  const parsed = parseKitPath(raw)
+  return parsed.ok && parsed.path === raw
+}, 'not a path inside .claude/')
+
+// TODO(security audit M2): the manifest alone authorises a
+// removal. A hand-edited entry whose checksum matches a checked-in file or hook outside the kit
+// makes sync remove it. Open decision: ship a history of every kit checksum and remove only what
+// the kit once wrote, or require --accept for removals.
+const manifestSchema = z.strictObject({
+  kitVersion: z.string().min(1),
+  files: z.record(kitPath, z.strictObject({ base: sha256.optional(), pending: sha256.optional() })),
+  hooks: z.record(
+    z.string().regex(HOOK_NAME),
+    z.strictObject({ base: hookDefinitionSchema, pending: sha256.optional() }),
+  ),
+  /** Checksum of the `settings.json.kit-new` sync wrote last. */
+  settingsKitNew: sha256.optional(),
+})
+
+export type Manifest = z.infer<typeof manifestSchema>
+
+export type ManifestResult = { ok: true; manifest: Manifest } | { ok: false; reason: string }
+
+export const EMPTY_MANIFEST: Manifest = { kitVersion: '0.0.0', files: {}, hooks: {} }
+
+export const parseManifest = (raw: unknown): ManifestResult => {
+  const parsed = manifestSchema.safeParse(raw)
+  if (!parsed.success) return { ok: false, reason: z.prettifyError(parsed.error) }
+  return { ok: true, manifest: parsed.data }
+}
+
+const sortedRecord = <T>(record: Record<string, T>): Record<string, T> =>
+  Object.fromEntries(Object.entries(record).sort(([left], [right]) => (left < right ? -1 : 1)))
+
+export const serializeManifest = (manifest: Manifest): string =>
+  `${JSON.stringify({ ...manifest, files: sortedRecord(manifest.files), hooks: sortedRecord(manifest.hooks) }, null, 2)}\n`

package/src/sync/next-steps.ts

@@ -0,0 +1,42 @@
+import { TERMINAL_ADAPTER, type TerminalAdapter } from '../config'
+import { PACKAGE_NAME } from '../version/release'
+import type { ToolPresence } from './tools'
+
+export type NextStepsRequest = {
+  /** The config's prefix: empty in a project without one, `kit-` in a global install. */
+  skillPrefix: string
+  adapter: TerminalAdapter
+  tools: ToolPresence
+  /** The kit's version, which pins the docs link. */
+  version: string
+  /** How the user runs the CLI here: `jh` after a global install, `bunx jackherd` in a project. */
+  cli: string
+}
+
+const herdrLine = (orchestrate: string, adapter: TerminalAdapter, tools: ToolPresence): string => {
+  const usesHerdr = adapter === TERMINAL_ADAPTER.herdr
+  if (tools.herdr && usesHerdr) return `herdr: ready; ${orchestrate} opens one workspace per lane.`
+  if (tools.herdr) return 'herdr: found, but lanes are off; set terminal.adapter to "herdr" in the config.'
+  if (!tools.herdrInstallable)
+    return 'herdr: not available on this system; every skill but parallel lanes works without it.'
+  if (usesHerdr) return 'herdr: not found, but the config uses it; install herdr.'
+  return 'herdr: not found; for lanes, install herdr and set terminal.adapter to "herdr" in the config.'
+}
+
+const ghLine = (orchestrate: string, { gh }: ToolPresence): string =>
+  gh ? 'gh: found.' : `gh: not found; install it to let ${orchestrate} follow pull requests.`
+
+/** What to do after `init`, eight lines: the skills by their installed names, what is ready, where to read on. */
+export const nextSteps = ({ skillPrefix, adapter, tools, version, cli }: NextStepsRequest): string[] => {
+  const orchestrate = `/${skillPrefix}orchestrate`
+  return [
+    `/${skillPrefix}start: check your setup and begin the first plan.`,
+    `/${skillPrefix}plan: write a plan with phases.`,
+    `/${skillPrefix}implement: build one phase of a plan.`,
+    `${orchestrate}: run a board's phases in parallel lanes.`,
+    herdrLine(orchestrate, adapter, tools),
+    ghLine(orchestrate, tools),
+    `${cli} plans: see every plan and lane in one view.`,
+    `Docs: https://www.npmjs.com/package/${PACKAGE_NAME}/v/${version}#documentation`,
+  ]
+}

package/src/sync/plan-file.ts

@@ -0,0 +1,154 @@
+/**
+ * `base` is the checksum of the kit version the local file is built on: what sync last wrote, or
+ * the version the user resolved a conflict against. `pending` is the checksum of the kit version
+ * sync wrote to `<file>.kit-new` and that the user has not dealt with yet. A foreign file at a kit
+ * path has a `pending` but no `base`.
+ */
+export type FileEntry = { base?: string; pending?: string }
+
+export type LocalState = { kind: 'missing' } | { kind: 'file'; checksum: string } | { kind: 'notFile' }
+
+export const FILE_MODE = { regular: 'regular', executable: 'executable' } as const
+
+export type FileMode = (typeof FILE_MODE)[keyof typeof FILE_MODE]
+
+export type RenderedFile = { content: string; checksum: string; mode: FileMode }
+
+export type FileInput = {
+  path: string
+  /** `null` when the kit no longer ships the file. */
+  rendered: RenderedFile | null
+  entry: FileEntry | undefined
+  local: LocalState
+  kitNew: LocalState
+  accept: boolean
+}
+
+export type FileTarget = 'file' | 'kitNew'
+
+export type FileEffect =
+  | { kind: 'write'; target: FileTarget; content: string; mode: FileMode }
+  | { kind: 'remove'; target: FileTarget }
+
+export const FILE_OUTCOME = {
+  created: 'created',
+  updated: 'updated',
+  unchanged: 'unchanged',
+  removed: 'removed',
+  kept: 'kept',
+  untracked: 'untracked',
+  deselected: 'deselected',
+  dropped: 'dropped',
+  resolved: 'resolved',
+  conflict: 'conflict',
+  blocked: 'blocked',
+  accepted: 'accepted',
+  notAcceptable: 'notAcceptable',
+} as const
+
+export type FileOutcome = (typeof FILE_OUTCOME)[keyof typeof FILE_OUTCOME]
+
+export type FilePlan = { path: string; outcome: FileOutcome; effects: FileEffect[]; entry: FileEntry | undefined }
+
+const checksumOf = (state: LocalState): string | undefined => (state.kind === 'file' ? state.checksum : undefined)
+
+/** Only a `.kit-new` that still holds exactly what sync wrote there may be replaced or removed. */
+const isOwnKitNew = (input: FileInput): boolean =>
+  input.entry?.pending !== undefined && checksumOf(input.kitNew) === input.entry.pending
+
+const cleanUpKitNew = (input: FileInput): FileEffect[] =>
+  isOwnKitNew(input) ? [{ kind: 'remove', target: 'kitNew' }] : []
+
+const plan = (
+  input: FileInput,
+  outcome: FileOutcome,
+  effects: FileEffect[],
+  entry: FileEntry | undefined,
+): FilePlan => ({
+  path: input.path,
+  outcome,
+  effects,
+  entry,
+})
+
+const leaveAlone = (input: FileInput, outcome: FileOutcome): FilePlan => plan(input, outcome, [], input.entry)
+
+const planKitDropped = (input: FileInput): FilePlan => {
+  if (input.local.kind === 'missing' || input.entry?.base === undefined) {
+    return plan(input, FILE_OUTCOME.dropped, cleanUpKitNew(input), undefined)
+  }
+  if (checksumOf(input.local) === input.entry.base) {
+    return plan(input, FILE_OUTCOME.removed, [{ kind: 'remove', target: 'file' }, ...cleanUpKitNew(input)], undefined)
+  }
+  return plan(input, FILE_OUTCOME.untracked, [], undefined)
+}
+
+const planConflict = (input: FileInput, rendered: RenderedFile): FilePlan => {
+  const entry = { ...input.entry, pending: rendered.checksum }
+  if (checksumOf(input.kitNew) === rendered.checksum) {
+    return plan(input, FILE_OUTCOME.conflict, [], entry)
+  }
+  if (input.kitNew.kind === 'missing' || isOwnKitNew(input)) {
+    return plan(
+      input,
+      FILE_OUTCOME.conflict,
+      [{ kind: 'write', target: 'kitNew', content: rendered.content, mode: FILE_MODE.regular }],
+      entry,
+    )
+  }
+  return leaveAlone(input, FILE_OUTCOME.blocked)
+}
+
+const planLocallyModified = (input: FileInput, rendered: RenderedFile): FilePlan => {
+  const { entry } = input
+  if (entry?.base === rendered.checksum) return leaveAlone(input, FILE_OUTCOME.kept)
+  if (entry?.pending === rendered.checksum && input.kitNew.kind === 'missing') {
+    return plan(input, FILE_OUTCOME.resolved, [], { base: rendered.checksum })
+  }
+  return planConflict(input, rendered)
+}
+
+const planKitShipped = (input: FileInput, rendered: RenderedFile): FilePlan => {
+  const write: FileEffect = { kind: 'write', target: 'file', content: rendered.content, mode: rendered.mode }
+  const local = checksumOf(input.local)
+  const base = input.entry?.base
+  if (input.local.kind === 'missing') {
+    if (input.entry) return leaveAlone(input, FILE_OUTCOME.deselected)
+    return plan(input, FILE_OUTCOME.created, [write], { base: rendered.checksum })
+  }
+  if (local === rendered.checksum) {
+    return plan(input, FILE_OUTCOME.unchanged, cleanUpKitNew(input), { base: rendered.checksum })
+  }
+  if (base !== undefined && local === base) {
+    return plan(input, FILE_OUTCOME.updated, [write, ...cleanUpKitNew(input)], { base: rendered.checksum })
+  }
+  return planLocallyModified(input, rendered)
+}
+
+const ACCEPTABLE: readonly FileOutcome[] = [FILE_OUTCOME.conflict, FILE_OUTCOME.blocked, FILE_OUTCOME.deselected]
+
+const planAccept = (input: FileInput, rendered: RenderedFile, withoutAccept: FilePlan): FilePlan => {
+  if (!ACCEPTABLE.includes(withoutAccept.outcome)) return leaveAlone(input, FILE_OUTCOME.notAcceptable)
+  return plan(
+    input,
+    FILE_OUTCOME.accepted,
+    [{ kind: 'write', target: 'file', content: rendered.content, mode: rendered.mode }, ...cleanUpKitNew(input)],
+    { base: rendered.checksum },
+  )
+}
+
+/**
+ * Decides what sync does with one kit path. Pure: the caller reads the disk, applies the effects
+ * and stores the returned manifest entry (`undefined` = forget the path). A local change is never
+ * overwritten or removed unless `accept` is set for this path.
+ */
+export const planFile = (input: FileInput): FilePlan => {
+  if (input.local.kind === 'notFile') return leaveAlone(input, FILE_OUTCOME.blocked)
+  const { rendered } = input
+  if (rendered === null) {
+    const dropped = planKitDropped(input)
+    return input.accept ? leaveAlone(input, FILE_OUTCOME.notAcceptable) : dropped
+  }
+  const withoutAccept = planKitShipped(input, rendered)
+  return input.accept ? planAccept(input, rendered, withoutAccept) : withoutAccept
+}

package/src/sync/plan-hooks.ts

@@ -0,0 +1,165 @@
+import { canonicalJson, checksum } from './checksum'
+import type { LocalState } from './plan-file'
+import { addHook, containsHook, type HookDefinition, hookKey, removeHook, type Settings } from './settings-hooks'
+
+/**
+ * `base` is the kit hook sync last put into the settings (stored whole, so it can be found and
+ * removed again); `pending` is the key of a newer kit version proposed in `settings.json.kit-new`.
+ */
+export type HookEntry = { base: HookDefinition; pending?: string }
+
+export type HooksInput = {
+  /** Kit hooks by their name in the kit. */
+  kit: Record<string, HookDefinition>
+  entries: Record<string, HookEntry>
+  settings: Settings
+  /** State of `.claude/settings.json.kit-new`. */
+  kitNew: LocalState
+  /** Checksum of the `settings.json.kit-new` sync wrote last, if it wrote one. */
+  kitNewRecorded: string | undefined
+  accept: boolean
+}
+
+export const HOOK_OUTCOME = {
+  created: 'created',
+  updated: 'updated',
+  unchanged: 'unchanged',
+  removed: 'removed',
+  dropped: 'dropped',
+  deselected: 'deselected',
+  resolved: 'resolved',
+  conflict: 'conflict',
+  blocked: 'blocked',
+  accepted: 'accepted',
+} as const
+
+export type HookOutcome = (typeof HOOK_OUTCOME)[keyof typeof HOOK_OUTCOME]
+
+export type KitNewEffect = { kind: 'none' } | { kind: 'write'; content: string } | { kind: 'remove' }
+
+export type HooksPlan = {
+  settings: Settings
+  /** False when the settings are semantically the same as before; the file is then not rewritten. */
+  changed: boolean
+  entries: Record<string, HookEntry>
+  outcomes: { name: string; outcome: HookOutcome }[]
+  kitNew: KitNewEffect
+  kitNewRecorded: string | undefined
+  /** `--accept` was given for the settings but no hook was in conflict or deselected. */
+  notAcceptable: boolean
+}
+
+type HookDecision = {
+  name: string
+  outcome: HookOutcome
+  entry: HookEntry | undefined
+  remove?: HookDefinition
+  add?: HookDefinition
+  proposal?: HookDefinition
+}
+
+const decideDropped = (name: string, entry: HookEntry, settings: Settings): HookDecision =>
+  containsHook(settings, entry.base)
+    ? { name, outcome: HOOK_OUTCOME.removed, entry: undefined, remove: entry.base }
+    : { name, outcome: HOOK_OUTCOME.dropped, entry: undefined }
+
+const decideMissingBase = (name: string, kit: HookDefinition, entry: HookEntry, input: HooksInput): HookDecision => {
+  const kitKey = hookKey(kit)
+  if (kitKey === hookKey(entry.base)) return { name, outcome: HOOK_OUTCOME.deselected, entry }
+  if (entry.pending === kitKey && input.kitNew.kind === 'missing') {
+    return { name, outcome: HOOK_OUTCOME.resolved, entry: { base: kit } }
+  }
+  return { name, outcome: HOOK_OUTCOME.conflict, entry, proposal: kit }
+}
+
+const decideShipped = (name: string, kit: HookDefinition, input: HooksInput): HookDecision => {
+  const entry = input.entries[name]
+  if (containsHook(input.settings, kit)) return { name, outcome: HOOK_OUTCOME.unchanged, entry: { base: kit } }
+  if (!entry) return { name, outcome: HOOK_OUTCOME.created, entry: { base: kit }, add: kit }
+  if (containsHook(input.settings, entry.base)) {
+    return { name, outcome: HOOK_OUTCOME.updated, entry: { base: kit }, remove: entry.base, add: kit }
+  }
+  return decideMissingBase(name, kit, entry, input)
+}
+
+const decide = (name: string, input: HooksInput): HookDecision => {
+  const kit = input.kit[name]
+  if (kit) return decideShipped(name, kit, input)
+  return decideDropped(name, input.entries[name], input.settings)
+}
+
+const ACCEPTABLE: readonly HookOutcome[] = [HOOK_OUTCOME.conflict, HOOK_OUTCOME.deselected]
+
+const applyAccept = (decision: HookDecision, input: HooksInput): HookDecision => {
+  const kit = input.kit[decision.name]
+  if (!input.accept || !kit || !ACCEPTABLE.includes(decision.outcome)) return decision
+  return { name: decision.name, outcome: HOOK_OUTCOME.accepted, entry: { base: kit }, add: kit }
+}
+
+const proposalContent = (proposals: HookDefinition[]): string =>
+  `${JSON.stringify(proposals.reduce<Settings>(addHook, {}), null, 2)}\n`
+
+const isOwnKitNew = (input: HooksInput): boolean =>
+  input.kitNewRecorded !== undefined && input.kitNew.kind === 'file' && input.kitNew.checksum === input.kitNewRecorded
+
+const planWithoutProposal = (input: HooksInput): Pick<HooksPlan, 'kitNew' | 'kitNewRecorded'> => ({
+  kitNew: isOwnKitNew(input) ? { kind: 'remove' } : { kind: 'none' },
+  kitNewRecorded: undefined,
+})
+
+const planProposal = (
+  input: HooksInput,
+  proposals: HookDefinition[],
+): Pick<HooksPlan, 'kitNew' | 'kitNewRecorded'> & { written: boolean } => {
+  const content = proposalContent(proposals)
+  const contentChecksum = checksum(content)
+  if (input.kitNew.kind === 'file' && input.kitNew.checksum === contentChecksum) {
+    return { kitNew: { kind: 'none' }, kitNewRecorded: contentChecksum, written: true }
+  }
+  if (input.kitNew.kind === 'missing' || isOwnKitNew(input)) {
+    return { kitNew: { kind: 'write', content }, kitNewRecorded: contentChecksum, written: true }
+  }
+  return { kitNew: { kind: 'none' }, kitNewRecorded: input.kitNewRecorded, written: false }
+}
+
+/** A conflict counts only once its proposal is on disk; otherwise it is blocked and nothing is recorded. */
+const settleConflict = (decision: HookDecision, written: boolean): HookDecision => {
+  if (decision.outcome !== HOOK_OUTCOME.conflict || !decision.proposal || !decision.entry) return decision
+  if (!written) return { ...decision, outcome: HOOK_OUTCOME.blocked }
+  return { ...decision, entry: { base: decision.entry.base, pending: hookKey(decision.proposal) } }
+}
+
+const applyToSettings = (settings: Settings, decision: HookDecision): Settings => {
+  const withoutOld = decision.remove ? removeHook(settings, decision.remove) : settings
+  return decision.add ? addHook(withoutOld, decision.add) : withoutOld
+}
+
+const settingsChanged = (before: Settings, after: Settings): boolean =>
+  canonicalJson(before.hooks ?? {}) !== canonicalJson(after.hooks ?? {})
+
+/**
+ * Merges the kit hooks into the project settings. Pure. Only handlers recorded in the manifest
+ * (or byte-identical to a kit hook) are ever removed; every other entry keeps its content. A kit
+ * hook the user removed or edited is not put back unless `accept` is set.
+ */
+export const planHooks = (input: HooksInput): HooksPlan => {
+  const names = [...new Set([...Object.keys(input.kit), ...Object.keys(input.entries)])].sort()
+  const decided = names.map((name) => applyAccept(decide(name, input), input))
+  const proposals = decided.flatMap((decision) =>
+    decision.outcome === HOOK_OUTCOME.conflict && decision.proposal ? [decision.proposal] : [],
+  )
+  const proposal =
+    proposals.length > 0 ? planProposal(input, proposals) : { ...planWithoutProposal(input), written: true }
+  const settled = decided.map((decision) => settleConflict(decision, proposal.written))
+  const settings = settled.reduce(applyToSettings, input.settings)
+  const entries = Object.fromEntries(settled.flatMap(({ name, entry }) => (entry ? [[name, entry]] : [])))
+  return {
+    settings,
+    changed: settingsChanged(input.settings, settings),
+    entries,
+    outcomes: settled.map(({ name, outcome }) => ({ name, outcome })),
+    kitNew: proposal.kitNew,
+    kitNewRecorded: proposal.kitNewRecorded,
+    notAcceptable: input.accept && !settled.some(({ outcome }) => outcome === HOOK_OUTCOME.accepted),
+  }
+}

package/src/sync/project-fs.ts

@@ -0,0 +1,132 @@
+import { randomBytes } from 'node:crypto'
+import { lstat, mkdir, readFile, realpath, rename, rm, writeFile } from 'node:fs/promises'
+import { basename, dirname, join, sep } from 'node:path'
+import { CLAUDE_DIRECTORY } from '../claude/paths'
+import { TOOL_DIRECTORY } from '../config/location'
+import { checksum } from './checksum'
+import { FILE_MODE, type FileMode, type LocalState } from './plan-file'
+
+const PERMISSIONS: Record<FileMode, number> = { [FILE_MODE.regular]: 0o644, [FILE_MODE.executable]: 0o755 }
+
+const isMissing = (err: unknown): boolean =>
+  typeof err === 'object' && err !== null && 'code' in err && (err.code === 'ENOENT' || err.code === 'ENOTDIR')
+
+const lstatOrMissing = async (path: string) => {
+  try {
+    return await lstat(path)
+  } catch (err) {
+    if (isMissing(err)) return undefined
+    throw err
+  }
+}
+
+/**
+ * True when every directory between `.claude/` and the path is a real directory or not there yet.
+ * A symlinked directory would let a write inside `.claude/` land anywhere on disk.
+ */
+const hasPlainAncestors = async (directory: string, path: string): Promise<boolean> => {
+  const segments = path.split('/').slice(0, -1)
+  for (let i = 1; i <= segments.length; i++) {
+    const entry = await lstatOrMissing(join(directory, ...segments.slice(0, i)))
+    if (!entry) return true
+    if (!entry.isDirectory()) return false
+  }
+  return true
+}
+
+/** `notFile` for a directory, a symlink, or a path behind a symlinked directory. */
+export const readLocalState = async (directory: string, path: string): Promise<LocalState> => {
+  if (!(await hasPlainAncestors(directory, path))) return { kind: 'notFile' }
+  const target = join(directory, path)
+  const entry = await lstatOrMissing(target)
+  if (!entry) return { kind: 'missing' }
+  if (!entry.isFile()) return { kind: 'notFile' }
+  return { kind: 'file', checksum: checksum(await readFile(target, 'utf8')) }
+}
+
+/** The file's text, `undefined` when it does not exist; throws for anything but a regular file. */
+export const readRegularFile = async (directory: string, path: string): Promise<string | undefined> => {
+  const state = await readLocalState(directory, path)
+  if (state.kind === 'missing') return undefined
+  if (state.kind === 'notFile') throw new Error(`${basename(directory)}/${path} is not a regular file`)
+  return readFile(join(directory, path), 'utf8')
+}
+
+const assertWritable = async (directory: string, path: string): Promise<void> => {
+  if ((await readLocalState(directory, path)).kind === 'notFile') {
+    throw new Error(`Refusing to write ${basename(directory)}/${path}: not a regular file or behind a symlink`)
+  }
+}
+
+/**
+ * Writes through a temporary file and a rename, so a crash never leaves half a file behind.
+ * The target is re-checked right before the write; a symlink or directory there is refused.
+ */
+export const writeFileSafely = async (
+  directory: string,
+  path: string,
+  content: string,
+  mode: FileMode,
+): Promise<void> => {
+  await assertWritable(directory, path)
+  const target = join(directory, path)
+  await mkdir(dirname(target), { recursive: true })
+  const temporary = `${target}.jackherd-${randomBytes(6).toString('hex')}.tmp`
+  try {
+    await writeFile(temporary, content, { flag: 'wx', mode: PERMISSIONS[mode] })
+    await rename(temporary, target)
+  } finally {
+    await rm(temporary, { force: true })
+  }
+}
+
+export const removeFileSafely = async (directory: string, path: string): Promise<void> => {
+  const state = await readLocalState(directory, path)
+  if (state.kind === 'notFile') throw new Error(`Refusing to remove ${basename(directory)}/${path}: not a regular file`)
+  if (state.kind === 'file') await rm(join(directory, path))
+}
+
+/** Creates the file only if nothing is at the path yet; returns false and writes nothing otherwise. */
+export const createFileExclusively = async (directory: string, path: string, content: string): Promise<boolean> => {
+  if ((await readLocalState(directory, path)).kind !== 'missing') return false
+  const target = join(directory, path)
+  await mkdir(dirname(target), { recursive: true })
+  try {
+    await writeFile(target, content, { flag: 'wx', mode: PERMISSIONS[FILE_MODE.regular] })
+    return true
+  } catch (err) {
+    if (typeof err === 'object' && err !== null && 'code' in err && err.code === 'EEXIST') return false
+    throw err
+  }
+}
+
+const assertDirectoryInProject = async (projectRoot: string, name: string): Promise<void> => {
+  const directory = join(projectRoot, name)
+  const entry = await lstatOrMissing(directory)
+  if (!entry?.isSymbolicLink()) return
+  const [target, root] = await Promise.all([realpath(directory), realpath(projectRoot)])
+  if (!target.startsWith(`${root}${sep}`)) {
+    throw new Error(`Refusing to follow ${name}/: it is a symlink to ${target}, outside the project`)
+  }
+}
+
+/**
+ * A symlinked `.claude/` or `.jackherd/` is followed only when it resolves inside the project; otherwise init and
+ * sync would write kit files, hooks and the lock wherever the link points, e.g. the user's global directories.
+ */
+export const assertOwnDirectoriesInProject = async (projectRoot: string): Promise<void> => {
+  await assertDirectoryInProject(projectRoot, CLAUDE_DIRECTORY)
+  await assertDirectoryInProject(projectRoot, TOOL_DIRECTORY)
+}
+
+/**
+ * A project sync or init never runs in the home directory: its `.claude/` is the global install, which a
+ * project run would fill without the prefix, give the kit's hooks in the user's `settings.json`, and a
+ * `.gitignore` in `~`. Compared after resolving symlinks.
+ */
+export const assertNotHomeDirectory = async (projectRoot: string, home: string): Promise<void> => {
+  const [root, homeDirectory] = await Promise.all([realpath(projectRoot), realpath(home)])
+  if (root === homeDirectory) {
+    throw new Error('Refusing to treat the home directory as a project; use `--global` to install into ~/.claude')
+  }
+}