gstack/lib/cso/preparation.ts

/** Inert dependency inspection. Nothing in this module invokes a package manager.
 * Commands are descriptions for the constrained runner, never host commands.
 */
import { createHash } from 'node:crypto';
import { lstatSync, readFileSync, realpathSync } from 'node:fs';
import { isAbsolute, relative, resolve, sep } from 'node:path';

export type CsoStack = 'node' | 'bun' | 'python' | 'rails';
export interface PreparationPrerequisite {
  code: string;
  message: string;
  path?: string;
}
export interface PreparationCommand {
  executable: string;
  args: string[];
  cwd: '/metadata' | '/work' | '/archives';
  env: Record<string, string>;
}
export interface PreparationInput {
  kind: 'public' | 'local';
  name: string;
  version: string;
  url?: string;
  path?: string;
  integrity?: string;
  integritySource?: 'lock' | 'registry-on-acquisition';
  platform?: string;
}
export interface PreparationPlan {
  schemaVersion: 1;
  stack: CsoStack;
  /** Ready means metadata is admissible; runtime and acquisition admission are separate. */
  status: 'ready' | 'prerequisites';
  prerequisites: PreparationPrerequisite[];
  metadata: Array<{ path: string; content: string; sha256: string }>;
  inputs: PreparationInput[];
  acquisition: PreparationCommand[];
  offline: PreparationCommand[];
  registryHosts: string[];
  runtimeProfile: string;
  runtimeRequirements: Record<string, string>;
  transformations: Array<{ path: string; reason: string; phase: 'acquisition' | 'execution' }>;
  database?: {
    supported: Array<'sqlite' | 'postgresql'>;
    selected: 'sqlite' | 'postgresql' | null;
    connections: string[];
    requiresSyntheticConfiguration: true;
  };
}

const MAX_METADATA = 8 * 1024 * 1024;
const MAX_PACKAGES = 25_000;
const MANIFEST_FIELDS = [
  'name',
  'version',
  'private',
  'dependencies',
  'devDependencies',
  'optionalDependencies',
  'peerDependencies',
  'peerDependenciesMeta',
  'engines',
  'os',
  'cpu',
  'workspaces',
  'overrides',
] as const;
const DEPENDENCY_FIELDS = [
  'dependencies',
  'devDependencies',
  'optionalDependencies',
  'peerDependencies',
] as const;
const NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/i;
const VERSION = /^[0-9][0-9a-zA-Z.+_-]*$/;
const SRI = /^(?:sha512-[A-Za-z0-9+/]{86}==|sha256-[A-Za-z0-9+/]{43}=)$/;
const connectionName = (value: string) =>
  Buffer.byteLength(value) <= 48 &&
  /^[A-Za-z_][A-Za-z0-9_]*$/.test(value) &&
  !['__proto__', 'prototype', 'constructor'].includes(value);
const sha256 = (content: string) => createHash('sha256').update(content).digest('hex');
const record = (value: unknown): value is Record<string, any> =>
  !!value && typeof value === 'object' && !Array.isArray(value);

