Skip to content

armgit / kiln

Public Imported from GitHub
0

Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.

8.0 KB
Raw Blame
import { createHash, randomUUID } from 'node:crypto';
import type { Stats } from 'node:fs';
import {
  chmod,
  lstat,
  link,
  mkdir,
  open,
  readFile,
  realpath,
  rename,
  stat,
  unlink,
  writeFile,
} from 'node:fs/promises';
import { basename, dirname, join, resolve } from 'node:path';

/**
 * Prepare the directories leading to a CLI destination.
 *
 * A destination the operator named is a statement of intent, not an assertion
 * that the path already exists. Refusing a missing parent is expensive out of
 * proportion to the mistake: by the time the CLI writes, the build has run and a
 * `programRef` is already on stdout, so the operator sees a successful render
 * followed by a bare ENOENT, with nothing in the message naming the parent
 * directory as the thing to fix. `recursive` also makes this a no-op for the
 * common case where the directory is already there.
 */
export async function prepareDestination(path: string): Promise<string> {
  await mkdir(dirname(path), { recursive: true });
  return path;
}

/**
 * Publish a complete replacement on the destination filesystem. Concurrent writers
 * use separate staging files; the last successful rename wins. This is per-file
 * replacement, not a multi-output transaction or a power-loss durability promise.
 */
export async function writeDestinationAtomic(
  path: string,
  data: Parameters<typeof writeFile>[1],
): Promise<void> {
  await prepareDestination(path);
  let existing: Stats | undefined;
  try {
    existing = await lstat(path);
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
  }
  // Preserve writes through existing symlinks instead of replacing the link itself.
  // A dangling link fails safely rather than being silently replaced.
  if (existing?.isSymbolicLink()) {
    path = await realpath(path);
    existing = await stat(path);
  }
  const temporary = join(dirname(path), `.kiln-write-${randomUUID()}.tmp`);
  // Acquire ownership before entering cleanup: an exclusive-open failure must
  // never remove a file owned by another writer.
  const file = await open(temporary, 'wx', existing?.mode ?? 0o666);
  try {
    try {
      await writeFile(file, data);
    } catch (error) {
      await file.close().catch(() => {});
      throw error;
    }
    await file.close();
    if (existing?.isFile()) await chmod(temporary, existing.mode);
    await rename(temporary, path);
  } finally {
    // Preserve the original write/rename error; never unlink the destination.
    await unlink(temporary).catch(() => {});
  }
}

/**
 * Stage an exclusive multi-file export, then publish in order (sidecar before GLB).
 * Hard links publish complete bytes without replacing existing files. A caught
 * failure rolls back this call's outputs. This is not a crash/power-loss transaction;
 * an interrupted process can leave a complete orphan sidecar, never a partial GLB.
 */
export async function writeNewDestinationsAtomic(
  outputs: { path: string; data: Parameters<typeof writeFile>[1] }[],
): Promise<void> {
  const paths = outputs.map(({ path }) => {
    const absolute = resolve(path);
    return process.platform === 'win32' ? absolute.toLowerCase() : absolute;
  });
  if (new Set(paths).size !== paths.length) throw new Error('Export destinations must be distinct');
  const staged: { path: string; temporary: string; published: boolean }[] = [];
  try {
    for (const { path, data } of outputs) {
      await prepareDestination(path);
      const temporary = join(dirname(path), `.kiln-write-${randomUUID()}.tmp`);
      const file = await open(temporary, 'wx');
      staged.push({ path, temporary, published: false });
      try {
        await writeFile(file, data);
      } finally {
        await file.close();
      }
    }
    for (const output of staged) {
      try {
        await link(output.temporary, output.path);
      } catch (error) {
        if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
        throw Object.assign(
          new Error(
            `${output.path} already exists and is never replaced; choose a new output path or remove the file.`,
          ),
          { code: 'EEXIST' },
        );
      }
      output.published = true;
    }
  } catch (error) {
    for (const output of staged.filter((item) => item.published).reverse()) {
      // An unrelated writer may have replaced an output since our publish. Never
      // remove it: only unlink the inode still shared with our staging file.
      try {
        const [destination, temporary] = await Promise.all([
          lstat(output.path),
          lstat(output.temporary),
        ]);
        if (destination.dev === temporary.dev && destination.ino === temporary.ino)
          await unlink(output.path);
      } catch {
        /* Preserve the original failure; leave an undeletable complete file. */
      }
    }
    throw error;
  } finally {
    await Promise.all(staged.map(({ temporary }) => unlink(temporary).catch(() => {})));
  }
}

/**
 * Publish content-addressed files (`<sha256 hex>.<ext>`). A file that already exists with the
 * same bytes is reused and never rewritten; one with different bytes is an error. Nothing here
 * ever removes a published file, including one this call created: another export may already
 * reference it, and a leftover file is harmless.
 */
export async function writeContentAddressedFiles(
  files: { path: string; data: Uint8Array }[],
): Promise<{ path: string; reused: boolean }[]> {
  const hex = (data: Uint8Array) => createHash('sha256').update(data).digest('hex');
  for (const { path, data } of files) {
    const name = basename(path);
    if (!/^[a-f0-9]{64}\.[a-z0-9]+$/.test(name) || name.slice(0, 64) !== hex(data))
      throw new Error(`${path} is not the content address of its bytes`);
  }
  const published: { path: string; reused: boolean }[] = [];
  const same = async (path: string, data: Uint8Array) => {
    const existing = await readFile(path);
    if (hex(existing) !== hex(data))
      throw Object.assign(
        new Error(
          `${path} already exists with different bytes; a content-addressed file is never replaced.`,
        ),
        { code: 'EEXIST' },
      );
  };
  for (const { path, data } of files) {
    try {
      await same(path, data);
      published.push({ path, reused: true });
      continue;
    } catch (error) {
      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
    }
    await prepareDestination(path);
    const temporary = join(dirname(path), `.kiln-write-${randomUUID()}.tmp`);
    const file = await open(temporary, 'wx');
    try {
      try {
        await writeFile(file, data);
      } finally {
        await file.close();
      }
      try {
        await link(temporary, path);
        published.push({ path, reused: false });
      } catch (error) {
        // A concurrent export published the same name first: reuse it only if identical.
        if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
        await same(path, data);
        published.push({ path, reused: true });
      }
    } finally {
      await unlink(temporary).catch(() => {});
    }
  }
  return published;
}

/**
 * External glTF export: content-addressed textures first, then the exclusive model files
 * (sidecar, buffers, `.gltf` last) under `writeNewDestinationsAtomic`'s never-replace and
 * rollback rules. An existing model destination is refused before any texture is written.
 */
export async function writeExternalTextureExport(
  textures: { path: string; data: Uint8Array }[],
  outputs: { path: string; data: Parameters<typeof writeFile>[1] }[],
): Promise<{ path: string; reused: boolean }[]> {
  for (const { path } of outputs) {
    try {
      await lstat(path);
    } catch (error) {
      if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue;
      throw error;
    }
    throw Object.assign(
      new Error(
        `${path} already exists and is never replaced; choose a new output path or remove the file.`,
      ),
      { code: 'EEXIST' },
    );
  }
  const published = await writeContentAddressedFiles(textures);
  await writeNewDestinationsAtomic(outputs);
  return published;
}