@xingular/harness 0.1.7 → 1.1.1

package/src/core/changes.ts

@@ -1,33 +0,0 @@
-// A note that something in a Wiki was written: a fact, a memory block, or a page. The memory
-// code calls `noteChange` after the file is in place; whoever wants to react listens. Listeners
-// run inline and must only take the note down: a write never waits for, or fails with, a listener.
-export interface Change {
-  /** The Wiki folder the entry is in. */
-  wiki: string
-  id: string
-  /** The file that was written. */
-  path: string
-  /** Its new contents, front matter included. */
-  text: string
-  actor: string
-  reason: string
-}
-
-type Listener = (change: Change) => void
-
-const listeners = new Set<Listener>()
-
-export function noteChange(change: Change): void {
-  for (const listener of listeners) {
-    try {
-      listener(change)
-    } catch {
-      // A listener must never break the write it is told about.
-    }
-  }
-}
-
-export function onChange(listener: Listener): () => void {
-  listeners.add(listener)
-  return () => void listeners.delete(listener)
-}

package/src/core/env.ts

@@ -1,27 +0,0 @@
-// What every harness module is given: where the data lives, and what the embedding application
-// knows that the harness does not.
-
-/** Names the harness shows but does not own. Every lookup may answer `null`. */
-export interface Directory {
-  /** An agent's display name. */
-  agentName(agentId: string): string | null
-  /** The agent a conversation belongs to, when the session id is not the agent's own id. */
-  sessionAgent(sessionId: string): string | null
-}
-
-/** The name used when an application gives none. */
-export const DEFAULT_PRODUCT_NAME = 'Xingular Harness'
-
-export const EMPTY_DIRECTORY: Directory = { agentName: () => null, sessionAgent: () => null }
-
-export interface HarnessEnv {
-  /** The data root: `wiki/`, `registry/`, `runs/`, `config/`, `index.sqlite`. */
-  root: string
-  directory: Directory
-  /** How the harness names itself to a model and in the Wiki it creates. */
-  productName: string
-}
-
-export function createEnv(root: string, options: Partial<Omit<HarnessEnv, 'root'>> = {}): HarnessEnv {
-  return { root, directory: options.directory ?? EMPTY_DIRECTORY, productName: options.productName ?? DEFAULT_PRODUCT_NAME }
-}

package/src/core/errors.ts

@@ -1,32 +0,0 @@
-/** A typed failure: a stable code, a message a person can read, and an optional hint on what to do next. */
-export class HarnessError extends Error {
-  readonly code: string
-  readonly retryHint: string | null
-
-  constructor(code: string, message: string, retryHint: string | null = null) {
-    super(message)
-    this.name = 'HarnessError'
-    this.code = code
-    this.retryHint = retryHint
-  }
-
-  withHint(hint: string): HarnessError {
-    return new HarnessError(this.code, this.message, hint)
-  }
-}
-
-export const invalid = (message: string): HarnessError => new HarnessError('invalid_request', message)
-export const notFound = (what: string): HarnessError => new HarnessError('not_found', `${what} was not found.`)
-
-export interface ErrorShape {
-  code: string
-  message: string
-  retryHint?: string | null
-}
-
-export function toErrorShape(error: unknown, fallbackCode = 'harness_error'): ErrorShape {
-  if (error instanceof HarnessError) return { code: error.code, message: error.message, retryHint: error.retryHint }
-  const code = (error as { code?: unknown } | null)?.code
-  if (error instanceof Error && typeof code === 'string' && code.startsWith('E')) return { code: 'io_error', message: error.message }
-  return { code: fallbackCode, message: error instanceof Error ? error.message : String(error) }
-}

package/src/core/frontmatter.ts

