@ljwei-stak/dsh-compositor 0.0.0-stage → 0.1.0

package/.dsh-plugin/client.js

@@ -0,0 +1,3 @@
+// This plugin has no web panel; the export exists so any client bundler that
+// imports "<plugin>/client" gets an empty module instead of an error.
+export {}

package/.dsh-plugin/index.mjs

@@ -0,0 +1,76 @@
+/**
+ * Host plugin of @ljwei-stak/dsh-compositor for DeepSeek Harness.
+ *
+ * Gives Harness agents everything needed to build and edit Compositor
+ * (.comp) image projects: live format documentation read from the synced
+ * github.com/robbietilton/Compositor checkout, a forward-compatible
+ * validator, atomic manifest writes, layer PNG/mask generation and a
+ * best-effort flattened preview. The checkout is the single source of truth
+ * — nothing about the format is frozen in the plugin, so `git pull` in the
+ * checkout is all it takes to follow upstream.
+ */
+import z from '@deepseek-ai/schemastery'
+import { loadRepoDocs } from './shared/comp-docs.mjs'
+import { buildCompositorTools } from './shared/comp-tools.mjs'
+
+/** Cordis plugin name; equals the profile entry id in cordis.patch.yml. */
+export const name = 'dsh-compositor'
+/** Optional services only; registration happens through ctx.inject(['tools']). */
+export const inject = []
+
+export const Config = z.object({
+  repoDir: z.string().default('F:\\everyAI\\dsh-Compositor\\Compositor').description('Compositor 源码库（git clone）的本地路径。插件的格式知识（blend modes、adjustment kinds、版本上限、各种限制）都从这个库的 docs/ 实时解析，git pull 之后自动跟上上游更新。'),
+  agentTools: z.boolean().default(true).description('向 Harness 的 Agent 提供 compositor_* 工具（文档、校验、原子写入、图层 PNG、预览、清理）。'),
+  previewEnabled: z.boolean().default(true).description('启用 compositor_preview（需要可选依赖 sharp 做图片解码；未安装时工具会明确报告）。'),
+  docsMaxChars: z.number().step(1000).min(10000).max(2000000).default(200000).description('compositor_docs 单次返回的文档字符上限。'),
+}).description('Compositor 图像项目工具')
+
+/**
+ * Register the agent tools once the host's `tools` service is up (optional:
+ * without it the plugin simply contributes nothing, never fails the boot).
+ */
+export function registerAgentTools(ctx, state = {}, definitions = null) {
+  if (typeof ctx?.inject !== 'function') { state.error = 'no inject'; return null }
+  try {
+    return ctx.inject(['tools'], toolCtx => {
+      toolCtx.effect(() => {
+        const tools = definitions ?? buildCompositorTools({ config: toolCtx.config ?? {} })
+        const disposers = tools.map(tool => toolCtx.tools.register(tool))
+        state.registered = tools.length
+        return () => {
+          state.registered = 0
+          for (const disposer of disposers) { try { disposer?.() } catch { /* gone */ } }
+        }
+      }, 'dsh-compositor: agent tools')
+    })
+  } catch (error) {
+    state.error = String(error?.message ?? error)
+    return null
+  }
+}
+
+export function apply(ctx, config = {}) {
+  const state = { registered: 0 }
+
+  if (config.agentTools === false) {
+    ctx.logger.info('agent tools disabled by settings')
+    return
+  }
+
+  // Report the checkout status once at startup: it is the compatibility
+  // contract, so make it visible when it is missing or unreadable.
+  loadRepoDocs(config.repoDir || 'F:\\everyAI\\dsh-Compositor\\Compositor')
+    .then(docs => {
+      if (!docs.repoExists) ctx.logger.warn(`Compositor checkout not found at ${docs.repoDir} — tools will run on built-in fallback docs; set the repoDir setting to the git clone of github.com/robbietilton/Compositor`)
+      else ctx.logger.info(`using Compositor checkout ${docs.repoDir}${docs.git?.commit ? ` @ ${docs.git.commit}` : ''} (v1–${docs.vocab.maxVersion}, ${docs.vocab.blendModes.length} blend modes from ${docs.vocab.blendModesSource})`)
+    })
+    .catch(() => { /* reported per call */ })
+
+  const definitions = buildCompositorTools({ config })
+  if (config.previewEnabled === false) {
+    const filtered = definitions.filter(tool => tool.name !== 'compositor_preview')
+    definitions.length = 0
+    definitions.push(...filtered)
+  }
+  registerAgentTools(ctx, state, definitions)
+}

