genesis-compiler 1.0.0 → 1.2.0

package/src/index/stack.js

@@ -0,0 +1,302 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { syncProjectSkills } from './agent-skills.js';
+import { GenesisError } from './errors.js';
+import { readBuiltinStackCatalog } from './stack-catalog.js';
+import { parseStackCommandLines } from './stack-command.js';
+import { resolveStackPieces } from './stack-composition.js';
+import {
+  composeStackEnvironmentFiles,
+  parseStackEnvironmentFileLines,
+} from './stack-environment-files.js';
+import { composeStackLaunchTargets, parseStackLaunchLines } from './stack-launch.js';
+import {
+  composeStackWorkspaceSetup,
+  parseStackWorkspaceSetupLines,
+} from './stack-workspace-setup.js';
+import {
+  applyStackPieceCustomization,
+  normalizeStackPieceId,
+  parseStackPieceCustomizationSource,
+} from './stack-piece.js';
+import { STACK_PATH } from './paths.js';
+import { sha256, stableJson, writeFileAtomic } from './utils.js';
+
+const COMPONENT_LINE = /^- `([a-z0-9]+(?:-[a-z0-9]+)*)`$/u;
+export const EMPTY_STACK_SOURCE = '# Stack\n\n## Components\n';
+const STACK_SECTIONS = new Set([
+  'Components',
+  'Environment files',
+  'Workspace setup',
+  'Commands',
+  'Launch',
+]);
+const STACK_CUSTOMIZATION_ROOT = 'genesis/stack';
+
+function parseSections(source) {
+  const lines = source.replace(/\r\n?/gu, '\n').split('\n');
+  if (lines.filter((line) => line.trim() === '# Stack').length !== 1) {
+    throw new GenesisError('STACK_INVALID', `${STACK_PATH} needs exactly one \`# Stack\` title.`);
+  }
+  const sections = new Map();
+  let current = null;
+  for (const line of lines) {
+    const heading = line.match(/^##\s+(.+?)\s*$/u);
+    if (heading) {
+      if (!STACK_SECTIONS.has(heading[1]) || sections.has(heading[1])) {
+        throw new GenesisError('STACK_INVALID', `Unknown or duplicate Stack section: ${heading[1]}.`);
+      }
+      current = [];
+      sections.set(heading[1], current);
+    } else if (current) current.push(line);
+    else if (line.trim() && line.trim() !== '# Stack') {
+      throw new GenesisError('STACK_INVALID', `${STACK_PATH} contains content outside a Stack section.`);
+    }
+  }
+  return sections;
+}
+
+function componentIds(sections) {
+  const componentLines = (sections.get('Components') || []).filter((line) => line.trim());
+  const ids = componentLines.map((line) => {
+    const match = line.trim().match(COMPONENT_LINE);
+    if (!match) {
+      throw new GenesisError(
+        'STACK_INVALID',
+        'Each Stack component must be exactly one bullet containing its backticked component id.',
+        { path: STACK_PATH, observed: line },
+      );
+    }
+    return normalizeStackPieceId(match[1]);
+  });
+  if (new Set(ids).size !== ids.length) {
+    throw new GenesisError('STACK_INVALID', 'Stack contains a duplicate component id.', { path: STACK_PATH });
+  }
+  return ids;
+}
+
+function knownPieces(resolution) {
+  if (resolution.unknown.length > 0) {
+    throw new GenesisError(
+      'STACK_PIECE_UNKNOWN',
+      `No installed Stack piece exists for ${resolution.unknown.join(', ')}.`,
+      { components: resolution.unknown },
+    );
+  }
+  return resolution.pieces;
+}
+
+function withoutOuterBlankLines(lines = []) {
+  const result = [...lines];
+  while (result[0]?.trim() === '') result.shift();
+  while (result.at(-1)?.trim() === '') result.pop();
+  return result;
+}
+
+function renderStack({
+  commandLines = [],
+  componentIds: componentIdsValue,
+  environmentFileLines = null,
+  launchLines = null,
+  workspaceSetupLines = null,
+}) {
+  return [
+    '# Stack',
+    '',
+    '## Components',
+    ...componentIdsValue.map((id) => `- \`${id}\``),
+    ...(environmentFileLines === null
+      ? []
+      : ['', '## Environment files', '', ...withoutOuterBlankLines(environmentFileLines)]),
+    ...(workspaceSetupLines === null
+      ? []
+      : ['', '## Workspace setup', '', ...withoutOuterBlankLines(workspaceSetupLines)]),
+    ...(commandLines.length > 0 ? ['', '## Commands', ...commandLines] : []),
+    ...(launchLines === null ? [] : ['', '## Launch', '', ...withoutOuterBlankLines(launchLines)]),
+    '',
+  ].join('\n');
+}
+
+export async function addStackPieces({ pieces, projectRoot }) {
+  if (!Array.isArray(pieces) || pieces.length === 0) {
+    throw new GenesisError('STACK_PIECE_REQUIRED', 'genesis stack add requires at least one component.');
+  }
+  const requested = [...new Set(pieces.map((piece) => normalizeStackPieceId(
+    piece,
+    { code: 'STACK_PIECE_UNKNOWN' },
+  )))];
+  const location = path.join(projectRoot, STACK_PATH);
+  let source;
+  try {
+    source = await readFile(location, 'utf8');
+  } catch (error) {
+    if (!['ENOENT', 'ENOTDIR'].includes(error?.code)) throw error;
+    source = EMPTY_STACK_SOURCE;
+  }
+  const sections = parseSections(source);
+  const existing = componentIds(sections);
+  const catalog = await readBuiltinStackCatalog();
+  const selected = (await Promise.all(
+    knownPieces(resolveStackPieces({ catalog, existing, requested }))
+      .map((piece) => customizePiece(projectRoot, piece)),
+  )).map(({ id }) => id);
+  const commandLines = parseStackCommandLines(sections.get('Commands') || [], { path: STACK_PATH })
+    .map(({ label, argv }) => `- Verify \`${label}\`: ${argv.map((value) => `\`${value}\``).join(' ')}`);
+  const environmentFileLines = sections.has('Environment files')
+    ? sections.get('Environment files')
+    : null;
+  parseStackEnvironmentFileLines(
+    environmentFileLines === null ? undefined : environmentFileLines,
+    { path: STACK_PATH },
+  );
+  const launchLines = sections.has('Launch') ? sections.get('Launch') : null;
+  parseStackLaunchLines(launchLines === null ? undefined : launchLines, { path: STACK_PATH });
+  const workspaceSetupLines = sections.has('Workspace setup')
+    ? sections.get('Workspace setup')
+    : null;
+  parseStackWorkspaceSetupLines(
+    workspaceSetupLines === null ? undefined : workspaceSetupLines,
+    { path: STACK_PATH },
+  );
+  const rendered = renderStack({
+    commandLines,
+    componentIds: selected,
+    environmentFileLines,
+    launchLines,
+    workspaceSetupLines,
+  });
+  const stackChanged = rendered !== source;
+  if (stackChanged) await writeFileAtomic(location, rendered);
+  const skills = await syncProjectSkills({ projectRoot, stack: await readStack(projectRoot) });
+  const changedFiles = [
+    ...(stackChanged ? [STACK_PATH] : []),
+    ...skills.changedFiles,
+  ].sort();
+  return {
+    status: changedFiles.length > 0 ? 'updated' : 'unchanged',
+    summary: stackChanged
+      ? `Selected Stack components: ${selected.join(', ')}.`
+      : 'Every requested Stack component and Agent Skill is already selected.',
+    components: selected,
+    changedFiles,
+    diagnostics: skills.diagnostics,
+  };
+}
+
+function distinctCommands(commands) {
+  const seen = new Set();
+  return commands.filter((command) => {
+    const key = JSON.stringify([command.label, command.argv]);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function resourceDeclarations(components) {
+  return components.flatMap((piece) => piece.resources.map((resource) => ({
+    component: piece.id,
+    resource,
+  })));
+}
+
+function composedProse(components, field) {
+  return components
+    .map((piece) => piece[field] || '')
+    .filter(Boolean)
+    .join('\n\n');
+}
+
+async function customizePiece(projectRoot, piece) {
+  const relative = `${STACK_CUSTOMIZATION_ROOT}/${piece.id}.md`;
+  let source;
+  try {
+    source = await readFile(path.join(projectRoot, relative), 'utf8');
+  } catch (error) {
+    if (['ENOENT', 'ENOTDIR'].includes(error?.code)) return piece;
+    throw error;
+  }
+  return applyStackPieceCustomization(piece, parseStackPieceCustomizationSource(source, {
+    expectedId: piece.id,
+    path: relative,
+  }));
+}
+
+export async function readStack(projectRoot) {
+  const location = path.join(projectRoot, STACK_PATH);
+  let source;
+  try {
+    source = await readFile(location, 'utf8');
+  } catch (error) {
+    if (['ENOENT', 'ENOTDIR'].includes(error?.code)) {
+      throw new GenesisError(
+        'STACK_REQUIRED',
+        `Genesis requires ${STACK_PATH}. Run genesis init first.`,
+      );
+    }
+    throw error;
+  }
+  const sections = parseSections(source);
+  const catalog = await readBuiltinStackCatalog();
+  const components = await Promise.all(knownPieces(resolveStackPieces({
+    catalog,
+    requested: componentIds(sections),
+  })).map((piece) => customizePiece(projectRoot, piece)));
+  const projectCommands = parseStackCommandLines(
+    sections.get('Commands') || [],
+    { path: STACK_PATH },
+  ).map(({ line: _line, ...command }) => command);
+  const componentCommands = components.flatMap((piece) => piece.commands);
+  const commands = distinctCommands(projectCommands.length > 0 ? projectCommands : componentCommands);
+  const resources = resourceDeclarations(components);
+  const projectEnvironmentFiles = parseStackEnvironmentFileLines(
+    sections.has('Environment files') ? sections.get('Environment files') : undefined,
+    { path: STACK_PATH },
+  );
+  const environmentFiles = composeStackEnvironmentFiles(components, projectEnvironmentFiles);
+  const projectLaunch = parseStackLaunchLines(
+    sections.has('Launch') ? sections.get('Launch') : undefined,
+    { path: STACK_PATH },
+  );
+  const launchTargets = composeStackLaunchTargets(components, projectLaunch);
+  const projectWorkspaceSetup = parseStackWorkspaceSetupLines(
+    sections.has('Workspace setup') ? sections.get('Workspace setup') : undefined,
+    { path: STACK_PATH },
+  );
+  const workspaceSetup = composeStackWorkspaceSetup(components, projectWorkspaceSetup);
+  return {
+    path: STACK_PATH,
+    identityHash: sha256(stableJson({
+      components: components.map(({ id }) => id),
+      commands: commands.map(({ label, argv }) => ({ label, argv })),
+      environmentFiles,
+      launchTargets,
+      resources,
+      workspaceSetup,
+    })),
+    components,
+    commands,
+    environmentFiles,
+    launchTargets,
+    workspaceSetup,
+    resources,
+    guidance: composedProse(components, 'guidance'),
+    deslop: composedProse(components, 'deslop'),
+  };
+}
+
+export function stackPromptContext(stack) {
+  return {
+    components: stack.components.map((piece) => ({
+      id: piece.id,
+      description: piece.description,
+      ...(piece.guidance ? { guidance: piece.guidance } : {}),
+      requires: piece.requires,
+    })),
+    verifyCommands: stack.commands.map(({ label, argv }) => ({ label, argv })),
+    environmentFiles: stack.environmentFiles,
+    launchTargets: stack.launchTargets,
+    workspaceSetup: stack.workspaceSetup,
+  };
+}

package/src/index/utils.js

@@ -0,0 +1,85 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants as fsConstants } from 'node:fs';
+import { lstat, mkdir, open, readlink, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { fail } from './errors.js';
+
+export function normalizeSource(source) {
+  return String(source).replace(/\r\n?/gu, '\n');
+}
+
+export function sha256(source) {
+  return `sha256:${createHash('sha256').update(source).digest('hex')}`;
+}
+
+function stable(value) {
+  if (Array.isArray(value)) return value.map(stable);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stable(value[key])]));
+  }
+  return value;
+}
+
+export function stableJson(value) {
+  return `${JSON.stringify(stable(value), null, 2)}\n`;
+}
+
+export function uniqueSorted(values = []) {
+  return [...new Set(values)].sort();
+}
+
+export async function writeFileAtomic(filePath, source, { mode = 0o644 } = {}) {
+  const temporary = `${filePath}.${randomUUID()}.tmp`;
+  await mkdir(path.dirname(filePath), { recursive: true });
+  try {
+    await writeFile(temporary, source, { flag: 'wx', mode });
+    await rename(temporary, filePath);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}
+
+function toPosix(value) {
+  return value.split(path.sep).join('/');
+}
+
+export function normalizeRelative(value) {
+  const source = String(value);
+  if ((path.sep !== '\\' && source.includes('\\')) || source.includes('\0')) {
+    fail('PROJECT_PATH_OUTSIDE_ROOT', `Path is not canonical: ${value}`, { path: value });
+  }
+  const normalized = path.posix.normalize(toPosix(source).replace(/^\.\//u, ''));
+  if (
+    normalized === '..'
+    || normalized.startsWith('../')
+    || path.posix.isAbsolute(normalized)
+  ) {
+    fail('PROJECT_PATH_OUTSIDE_ROOT', `Path is outside the project root: ${value}`, { path: value });
+  }
+  return normalized === '.' ? '' : normalized;
+}
+
+export async function pathState(filePath) {
+  let handle;
+  try {
+    const info = await lstat(filePath);
+    if (info.isSymbolicLink()) {
+      return { exists: true, symlink: true, mode: 0o120000, hash: sha256(await readlink(filePath)) };
+    }
+    if (!info.isFile()) return { exists: true, special: true, mode: null, hash: null };
+    handle = await open(filePath, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW || 0));
+    const content = await handle.readFile();
+    return {
+      exists: true,
+      hash: sha256(content),
+      mode: (info.mode & 0o111) === 0 ? 0o100644 : 0o100755,
+    };
+  } catch (error) {
+    if (error?.code === 'ELOOP') return { exists: true, symlink: true, mode: null, hash: null };
+    if (['ENOENT', 'ENOTDIR'].includes(error?.code)) return { exists: false, hash: null, mode: null };
+    throw error;
+  } finally {
+    await handle?.close().catch(() => {});
+  }
+}

package/src/index/verification.js

@@ -0,0 +1,77 @@
+import { runProcess } from './process.js';
+import { asDiagnostic } from './errors.js';
+import { gitContext } from './git.js';
+import { clearVerification, writeVerification } from './project-state.js';
+import { missingStackResources } from './stack-preflight.js';
+import { readStack } from './stack.js';
+
+async function emit(onEvent, event) {
+  try { await onEvent?.(event); } catch { /* Progress observers do not control verification. */ }
+}
+
+export async function verifyProject({
+  environment = process.env,
+  onEvent,
+  processRunner = runProcess,
+  projectRoot,
+} = {}) {
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  const stack = await readStack(root);
+  const missing = missingStackResources({ environment, resources: stack.resources });
+  if (missing.length > 0) {
+    return {
+      status: 'blocked',
+      summary: missing.map(({ message }) => message).join(' '),
+      commands: [],
+      diagnostics: missing,
+    };
+  }
+  if (stack.commands.length === 0) {
+    return {
+      status: 'unconfigured',
+      summary: 'The selected Stack declares no verification commands.',
+      commands: [],
+      diagnostics: [],
+    };
+  }
+
+  await clearVerification(root);
+  try {
+    const commands = [];
+    for (const command of stack.commands) {
+      await emit(onEvent, {
+        type: 'genesis.verification',
+        code: 'VERIFICATION_STARTED',
+        message: `Verifying: ${command.label}.`,
+        details: { label: command.label, argv: command.argv },
+      });
+      await processRunner(command.argv[0], command.argv.slice(1), {
+        cwd: root,
+        maxBytes: 32 * 1024 * 1024,
+        code: 'VERIFICATION_FAILED',
+      });
+      await emit(onEvent, {
+        type: 'genesis.verification',
+        code: 'VERIFICATION_COMPLETED',
+        message: `Verification passed: ${command.label}.`,
+        details: { label: command.label, argv: command.argv },
+      });
+      commands.push({ label: command.label, argv: command.argv });
+    }
+    const evidence = await writeVerification({ projectRoot: root, stack });
+    return {
+      status: 'passed',
+      summary: `Passed ${commands.length} declared verification command${commands.length === 1 ? '' : 's'}.`,
+      commands,
+      evidence,
+      diagnostics: [],
+    };
+  } catch (error) {
+    return {
+      status: 'failed',
+      summary: error.message,
+      commands: [],
+      diagnostics: [asDiagnostic(error)],
+    };
+  }
+}

package/src/index/workspace-setup.js

@@ -0,0 +1,55 @@
+import { access } from 'node:fs/promises';
+import path from 'node:path';
+
+import { gitContext } from './git.js';
+import { readStack } from './stack.js';
+import { sha256, stableJson, uniqueSorted } from './utils.js';
+
+/** Read the Stack's workspace preparation recipe without executing it. */
+export async function inspectProjectWorkspaceSetup({
+  projectRoot,
+} = {}) {
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  const stack = await readStack(root);
+  const diagnostics = [...stack.workspaceSetup.diagnostics];
+  if (diagnostics.length === 0) {
+    const waitingFor = [];
+    for (const step of stack.workspaceSetup.steps) {
+      if (!step.readyWhen) continue;
+      try {
+        await access(path.join(root, step.readyWhen));
+      } catch (error) {
+        if (!['ENOENT', 'ENOTDIR'].includes(error?.code)) throw error;
+        waitingFor.push(step.readyWhen);
+      }
+    }
+    if (waitingFor.length > 0) {
+      const paths = uniqueSorted(waitingFor);
+      diagnostics.push({
+        code: 'STACK_WORKSPACE_SETUP_WAITING',
+        message: `Workspace setup is waiting for project ${paths.length === 1 ? 'path' : 'paths'}: ${paths.join(', ')}.`,
+        details: { paths },
+      });
+    }
+  }
+  const waiting = diagnostics.some(({ code }) => code === 'STACK_WORKSPACE_SETUP_WAITING');
+  const blocked = diagnostics.some(({ code }) => code !== 'STACK_WORKSPACE_SETUP_WAITING');
+  let status = 'unconfigured';
+  if (blocked) status = 'blocked';
+  else if (!waiting && stack.workspaceSetup.steps.length > 0) status = 'ready';
+  const recipeHash = status === 'ready'
+    ? sha256(stableJson({ version: 1, steps: stack.workspaceSetup.steps }))
+    : '';
+  return {
+    status,
+    stackHash: stack.identityHash,
+    recipeHash,
+    components: stack.components.map(({ id }) => id),
+    source: stack.workspaceSetup.source,
+    runtimeRequirements: uniqueSorted(
+      stack.workspaceSetup.steps.flatMap((step) => step.runtimeRequirements),
+    ),
+    steps: stack.workspaceSetup.steps,
+    diagnostics,
+  };
+}

package/src/index.js

@@ -0,0 +1,102 @@
+import path from 'node:path';
+
+import { checkProject } from './index/check.js';
+import { buildProjectIndex } from './index/code-index.js';
+import { contextForProjectPaths } from './index/context.js';
+import { generateProjectPrompt } from './index/prompt.js';
+import { initializeProject } from './index/init.js';
+import { installCodexPlugin } from './index/codex-plugin.js';
+import { inspectProjectEnvironment } from './index/environment-files.js';
+import { inspectProjectLaunch } from './index/launch.js';
+import { listBuiltinStackPieces } from './index/stack-catalog.js';
+import { addStackPieces } from './index/stack.js';
+import { verifyProject } from './index/verification.js';
+import { inspectProjectWorkspaceSetup } from './index/workspace-setup.js';
+
+function withIndexResult(result, index) {
+  const changedFiles = [...new Set([...result.changedFiles, ...index.changedFiles])].sort();
+  const refreshedOnly = result.status === 'unchanged' && index.changedFiles.length > 0;
+  return {
+    ...result,
+    status: changedFiles.length > 0 ? 'updated' : result.status,
+    summary: refreshedOnly ? `${result.summary} Refreshed the City indexes.` : result.summary,
+    changedFiles,
+    diagnostics: [...(result.diagnostics || []), ...index.diagnostics],
+  };
+}
+
+async function initializeWithIndex(projectRoot) {
+  const initialized = await initializeProject({ projectRoot });
+  const index = await buildProjectIndex({ projectRoot });
+  return withIndexResult(initialized, index);
+}
+
+export function initialize({ projectRoot = process.cwd() } = {}) {
+  return initializeWithIndex(projectRoot);
+}
+
+export async function adoptProject({ projectRoot = process.cwd(), request = '' } = {}) {
+  const initialized = await initializeWithIndex(projectRoot);
+  const description = await generateProjectPrompt({
+    projectRoot,
+    request,
+    task: 'describe',
+  });
+  return {
+    status: 'ready',
+    summary: initialized.status === 'updated'
+      ? 'Adopted Genesis in this existing project.'
+      : 'Genesis is already initialized for this project.',
+    changedFiles: initialized.changedFiles,
+    prompt: description.prompt,
+    warnings: description.warnings,
+    guidance: 'Follow the generated description prompt now. Genesis does not start another agent.',
+  };
+}
+
+export function installCodex({ environment = process.env } = {}) {
+  return installCodexPlugin({ environment });
+}
+
+export async function addStack({ pieces, projectRoot = process.cwd() } = {}) {
+  const root = path.resolve(projectRoot);
+  const selected = await addStackPieces({ pieces, projectRoot: root });
+  const index = await buildProjectIndex({ projectRoot: root });
+  return withIndexResult(selected, index);
+}
+
+export function listStackPieces() {
+  return listBuiltinStackPieces();
+}
+
+export function inspectLaunch(options) {
+  return inspectProjectLaunch(options);
+}
+
+export function inspectEnvironment(options) {
+  return inspectProjectEnvironment(options);
+}
+
+export function inspectWorkspaceSetup(options) {
+  return inspectProjectWorkspaceSetup(options);
+}
+
+export function generatePrompt(options) {
+  return generateProjectPrompt(options);
+}
+
+export function getContext({ paths, projectRoot = process.cwd() } = {}) {
+  return contextForProjectPaths({ paths, projectRoot });
+}
+
+export function indexCodebase({ projectRoot = process.cwd(), queries = [], write = true } = {}) {
+  return buildProjectIndex({ projectRoot, queries, write });
+}
+
+export function verify(options) {
+  return verifyProject(options);
+}
+
+export function check(options) {
+  return checkProject(options);
+}

package/stacks/pieces/cpp.md

@@ -0,0 +1,22 @@
+# Stack piece: cpp
+
+## Description
+
+C and C++ translation-unit, header, callable, ownership, build, and test conventions.
+
+## Requires
+
+- Nothing.
+
+## Indexers
+
+- `cpp`
+
+## Deslop
+
+- Preserve public header boundaries, ABI expectations, build configuration,
+  const correctness, lifetime ownership, and the codebase's C or C++ level.
+- Keep file-local helpers internal and near their callers. Consolidate repeated
+  allocation, cleanup, conversion, and error paths with explicit ownership.
+- Remove unused wrappers, speculative templates, duplicate overload plumbing,
+  and abstractions that obscure control flow without protecting a real boundary.

package/stacks/pieces/csharp.md

@@ -0,0 +1,22 @@
+# Stack piece: csharp
+
+## Description
+
+C# namespace, public type, dependency, lifecycle, and test conventions.
+
+## Requires
+
+- Nothing.
+
+## Indexers
+
+- `csharp`
+
+## Deslop
+
+- Preserve established namespaces, public contracts, dependency injection,
+  async ownership, disposal, nullable annotations, and project conventions.
+- Keep private helpers with their owning type. Consolidate repeated mapping,
+  validation, and error translation at an existing application boundary.
+- Remove redundant service wrappers, interfaces with no useful substitution
+  boundary, and extension methods that only rename direct framework behavior.

package/stacks/pieces/go.md

@@ -0,0 +1,22 @@
+# Stack piece: go
+
+## Description
+
+Go package, exported callable, interface, concurrency, resource, and test conventions.
+
+## Requires
+
+- Nothing.
+
+## Indexers
+
+- `go`
+
+## Deslop
+
+- Preserve package ownership, exported APIs, context propagation, error
+  wrapping, goroutine lifetime, and standard Go tooling conventions.
+- Keep unexported helpers close to their caller. Consolidate repeated setup,
+  validation, cleanup, and conversion only at a clear package boundary.
+- Remove unnecessary interfaces, constructor wrappers, channels, and generic
+  helpers that make direct control flow harder to follow.