@@ -1,47 +0,0 @@
-// Markdown files with a YAML frontmatter block (`---` … `---`), used by Wiki pages, facts, blocks and registry items.
-import { parse as parseYaml, stringify } from 'yaml'
-
-import { HarnessError } from './errors'
-
-export function split(text: string): { yaml: string; body: string } | null {
-  const rest = text.startsWith('---\n') ? text.slice(4) : text.startsWith('---\r\n') ? text.slice(5) : null
-  if (rest === null) return null
-  const end = rest.indexOf('\n---')
-  if (end < 0) return null
-  return { yaml: rest.slice(0, end), body: rest.slice(end + 4).replace(/^[\r\n]+/, '') }
-}
-
-/** The frontmatter as a plain object and the body, or `null` when the block is missing or is not a mapping. */
-export function parse(text: string): { front: Record<string, unknown>; body: string } | null {
-  const parts = split(text)
-  if (!parts) return null
-  try {
-    const front = parseYaml(parts.yaml)
-    if (!front || typeof front !== 'object' || Array.isArray(front)) return null
-    return { front: front as Record<string, unknown>, body: parts.body }
-  } catch {
-    return null
-  }
-}
-
-/** The text after a readable frontmatter block, or the whole text when there is none. */
-export function bodyOf(text: string): string {
-  const parts = split(text)
-  if (!parts) return text
-  try {
-    parseYaml(parts.yaml)
-    return parts.body
-  } catch {
-    return text
-  }
-}
-
-export function serialize(front: Record<string, unknown>, body: string): string {
-  let yaml: string
-  try {
-    yaml = stringify(front, { lineWidth: 0 })
-  } catch (error) {
-    throw new HarnessError('invalid_data', error instanceof Error ? error.message : String(error))
-  }
-  return `---\n${yaml}---\n\n${body.trimEnd()}\n`
-}

package/src/core/fs.test.ts

@@ -1,38 +0,0 @@
-import { mkdtempSync, readdirSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { dirname, join } from 'node:path'
-import { expect, test } from 'vitest'
-
-import { parse, serialize } from './frontmatter'
-import { appendLine, readJson, readText, safeId, safeRelative, writeJson } from './fs'
-
-test('atomic write replaces contents', () => {
-  const path = join(mkdtempSync(join(tmpdir(), 'harness-')), 'nested/value.json')
-  writeJson(path, { a: 1 })
-  writeJson(path, { a: 2 })
-  expect(readJson<{ a: number }>(path)?.a).toBe(2)
-  expect(readdirSync(dirname(path))).toHaveLength(1)
-  expect(readJson(join(dirname(path), 'missing.json'))).toBeNull()
-})
-
-test('rejects unsafe ids and paths', () => {
-  expect(safeId('abc-123')).toBe('abc-123')
-  expect(() => safeId('../x')).toThrow()
-  expect(safeRelative('src/main.rs')).toBe('src/main.rs')
-  expect(() => safeRelative('../secret')).toThrow()
-  expect(() => safeRelative('/etc/passwd')).toThrow()
-})
-
-test('appends whole lines', () => {
-  const path = join(mkdtempSync(join(tmpdir(), 'harness-')), 'log.md')
-  appendLine(path, 'one')
-  appendLine(path, 'two')
-  expect(readText(path)).toBe('one\ntwo\n')
-})
-
-test('frontmatter round-trips', () => {
-  const text = serialize({ id: 'a', title: 'Has: a colon', tags: ['x'] }, 'Body\n\n')
-  expect(text.startsWith('---\n')).toBe(true)
-  expect(parse(text)).toEqual({ front: { id: 'a', title: 'Has: a colon', tags: ['x'] }, body: 'Body\n' })
-  expect(parse('no frontmatter')).toBeNull()
-})

package/src/core/fs.ts

@@ -1,92 +0,0 @@
-import { randomUUID } from 'node:crypto'
-import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeSync } from 'node:fs'
-import { basename, dirname, isAbsolute, join, normalize, sep } from 'node:path'
-
-import { HarnessError, invalid } from './errors'
-
-/** Writes through a temporary sibling file and renames it into place so readers never see a partial file. */
-export function atomicWrite(path: string, contents: string | Uint8Array): void {
-  const parent = dirname(path)
-  mkdirSync(parent, { recursive: true })
-  const temporary = join(parent, `.${basename(path)}.${randomUUID()}.tmp`)
-  const file = openSync(temporary, 'w')
-  try {
-    writeSync(file, contents as string)
-    fsyncSync(file)
-  } finally {
-    closeSync(file)
-  }
-  try {
-    renameSync(temporary, path)
-  } catch (error) {
-    rmSync(temporary, { force: true })
-    throw error
-  }
-}
-
-export function writeJson(path: string, value: unknown): void {
-  atomicWrite(path, `${JSON.stringify(value, null, 2)}\n`)
-}
-
-/** `null` when the file does not exist; a file that exists but does not parse is an error. */
-export function readJson<T>(path: string): T | null {
-  let text: string
-  try {
-    text = readFileSync(path, 'utf8')
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null
-    throw error
-  }
-  try {
-    return JSON.parse(text) as T
-  } catch (error) {
-    throw new HarnessError('invalid_data', `Stored data could not be read: ${error instanceof Error ? error.message : String(error)}`)
-  }
-}
-
-/** `readJson` for callers that treat an unreadable file like a missing one. */
-export function readJsonOr<T>(path: string, fallback: T): T {
-  try {
-    return readJson<T>(path) ?? fallback
-  } catch {
-    return fallback
-  }
-}
-
-export function readText(path: string): string | null {
-  try {
-    return readFileSync(path, 'utf8')
-  } catch {
-    return null
-  }
-}
-
-export function appendLine(path: string, line: string): void {
-  let next = readText(path) ?? ''
-  if (next && !next.endsWith('\n')) next += '\n'
-  atomicWrite(path, `${next}${line}\n`)
-}
-
-/** Accepts only IDs that are safe as a single path segment. */
-export function safeId(id: string): string {
-  if (id.length > 0 && id.length <= 128 && /^[A-Za-z0-9_-]+$/.test(id)) return id
-  throw invalid('Invalid identifier.')
-}
-
-/** Accepts a relative path that stays inside its base directory. */
-export function safeRelative(path: string): string {
-  const parts = path.split(/[\\/]/)
-  if (!path || isAbsolute(path) || parts.some((part) => part === '' || part === '.' || part === '..')) {
-    throw invalid('Path must stay inside the working directory.')
-  }
-  return normalize(path).split(sep).join('/')
-}
-
-/** Millisecond UTC timestamp, the format every record uses. */
-export function now(): string {
-  return new Date().toISOString()
-}
-
-export function newId(): string {
-  return randomUUID()
-}