package/.dsh-plugin/shared/comp-blend.mjs

@@ -0,0 +1,142 @@
+/**
+ * Photoshop blend math for the preview renderer.
+ *
+ * All 24 Compositor blend modes, implemented on straight (unpremultiplied)
+ * 8-bit RGBA buffers using the W3C compositing and blending model:
+ *   Co = αs × (1−αb) × Cs + αs × αb × B(Cb, Cs)   (premultiplied result)
+ *   αo = αs + αb × (1−αs)
+ * Non-separable modes (Hue, Saturation, Color, Luminosity) use the standard
+ * lum/sat clip functions. Inputs and outputs are 0–255 per channel; the
+ * caller applies this per destination pixel over a source scan.
+ */
+
+const clamp01 = t => (t < 0 ? 0 : t > 1 ? 1 : t)
+const divide = (a, b) => (b === 0 ? 1 : a / b)
+
+// separable blend functions on 0–1 channels
+const separable = {
+  normal: (b, s) => s,
+  multiply: (b, s) => b * s,
+  screen: (b, s) => b + s - b * s,
+  overlay: (b, s) => hardLight(s, b),
+  darken: (b, s) => Math.min(b, s),
+  lighten: (b, s) => Math.max(b, s),
+  'color-dodge': (b, s) => (s >= 1 ? 1 : Math.min(1, b / (1 - s))),
+  'color-burn': (b, s) => (s <= 0 ? 0 : 1 - Math.min(1, (1 - b) / s)),
+  'linear-burn': (b, s) => clamp01(b + s - 1),
+  'linear-dodge': (b, s) => clamp01(b + s),
+  difference: (b, s) => Math.abs(b - s),
+  exclusion: (b, s) => b + s - 2 * b * s,
+  subtract: (b, s) => clamp01(b - s),
+  divide: (b, s) => (s <= 0 ? 1 : clamp01(b / s)),
+  'soft-light': (b, s) => {
+    const d = b <= 0.25 ? ((16 * b - 12) * b + 4) * b : Math.sqrt(b)
+    return s <= 0.5 ? b - (1 - 2 * s) * b * (1 - b) : b + (2 * s - 1) * (d - b)
+  },
+  'vivid-light': (b, s) => (s < 0.5 ? (s <= 0 ? 0 : 1 - Math.min(1, (1 - b) / (2 * s))) : s >= 1 ? 1 : Math.min(1, b / (2 * (1 - s)))),
+  'linear-light': (b, s) => clamp01(b + 2 * s - 1),
+  'pin-light': (b, s) => (s < 0.5 ? Math.min(b, 2 * s) : Math.max(b, 2 * s - 1)),
+  'hard-mix': (b, s) => (separable['vivid-light'](b, s) < 0.5 ? 0 : 1),
+}
+
+function hardLight(b, s) {
+  return s <= 0.5 ? 2 * b * s : 1 - 2 * (1 - b) * (1 - s)
+}
+separable['hard-light'] = hardLight
+
+// non-separable: HSL helpers
+function lum(r, g, b) {
+  return 0.3 * r + 0.59 * g + 0.11 * b
+}
+function clipColor(r, g, b) {
+  const l = lum(r, g, b)
+  const min = Math.min(r, g, b)
+  const max = Math.max(r, g, b)
+  if (min < 0) { r = l + ((r - l) * l) / (l - min); g = l + ((g - l) * l) / (l - min); b = l + ((b - l) * l) / (l - min) }
+  if (max > 1) { r = l + ((r - l) * (1 - l)) / (max - l); g = l + ((g - l) * (1 - l)) / (max - l); b = l + ((b - l) * (1 - l)) / (max - l) }
+  return [r, g, b]
+}
+function sat(r, g, b) {
+  return Math.max(r, g, b) - Math.min(r, g, b)
+}
+function setLum([r, g, b], l) {
+  const d = l - lum(r, g, b)
+  return clipColor(r + d, g + d, b + d)
+}
+function setSat([r, g, b], s) {
+  // order the channels, set the middle-to-max span to s, min stays 0
+  const ordered = [r, g, b].map((c, i) => ({ c, i })).sort((a, b2) => a.c - b2.c)
+  const out = [0, 0, 0]
+  if (ordered[2].c > ordered[0].c) {
+    out[ordered[1].i] = ((ordered[1].c - ordered[0].c) * s) / (ordered[2].c - ordered[0].c)
+    out[ordered[2].i] = s
+  }
+  return out
+}
+
+const nonSeparable = {
+  hue: (b, s) => setLum(setSat(s, sat(b[0], b[1], b[2])), lum(b[0], b[1], b[2])),
+  saturation: (b, s) => setLum(setSat(b, sat(s[0], s[1], s[2])), lum(b[0], b[1], b[2])),
+  color: (b, s) => setLum(s, lum(b[0], b[1], b[2])),
+  luminosity: (b, s) => setLum(b, lum(s[0], s[1], s[2])),
+}
+
+// Compositor blend name → blending function; b and s are [r,g,b] in 0–1.
+// Separable modes work per channel, so they are lifted to RGB-array form.
+const separableMode = channelFn => (b, s) => [channelFn(b[0], s[0]), channelFn(b[1], s[1]), channelFn(b[2], s[2])]
+
+const MODES = {
+  Normal: separableMode(separable.normal),
+  Multiply: separableMode(separable.multiply),
+  Screen: separableMode(separable.screen),
+  Overlay: separableMode(separable.overlay),
+  Darken: separableMode(separable.darken),
+  Lighten: separableMode(separable.lighten),
+  'Color Dodge': separableMode(separable['color-dodge']),
+  'Color Burn': separableMode(separable['color-burn']),
+  'Linear Burn': separableMode(separable['linear-burn']),
+  'Linear Dodge (Add)': separableMode(separable['linear-dodge']),
+  Difference: separableMode(separable.difference),
+  Exclusion: separableMode(separable.exclusion),
+  Subtract: separableMode(separable.subtract),
+  Divide: separableMode(separable.divide),
+  'Soft Light': separableMode(separable['soft-light']),
+  'Hard Light': separableMode(separable['hard-light']),
+  'Vivid Light': separableMode(separable['vivid-light']),
+  'Linear Light': separableMode(separable['linear-light']),
+  'Pin Light': separableMode(separable['pin-light']),
+  'Hard Mix': separableMode(separable['hard-mix']),
+  Hue: nonSeparable.hue,
+  Saturation: nonSeparable.saturation,
+  Color: nonSeparable.color,
+  Luminosity: nonSeparable.luminosity,
+}
+
+export function blendFunction(blendMode) {
+  return MODES[blendMode] ?? null
+}
+
+export const SUPPORTED_BLEND_MODES = Object.keys(MODES)
+
+/**
+ * Composite one source pixel over one destination pixel (straight alpha,
+ * 0–255 channels). `mode` is a Compositor blend name; anything unknown falls
+ * back to Normal. `opacity` is the layer/coverage product in 0–1; the source
+ * pixel's own alpha is applied here.
+ */
+export function compositePixel(dst, di, src, si, mode, opacity) {
+  const sa = opacity * src[si + 3] / 255
+  if (sa <= 0) return
+  const br = dst[di] / 255, bg = dst[di + 1] / 255, bb = dst[di + 2] / 255, ba = dst[di + 3] / 255
+  const sr = src[si] / 255, sg = src[si + 1] / 255, sb = src[si + 2] / 255
+  const blend = MODES[mode] ?? MODES.Normal
+  const mixed = blend([br, bg, bb], [sr, sg, sb])
+  const alphaOut = sa + ba * (1 - sa)
+  if (alphaOut <= 0) { dst[di] = dst[di + 1] = dst[di + 2] = dst[di + 3] = 0; return }
+  // W3C simple alpha compositing: source-only ∪ blended intersection ∪ backdrop-only
+  const channel = (s, m, b) => (sa * (1 - ba) * s + sa * ba * m + (1 - sa) * ba * b) / alphaOut
+  dst[di] = Math.round(clamp01(channel(sr, mixed[0], br)) * 255)
+  dst[di + 1] = Math.round(clamp01(channel(sg, mixed[1], bg)) * 255)
+  dst[di + 2] = Math.round(clamp01(channel(sb, mixed[2], bb)) * 255)
+  dst[di + 3] = Math.round(alphaOut * 255)
+}

