projectkeeper 0.0.0-stage → 1.0.0

package/src/sources/anchor.ts

@@ -0,0 +1,129 @@
+/**
+ * Source identity and credential redaction shared by every reader (files, sessions, git).
+ */
+import type { FileAnchor, SessionAnchor, Source, SourceAnchor } from '../model/types.ts';
+import { fingerprint, stableId } from '../model/ids.ts';
+import { pathKey } from '../util/paths.ts';
+
+export function fileSourceId(path: string, headingPath: readonly string[]): string {
+  return stableId('src', 'file', pathKey(path), headingPath.join(' / '));
+}
+
+export function sessionSourceId(host: string, sessionId: string, messageStart: number): string {
+  return stableId('src', 'session', host, sessionId, messageStart);
+}
+
+export function commitSourceId(repo: string, commit: string): string {
+  return stableId('src', 'commit', pathKey(repo), commit);
+}
+
+/** A file as it was at a commit (§1.2 `History only`): one source per repository, commit and path. */
+export function revisionSourceId(repo: string, commit: string, path: string): string {
+  return stableId('src', 'revision', pathKey(repo), commit, path.split('\\').join('/'));
+}
+
+export function anchorId(anchor: SourceAnchor): string {
+  switch (anchor.kind) {
+    case 'file': return fileSourceId(anchor.path, anchor.headingPath);
+    case 'session': return sessionSourceId(anchor.host, anchor.sessionId, anchor.messageStart);
+    case 'commit': return commitSourceId(anchor.repo, anchor.commit);
+    case 'command': return stableId('src', 'command', anchor.cwd, anchor.command, anchor.ranAt);
+    case 'status': return stableId('src', 'status', anchor.description, anchor.at);
+    case 'revision': return revisionSourceId(anchor.repo, anchor.commit, anchor.path);
+  }
+}
+
+/** Human-readable locator, e.g. `design/DECISIONS.md › 一 · 已定 › D14 (L102–L107)`. */
+export function anchorLabel(anchor: SourceAnchor): string {
+  switch (anchor.kind) {
+    case 'file': {
+      const heading = anchor.headingPath.length ? ` › ${anchor.headingPath.join(' › ')}` : '';
+      return `${anchor.path}${heading} (L${anchor.lineStart}–L${anchor.lineEnd})`;
+    }
+    case 'session': return `${anchor.host} session ${anchor.sessionId.slice(0, 8)} · messages ${anchor.messageStart}–${anchor.messageEnd}${anchor.at ? ` · ${anchor.at}` : ''}`;
+    case 'commit': return `${anchor.repo} @ ${anchor.commit.slice(0, 10)}`;
+    case 'command': return `${anchor.command} (in ${anchor.cwd}, ${anchor.ranAt})`;
+    case 'status': return `${anchor.description} (${anchor.at})`;
+    case 'revision': return `${anchor.path} @ ${anchor.commit.slice(0, 10)} in ${anchor.repo} (version history)`;
+  }
+}
+
+const CREDENTIAL_PATTERNS: readonly RegExp[] = [
+  /\b(sk-[A-Za-z0-9_-]{16,})/g,                                   // OpenAI-style keys
+  /\b(sk-ant-[A-Za-z0-9_-]{16,})/g,
+  /\b(ghp_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})/g,        // GitHub tokens
+  /\b(AKIA[0-9A-Z]{16})\b/g,                                        // AWS access key id
+  /\b(xox[baprs]-[A-Za-z0-9-]{10,})/g,                               // Slack
+  /\b(AIza[0-9A-Za-z_-]{30,})/g,                                     // Google API key
+  /((?:api[_-]?key|apikey|secret|token|password|passwd|authorization)\s*[:=]\s*["']?)([A-Za-z0-9_\-./+=]{12,})/gi,
+  /(Bearer\s+)([A-Za-z0-9_\-.=]{20,})/g,
+  /\b(eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,})/g, // JWT
+];
+
+export const REDACTED = '[credential redacted]';
+
+/** Replace credential values with a marker; the fact that a credential is there stays visible (§3.1). */
+export function redactCredentials(text: string): { text: string; found: boolean } {
+  let found = false;
+  let out = text;
+  for (const pattern of CREDENTIAL_PATTERNS) {
+    out = out.replace(pattern, (...args: unknown[]) => {
+      found = true;
+      // The replacer gets the match, the capture groups, then the offset and the whole input: only the groups count.
+      // Counting the input as a group kept every token-shaped credential (sk-…, ghp_…, AKIA…) in the text.
+      const groups = args.slice(1, args.findIndex((a, i) => i > 0 && typeof a === 'number'));
+      const captured = groups.filter((g): g is string => typeof g === 'string');
+      if (captured.length >= 2) return `${captured[0]}${REDACTED}`;
+      return REDACTED;
+    });
+  }
+  return { text: out, found };
+}
+
+export function makeFileSource(input: {
+  projectId: string; path: string; headingPath: readonly string[]; lineStart: number; lineEnd: number;
+  excerpt: string; fileText: string; scopeItemId: string; title?: string; ids?: readonly string[];
+  commit?: string | null; readAt?: string; tableRow?: number;
+}): Source {
+  const anchor: FileAnchor = {
+    kind: 'file', path: input.path, headingPath: input.headingPath, lineStart: input.lineStart,
+    lineEnd: input.lineEnd, ...(input.tableRow === undefined ? {} : { tableRow: input.tableRow }),
+  };
+  const redacted = redactCredentials(input.excerpt);
+  return {
+    id: fileSourceId(input.path, input.headingPath), projectId: input.projectId,
+    title: input.title ?? (input.headingPath.length ? input.headingPath[input.headingPath.length - 1]! : input.path.split(/[\\/]/).pop()!),
+    anchor, ids: input.ids ?? [],
+    version: { fingerprint: fingerprint(input.fileText), readAt: input.readAt ?? new Date().toISOString(), commit: input.commit ?? null },
+    excerpt: redacted.text, usedAs: null, usedAsBy: null, availability: null, movedTo: null,
+    scopeItemId: input.scopeItemId, hasCredential: redacted.found, bytes: Buffer.byteLength(input.excerpt, 'utf8'),
+  };
+}
+
+export function makeSessionSource(input: {
+  projectId: string; host: SessionAnchor['host']; sessionId: string; file: string; cwd: string | null;
+  messageStart: number; messageEnd: number; at: string | null; excerpt: string; title: string;
+  scopeItemId: string; ids?: readonly string[]; readAt?: string;
+}): Source {
+  const anchor: SessionAnchor = {
+    kind: 'session', host: input.host, sessionId: input.sessionId, file: input.file, cwd: input.cwd,
+    messageStart: input.messageStart, messageEnd: input.messageEnd, at: input.at,
+  };
+  const redacted = redactCredentials(input.excerpt);
+  return {
+    id: sessionSourceId(input.host, input.sessionId, input.messageStart), projectId: input.projectId,
+    title: input.title, anchor, ids: input.ids ?? [],
+    version: { fingerprint: fingerprint(input.excerpt), readAt: input.readAt ?? new Date().toISOString(), commit: null },
+    excerpt: redacted.text, usedAs: null, usedAsBy: null, availability: null, movedTo: null,
+    scopeItemId: input.scopeItemId, hasCredential: redacted.found, bytes: Buffer.byteLength(input.excerpt, 'utf8'),
+  };
+}
+
+/** Numbers the material itself uses: DEC-020, TASK-7.2, CKC-01, REQ-3, #18, D14, PA-6 … */
+export function extractIds(text: string): string[] {
+  const out = new Set<string>();
+  for (const m of text.matchAll(/\b([A-Z]{2,6}-\d{1,3}(?:\.\d{1,3})?)\b/g)) out.add(m[1]!);
+  for (const m of text.matchAll(/(?<![\w-])(#\d{1,5})\b/g)) out.add(m[1]!);
+  for (const m of text.matchAll(/(?<![A-Za-z])(D\d{1,2}|PA-\d{1,2}|U\d{1,2}|S\d{1,2}|G\d)(?![\w.])/g)) out.add(m[1]!);
+  return [...out].sort();
+}

package/src/sources/files.ts

@@ -0,0 +1,267 @@
+/**
+ * Read project files into sources (Spec §1.2). Markdown is split into sections by heading,
+ * each section a source with its heading path and line range; other text files become one
+ * source each with a head excerpt. Binary and oversized files are skipped and reported.
+ * Nothing is written to the project.
+ *
+ * What is read from where follows the scope (Spec §1.1; ../scope/skip.ts): the project's ignore rules leave content out
+ * (git decides), generated output is not read, third-party material gives only its documents (as `Reference only`),
+ * and a registered worktree gives only what it adds to the trunk (E60).
+ */
+import { readFileSync, readdirSync, statSync, type Dirent } from 'node:fs';
+import { dirname, extname, join } from 'node:path';
+import { Worker } from 'node:worker_threads';
+import type { ScopeItem, Source } from '../model/types.ts';
+import type { UsedAs } from '../model/vocab.ts';
+import { fingerprint } from '../model/ids.ts';
+import { isWithin, nameForm, normalizePath, pathKey, relativeDisplay } from '../util/paths.ts';
+import { extractIds, makeFileSource } from './anchor.ts';
+import { isDocumentPath, isReadRoot, isSkippedName, overridesIgnoreRules, readingOf, treatmentOf } from '../scope/skip.ts';
+import { ignoredPredicate } from '../scope/ignore.ts';
+import { measureWorktree } from '../scope/worktree.ts';
+import { OWN_TS_WORKER_OPTIONS } from '../util/own-ts.ts';
+
+export interface FileEntry {
+  readonly path: string;
+  readonly scopeItemId: string;
+  readonly bytes: number;
+  readonly mtimeMs: number;
+  /** The `Used as` the file's location sets (§1.1: the documents third-party material brings are `Reference only`). */
+  readonly usedAs?: { readonly value: UsedAs; readonly by: 'keeper' | 'owner'; readonly scopeItemId: string } | null;
+}
+export interface ScanResult {
+  readonly files: readonly FileEntry[];
+  readonly sources: readonly Source[];
+  readonly skipped: readonly { readonly path: string; readonly reason: string }[];
+}
+
+const TEXT_EXT = new Set(['.md', '.markdown', '.txt', '.json', '.jsonl', '.yaml', '.yml', '.toml', '.ts', '.tsx', '.js', '.mjs', '.cjs', '.py', '.rs', '.go', '.java', '.kt', '.cs', '.c', '.cc', '.cpp', '.h', '.hpp', '.css', '.html', '.sh', '.ps1', '.bat', '.sql', '.xml', '.ini', '.cfg', '.env.example', '.gitignore', '.gitattributes']);
+const MAX_FILE_BYTES = 2_000_000;
+const MAX_SECTION_CHARS = 14_000;
+const CODE_HEAD_LINES = 120;
+
+export function isTextFile(path: string): boolean {
+  const ext = extname(path).toLowerCase();
+  if (TEXT_EXT.has(ext)) return true;
+  const base = path.split(/[\\/]/).pop() ?? '';
+  return ['README', 'LICENSE', 'AGENTS.md', 'CLAUDE.md', 'Makefile'].includes(base);
+}
+
+function looksBinary(buf: Buffer): boolean {
+  const n = Math.min(buf.length, 4000);
+  for (let i = 0; i < n; i += 1) if (buf[i] === 0) return true;
+  return false;
+}
+
+export interface MarkdownSection {
+  readonly headingPath: readonly string[];
+  readonly lineStart: number;
+  readonly lineEnd: number;
+  readonly text: string;
+}
+
+/** Split markdown into sections by heading; text before the first heading is its own section. */
+export function splitMarkdown(text: string): MarkdownSection[] {
+  const lines = text.split(/\r?\n/);
+  const sections: MarkdownSection[] = [];
+  const stack: { level: number; title: string }[] = [];
+  let start = 0;
+  let inFence = false;
+  const flush = (end: number) => {
+    if (end < start) return;
+    const body = lines.slice(start, end + 1).join('\n');
+    if (body.trim().length === 0) return;
+    sections.push({ headingPath: stack.map((s) => s.title), lineStart: start + 1, lineEnd: end + 1, text: body });
+  };
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i]!;
+    if (/^\s*(```|~~~)/.test(line)) inFence = !inFence;
+    if (inFence) continue;
+    const m = /^(#{1,6})\s+(.*)$/.exec(line);
+    if (!m) continue;
+    flush(i - 1);
+    const level = m[1]!.length;
+    while (stack.length && stack[stack.length - 1]!.level >= level) stack.pop();
+    stack.push({ level, title: m[2]!.trim().replace(/\s+#+\s*$/, '') });
+    start = i;
+  }
+  flush(lines.length - 1);
+  return sections;
+}
+
+/** Cut a long section into parts at paragraph boundaries so excerpts stay readable. */
+function splitLong(section: MarkdownSection): MarkdownSection[] {
+  if (section.text.length <= MAX_SECTION_CHARS) return [section];
+  const parts: MarkdownSection[] = [];
+  const lines = section.text.split('\n');
+  let buf: string[] = [];
+  let bufStart = section.lineStart;
+  let part = 1;
+  const flush = (endLine: number) => {
+    if (buf.length === 0) return;
+    parts.push({ headingPath: [...section.headingPath, `part ${part}`], lineStart: bufStart, lineEnd: endLine, text: buf.join('\n') });
+    part += 1;
+    buf = [];
+    bufStart = endLine + 1;
+  };
+  let size = 0;
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i]!;
+    if (size + line.length > MAX_SECTION_CHARS && buf.length > 0 && line.trim() === '') flush(section.lineStart + i - 1);
+    buf.push(line);
+    size = buf.reduce((n, l) => n + l.length + 1, 0);
+  }
+  flush(section.lineEnd);
+  return parts;
+}
+
+/**
+ * The files of one scope item's own region: what the one skip list leaves out is not entered, links are not followed,
+ * and a location that is a scope item of its own (`separate`) is left to that item. `ignored` is the project's ignore
+ * rules for this root (relative paths), `keep` the ignored files the owner chose to include anyway.
+ */
+function walkRegion(root: string, scopeItemId: string, opts: {
+  readonly separate?: ReadonlySet<string>; readonly ignored?: ((rel: string) => boolean) | null; readonly keep?: ReadonlySet<string>;
+  readonly documentsOnly?: boolean; readonly usedAs?: FileEntry['usedAs'];
+} = {}): FileEntry[] {
+  const out: FileEntry[] = [];
+  const walk = (dir: string, depth: number) => {
+    if (depth > 12) return;
+    let entries: Dirent[] = [];
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.isSymbolicLink()) continue;
+      const name = nameForm(e.name);   // as git names it, where the listing gives another Unicode form (macOS)
+      const full = join(dir, name);
+      if (opts.separate?.has(pathKey(full))) continue;
+      if (opts.ignored && opts.ignored(relativeDisplay(root, full)) && !opts.keep?.has(pathKey(full))) continue;
+      if (e.isDirectory()) { if (!isSkippedName(name)) walk(full, depth + 1); continue; }
+      if (!e.isFile()) continue;
+      if (opts.documentsOnly && !isDocumentPath(name)) continue;
+      let st;
+      try { st = statSync(full); } catch { continue; }
+      out.push({ path: normalizePath(full), scopeItemId, bytes: st.size, mtimeMs: st.mtimeMs, usedAs: opts.usedAs ?? null });
+    }
+  };
+  walk(root, 0);
+  return out;
+}
+
+/** Every file under `root` except what the skip list leaves out and the `excluded` locations. */
+export function listFiles(root: string, scopeItemId: string, excluded: readonly string[]): FileEntry[] {
+  return walkRegion(root, scopeItemId).filter((f) => !excluded.some((e) => isWithin(e, f.path)));
+}
+
+/**
+ * Read one file into sources. `scope`, when given, sets the `Used as` the file's location implies (third-party
+ * documents are `Reference only`) for an entry that does not carry it already.
+ */
+export function readFileSources(projectId: string, entry: FileEntry, commit: string | null = null, scope: readonly ScopeItem[] | null = null): { sources: Source[]; skipped: string | null } {
+  if (entry.bytes > MAX_FILE_BYTES) return { sources: [], skipped: `larger than ${MAX_FILE_BYTES} bytes` };
+  if (!isTextFile(entry.path)) return { sources: [], skipped: 'not a text file type' };
+  let buf: Buffer;
+  try { buf = readFileSync(entry.path); } catch (e) { return { sources: [], skipped: `unreadable: ${(e as Error).message}` }; }
+  if (looksBinary(buf)) return { sources: [], skipped: 'binary content' };
+  const text = buf.toString('utf8');
+  const readAt = new Date().toISOString();
+  const ext = extname(entry.path).toLowerCase();
+  const sources: Source[] = [];
+  const usedAs = entry.usedAs ?? (scope ? readingOf(scope, entry.path).usedAs : null);
+  const judged = (s: Source): Source => (usedAs ? { ...s, usedAs: usedAs.value, usedAsBy: usedAs.by, usedAsByScopeItemId: usedAs.scopeItemId } : s);
+  if (ext === '.md' || ext === '.markdown') {
+    for (const section of splitMarkdown(text).flatMap(splitLong)) {
+      sources.push(judged(makeFileSource({
+        projectId, path: entry.path, headingPath: section.headingPath, lineStart: section.lineStart, lineEnd: section.lineEnd,
+        excerpt: section.text, fileText: text, scopeItemId: entry.scopeItemId, ids: extractIds(section.text), commit, readAt,
+        title: section.headingPath.length ? section.headingPath[section.headingPath.length - 1]! : entry.path.split(/[\\/]/).pop()!,
+      })));
+    }
+    return { sources, skipped: null };
+  }
+  const lines = text.split(/\r?\n/);
+  const head = lines.slice(0, CODE_HEAD_LINES).join('\n');
+  sources.push(judged(makeFileSource({
+    projectId, path: entry.path, headingPath: [], lineStart: 1, lineEnd: Math.min(lines.length, CODE_HEAD_LINES),
+    excerpt: lines.length > CODE_HEAD_LINES ? `${head}\n…(${lines.length} lines in total; the Keeper reads the rest on demand)` : head,
+    fileText: text, scopeItemId: entry.scopeItemId, ids: extractIds(head), commit, readAt,
+  })));
+  return { sources, skipped: null };
+}
+
+/** Full scan of every included directory in scope. */
+/** The same scan on a worker thread: a large project must not freeze the workbench while it is read (CKC-09 AC-1). */
+export function scanFilesAsync(projectId: string, scope: readonly ScopeItem[]): Promise<ScanResult> {
+  return new Promise((resolve, reject) => {
+    const worker = new Worker(new URL('./scan-worker.ts', import.meta.url), { workerData: { projectId, scope }, ...OWN_TS_WORKER_OPTIONS });
+    let settled = false;
+    worker.once('message', (result: ScanResult) => { settled = true; resolve(result); void worker.terminate(); });
+    worker.once('error', (error) => { settled = true; reject(error); });
+    worker.once('exit', (code) => { if (!settled) reject(new Error(`file scan worker exited with code ${code}`)); });
+  });
+}
+
+/** The files a registered worktree adds to the trunk (E60), measured now from git's records. */
+function worktreeFiles(item: ScopeItem): FileEntry[] {
+  if (!item.worktreeOf) return [];
+  const measured = measureWorktree(item.path, item.worktreeOf);
+  const out: FileEntry[] = [];
+  for (const t of measured.taken) {
+    if (t.deleted) continue;
+    const full = join(item.path, t.path);
+    try {
+      const st = statSync(full);
+      if (st.isFile()) out.push({ path: normalizePath(full), scopeItemId: item.id, bytes: st.size, mtimeMs: st.mtimeMs, usedAs: null });
+    } catch { /* gone since it was measured */ }
+  }
+  return out;
+}
+
+/**
+ * Every scope item read in its own region, as its relation says (../scope/skip.ts `treatmentOf`): a location that is
+ * an item of its own is read — or not — by that item, so nothing is read twice and nothing left out comes in through
+ * a directory above it.
+ */
+export function scanFiles(projectId: string, scope: readonly ScopeItem[]): ScanResult {
+  const locations = scope.filter((i) => i.category !== 'Session source');
+  // Locations read (or left out) by an item of their own. Ignored files the owner took in are read where they lie.
+  const itemPaths = new Set(locations.filter((i) => !(i.ignoredBy?.paths && i.relation !== 'Excluded')).map((i) => pathKey(i.path)));
+  // Ignored files the owner chose to include anyway (an answer to the scope question, or a correction).
+  // Files ignored one by one are listed per directory, so each lives in the directory of its item's path.
+  const keep = new Set(locations.filter((i) => i.relation !== 'Excluded' && i.ignoredBy?.paths).flatMap((i) => (i.ignoredBy!.paths ?? []).map((p) => pathKey(join(dirname(i.path), p.split('/').pop()!)))));
+  const files: FileEntry[] = [];
+  const sources: Source[] = [];
+  const skipped: { path: string; reason: string }[] = [];
+  for (const root of locations.filter((i) => isReadRoot(scope, i))) {
+    const treatment = treatmentOf(root);
+    let entries: FileEntry[];
+    if (root.category === 'Worktree' && (treatment === 'changes' || treatment === 'history')) {
+      entries = worktreeFiles(root);
+    } else {
+      try { if (!statSync(root.path).isDirectory()) continue; } catch { continue; }
+      const separate = new Set([...itemPaths].filter((p) => p !== pathKey(root.path)));
+      const documents = treatment === 'documents';
+      entries = walkRegion(root.path, root.id, {
+        separate,
+        ignored: overridesIgnoreRules(scope, root) ? null : ignoredPredicate(root.path),
+        keep,
+        documentsOnly: documents,
+        usedAs: documents ? { value: 'Reference only', by: root.classification?.by === 'owner' ? 'owner' : 'keeper', scopeItemId: root.id } : null,
+      });
+    }
+    for (const entry of entries) {
+      files.push(entry);
+      const read = readFileSources(projectId, entry);
+      if (read.skipped) { if (isTextFile(entry.path) || entry.bytes > MAX_FILE_BYTES) skipped.push({ path: entry.path, reason: read.skipped }); continue; }
+      sources.push(...read.sources);
+    }
+  }
+  return { files, sources, skipped };
+}
+
+export function fileFingerprint(path: string): string | null {
+  try { return fingerprint(readFileSync(path)); } catch { return null; }
+}
+
+export function displayPath(root: string, path: string): string {
+  return relativeDisplay(root, path);
+}

package/src/sources/gitobs.ts

@@ -0,0 +1,41 @@
+/**
+ * Observe repositories in scope: recent commits become commit sources; the current branch,
+ * head and uncommitted changes become one status source per repository. Read-only.
+ *
+ * When a commit was made goes on its anchor, where the program reads it (how recent a repository's commits are); the
+ * excerpt is the commit as people read it, never parsed back into facts.
+ */
+import type { ScopeItem, Source } from '../model/types.ts';
+import { fingerprint, stableId } from '../model/ids.ts';
+import { gitRecentCommits, gitStatus } from '../util/git.ts';
+import { pathKey } from '../util/paths.ts';
+import { commitSourceId, extractIds, redactCredentials } from './anchor.ts';
+
+/** Commit sources of a repository: every commit reachable from HEAD (since `since`), unless `limit` asks for fewer (D77). */
+export function commitSources(projectId: string, repo: ScopeItem, since: string | null, limit: number | null = null, notFrom: string | null = null): Source[] {
+  const readAt = new Date().toISOString();
+  return gitRecentCommits(repo.path, since, limit, notFrom).map((c) => {
+    const excerpt = `${c.subject}\n\nauthor: ${c.author}\nat: ${c.at}\nfiles:\n${c.files.map((f) => `  ${f}`).join('\n')}`;
+    const red = redactCredentials(excerpt);
+    return {
+      id: commitSourceId(repo.path, c.hash), projectId, title: `${c.hash.slice(0, 8)} ${c.subject.slice(0, 80)}`,
+      anchor: { kind: 'commit', repo: repo.path, commit: c.hash, ...(c.at ? { at: c.at } : {}) }, ids: extractIds(c.subject),
+      version: { fingerprint: fingerprint(excerpt), readAt, commit: c.hash }, excerpt: red.text, usedAs: null, usedAsBy: null,
+      availability: null, movedTo: null, scopeItemId: repo.id, hasCredential: red.found, bytes: Buffer.byteLength(excerpt),
+    };
+  });
+}
+
+export function statusSource(projectId: string, repo: ScopeItem): Source | null {
+  const st = gitStatus(repo.path);
+  if (!st) return null;
+  const readAt = new Date().toISOString();
+  const description = `git status of ${repo.path}`;
+  const excerpt = `branch: ${st.branch ?? '(detached)'}\nhead: ${st.head ?? '(none)'}\nuncommitted: ${st.dirty.length}\n${st.dirty.slice(0, 80).map((l) => `  ${l}`).join('\n')}${st.dirty.length > 80 ? `\n  …${st.dirty.length - 80} more` : ''}`;
+  return {
+    id: stableId('src', 'status', pathKey(repo.path)), projectId, title: `Repository status · ${repo.path.split(/[\\/]/).pop()}`,
+    anchor: { kind: 'status', description, at: readAt }, ids: [],
+    version: { fingerprint: fingerprint(excerpt), readAt, commit: st.head }, excerpt, usedAs: 'Status', usedAsBy: null,
+    availability: null, movedTo: null, scopeItemId: repo.id, hasCredential: false, bytes: Buffer.byteLength(excerpt),
+  };
+}