package/src/core/index.ts

@@ -1,193 +0,0 @@
-// Derived SQLite index at `<data root>/index.sqlite`: full-text search over every Wiki entry
-// (pages, facts, blocks, registry skills/prompts/rules), links, sources, revisions, run
-// metadata, and recall passages. Markdown, raw sources, revision manifests, registry files, and
-// run files stay canonical; the index can always be deleted and rebuilt from them.
-import { copyFileSync, existsSync, readdirSync, rmSync } from 'node:fs'
-import { join } from 'node:path'
-import { DatabaseSync, type SQLInputValue } from 'node:sqlite'
-
-import { HarnessError } from './errors'
-
-/** Index migration 4: recall, the searchable record of conversations and runs. */
-const RECALL_SCHEMA = `CREATE TABLE recall_runs (run_id TEXT PRIMARY KEY, passages INTEGER NOT NULL, status TEXT NOT NULL);
-     CREATE VIRTUAL TABLE recall_fts USING fts5(run_id UNINDEXED, seq UNINDEXED, role UNINDEXED, at UNINDEXED,
-        mode UNINDEXED, session_id UNINDEXED, project_id UNINDEXED, text, tokenize = 'unicode61 remove_diacritics 2');`
-
-/** Ordered, append-only migrations. Each runs in one transaction; the file is backed up first. */
-export const MIGRATIONS: readonly string[] = [
-  // 1: initial schema
-  `CREATE TABLE pages (scope TEXT NOT NULL, id TEXT NOT NULL, title TEXT NOT NULL, type TEXT NOT NULL,
-        updated_at TEXT, path TEXT NOT NULL, source_ids TEXT NOT NULL, PRIMARY KEY (scope, id));
-     CREATE VIRTUAL TABLE pages_fts USING fts5(scope UNINDEXED, id UNINDEXED, title, body, links, sources,
-        tokenize = 'unicode61 remove_diacritics 2');
-     CREATE TABLE links (scope TEXT NOT NULL, from_id TEXT NOT NULL, to_id TEXT NOT NULL, type TEXT NOT NULL);
-     CREATE INDEX links_to ON links (scope, to_id);
-     CREATE TABLE sources (scope TEXT NOT NULL, id TEXT NOT NULL, name TEXT NOT NULL, imported_at TEXT, version INTEGER,
-        PRIMARY KEY (scope, id));
-     CREATE TABLE revisions (scope TEXT NOT NULL, page_id TEXT NOT NULL, id TEXT NOT NULL, created_at TEXT, actor TEXT,
-        PRIMARY KEY (scope, id));
-     CREATE TABLE runs (id TEXT PRIMARY KEY, project_id TEXT, mode TEXT, harness TEXT, session_type TEXT,
-        session_id TEXT, status TEXT, started_at TEXT, ended_at TEXT);
-     CREATE INDEX runs_session ON runs (session_id, started_at);`,
-  // 2: accounts and token usage per run
-  `ALTER TABLE runs ADD COLUMN account_id TEXT;
-     CREATE INDEX runs_account ON runs (account_id, started_at);
-     CREATE TABLE usage (run_id TEXT PRIMARY KEY, account_id TEXT, harness TEXT, model TEXT, day TEXT NOT NULL,
-        input_tokens INTEGER NOT NULL DEFAULT 0, output_tokens INTEGER NOT NULL DEFAULT 0);
-     CREATE INDEX usage_account ON usage (account_id, day);`,
-  // 3: one global Wiki; entries replace per-scope pages and include facts and registry items
-  `DROP TABLE IF EXISTS pages_fts; DROP TABLE IF EXISTS pages; DROP TABLE IF EXISTS links;
-     DROP TABLE IF EXISTS sources; DROP TABLE IF EXISTS revisions;
-     CREATE TABLE entries (id TEXT PRIMARY KEY, kind TEXT NOT NULL, title TEXT NOT NULL, type TEXT, path TEXT NOT NULL,
-        namespace TEXT NOT NULL, file TEXT NOT NULL, updated_at TEXT, source_ids TEXT NOT NULL);
-     CREATE VIRTUAL TABLE entries_fts USING fts5(id UNINDEXED, kind UNINDEXED, namespace UNINDEXED, title, body, links, sources,
-        tokenize = 'unicode61 remove_diacritics 2');
-     CREATE TABLE links (from_id TEXT NOT NULL, to_id TEXT NOT NULL, type TEXT NOT NULL);
-     CREATE INDEX links_to ON links (to_id);
-     CREATE TABLE sources (id TEXT PRIMARY KEY, name TEXT NOT NULL, imported_at TEXT, version INTEGER);
-     CREATE TABLE revisions (entry_id TEXT NOT NULL, id TEXT PRIMARY KEY, created_at TEXT, actor TEXT);
-     CREATE INDEX revisions_entry ON revisions (entry_id, created_at);`,
-  RECALL_SCHEMA,
-  // 5: a per-run summary cache for the embedding application's analytics
-  `CREATE TABLE run_stats (run_id TEXT PRIMARY KEY, session_id TEXT NOT NULL, version INTEGER NOT NULL, stats TEXT NOT NULL);
-     CREATE INDEX run_stats_session ON run_stats (session_id, version);`,
-  // 6: the agent that replied, so one agent's runs can be read across its sessions
-  `ALTER TABLE runs ADD COLUMN agent_id TEXT;
-     CREATE INDEX runs_agent ON runs (agent_id, started_at);
-     CREATE INDEX runs_started ON runs (started_at);`,
-  // 7: the per-account usage table goes
-  'DROP TABLE IF EXISTS usage;'
-]
-
-const connections = new Map<string, DatabaseSync>()
-
-export function dbPath(root: string): string {
-  return join(root, 'index.sqlite')
-}
-
-function sqlError(error: unknown): HarnessError {
-  return new HarnessError('index_error', error instanceof Error ? error.message : String(error), 'Settings → Projects and Storage → Repair index.')
-}
-
-function schemaVersion(database: DatabaseSync): number {
-  database.exec('CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);')
-  const row = database.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get() as { value?: string } | undefined
-  const version = Number.parseInt(row?.value ?? '', 10)
-  return Number.isInteger(version) && version >= 0 ? version : 0
-}
-
-/** Runs `work` inside one transaction, rolling back if it throws. */
-export function transaction<T>(database: DatabaseSync, work: () => T): T {
-  database.exec('BEGIN')
-  try {
-    const result = work()
-    database.exec('COMMIT')
-    return result
-  } catch (error) {
-    try {
-      database.exec('ROLLBACK')
-    } catch {
-      // The transaction is already gone.
-    }
-    throw error
-  }
-}
-
-/**
- * Applies pending migrations. The database file is copied first; if any migration fails, the
- * copy is restored and the error is reported.
- */
-export function migrate(path: string, migrations: readonly string[]): DatabaseSync {
-  let database: DatabaseSync
-  let current: number
-  try {
-    database = new DatabaseSync(path)
-    current = schemaVersion(database)
-  } catch (error) {
-    throw sqlError(error)
-  }
-  if (current >= migrations.length) return database
-  const backup = `${path.replace(/\.sqlite$/, '')}.sqlite.bak-v${current}`
-  const hadFile = existsSync(path) && current > 0
-  if (hadFile) {
-    try {
-      database.exec('PRAGMA wal_checkpoint(TRUNCATE);')
-    } catch {
-      // A checkpoint that cannot run leaves the copy slightly behind, which a rebuild repairs.
-    }
-    copyFileSync(path, backup)
-  }
-  for (let index = current; index < migrations.length; index += 1) {
-    try {
-      transaction(database, () => {
-        database.exec(migrations[index])
-        database.prepare("INSERT INTO meta (key, value) VALUES ('schema_version', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(String(index + 1))
-      })
-    } catch (error) {
-      database.close()
-      if (hadFile) copyFileSync(backup, path)
-      else rmSync(path, { force: true })
-      throw new HarnessError('migration_failed', `Index migration ${index + 1} failed and the previous index was restored: ${error instanceof Error ? error.message : String(error)}`)
-    }
-  }
-  return database
-}
-
-/** Runs `work` with the shared connection for this data root, opening and migrating it on first use. */
-export function withIndex<T>(root: string, work: (database: DatabaseSync) => T): T {
-  const path = dbPath(root)
-  let database = connections.get(path)
-  if (!database) {
-    database = migrate(path, MIGRATIONS)
-    try {
-      database.exec('PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON; PRAGMA busy_timeout = 5000;')
-    } catch (error) {
-      database.close()
-      throw sqlError(error)
-    }
-    connections.set(path, database)
-  }
-  try {
-    return work(database)
-  } catch (error) {
-    throw error instanceof HarnessError ? error : sqlError(error)
-  }
-}
-
-/** Closes this data root's connection, if one is open. */
-export function closeIndex(root: string): void {
-  const path = dbPath(root)
-  connections.get(path)?.close()
-  connections.delete(path)
-}
-
-/** Closes the connection and removes the index files; the next use rebuilds the schema. */
-export function deleteIndex(root: string): void {
-  closeIndex(root)
-  for (const suffix of ['', '-wal', '-shm']) rmSync(`${dbPath(root)}${suffix}`, { force: true })
-}
-
-export type Param = SQLInputValue
-
-export function all<T>(database: DatabaseSync, sql: string, ...params: Param[]): T[] {
-  return database.prepare(sql).all(...params) as T[]
-}
-
-export function run(database: DatabaseSync, sql: string, ...params: Param[]): void {
-  database.prepare(sql).run(...params)
-}
-
-/** Folder names under `<data root>/runs`. */
-export function runFolders(root: string): string[] {
-  try {
-    return readdirSync(join(root, 'runs'))
-  } catch {
-    return []
-  }
-}
-
-/** Turns free text into an FTS5 query: each word becomes a quoted prefix term. */
-export function ftsQuery(query: string): string | null {
-  const terms = query.split(/[^\p{Alphabetic}\p{N}]+/u).filter(Boolean).map((term) => `"${term.replaceAll('"', '')}"*`)
-  return terms.length ? terms.join(' ') : null
-}

package/src/core/path.test.ts

@@ -1,14 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { prependSearchPath } from './path'
-
-describe('search paths', () => {
-  it('uses Windows separators and keeps the inherited PATH key casing', () => {
-    expect(prependSearchPath('C:\\Harness\\bin', 'C:\\Windows\\System32;C:\\Node', { Path: 'C:\\Windows\\System32;C:\\Node' }, 'win32'))
-      .toEqual({ Path: 'C:\\Harness\\bin;C:\\Windows\\System32;C:\\Node' })
-  })
-
-  it('uses the platform default key when the environment has no PATH entry', () => {
-    expect(prependSearchPath('/harness/bin', '/usr/bin', {}, 'linux')).toEqual({ PATH: '/harness/bin:/usr/bin' })
-  })
-})

package/src/core/path.ts

@@ -1,79 +0,0 @@
-// Where executables are found. POSIX desktop apps may start with a minimal PATH, so the login
-// shell's PATH is resolved once. Windows keeps the inherited PATH and its native separator.
-import { execFileSync } from 'node:child_process'
-import { accessSync, constants, statSync } from 'node:fs'
-import { homedir } from 'node:os'
-import { delimiter, extname, isAbsolute, join } from 'node:path'
-
-let resolved: { platform: NodeJS.Platform; inherited: string; path: string } | null = null
-
-export function searchPath(): string {
-  const platform = process.platform
-  const pathKey = pathVariableName(process.env)
-  const inherited = process.env[pathKey] ?? ''
-  if (resolved?.platform === platform && resolved.inherited === inherited) return resolved.path
-  const separator = pathSeparator(platform)
-  const entries: string[] = []
-  if (platform !== 'win32') {
-    try {
-      const output = execFileSync(process.env.SHELL || '/bin/zsh', ['-ilc', 'printf %s "$PATH"'], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] })
-      // Interactive shells may print banners; the PATH is the last line.
-      entries.push(...(output.split('\n').filter(Boolean).at(-1) ?? '').split(separator))
-    } catch {
-      // The inherited PATH and the usual folders still apply.
-    }
-  }
-  entries.push(...inherited.split(separator))
-  if (platform !== 'win32') {
-    const home = homedir()
-    if (home) entries.push(...['.local/bin', '.bun/bin', '.npm-global/bin', '.cargo/bin'].map((folder) => join(home, folder)))
-    entries.push('/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin')
-  }
-  const path = [...new Set(entries.filter(Boolean))].join(separator)
-  resolved = { platform, inherited, path }
-  return path
-}
-
-/** The inherited PATH key, preserving Windows' existing capitalization. */
-export function pathVariableName(environment: NodeJS.ProcessEnv): string {
-  return Object.keys(environment).find((name) => name.toLowerCase() === 'path') ?? 'PATH'
-}
-
-/** A child environment with a directory prepended using the selected platform's PATH rules. */
-export function prependSearchPath(directory: string, existing: string, environment: NodeJS.ProcessEnv = process.env, platform: NodeJS.Platform = process.platform): Record<string, string> {
-  const values = [directory, existing].filter(Boolean)
-  return { [pathVariableName(environment)]: values.join(pathSeparator(platform)) }
-}
-
-function pathSeparator(platform: NodeJS.Platform): string {
-  return platform === 'win32' ? ';' : delimiter
-}
-
-function isExecutable(path: string): boolean {
-  try {
-    accessSync(path, process.platform === 'win32' ? constants.F_OK : constants.X_OK)
-    return statSync(path).isFile()
-  } catch {
-    return false
-  }
-}
-
-/** The executable `name` resolves to: itself when absolute, else the first match on the search path. */
-export function findBinary(name: string): string | null {
-  const platform = process.platform
-  const suffixes = platform === 'win32' && !extname(name)
-    ? (process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)
-    : []
-  const names = [name, ...suffixes.map((suffix) => `${name}${suffix}`)]
-  if (isAbsolute(name)) {
-    for (const candidate of names) if (isExecutable(candidate)) return candidate
-    return null
-  }
-  for (const directory of searchPath().split(pathSeparator(platform))) {
-    for (const candidateName of names) {
-      const candidate = join(directory, candidateName)
-      if (isExecutable(candidate)) return candidate
-    }
-  }
-  return null
-}