package/.dsh-plugin/shared/comp-docs.mjs

@@ -0,0 +1,186 @@
+/**
+ * Live documentation loader — the compatibility core of this plugin.
+ *
+ * Nothing about the .comp format is frozen here: blend modes, adjustment
+ * kinds, the highest known manifest version and the numeric limits are all
+ * parsed at runtime from the docs inside the synced Compositor git checkout
+ * (github.com/robbietilton/Compositor). When upstream changes the format and
+ * the checkout is pulled, the plugin follows automatically. The constants
+ * below are only fallbacks for when a doc cannot be read or its wording has
+ * drifted; every value also reports where it came from so an agent can tell.
+ */
+import { readFile, stat } from 'node:fs/promises'
+import { join } from 'node:path'
+import { readGitState } from './comp-paths.mjs'
+
+export const DOCS = {
+  writing: 'docs/writing-comp-files.md',
+  format: 'docs/project-format.md',
+}
+
+export const FALLBACK = {
+  // writing-comp-files.md "Blend modes are spelled exactly" (24 modes)
+  blendModes: [
+    'Normal', 'Darken', 'Multiply', 'Color Burn', 'Linear Burn', 'Lighten', 'Screen',
+    'Color Dodge', 'Linear Dodge (Add)', 'Overlay', 'Soft Light', 'Hard Light',
+    'Vivid Light', 'Linear Light', 'Pin Light', 'Hard Mix', 'Difference', 'Exclusion',
+    'Subtract', 'Divide', 'Hue', 'Saturation', 'Color', 'Luminosity',
+  ],
+  // writing-comp-files.md "`kind` is one of ..." (13 kinds, versions 7 and 9)
+  adjustmentKinds: [
+    'Hue/Saturation', 'Levels', 'Curves', 'Exposure', 'Gradient Map', 'Grain',
+    'Invert', 'Black & White', 'Color Balance', 'Gaussian Blur', 'Motion Blur', 'Add Noise',
+  ],
+  maxVersion: 13,
+  limits: { canvasSide: 30000, totalLayerPixels: 100_000_000, totalMaskPixels: 100_000_000, layers: 10000, manifestBytes: 4 * 1024 * 1024, assetBytes: 512 * 1024 * 1024, guideCount: 1000, guidePosition: 1_000_000, nestDepth: 64, maskSourceChain: 256 },
+}
+
+const backticked = line => {
+  const values = []
+  const pattern = /`([^`]+)`/g
+  let match
+  while ((match = pattern.exec(line))) values.push(match[1])
+  return values
+}
+
+function parseBlendModes(writingText) {
+  if (!writingText) return null
+  const line = writingText.split('\n').find(text => text.includes('Blend modes are spelled exactly'))
+  if (!line) return null
+  const modes = backticked(line)
+  return modes.length >= 8 ? modes : null
+}
+
+function parseAdjustmentKinds(writingText, formatText) {
+  const sources = [writingText, formatText].filter(Boolean)
+  const kinds = new Set()
+  for (const text of sources) {
+    for (const line of text.split('\n')) {
+      // "`kind` is one of `Hue/Saturation`, `Levels`, ..."
+      if (/`kind`\s+is one of/.test(line)) for (const kind of backticked(line)) if (kind !== 'kind') kinds.add(kind)
+      // "... version 9 adds three adjustment kinds: `Gaussian Blur` (...), ..."
+      if (/adds?\s+(?:three|new|\d+)\s+adjustment kinds/.test(line)) for (const kind of backticked(line)) kinds.add(kind)
+    }
+  }
+  return kinds.size >= 8 ? [...kinds] : null
+}
+
+function parseMaxVersion(formatText) {
+  if (!formatText) return null
+  const title = formatText.split('\n', 1)[0] || ''
+  // "# Compositor project format, versions 1–13" (also handles 1-13, 1—13)
+  const match = /versions?\s*1\s*[–—\-]\s*(\d+)/i.exec(title)
+  return match ? Number(match[1]) : null
+}
+
+function parseLimits(formatText, writingText) {
+  const text = `${formatText ?? ''}\n${writingText ?? ''}`
+  const out = {}
+  // "30,000 pixels per canvas/image side" / "canvases up to 30,000 pixels on a side"
+  for (const pattern of [/(\d[\d,]*)\s*pixels per canvas\/image side/, /up to (\d[\d,]*)\s*pixels on a side/]) {
+    const match = pattern.exec(text)
+    if (match) { out.canvasSide = Number(match[1].replace(/,/g, '')); break }
+  }
+  // "100 million total source pixels" / "Up to 100 million mask pixels"
+  let match = /(\d+)\s*million total source pixels/.exec(text)
+  if (match) out.totalLayerPixels = Number(match[1]) * 1e6
+  match = /(\d+)\s*million mask pixels/.exec(text)
+  if (match) out.totalMaskPixels = Number(match[1]) * 1e6
+  match = /(\d[\d,]*)\s*layers/.exec(text)
+  if (match) out.layers = Number(match[1].replace(/,/g, ''))
+  match = /(\d[\d.]*)\s*MiB manifest/.exec(text)
+  if (match) out.manifestBytes = Math.round(Number(match[1]) * 1024 * 1024)
+  match = /(\d[\d.]*)\s*MiB per encoded asset/.exec(text)
+  if (match) out.assetBytes = Math.round(Number(match[1]) * 1024 * 1024)
+  return out
+}
+
+const cache = new Map()
+
+async function readDocIfChanged(repoDir, relative, entry) {
+  const path = join(repoDir, relative)
+  const fileStat = await stat(path).catch(() => null)
+  if (!fileStat || !fileStat.isFile()) {
+    if (entry?.text !== undefined) return entry
+    return { text: null, mtimeMs: 0, bytes: 0 }
+  }
+  if (entry && entry.mtimeMs === fileStat.mtimeMs && entry.size === fileStat.size) return entry
+  const text = await readFile(path, 'utf8').catch(() => null)
+  return { text, mtimeMs: fileStat.mtimeMs, size: fileStat.size, bytes: Buffer.byteLength(text ?? '') }
+}
+
+/**
+ * Load docs and vocab from the checkout. Cached per repoDir; the cache is
+ * keyed on doc mtimes so a `git pull` invalidates it immediately.
+ */
+export async function loadRepoDocs(repoDir) {
+  const cached = cache.get(repoDir)
+  const [writing, format] = await Promise.all([
+    readDocIfChanged(repoDir, DOCS.writing, cached?.writing),
+    readDocIfChanged(repoDir, DOCS.format, cached?.format),
+  ])
+
+  const warnings = []
+  if (writing.text === null) warnings.push(`cannot read ${DOCS.writing} in ${repoDir}`)
+  if (format.text === null) warnings.push(`cannot read ${DOCS.format} in ${repoDir}`)
+
+  const parsedBlend = parseBlendModes(writing.text)
+  const parsedKinds = parseAdjustmentKinds(writing.text, format.text)
+  const parsedMaxVersion = parseMaxVersion(format.text)
+  const parsedLimits = parseLimits(format.text, writing.text)
+
+  const blendModes = parsedBlend ?? FALLBACK.blendModes
+  const adjustmentKinds = parsedKinds ?? FALLBACK.adjustmentKinds
+  const maxVersion = parsedMaxVersion ?? FALLBACK.maxVersion
+  const limits = { ...FALLBACK.limits, ...parsedLimits }
+  if (!parsedBlend) warnings.push('blend mode list fell back to the built-in copy; the doc wording may have changed')
+  if (!parsedKinds) warnings.push('adjustment kind list fell back to the built-in copy')
+  if (!parsedMaxVersion) warnings.push('max manifest version fell back to the built-in value')
+
+  const git = await readGitState(repoDir)
+  const entry = {
+    repoDir,
+    repoExists: writing.text !== null || format.text !== null,
+    git,
+    docs: { writing: { path: join(repoDir, DOCS.writing), found: writing.text !== null, bytes: writing.bytes }, format: { path: join(repoDir, DOCS.format), found: format.text !== null, bytes: format.bytes } },
+    texts: { writing: writing.text, format: format.text },
+    vocab: {
+      blendModes,
+      blendModesSource: parsedBlend ? 'docs' : 'fallback',
+      adjustmentKinds,
+      adjustmentKindsSource: parsedKinds ? 'docs' : 'fallback',
+      maxVersion,
+      maxVersionSource: parsedMaxVersion ? 'docs' : 'fallback',
+      limits,
+      limitsSource: Object.keys(parsedLimits).length ? 'docs+fallback' : 'fallback',
+    },
+    warnings,
+    writingEntry: writing,
+    formatEntry: format,
+  }
+  cache.set(repoDir, entry)
+  return entry
+}
+
+/** Public shape without internal cache entries or huge text blobs. */
+export function publicDocs(entry, { includeText = false } = {}) {
+  const out = {
+    repoDir: entry.repoDir,
+    repoExists: entry.repoExists,
+    git: entry.git,
+    docs: entry.docs,
+    vocab: {
+      blendModeCount: entry.vocab.blendModes.length,
+      blendModes: entry.vocab.blendModes,
+      blendModesSource: entry.vocab.blendModesSource,
+      adjustmentKinds: entry.vocab.adjustmentKinds,
+      adjustmentKindsSource: entry.vocab.adjustmentKindsSource,
+      maxManifestVersion: entry.vocab.maxVersion,
+      maxVersionSource: entry.vocab.maxVersionSource,
+      limits: entry.vocab.limits,
+    },
+    warnings: entry.warnings,
+  }
+  if (includeText) out.texts = entry.texts
+  return out
+}

package/.dsh-plugin/shared/comp-paths.mjs

@@ -0,0 +1,102 @@
+/**
+ * Path helpers for .comp packages and best-effort git state for the
+ * Compositor checkout. Git state is read straight from the .git directory
+ * (HEAD, refs, packed-refs, loose commit objects) so it works without git
+ * on PATH and without spawning processes.
+ */
+import { readFile, stat } from 'node:fs/promises'
+import { inflateSync } from 'node:zlib'
+import { basename, isAbsolute, join, resolve } from 'node:path'
+
+const UUID_RE = /^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$/
+
+export function isUuid(value) {
+  return typeof value === 'string' && UUID_RE.test(value)
+}
+
+export function looksLikeManifestPath(path) {
+  return basename(path).toLowerCase() === 'manifest.json'
+}
+
+/**
+ * Accept a .comp folder, its manifest.json path, or a folder that contains
+ * manifest.json; return { compDir, manifestPath, imagesDir }.
+ */
+export async function resolveCompPath(input) {
+  if (typeof input !== 'string' || !input.trim()) throw new Error('path is required')
+  const path = resolve(input.trim().replace(/[\\/]+$/, ''))
+  if (!isAbsolute(path)) throw new Error(`expected an absolute path, got ${input}`)
+  const compDir = looksLikeManifestPath(path) ? resolve(path, '..') : path
+  const manifestPath = join(compDir, 'manifest.json')
+  const imagesDir = join(compDir, 'images')
+  const manifestStat = await stat(manifestPath).catch(() => null)
+  if (!manifestStat || !manifestStat.isFile()) {
+    throw new Error(`no manifest.json found at ${manifestPath} — a .comp project is a folder containing manifest.json and images/`)
+  }
+  return { compDir, manifestPath, imagesDir }
+}
+
+async function readGitDir(repoDir) {
+  const dotGitPath = join(repoDir, '.git')
+  const gitStat = await stat(dotGitPath).catch(() => null)
+  if (!gitStat) return null
+  if (gitStat.isDirectory()) return dotGitPath
+  // worktree/submodule: .git is a file "gitdir: <path>"
+  try {
+    const text = (await readFile(dotGitPath, 'utf8')).trim()
+    const match = /^gitdir:\s*(.+)$/.exec(text)
+    if (match) return resolve(match[1])
+  } catch { /* unreadable */ }
+  return null
+}
+
+async function resolveRef(gitDir, ref) {
+  const direct = await readFile(join(gitDir, ref), 'utf8').catch(() => null)
+  if (direct && /^[0-9a-f]{40}$/i.test(direct.trim())) return direct.trim()
+  try {
+    const packed = await readFile(join(gitDir, 'packed-refs'), 'utf8')
+    for (const line of packed.split('\n')) {
+      const match = /^([0-9a-f]{40})\s+(\S+)$/.exec(line.trim())
+      if (match && match[2] === ref) return match[1]
+    }
+  } catch { /* no packed-refs */ }
+  return null
+}
+
+async function commitSubject(gitDir, commit) {
+  const loose = join(gitDir, 'objects', commit.slice(0, 2), commit.slice(2))
+  try {
+    const raw = inflateSync(await readFile(loose))
+    const text = raw.toString('utf8')
+    if (!text.startsWith('commit ')) return null
+    const body = text.slice(text.indexOf('\n\n') + 2)
+    return (body.split('\n')[0] || '').slice(0, 160) || null
+  } catch { /* packed object or missing: subject unavailable */ }
+  return null
+}
+
+/**
+ * Read { branch, commit, subject } from a git checkout without running git.
+ * Returns null when repoDir is not a git checkout.
+ */
+export async function readGitState(repoDir) {
+  const gitDir = await readGitDir(repoDir)
+  if (!gitDir) return null
+  let branch = null
+  let commit = null
+  try {
+    const head = (await readFile(join(gitDir, 'HEAD'), 'utf8')).trim()
+    const refMatch = /^ref:\s*(?:refs\/heads\/)?(\S+)$/.exec(head)
+    if (refMatch) {
+      branch = refMatch[1]
+      commit = await resolveRef(gitDir, `refs/heads/${branch}`)
+    } else if (/^[0-9a-f]{40}$/i.test(head)) commit = head
+  } catch { /* HEAD unreadable */ }
+  const subject = commit ? await commitSubject(gitDir, commit) : null
+  return {
+    branch,
+    commit: commit ? commit.slice(0, 12) : null,
+    subject,
+    note: 'read from the .git directory without running git; run `git -C <repo> pull` yourself when the user wants the checkout updated',
+  }
+}