class MetadataError extends Error {
  constructor(
    readonly code: string,
    message: string,
    readonly path?: string,
  ) {
    super(message);
  }
}
function fail(code: string, message: string, path?: string): never {
  throw new MetadataError(code, message, path);
}
function contained(root: string, path: string): string {
  if (!path || isAbsolute(path) || path.includes('\\') || path.includes('\0'))
    fail('EXTERNAL_PATH', 'Dependency paths must stay within the captured source.', path);
  const full = resolve(root, path);
  const rel = relative(root, full);
  if (rel.startsWith(`..${sep}`) || rel === '..' || isAbsolute(rel))
    fail('EXTERNAL_PATH', 'Dependency path escapes the captured source.', path);
  return full;
}
function read(root: string, path: string, optional = false): string | undefined {
  const full = contained(root, path);
  let stat;
  try {
    stat = lstatSync(full);
  } catch (error: any) {
    if (optional && error.code === 'ENOENT') return undefined;
    fail('MISSING_METADATA', 'Required dependency metadata is missing or unreadable.', path);
  }
  const actual = realpathSync(full);
  if (stat!.isSymbolicLink() || actual !== full || !stat!.isFile())
    fail('UNSAFE_METADATA', 'Dependency metadata must be a regular file without symlink ancestors.', path);
  if (stat!.size > MAX_METADATA)
    fail('METADATA_LIMIT', 'Dependency metadata exceeds the 8 MiB inspection limit.', path);
  return readFileSync(full, 'utf8');
}
function json(root: string, path: string, jsonc = false): Record<string, any> {
  try {
    const parsed = jsonc ? Bun.JSONC.parse(read(root, path)!) : JSON.parse(read(root, path)!);
    if (!record(parsed)) fail('INVALID_METADATA', 'Expected a metadata object.', path);
    return parsed;
  } catch (error) {
    if (error instanceof MetadataError) throw error;
    fail('INVALID_METADATA', 'Dependency metadata is not valid JSON.', path);
  }
}
function publicUrl(value: unknown, hosts: string[], path?: string): string {
  if (typeof value !== 'string') fail('UNPINNED_ARCHIVE', 'A public registry archive URL is required.', path);
  let url: URL;
  try {
    url = new URL(value);
  } catch {
    fail('UNSUPPORTED_SOURCE', 'Dependency URL is invalid.', path);
  }
  if (
    url!.protocol !== 'https:' ||
    url!.username ||
    url!.password ||
    url!.port ||
    url!.hash ||
    url!.search ||
    !hosts.includes(url!.hostname)
  ) {
    fail(
      'UNSUPPORTED_SOURCE',
      'Only credential-free HTTPS URLs on the declared public registry are supported.',
      path,
    );
  }
  return url!.href;
}
function integrity(value: unknown, path: string): string {
  if (typeof value !== 'string' || !SRI.test(value))
    fail('UNPINNED_ARCHIVE', 'A SHA-256 or SHA-512 archive integrity value is required.', path);
  return value;
}
function packageCount(entries: unknown[], path: string) {
  if (entries.length > MAX_PACKAGES)
    fail('METADATA_LIMIT', 'The lock exceeds the 25,000-package inspection limit.', path);
}
function metadata(plan: PreparationPlan, path: string, value: string | object, reason?: string) {
  const content = typeof value === 'string' ? value : JSON.stringify(value, null, 2) + '\n';
  plan.metadata.push({ path, content, sha256: sha256(content) });
  if (reason) plan.transformations.push({ path, reason, phase: 'acquisition' });
}
function command(
  executable: string,
  args: string[],
  cwd: PreparationCommand['cwd'],
  env: Record<string, string> = {},
): PreparationCommand {
  return { executable, args, cwd, env };
}
function dependencySpecs(value: unknown, path: string) {
  if (value === undefined) return;
  if (!record(value)) fail('INVALID_METADATA', 'Dependency maps must be objects.', path);
  for (const [name, spec] of Object.entries(value)) {
    if (!NAME.test(name) || typeof spec !== 'string' || spec.length > 256 || /[\r\n\0]/.test(spec))
      fail('INVALID_METADATA', 'Invalid dependency name or version constraint.', path);
    if (/^(?:file:|link:|workspace:)/.test(spec)) {
      if (spec.startsWith('workspace:')) continue; // The lock must independently identify a contained workspace.
      const local = spec.replace(/^(file:|link:)/, '');
      if (isAbsolute(local) || local.split(/[\\/]/).includes('..'))
        fail('EXTERNAL_PATH', 'Local dependency escapes the snapshot.', path);
    } else if (
      /[/:@]/.test(spec) &&
      !/^npm:(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+@[~^*<>=| 0-9a-z.+_-]+$/i.test(spec)
    ) {
      fail(
        'UNSUPPORTED_SOURCE',
        'Private, VCS, and arbitrary URL dependencies require explicit provisioning.',
        path,
      );
    }
  }
}
function rejectConflictingLogicalArchives(inputs: PreparationInput[], path: string): void {
  const identities = new Map<string, string>();
  for (const input of inputs) {
    if (input.kind !== 'public') continue;
    const key = `${input.name.toLowerCase()}\0${input.version}`;
    const archive = JSON.stringify({
      url: input.url ?? null,
      integrity: input.integrity ?? null,
      integritySource: input.integritySource ?? null,
      platform: input.platform ?? null,
    });
    const prior = identities.get(key);
    if (prior !== undefined && prior !== archive)
      fail(
        'CONFLICTING_LOCK_IDENTITY',
        `Multiple locked archives disagree for ${input.name}@${input.version}.`,
        path,
      );
    identities.set(key, archive);
  }
}
function manifest(root: string, path: string, plan: PreparationPlan): Record<string, any> {
  const source = json(root, path);
  for (const field of DEPENDENCY_FIELDS) dependencySpecs(source[field], path);
  if (source.patchedDependencies)
    fail(
      'UNSUPPORTED_PATCHES',
      'Package-manager patches require an explicitly qualified offline preparation profile.',
      path,
    );
  if (source.overrides && JSON.stringify(source.overrides).match(/(?:https?:|git[+:]|file:|link:)/))
    fail('UNSUPPORTED_SOURCE', 'Dependency overrides must resolve to public version constraints.', path);
  if (source.workspaces !== undefined) {
    const workspaces = Array.isArray(source.workspaces) ? source.workspaces : source.workspaces?.packages;
    if (
      !Array.isArray(workspaces) ||
      workspaces.some(
        (item: unknown) =>
          typeof item !== 'string' ||
          !/^[A-Za-z0-9_.*\/-]+$/.test(item) ||
          item.startsWith('/') ||
          item.split('/').includes('..'),
      )
    )
      fail('EXTERNAL_PATH', 'Workspace patterns must remain inside captured source.', path);
  }
  const clean: Record<string, any> = {};
  for (const field of MANIFEST_FIELDS) if (source[field] !== undefined) clean[field] = source[field];
  metadata(
    plan,
    path,
    clean,
    'Acquisition manifest omits scripts, package-manager plugins, and target runtime configuration.',
  );
  if (record(source.engines))
    for (const key of ['node', 'bun'])
      if (typeof source.engines[key] === 'string') plan.runtimeRequirements[key] = source.engines[key];
  if (typeof source.packageManager === 'string')
    plan.runtimeRequirements.packageManager = source.packageManager;
  return clean;
}

function inspectNode(root: string, plan: PreparationPlan) {
  const lockPath =
    read(root, 'npm-shrinkwrap.json', true) !== undefined ? 'npm-shrinkwrap.json' : 'package-lock.json';
  const lock = json(root, lockPath);
  if (![2, 3].includes(lock.lockfileVersion) || !record(lock.packages))
    fail('UNSUPPORTED_LOCK', 'Node preparation requires npm lock/shrinkwrap version 2 or 3.', lockPath);
  manifest(root, 'package.json', plan);
  const entries = Object.entries(lock.packages);
  packageCount(entries, lockPath);
  const clean = structuredClone(lock);
  // Version-2's redundant dependency tree is accepted only when every resolved URL is safe.
  function validateTree(tree: unknown) {
    if (!record(tree)) return;
    for (const dep of Object.values(tree)) {
      if (!record(dep)) fail('INVALID_METADATA', 'Invalid npm dependency record.', lockPath);
      if (dep.resolved) publicUrl(dep.resolved, ['registry.npmjs.org'], lockPath);
      if (dep.integrity) integrity(dep.integrity, lockPath);
      validateTree(dep.dependencies);
    }
  }
  validateTree(lock.dependencies);
  for (const [path, raw] of entries) {
    if (!record(raw)) fail('INVALID_METADATA', 'Invalid locked npm package.', lockPath);
    if (path) contained(root, path);
    if (!path || !path.split('/').includes('node_modules')) {
      if (path) manifest(root, `${path}/package.json`, plan);
      for (const field of DEPENDENCY_FIELDS) dependencySpecs(raw[field], lockPath);
      delete clean.packages[path].scripts;
      continue;
    }
    if (raw.link === true) {
      const local = String(raw.resolved ?? '');
      contained(root, local);
      if (!record(lock.packages[local]))
        fail('MISSING_LOCAL_PACKAGE', 'Workspace link has no captured lock entry.', lockPath);
      plan.inputs.push({
        kind: 'local',
        name: local,
        version: String(lock.packages[local].version ?? '0'),
        path: local,
      });
      continue;
    }
    const name = typeof raw.name === 'string' ? raw.name : path.split('node_modules/').at(-1)!;
    if (!NAME.test(name) || typeof raw.version !== 'string' || !VERSION.test(raw.version))
      fail('INVALID_METADATA', 'Locked npm package needs an exact name and version.', lockPath);
    for (const field of DEPENDENCY_FIELDS) dependencySpecs(raw[field], lockPath);
    plan.inputs.push({
      kind: 'public',
      name,
      version: raw.version,
      url: publicUrl(raw.resolved, ['registry.npmjs.org'], lockPath),
      integrity: integrity(raw.integrity, lockPath),
      integritySource: 'lock',
    });
    delete clean.packages[path].scripts;
  }
  rejectConflictingLogicalArchives(plan.inputs, lockPath);
  metadata(
    plan,
    lockPath,
    clean,
    'Acquisition lock retains resolution and integrity data but omits executable script fields.',
  );
  const acquisition = [
    'ci',
    '--ignore-scripts',
    '--no-audit',
    '--no-fund',
    '--cache',
    '/archives/npm',
    '--userconfig',
    '/opt/cso/empty-config',
    '--globalconfig',
    '/opt/cso/empty-config',
  ];
  const offline = [
    'ci',
    '--ignore-scripts',
    '--no-audit',
    '--no-fund',
    '--cache',
    '/work/.cso-npm-cache',
    '--userconfig',
    '/opt/cso/empty-config',
    '--globalconfig',
    '/opt/cso/empty-config',
  ];
  plan.acquisition.push(
    command('/usr/local/bin/npm', [...acquisition, '--registry', 'https://registry.npmjs.org'], '/metadata', {
      NPM_CONFIG_UPDATE_NOTIFIER: 'false',
    }),
  );
  plan.offline.push(command('/usr/local/bin/npm', [...offline, '--offline'], '/work'));
  plan.offline.push(
    command(
      '/usr/local/bin/npm',
      [
        'rebuild',
        '--offline',
        '--no-audit',
        '--no-fund',
        '--cache',
        '/work/.cso-npm-cache',
        '--userconfig',
        '/opt/cso/empty-config',
        '--globalconfig',
        '/opt/cso/empty-config',
      ],
      '/work',
    ),
  );
  plan.registryHosts = ['registry.npmjs.org'];
}

function inspectBun(root: string, plan: PreparationPlan) {
  if (read(root, 'bun.lock', true) === undefined)
    fail(
      'UNSUPPORTED_LOCK',
      'Bun preparation requires the text bun.lock format; bun.lockb is not supported.',
      'bun.lock',
    );
  const lock = json(root, 'bun.lock', true);
  if (lock.lockfileVersion !== 1 || !record(lock.packages) || !record(lock.workspaces))
    fail('UNSUPPORTED_LOCK', 'Unsupported Bun text-lock schema.', 'bun.lock');
  if (lock.patchedDependencies)
    fail(
      'UNSUPPORTED_PATCHES',
      'Bun patched dependencies require an explicitly qualified offline profile.',
      'bun.lock',
    );
  const workspacePaths = Object.keys(lock.workspaces);
  packageCount(workspacePaths, 'bun.lock');
  for (const path of workspacePaths) {
    if (path) contained(root, path);
    manifest(root, path ? `${path}/package.json` : 'package.json', plan);
    for (const field of DEPENDENCY_FIELDS) dependencySpecs(lock.workspaces[path][field], 'bun.lock');
  }
  const entries = Object.entries(lock.packages);
  packageCount(entries, 'bun.lock');
  for (const [key, raw] of entries) {
    if (!Array.isArray(raw) || typeof raw[0] !== 'string')
      fail('INVALID_METADATA', 'Invalid Bun package tuple.', 'bun.lock');
    const split = raw[0].lastIndexOf('@');
    const name = raw[0].slice(0, split),
      version = raw[0].slice(split + 1);
    if (version.startsWith('workspace:')) {
      const path = version.slice(10);
      contained(root, path);
      if (!workspacePaths.includes(path))
        fail('MISSING_LOCAL_PACKAGE', 'Bun workspace is not captured in the lock.', 'bun.lock');
      plan.inputs.push({ kind: 'local', name, version, path });
      continue;
    }
    if (!NAME.test(name) || !VERSION.test(version))
      fail('UNSUPPORTED_SOURCE', 'Bun package must resolve to an exact public registry version.', 'bun.lock');
    const archiveUrl =
      raw[1] || `https://registry.npmjs.org/${name}/-/${name.split('/').at(-1)}-${version}.tgz`;
    publicUrl(archiveUrl, ['registry.npmjs.org'], 'bun.lock');
    if (!record(raw[2])) fail('INVALID_METADATA', 'Bun package metadata must be an object.', 'bun.lock');
    for (const field of DEPENDENCY_FIELDS) dependencySpecs(raw[2][field], 'bun.lock');
    plan.inputs.push({
      kind: 'public',
      name,
      version,
      url: archiveUrl,
      integrity: integrity(raw[3], 'bun.lock'),
      integritySource: 'lock',
    });
  }
  rejectConflictingLogicalArchives(plan.inputs, 'bun.lock');
  metadata(plan, 'bun.lock', lock);
  const acquisitionEnv = {
    BUN_INSTALL_CACHE_DIR: '/metadata/.cso-bun-cache',
    BUN_CONFIG_NO_CLEAR_TERMINAL: '1',
    BUN_FEATURE_FLAG_DISABLE_NATIVE_DEPENDENCY_LINKER: '1',
  };
  const offlineEnv = { ...acquisitionEnv, BUN_INSTALL_CACHE_DIR: '/work/.cso-bun-cache' };
  plan.acquisition.push(
    command(
      '/usr/local/bin/bun',
      [
        'install',
        '--config=/opt/cso/empty-config',
        '--frozen-lockfile',
        '--ignore-scripts',
        '--no-progress',
        '--backend=hardlink',
        '--registry=https://registry.npmjs.org',
      ],
      '/metadata',
      acquisitionEnv,
    ),
  );
  // The runner enforces network-none; Bun's --offline availability is version-specific.
  plan.offline.push(
    command(
      '/usr/local/bin/bun',
      [
        'install',
        '--config=/opt/cso/empty-config',
        '--frozen-lockfile',
        '--no-progress',
        '--backend=copyfile',
      ],
      '/work',
      offlineEnv,
    ),
  );
  plan.registryHosts = ['registry.npmjs.org'];
}

function requirementLines(text: string, plan: PreparationPlan, path: string) {
  const lines = text.replace(/\\\r?\n/g, ' ').split(/\r?\n/);
  for (const raw of lines) {
    const line = raw.replace(/\s+#.*$/, '').trim();
    if (!line || line.startsWith('#')) continue;
    const hashes = [...line.matchAll(/(?:^|\s)--hash=sha256:([a-f0-9]{64})(?=\s|$)/gi)];
    const requirement = line.replace(/(?:^|\s)--hash=sha256:[a-f0-9]{64}(?=\s|$)/gi, '').trim();
    const match = requirement.match(
      /^([A-Za-z0-9][A-Za-z0-9._-]*)(?:\[[A-Za-z0-9_,.-]+\])?==([A-Za-z0-9][A-Za-z0-9.!+_-]*)(?:\s*;\s*([A-Za-z0-9_.'" ()<>=!~+,-]+))?$/,
    );
    if (!match || !hashes.length || requirement.includes('--'))
      fail(
        'UNPINNED_REQUIREMENTS',
        'Requirements must contain only exact public package pins with SHA-256 hashes; includes, URLs, editable paths, and index options are unsupported.',
        path,
      );
    if (match[3])
      fail(
        'UNSUPPORTED_MARKER',
        'PEP 508 environment markers require a qualified runtime-specific lock export.',
        path,
      );
    plan.inputs.push({
      kind: 'public',
      name: match[1],
      version: match[2],
      integrity: hashes.map((h) => `sha256:${h[1].toLowerCase()}`).join(' '),
      integritySource: 'lock',
    });
  }
  packageCount(plan.inputs, path);
}
function toml(root: string, path: string): Record<string, any> {
  try {
    const result = Bun.TOML.parse(read(root, path)!);
    if (!record(result)) fail('INVALID_METADATA', 'Expected a TOML object.', path);
    return result;
  } catch (error) {
    if (error instanceof MetadataError) throw error;
    fail('INVALID_METADATA', 'Dependency metadata is not valid TOML.', path);
  }
}
function hasUvEnvironmentMarker(value: unknown, seen = new WeakSet<object>()): boolean {
  if (value === null || typeof value !== 'object') return false;
  if (seen.has(value as object)) return true;
  seen.add(value as object);
  if (Array.isArray(value)) return value.some((item) => hasUvEnvironmentMarker(item, seen));
  for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
    if (key === 'marker' || key === 'resolution-markers' || key === 'fork-markers') return true;
    if (hasUvEnvironmentMarker(item, seen)) return true;
  }
  return false;
}
function inspectPython(root: string, plan: PreparationPlan) {
  const hasUv = read(root, 'uv.lock', true) !== undefined;
  const acquisitionEnv = {
    UV_NO_CONFIG: '1',
    UV_PYTHON_DOWNLOADS: 'never',
    UV_NO_MANAGED_PYTHON: '1',
    UV_CACHE_DIR: '/archives/uv',
    PIP_CONFIG_FILE: '/dev/null',
    PIP_DISABLE_PIP_VERSION_CHECK: '1',
    PIP_NO_CACHE_DIR: '1',
  };
  const offlineEnv = { ...acquisitionEnv, UV_CACHE_DIR: '/work/.cso-uv-cache', UV_LINK_MODE: 'copy' };
  let requirementsPath = 'requirements.txt';
  let publicRequirements = '/metadata/requirements.txt';
  const localBuildPaths: string[] = [];
  const buildRequirements = new Set<string>();
  if (hasUv) {
    const lock = toml(root, 'uv.lock');
    if (lock.version !== 1 || !Array.isArray(lock.package))
      fail('UNSUPPORTED_LOCK', 'Unsupported uv.lock schema.', 'uv.lock');
    if (hasUvEnvironmentMarker(lock))
      fail(
        'UNSUPPORTED_MARKER',
        'Universal uv locks with environment or resolution markers require a qualified runtime-specific export before automatic preparation.',
        'uv.lock',
      );
    packageCount(lock.package, 'uv.lock');
    for (const pkg of lock.package) {
      if (!record(pkg) || !record(pkg.source) || !NAME.test(pkg.name) || !VERSION.test(pkg.version))
        fail('INVALID_METADATA', 'Invalid uv locked package.', 'uv.lock');
      if (pkg.source.registry !== undefined) {
        if (Object.keys(pkg.source).length !== 1)
          fail(
            'UNSUPPORTED_SOURCE',
            'Python registry entries cannot contain alternate dependency sources.',
            'uv.lock',
          );
        const registry = publicUrl(pkg.source.registry, ['pypi.org'], 'uv.lock');
        if (!['https://pypi.org/simple', 'https://pypi.org/simple/'].includes(registry))
          fail(
            'UNSUPPORTED_SOURCE',
            'Python acquisition supports the public PyPI simple index only.',
            'uv.lock',
          );
        if (!Array.isArray(pkg.wheels) || !pkg.wheels.length)
          fail(
            'MISSING_PUBLIC_WHEEL',
            'A matching public wheel is required; source distributions are never built during acquisition.',
            'uv.lock',
          );
        for (const wheel of pkg.wheels) {
          if (!record(wheel) || typeof wheel.hash !== 'string' || !/^sha256:[a-f0-9]{64}$/.test(wheel.hash))
            fail('UNPINNED_ARCHIVE', 'uv wheels require SHA-256 hashes.', 'uv.lock');
          plan.inputs.push({
            kind: 'public',
            name: pkg.name,
            version: pkg.version,
            url: publicUrl(wheel.url, ['files.pythonhosted.org'], 'uv.lock'),
            integrity: wheel.hash,
            integritySource: 'lock',
          });
        }
        if (pkg.sdist) {
          publicUrl(pkg.sdist.url, ['files.pythonhosted.org'], 'uv.lock');
          if (!/^sha256:[a-f0-9]{64}$/.test(pkg.sdist.hash ?? ''))
            fail('UNPINNED_ARCHIVE', 'uv source archive hash is invalid.', 'uv.lock');
        }
      } else {
        const local = pkg.source.editable ?? pkg.source.virtual ?? pkg.source.directory;
        if (
          typeof local !== 'string' ||
          Object.keys(pkg.source).some((k) => !['editable', 'virtual', 'directory'].includes(k))
        )
          fail(
            'UNSUPPORTED_SOURCE',
            'Private, VCS, and direct-URL Python sources require explicit provisioning.',
            'uv.lock',
          );
        contained(root, local);
        plan.inputs.push({ kind: 'local', name: pkg.name, version: pkg.version, path: local });
        if (pkg.source.virtual === undefined) {
          localBuildPaths.push(local);
          const pyprojectPath = local === '.' ? 'pyproject.toml' : `${local}/pyproject.toml`;
          const localProject = read(root, pyprojectPath, true) === undefined ? {} : toml(root, pyprojectPath);
          const build = localProject['build-system'];
          const requirements = build?.requires ?? ['setuptools>=40.8.0'];
          if (!Array.isArray(requirements))
            fail(
              'DYNAMIC_BUILD_DEPENDENCIES',
              'Local build dependencies must be declared as static package requirements.',
              pyprojectPath,
            );
          for (const requirement of requirements) {
            if (
              typeof requirement !== 'string' ||
              !/^[A-Za-z0-9][A-Za-z0-9._-]*(?:\[[A-Za-z0-9_,.-]+\])?\s*[A-Za-z0-9.!~<>=+*, -]*$/.test(
                requirement,
              )
            )
              fail(
                'UNSUPPORTED_BUILD_DEPENDENCY',
                'Local build dependencies must be public package requirements without URLs or paths.',
                pyprojectPath,
              );
            buildRequirements.add(
              requirement
                .match(/^[A-Za-z0-9][A-Za-z0-9._-]*/)![0]
                .toLowerCase()
                .replace(/[_.]+/g, '-'),
            );
          }
        }
      }
    }
    const project = toml(root, 'pyproject.toml');
    if (!record(project.project))
      fail('UNSUPPORTED_METADATA', 'uv export requires static PEP 621 project metadata.', 'pyproject.toml');
    if (
      project.tool?.uv?.workspace !== undefined ||
      plan.inputs.some((input) => input.kind === 'local' && input.path !== '.')
    )
      fail(
        'UNSUPPORTED_WORKSPACE',
        'uv workspace/member metadata is not yet qualified for sanitized automatic preparation.',
        'pyproject.toml',
      );
    if (project.project.dynamic?.includes('dependencies'))
      fail(
        'DYNAMIC_METADATA',
        'Dynamic project dependencies require qualified offline build dependencies.',
        'pyproject.toml',
      );
    // Only the export process sees this metadata; no build-system or tool.uv sources/config.
    const clean: Record<string, any> = { project: project.project };
    if (project['dependency-groups']) clean['dependency-groups'] = project['dependency-groups'];
    // uv accepts a static pyproject file. Keep original syntax only after excluding every
    // non-project table would require a TOML writer; use JSON-compatible TOML literals.
    metadata(
      plan,
      'pyproject.toml',
      toToml(clean),
      'Acquisition pyproject omits all build backends and tool configuration; local packages are excluded by --no-emit-local.',
    );
    metadata(plan, 'uv.lock', read(root, 'uv.lock')!);
    plan.runtimeRequirements.python = String(
      lock['requires-python'] ?? project.project['requires-python'] ?? '',
    );
    requirementsPath = 'cso-public-requirements.txt';
    publicRequirements = `/archives/${requirementsPath}`;
    plan.acquisition.push(
      command(
        '/usr/local/bin/uv',
        [
          'export',
          '--frozen',
          '--no-emit-local',
          '--all-packages',
          '--all-extras',
          '--all-groups',
          '--no-config',
          '--format',
          'requirements-txt',
          '--output-file',
          publicRequirements,
        ],
        '/metadata',
        acquisitionEnv,
      ),
    );
    plan.offline.push(
      command(
        '/usr/local/bin/uv',
        [
          'export',
          '--offline',
          '--frozen',
          '--no-emit-local',
          '--all-packages',
          '--all-extras',
          '--all-groups',
          '--no-config',
          '--format',
          'requirements-txt',
          '--output-file',
          '/work/.gstack-cso-public-requirements.txt',
        ],
        '/metadata',
        offlineEnv,
      ),
    );
    plan.offline.push(
      command('/usr/local/bin/python', ['-I', '-m', 'venv', '--copies', '/work/.venv'], '/work', offlineEnv),
    );
    plan.offline.push(
      command(
        '/usr/local/bin/uv',
        [
          'pip',
          'install',
          '--offline',
          '--no-config',
          '--python',
          '/work/.venv/bin/python',
          '--link-mode',
          'copy',
          '--no-index',
          '--find-links',
          '/archives/wheels',
          '--require-hashes',
          '--only-binary',
          ':all:',
          '--requirement',
          '/work/.gstack-cso-public-requirements.txt',
        ],
        '/work',
        offlineEnv,
      ),
    );
    if (buildRequirements.size) {
      const lines: string[] = [];
      for (const name of buildRequirements) {
        const locked = plan.inputs.filter(
          (input) => input.kind === 'public' && input.name.toLowerCase().replace(/[_.]+/g, '-') === name,
        );
        if (!locked.length || new Set(locked.map((input) => input.version)).size !== 1)
          fail(
            'MISSING_BUILD_DEPENDENCY',
            'Every local build dependency needs one exact public wheel version in uv.lock.',
            'uv.lock',
          );
        lines.push(
          `${name}==${locked[0].version} ${[...new Set(locked.map((input) => input.integrity))].map((hash) => `--hash=${hash}`).join(' ')}`,
        );
      }
      metadata(
        plan,
        '.gstack-cso/build-requirements.txt',
        lines.join('\n') + '\n',
        'Local build dependencies are acquired only as exact hashed public wheels.',
      );
      plan.acquisition.push(
        command(
          '/usr/local/bin/python',
          [
            '-I',
            '-m',
            'pip',
            '--isolated',
            'download',
            '--index-url',
            'https://pypi.org/simple',
            '--require-hashes',
            '--only-binary=:all:',
            '--dest',
            '/archives/wheels',
            '--requirement',
            '/metadata/.gstack-cso/build-requirements.txt',
          ],
          '/metadata',
          acquisitionEnv,
        ),
      );
      plan.offline.push(
        command(
          '/usr/local/bin/uv',
          [
            'pip',
            'install',
            '--offline',
            '--no-config',
            '--python',
            '/work/.venv/bin/python',
            '--link-mode',
            'copy',
            '--no-index',
            '--find-links',
            '/archives/wheels',
            '--require-hashes',
            '--only-binary',
            ':all:',
            '--requirement',
            '/metadata/.gstack-cso/build-requirements.txt',
          ],
          '/work',
          offlineEnv,
        ),
      );
    }
    if (localBuildPaths.length)
      plan.offline.push(
        command(
          '/usr/local/bin/uv',
          [
            'pip',
            'install',
            '--offline',
            '--no-config',
            '--python',
            '/work/.venv/bin/python',
            '--link-mode',
            'copy',
            '--no-index',
            '--find-links',
            '/archives/wheels',
            '--no-deps',
            '--no-build-isolation',
            ...localBuildPaths.map((path) => `/work/${path}`),
          ],
          '/work',
          offlineEnv,
        ),
      );
    plan.offline.push(
      command(
        '/usr/local/bin/uv',
        ['pip', 'check', '--offline', '--no-config', '--python', '/work/.venv/bin/python'],
        '/work',
        offlineEnv,
      ),
    );
  } else {
    const contents = read(root, requirementsPath)!;
    requirementLines(contents, plan, requirementsPath);
    metadata(plan, requirementsPath, contents);
    plan.offline.push(
      command('/usr/local/bin/python', ['-I', '-m', 'venv', '--copies', '/work/.venv'], '/work', offlineEnv),
    );
    plan.offline.push(
      command(
        '/work/.venv/bin/python',
        [
          '-I',
          '-m',
          'pip',
          '--isolated',
          'install',
          '--no-index',
          '--find-links',
          '/archives/wheels',
          '--require-hashes',
          '--only-binary=:all:',
          '--requirement',
          '/work/requirements.txt',
        ],
        '/work',
        offlineEnv,
      ),
    );
    plan.offline.push(
      command('/work/.venv/bin/python', ['-I', '-m', 'pip', '--isolated', 'check'], '/work', offlineEnv),
    );
  }
  plan.acquisition.push(
    command(
      '/usr/local/bin/python',
      [
        '-I',
        '-m',
        'pip',
        '--isolated',
        'download',
        '--index-url',
        'https://pypi.org/simple',
        '--require-hashes',
        '--only-binary=:all:',
        '--dest',
        '/archives/wheels',
        '--requirement',
        publicRequirements,
      ],
      '/metadata',
      acquisitionEnv,
    ),
  );
  plan.registryHosts = ['pypi.org', 'files.pythonhosted.org'];
}
function toToml(value: Record<string, any>): string {
  const literal = (x: any): string => {
    if (typeof x === 'string' || typeof x === 'boolean' || typeof x === 'number') return JSON.stringify(x);
    if (Array.isArray(x)) return `[${x.map(literal).join(', ')}]`;
    if (record(x))
      return `{ ${Object.entries(x)
        .map(([k, v]) => `${JSON.stringify(k)} = ${literal(v)}`)
        .join(', ')} }`;
    fail('INVALID_METADATA', 'Unsupported TOML metadata value.', 'pyproject.toml');
  };
  return (
    Object.entries(value)
      .map(([key, val]) => `${JSON.stringify(key)} = ${literal(val)}`)
      .join('\n') + '\n'
  );
}

function inspectRails(root: string, plan: PreparationPlan) {
  const contents = read(root, 'Gemfile.lock')!;
  read(root, 'Gemfile'); // Presence only; never parse/evaluate Ruby during acquisition.
  let section = '',
    sawPublicRemote = false;
  const checksums = new Map<string, string>();
  for (const line of contents.split(/\r?\n/)) {
    if (/^[A-Z][A-Z ]+$/.test(line)) {
      section = line;
      if (
        !['GEM', 'PLATFORMS', 'DEPENDENCIES', 'RUBY VERSION', 'BUNDLED WITH', 'CHECKSUMS'].includes(section)
      )
        fail(
          'UNSUPPORTED_SOURCE',
          'Gemfile.lock contains a non-public source or unsupported section.',
          'Gemfile.lock',
        );
      continue;
    }
    if (!line.trim()) continue;
    if (section === 'GEM' && line.startsWith('  remote: ')) {
      const remote = publicUrl(line.slice(10), ['rubygems.org'], 'Gemfile.lock');
      if (remote !== 'https://rubygems.org/')
        fail(
          'UNSUPPORTED_SOURCE',
          'Ruby acquisition supports the public RubyGems root only.',
          'Gemfile.lock',
        );
      sawPublicRemote = true;
    } else if (section === 'GEM' && /^    \S/.test(line)) {
      const match = line.match(
        /^    ([A-Za-z0-9][A-Za-z0-9_.-]*) \(([0-9]+(?:\.[0-9A-Za-z]+)*)(?:-([A-Za-z0-9][A-Za-z0-9_.-]*))?\)$/,
      );
      if (!match) fail('INVALID_METADATA', 'Invalid exact Ruby gem lock entry.', 'Gemfile.lock');
      plan.inputs.push({
        kind: 'public',
        name: match[1],
        version: match[2],
        platform: match[3] || 'ruby',
        integritySource: 'registry-on-acquisition',
      });
    } else if (section === 'CHECKSUMS') {
      const match = line.match(/^  ([A-Za-z0-9][A-Za-z0-9_.-]*) \(([^)]+)\) sha256=([a-f0-9]{64})$/);
      if (!match) fail('INVALID_METADATA', 'Unsupported RubyGems checksum entry.', 'Gemfile.lock');
      checksums.set(`${match[1]}@${match[2]}`, `sha256:${match[3]}`);
    } else if (section === 'RUBY VERSION') {
      const match = line.trim().match(/^ruby ([0-9]+\.[0-9]+\.[0-9]+)(?:p[0-9]+)?$/);
      if (!match) fail('UNSUPPORTED_RUNTIME', 'Unsupported Ruby runtime declaration.', 'Gemfile.lock');
      plan.runtimeRequirements.ruby = match[1];
    } else if (section === 'BUNDLED WITH') {
      const version = line.trim();
      if (!/^[0-9]+\.[0-9]+\.[0-9]+$/.test(version))
        fail('UNSUPPORTED_RUNTIME', 'Bundler must be pinned to an exact version.', 'Gemfile.lock');
      plan.runtimeRequirements.bundler = version;
    }
  }
  if (!sawPublicRemote)
    fail('UNSUPPORTED_SOURCE', 'Gemfile.lock needs an explicit public RubyGems source.', 'Gemfile.lock');
  if (!plan.runtimeRequirements.bundler)
    fail('UNSUPPORTED_RUNTIME', 'Gemfile.lock must record BUNDLED WITH.', 'Gemfile.lock');
  packageCount(plan.inputs, 'Gemfile.lock');
  for (const input of plan.inputs) {
    const key = `${input.name}@${input.version}${input.platform === 'ruby' ? '' : `-${input.platform}`}`;
    const hash = checksums.get(key);
    if (hash) {
      input.integrity = hash;
      input.integritySource = 'lock';
    }
    // gem fetch downloads without evaluating a Gemfile/gemspec or building extensions.
    plan.acquisition.push(
      command(
        '/usr/local/bin/gem',
        [
          'fetch',
          input.name,
          '--version',
          input.version,
          '--platform',
          input.platform!,
          '--clear-sources',
          '--source',
          'https://rubygems.org',
          '--norc',
        ],
        '/archives',
      ),
    );
  }
  metadata(plan, 'Gemfile.lock', contents);
  const env = {
    RAILS_ENV: 'test',
    RACK_ENV: 'test',
    SECRET_KEY_BASE: 'cso-synthetic-test-key-never-a-production-credential',
    BUNDLE_PATH: '/work/vendor/bundle',
    BUNDLE_FROZEN: 'true',
    BUNDLE_DEPLOYMENT: 'true',
    BUNDLE_DISABLE_SHARED_GEMS: 'true',
    BUNDLE_IGNORE_CONFIG: 'true',
    BUNDLE_ALLOW_OFFLINE_INSTALL: 'true',
    BUNDLE_CACHE_PATH: '/archives',
    BUNDLE_USER_HOME: '/work/.cso-bundle',
  };
  plan.offline.push(
    command('/usr/local/bin/bundle', ['install', '--local', '--jobs', '2', '--retry', '0'], '/work', env),
  );
  plan.registryHosts = ['rubygems.org', 'index.rubygems.org'];
  const declared = railsDatabaseConfiguration(read(root, 'config/database.yml', true));
  const supported: Array<'sqlite' | 'postgresql'> = [];
  if (plan.inputs.some((input) => input.name === 'sqlite3')) supported.push('sqlite');
  if (plan.inputs.some((input) => input.name === 'pg')) supported.push('postgresql');
  if (!supported.length)
    fail(
      'MISSING_DATABASE_ADAPTER',
      'Rails automatic preparation requires a locked sqlite3 or pg adapter.',
      'Gemfile.lock',
    );
  const declaredSupported = [...declared.adapters].filter((adapter) => supported.includes(adapter));
  const selected =
    supported.length === 1 ? supported[0] : declaredSupported.length === 1 ? declaredSupported[0] : null;
  plan.database = {
    supported,
    selected,
    connections: declared.connections,
    requiresSyntheticConfiguration: true,
  };
}

function railsDatabaseConfiguration(contents: string | undefined): {
  connections: string[];
  adapters: Set<'sqlite' | 'postgresql'>;
} {
  if (contents === undefined) return { connections: ['primary'], adapters: new Set() };
  if (contents.includes('\t'))
    fail(
      'DYNAMIC_DATABASE_CONFIG',
      'Database configuration must use spaces for bounded inert parsing.',
      'config/database.yml',
    );
  // ERB is never evaluated. It may supply scalar values, but dynamic YAML structure is unsupported.
  let safe = contents.replace(/<%=[\s\S]*?%>/g, 'CSO_REDACTED_ERB');
  if (safe.includes('<%'))
    fail(
      'DYNAMIC_DATABASE_CONFIG',
      'Database configuration uses structural ERB; supply explicit synthetic connection names.',
      'config/database.yml',
    );
  // Stock Rails uses one inert `default` anchor. Remove only that exact merge
  // syntax before parsing so the YAML implementation never expands aliases.
  safe = safe
    .split(/\r?\n/)
    .map((line) => {
      if (/^default:\s*&default\s*(?:#.*)?$/.test(line)) return 'default:';
      if (/^\s+<<:\s*\*default\s*(?:#.*)?$/.test(line))
        return line.replace(/<<:[\s\S]*$/, '# cso: inert default merge');
      return line;
    })
    .join('\n');
  if (/(^|[\s\[{,])(?:[&*][A-Za-z0-9_-]+|!\S+)/m.test(safe))
    fail(
      'DYNAMIC_DATABASE_CONFIG',
      'Only the stock Rails default anchor and merge are accepted by the trusted readiness parser.',
      'config/database.yml',
    );
  let parsed: any;
  try {
    parsed = Bun.YAML.parse(safe);
  } catch {
    fail(
      'DYNAMIC_DATABASE_CONFIG',
      'Database connection names could not be read without evaluating ERB.',
      'config/database.yml',
    );
  }
  if (!record(parsed))
    fail('INVALID_DATABASE_CONFIG', 'Database configuration must be a mapping.', 'config/database.yml');
  const connections = new Set<string>(),
    adapters = new Set<'sqlite' | 'postgresql'>();
  const recordAdapter = (config: Record<string, any>) => {
    if (config.adapter === 'sqlite3') adapters.add('sqlite');
    if (config.adapter === 'postgresql' || config.adapter === 'postgres') adapters.add('postgresql');
  };
  for (const [environment, config] of Object.entries(parsed)) {
    if (!record(config)) continue;
    recordAdapter(config);
    if (environment === 'default') continue;
    if ('adapter' in config || 'url' in config || 'database' in config) {
      connections.add('primary');
      continue;
    }
    for (const [name, connection] of Object.entries(config)) {
      if (!connectionName(name) || name.includes('CSO_REDACTED_ERB') || !record(connection))
        fail(
          'DYNAMIC_DATABASE_CONFIG',
          'Database connection names must be static identifiers.',
          'config/database.yml',
        );
      recordAdapter(connection);
      connections.add(name);
    }
  }
  return { connections: connections.size ? [...connections].sort() : ['primary'], adapters };
}

/** Synthetic files are declared execution transformations; a boundary-changing target is blocked by the runner. */
export function railsTestConfiguration(
  connections: string[],
  adapter: 'sqlite' | 'postgresql',
): Array<{ path: string; content: string }> {
  if (!connections.length || connections.some((name) => !connectionName(name)))
    throw new Error('Invalid Rails connection names');
  const database: Record<string, any> = { test: {} };
  for (const name of connections)
    database.test[name] =
      adapter === 'sqlite'
        ? { adapter: 'sqlite3', database: `/work/tmp/cso-${name}.sqlite3`, pool: 3 }
        : {
            adapter: 'postgresql',
            host: '127.0.0.1',
            port: 5432,
            username: 'cso',
            password: 'cso-disposable-test',
            database: `cso_${name}`,
            pool: 3,
          };
  return [
    // JSON is valid YAML; no interpolation, anchors, inherited URLs, or production connections.
    { path: 'config/database.yml', content: JSON.stringify(database, null, 2) + '\n' },
    {
      path: 'config/initializers/zzzz_cso_test.rb',
      content: `# Trusted synthetic test environment; recorded in the transformation manifest.\nraise "CSO requires test environment" unless Rails.env.test?\nRails.application.config.secret_key_base = ENV.fetch("SECRET_KEY_BASE")\nRails.application.config.active_storage.service = :cso_test if defined?(ActiveStorage)\nRails.application.config.active_job.queue_adapter = :test if defined?(ActiveJob)\nRails.application.config.action_mailer.delivery_method = :test if defined?(ActionMailer)\nRails.application.config.action_mailer.perform_deliveries = false if defined?(ActionMailer)\nRails.application.config.after_initialize do\n  ActiveJob::Base.queue_adapter = :test if defined?(ActiveJob::Base)\n  ActionMailer::Base.delivery_method = :test if defined?(ActionMailer::Base)\nend\n`,
    },
    {
      path: 'config/storage.yml',
      content:
        JSON.stringify({ cso_test: { service: 'Disk', root: '/work/tmp/cso-storage' } }, null, 2) + '\n',
    },
  ];
}

export function inspectPreparation(snapshotPath: string, stack?: CsoStack): PreparationPlan {
  const root = resolve(snapshotPath);
  const plan: PreparationPlan = {
    schemaVersion: 1,
    stack: stack ?? 'python',
    status: 'ready',
    prerequisites: [],
    metadata: [],
    inputs: [],
    acquisition: [],
    offline: [],
    registryHosts: [],
    runtimeProfile: stack ?? 'python',
    runtimeRequirements: {},
    transformations: [],
  };
  try {
    const detectedStacks: CsoStack[] = [];
    const hasBun = read(root, 'bun.lock', true) !== undefined || read(root, 'bun.lockb', true) !== undefined;
    if (hasBun) detectedStacks.push('bun');
    if (
      read(root, 'package-lock.json', true) !== undefined ||
      read(root, 'npm-shrinkwrap.json', true) !== undefined ||
      (!hasBun && read(root, 'package.json', true) !== undefined)
    )
      detectedStacks.push('node');
    if (read(root, 'Gemfile.lock', true) !== undefined || read(root, 'Gemfile', true) !== undefined)
      detectedStacks.push('rails');
    if (
      read(root, 'uv.lock', true) !== undefined ||
      read(root, 'requirements.txt', true) !== undefined ||
      read(root, 'pyproject.toml', true) !== undefined
    )
      detectedStacks.push('python');
    if (!stack && detectedStacks.length > 1)
      fail(
        'MULTIPLE_STACKS',
        `Multiple executable stacks were detected (${detectedStacks.join(', ')}); verification must select a matching qualified runtime.`,
      );
    const detected = stack ?? detectedStacks[0] ?? 'python';
    plan.stack = detected;
    plan.runtimeProfile = detected;
    if (!['node', 'bun', 'python', 'rails'].includes(detected))
      fail('UNSUPPORTED_STACK', 'Supported runtime stacks are Node, Bun, Python, and Rails.');
    ({ node: inspectNode, bun: inspectBun, python: inspectPython, rails: inspectRails })[detected](
      root,
      plan,
    );
  } catch (error) {
    plan.status = 'prerequisites';
    plan.prerequisites.push(
      error instanceof MetadataError
        ? { code: error.code, message: error.message, path: error.path }
        : { code: 'INVALID_METADATA', message: 'Dependency metadata could not be inspected safely.' },
    );
    // Never execute a partially validated acquisition plan.
    plan.acquisition = [];
    plan.offline = [];
    plan.metadata = [];
  }
  return plan;
}