@xingular/harness 0.0.0-stage → 0.1.1

package/src/core/env.ts

@@ -0,0 +1,27 @@
+// 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

@@ -0,0 +1,32 @@
+/** 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

@@ -0,0 +1,47 @@
+// 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

@@ -0,0 +1,38 @@
+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

@@ -0,0 +1,92 @@
+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

@@ -0,0 +1,193 @@
+// 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.ts

@@ -0,0 +1,45 @@
+// Where executables are found. A desktop application starts with a minimal PATH, so the login
+// shell's PATH is resolved once and used for everything the harness launches.
+import { execFileSync } from 'node:child_process'
+import { accessSync, constants, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { delimiter, isAbsolute, join } from 'node:path'
+
+let resolved: string | null = null
+
+export function searchPath(): string {
+  if (resolved !== null) return resolved
+  const entries: string[] = []
+  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(delimiter))
+  } catch {
+    // The inherited PATH and the usual folders still apply.
+  }
+  entries.push(...(process.env.PATH ?? '').split(delimiter))
+  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')
+  resolved = [...new Set(entries.filter(Boolean))].join(delimiter)
+  return resolved
+}
+
+function isExecutable(path: string): boolean {
+  try {
+    accessSync(path, 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 {
+  if (isAbsolute(name)) return isExecutable(name) ? name : null
+  for (const directory of searchPath().split(delimiter)) {
+    const candidate = join(directory, name)
+    if (isExecutable(candidate)) return candidate
+  }
+  return null
+}

package/src/core/projects.ts

@@ -0,0 +1,90 @@
+// 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
+}

package/src/core/text.ts

@@ -0,0 +1,39 @@
+// Text helpers that count Unicode characters, not UTF-16 units, so budgets and cuts agree across languages.
+
+export function charCount(text: string): number {
+  let count = 0
+  for (const _ of text) count += 1
+  return count
+}
+
+export function takeChars(text: string, count: number): string {
+  if (text.length <= count) return text
+  let taken = 0
+  let end = 0
+  for (const character of text) {
+    if (taken >= count) break
+    taken += 1
+    end += character.length
+  }
+  return text.slice(0, end)
+}
+
+/** Lines without their terminators; a final newline does not add an empty last line. */
+export function lines(text: string): string[] {
+  if (!text) return []
+  const parts = text.split('\n')
+  if (parts[parts.length - 1] === '') parts.pop()
+  return parts.map((line) => (line.endsWith('\r') ? line.slice(0, -1) : line))
+}
+
+/** Orders file paths segment by segment, so a folder sorts before a sibling whose name extends it. */
+export function comparePaths(left: string, right: string): number {
+  const a = left.split('/')
+  const b = right.split('/')
+  for (let index = 0; index < Math.min(a.length, b.length); index += 1) {
+    if (a[index] !== b[index]) return a[index] < b[index] ? -1 : 1
+  }
+  return a.length - b.length
+}
+
+export const compareText = (left: string, right: string): number => (left < right ? -1 : left > right ? 1 : 0)