package/src/core/projects.ts

@@ -1,90 +0,0 @@
-// Projects: named working folders, each with a Wiki namespace (`/projects/<slug>`). The harness
-// reads `<data root>/projects.json`; the embedding application adds, renames, and removes them.
-import { existsSync } from 'node:fs'
-import { join } from 'node:path'
-
-import { notFound } from './errors'
-import { readJson } from './fs'
-import { newId } from './fs'
-
-interface ProjectRecord {
-  id: string
-  name: string
-  rootPath: string
-  autoMaintenance: boolean
-  createdAt: string
-  /** Stable Wiki namespace segment; kept when the project is renamed. */
-  slug?: string
-}
-
-export interface Project {
-  id: string
-  name: string
-  rootPath: string
-  isGitRepository: boolean
-  autoMaintenance: boolean
-  createdAt: string
-  slug: string
-  /** `/projects/<slug>`: where this project's pages live in the Wiki. */
-  wikiNamespace: string
-}
-
-/** Same rule as the Wiki's page slugs, kept here so `core` does not depend on `memory`. */
-export function slugify(text: string): string {
-  let value = ''
-  for (const character of text.toLowerCase()) {
-    if (/^[a-z0-9]$/.test(character)) value += character
-    else if (value && !value.endsWith('-')) value += '-'
-  }
-  value = value.replace(/^-+|-+$/g, '').slice(0, 60)
-  return value || `page-${newId().slice(0, 8)}`
-}
-
-export function uniqueSlug(name: string, taken: readonly string[]): string {
-  const slug = slugify(name)
-  const base = slug.startsWith('page-') ? 'project' : slug
-  let candidate = base
-  for (let counter = 2; taken.includes(candidate); counter += 1) candidate = `${base}-${counter}`
-  return candidate
-}
-
-function load(root: string): ProjectRecord[] {
-  const records = readJson<ProjectRecord[]>(join(root, 'projects.json')) ?? []
-  // Records without a slug get a unique one derived from the name, in list order, so the result
-  // is the same on every read until the application persists it.
-  const taken = records.map((record) => record.slug ?? '').filter(Boolean)
-  for (const record of records) {
-    if (record.slug) continue
-    record.slug = uniqueSlug(record.name, taken)
-    taken.push(record.slug)
-  }
-  return records
-}
-
-export function listProjects(root: string): Project[] {
-  return load(root).map((record) => ({
-    id: record.id,
-    name: record.name,
-    rootPath: record.rootPath,
-    isGitRepository: existsSync(join(record.rootPath, '.git')),
-    autoMaintenance: record.autoMaintenance,
-    createdAt: record.createdAt,
-    slug: record.slug!,
-    wikiNamespace: `/projects/${record.slug}`
-  }))
-}
-
-/** `listProjects` for callers that treat an unreadable registry like an empty one. */
-export function projectsOrNone(root: string): Project[] {
-  try {
-    return listProjects(root)
-  } catch {
-    return []
-  }
-}
-
-export function findProject(root: string, projectId: string): Project {
-  const project = listProjects(root).find((entry) => entry.id === projectId)
-  if (!project) throw notFound('Project')
-  return project
-}