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.
JavaScript 3d3d-assets3d-modelingagent-skillsagent-toolsai-agentsasset-pipelinecligame-assetsglbgltfmcpmcp-servermodel-context-protocolprocedural-generationprocedural-modelingtext-to-3dthreejstypescript
import { readFile, writeFile, stat, mkdir, rename } from 'node:fs/promises';
import { basename, resolve, dirname, isAbsolute } from 'node:path';
import { randomUUID } from 'node:crypto';
import { createHash } from 'node:crypto';
import { assertCollectionRoot, localAssetLibrary, collectionConfigPath } from './assets-node';
import { listAssetCatalog } from './asset-catalog';
import { ASSET_LIMIT, assetIdSchema, decodeAssetBundle } from './assets';
import { localProgramStore } from './program-store-node';
import { programRefPattern, retainProgram } from './program-store';
import { createKilnProgramToolRegistry, newestRevision } from './tools/registry';
import { writeExternalTextureExport, writeNewDestinationsAtomic } from './cli-output';
import { createKtx2Encoder, exportAssetGlb } from './asset-export';
import { inspectDrawDiagnostics } from './draw-diagnostics';
import { createPackagedLocalToolContext } from './local-runtime';
import { buildRenderPort, resolveRenderMode } from './cli-render-mode';
import { startAssetViewer } from './asset-viewer';
import { FileWorkspace, localWorkspaceRoot } from './workspace-node';
import { FileLiveReview } from './live-review-node';
import { resolveAssetMaterialPayload } from './project-bundle-node';
import { FULL_OPTIMIZATION_PIPELINE, rebuildOptionsSchema } from './rebuild-options';
import { assertSavedRequirementsAuthorized } from './requirements-assets';
import { resolveRequirementsContext } from './requirements-context';
import { assetViewerHref } from './viewer/deep-link';
import { CATEGORY_MIGRATION_MESSAGE, readHostRequirementsFile } from './requirements-file';
import { observeLiveReview } from './tools/workspace';
import { cliWorkspaceSelection, readMaterialDependencies } from './workspace-cli';
/** `kiln textures` reads every asset into memory, so the set is bounded. */
const TEXTURE_REPORT_LIMIT = 1024;
const SAVE_LINES = ` kiln save <source.js|programRef> --name <name> [--collection project]
[--asset <id> --parent <revision>] [--description <text>] [--tag <tag>]
[--model <model>] [--harness <harness>] [--author <author>] declared attribution
[--backdrop neutral|dark|light] preview backdrop; the one the reviewed sheet used
[--project <id> | --no-project] [--project-revision <r>] [--materials <json>]`;
/** What `kiln save --help` prints: the one command (a blind run read 16,077 characters of global usage for it). */
export const SAVE_USAGE = `
SAVE
${SAVE_LINES}
[--render auto|cpu|gpu] views for the preview and its review (default: auto)
[--requirements <host-binding.json>] optional host policy
Prints the saved revision as JSON: assetId, revisionId and the review. A later revision
of the same asset names it with --asset and --parent. kiln --help lists every command.
`;
export const ASSET_USAGE = `
ASSETS & VIEWER
${SAVE_LINES}
kiln collections list configured collections and their directories
kiln collections add <name> <directory> remember another collection root
--requirements <host-binding.json> optional host policy for save or asset --restore
kiln assets [--collection project] list saved revisions (JSON)
kiln assets --all Library across all registered collections
kiln asset <id> [<revision>] [--collection project] [--restore] newest revision by default
kiln asset <id> [<revision>] --rebuild --out rebuilt.glb [--requirements file]
kiln export <id> <revision> --out asset.zip [--format bundle|glb|source]
[--profile editable|runtime] runtime writes GLB + sibling metadata JSON
[--target three] runtime only: meshopt + quantization, repeatInstances GPU
instancing; sidecar states node scales; KTX2 skipped unless --ktx2
[--compression meshopt|none] with --target three: none writes plain buffers
for loaders without a Meshopt decoder (default meshopt)
[--max-lod N] with --target three: keep LOD0..LODN of each MSFT_lod chain and
drop the rest (0 keeps LOD0 only); the sidecar lists what was dropped
[--position-bits 8..16|float] with --target three: position quantization bits
(default 14) or float positions; the sidecar reports the grid step
[--ktx2] with --target three: KTX2 through the optional [email protected] peer
(npm install [email protected]), ETC1S colour, UASTC data maps
[--draws minimal] runtime only: batch every repeated mesh and merge one-off parts
per material; the saved revision is unchanged, the sidecar reports it
[--draw-cell M] with --draws minimal: merge cell size in metres (default 15)
[--textures manifest] runtime only: the sidecar names each image's exact bytes
[--textures external] with --target three and --out x.gltf: x.gltf, x.bin and
shared textures/<sha256>.<ext> files that are never replaced
[--json] receipt naming each file with its bytes and sha256
export never replaces an existing file: an export hands off one exact
saved revision, while render --out replaces its own working output
kiln textures <file-or-directory>... [--json]
how many distinct images a delivered set carries against how many it ships,
and the bytes sharing them would save. The duplication is between assets,
never inside one, so point this at a whole delivery folder. Reads only:
it writes and rewrites nothing
kiln import <asset.zip|asset.glb> [--collection project] [--name <name>]
prints the directory of each imported revision
kiln view [collection-directory|asset.glb|asset.zip] [--port 4318]
[--collection project --asset <id> --revision <revision>]
[--observe-workspace <directory>] repeat to review other explicit workspaces
KILN_COLLECTIONS is an optional JSON map of collection names to absolute folders.
On Windows these name a drive or share, such as C:/Users/you/kiln-assets; a Git Bash
path such as /c/Users/you/kiln-assets is refused rather than read as C:\\c\\Users\\...
Defaults: project -> <workspace>/assets/kiln; library -> your OS user-data directory.
An explicit map replaces both defaults. Existing source/render commands still work.
View prints a local browser URL and remains running until interrupted.
`;
export async function assetMain(argv: readonly string[]): Promise<number> {
const command = argv[0];
const positional: string[] = [];
const flags: Record<string, string> = {};
const tags: string[] = [];
const observeWorkspaces: string[] = [];
const allowed = new Set([
'collection',
'name',
'asset',
'parent',
'revision',
'description',
'brief',
'model',
'harness',
'author',
'tag',
'out',
'format',
'profile',
'target',
'compression',
'max-lod',
'position-bits',
'draws',
'draw-cell',
'textures',
'port',
'render',
'backdrop',
'requirements',
'project',
'project-revision',
'materials',
]);
for (let i = 1; i < argv.length; i++) {
const arg = argv[i]!;
if (arg === '--observe-workspace') {
const path = argv[++i];
if (command !== 'view' || !path || path.startsWith('--') || observeWorkspaces.length >= 32)
throw new Error('view accepts up to 32 --observe-workspace directories');
observeWorkspaces.push(resolve(path));
continue;
}
if (arg === '--all') {
if (command !== 'assets' || flags.all)
throw new Error('--all is supported once by assets only');
flags.all = 'true';
continue;
}
if (arg === '--help' || arg === '-h') {
console.log(command === 'save' ? SAVE_USAGE : ASSET_USAGE);
return 0;
}
if (arg === '--category' || arg.startsWith('--category='))
throw new Error(CATEGORY_MIGRATION_MESSAGE);
// The CLI's --json rule (cli-json.ts) leaves the switch on the export and textures receipts.
if (arg === '--json' && (command === 'export' || command === 'textures')) {
flags.json = 'true';
continue;
}
if (arg === '--ktx2' && command === 'export') {
flags.ktx2 = 'true';
continue;
}
if (arg === '--restore' || arg === '--rebuild' || arg === '--no-project') {
flags[arg.slice(2)] = 'true';
continue;
}
if (arg.startsWith('--')) {
const key = arg.slice(2);
const value = argv[++i];
if (!allowed.has(key) || value === undefined) throw new Error(`Invalid option ${arg}`);
if (key === 'tag') tags.push(value);
else flags[key] = value;
} else positional.push(arg);
}
if (command !== 'save' && ['model', 'harness', 'author'].some((key) => flags[key] !== undefined))
throw new Error('--model, --harness and --author are supported by save only.');
if (
flags.rebuild &&
(command !== 'asset' ||
flags.restore ||
!flags.out ||
flags.project ||
flags['project-revision'] ||
flags['no-project'] ||
flags.materials)
)
throw new Error(
'--rebuild requires asset and --out; it uses saved dependencies and cannot combine with --restore or project overrides.',
);
if (
command !== 'save' &&
['project', 'project-revision', 'no-project', 'materials'].some((key) =>
Object.hasOwn(flags, key),
)
)
throw new Error(
'--project, --project-revision, --no-project and --materials are supported by save only.',
);
if (
flags.requirements &&
command !== 'save' &&
!(command === 'asset' && (flags.restore || flags.rebuild))
)
throw new Error(
'--requirements is supported by save, asset --restore and asset --rebuild only.',
);
const requirements = flags.requirements
? await readHostRequirementsFile(flags.requirements)
: undefined;
const library = localAssetLibrary();
const collection = flags.collection ?? 'project';
const fileBytes = async (path: string) => {
if ((await stat(path)).size > ASSET_LIMIT) throw new Error('File exceeds 64 MiB');
return new Uint8Array(await readFile(path));
};
if (command === 'collections') {
if (positional[0] === 'add') {
if (process.env.KILN_COLLECTIONS)
throw new Error(
'KILN_COLLECTIONS overrides saved configuration. Unset it before changing workspace collections.',
);
const [, name, directory] = positional;
if (!name || !directory) throw new Error('collections add requires name and directory');
assetIdSchema.parse(name);
// A relative directory resolves against the working directory, as typed. A rooted
// one must name a drive on Windows, where /c/Users/x would land in C:\c\Users\x.
assertCollectionRoot(name, isAbsolute(directory) ? directory : resolve(directory));
const roots = Object.fromEntries(
library.collections().map((c) => [c.id, library.directory(c.id)]),
);
if (roots[name] && roots[name] !== resolve(directory))
throw new Error('Collection name already points to another directory');
roots[name] = resolve(directory);
const path = collectionConfigPath();
await mkdir(dirname(path), { recursive: true });
const temporary = `${path}.${randomUUID()}.tmp`;
await writeFile(temporary, JSON.stringify(roots, null, 2), { flag: 'wx' });
await rename(temporary, path);
console.log(
`Collection ${name}: ${roots[name]}. Restart running MCP/viewer processes to load it.`,
);
} else {
// The CLI names each root so a misconfigured one is visible; the shared
// collections() list feeding MCP and the viewer stays name-only.
const collections = library
.collections()
.map((entry) => ({ ...entry, directory: library.directory(entry.id) }));
console.log(JSON.stringify({ collections }, null, 2));
}
} else if (command === 'assets') {
if (flags.all && flags.collection) throw new Error('Use --all or --collection, not both');
console.log(
JSON.stringify(
flags.all ? await listAssetCatalog(library) : { assets: await library.list(collection) },
null,
2,
),
);
} else if (command === 'save') {
const selection = cliWorkspaceSelection(
flags.project,
flags['project-revision'],
flags['no-project'] === 'true',
);
const materialDependencies = flags.materials
? await readMaterialDependencies(flags.materials)
: undefined;
const input = positional[0];
if (!input || !flags.name) throw new Error('save requires source/ref and --name');
const store = localProgramStore();
const programRef = programRefPattern.test(input)
? input
: await retainProgram(store, new TextDecoder().decode(await fileBytes(input)));
const context = await createPackagedLocalToolContext(
await buildRenderPort(resolveRenderMode(flags.render), undefined),
);
const def = createKilnProgramToolRegistry({
...context,
requirements,
assetLibrary: library,
programStore: store,
}).find((d) => d.name === 'kiln_save')!;
try {
console.log(
JSON.stringify(
await def.run({
collection,
programRef,
name: flags.name,
assetId: flags.asset,
parentRevision: flags.parent,
description: flags.description,
brief: flags.brief,
attribution:
flags.model !== undefined || flags.harness !== undefined || flags.author !== undefined
? { model: flags.model, harness: flags.harness, author: flags.author }
: undefined,
tags,
backdrop: flags.backdrop,
...selection,
...(materialDependencies ? { materialDependencies } : {}),
}),
null,
2,
),
);
} finally {
try {
await context.liveReview?.flush?.();
} catch {
/* Optional observation. */
}
}
} else if (command === 'asset' || command === 'export') {
const [assetId, named] = positional;
if (!assetId || (command === 'export' && !named))
throw new Error(`${command} requires asset ID and revision ID`);
// `asset` without a revision reads the newest one, as kiln_assets get does (decision
// 28 of 2 October 2026); export hands off one exact revision and still names it.
const revisionId = named ?? (await newestRevision(library, collection, assetId));
const record = await library.read(collection, assetId, revisionId);
if (command === 'asset') {
if (flags.rebuild) {
const context = await createPackagedLocalToolContext({ requirements });
const execute = async () => {
const source = record.files['source.kiln.js'];
if (!source) throw new Error('Editable source unavailable');
assertSavedRequirementsAuthorized(
record.manifest,
resolveRequirementsContext(requirements),
);
const parsed = rebuildOptionsSchema.safeParse(record.manifest.build?.options);
if (!parsed.success)
throw new Error(
'Saved exporter settings are incomplete; use an explicit new authoring run instead of an exact rebuild.',
);
if (
parsed.data.optimize === 'full' &&
parsed.data.optimizationPipeline !== FULL_OPTIMIZATION_PIPELINE
)
throw new Error(
'Saved revision uses an unversioned full optimization pipeline; rebuild with its original pinned engine, or explicitly author and save a new child revision to migrate.',
);
// The pipeline version is replay metadata, not an evaluator input option.
const { optimizationPipeline: _pipeline, ...renderOptions } = parsed.data;
const materialResources = await resolveAssetMaterialPayload(
new FileWorkspace(localWorkspaceRoot()),
record,
);
const code = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(source);
const rendered = await context.evaluatorPort!.render(code, {
...renderOptions,
materialResources,
requirements,
});
try {
context.liveReview?.artifact(code, rendered);
} catch {
/* Optional observation. */
}
await writeNewDestinationsAtomic([{ path: resolve(flags.out!), data: rendered.glb }]);
return {
ok: true,
file: resolve(flags.out!),
artifactGlbSha256: rendered.artifactGlbSha256,
savedArtifactGlbSha256: record.manifest.files['asset.glb']!.sha256,
matchesSavedArtifact:
rendered.artifactGlbSha256 === record.manifest.files['asset.glb']!.sha256,
rebuildOptions: rendered.rebuildOptions,
tris: rendered.tris,
warnings: rendered.warnings,
};
};
try {
const result = await observeLiveReview(
context.liveReview,
'kiln_asset_rebuild',
{ runtimeIdentity: context.localExecution.runtimeIdentity },
execute,
);
console.log(JSON.stringify(result, null, 2));
} finally {
try {
await context.liveReview?.flush?.();
} catch {
/* Optional observation. */
}
}
} else if (flags.restore) {
const restore = createKilnProgramToolRegistry({
assetLibrary: library,
programStore: localProgramStore(),
requirements,
}).find((def) => def.name === 'kiln_assets')!;
console.log(
JSON.stringify(
await restore.run({
action: 'restore',
collection,
assetId,
revisionId,
}),
null,
2,
),
);
} else console.log(JSON.stringify(record.manifest, null, 2));
} else {
if (!flags.out) throw new Error('export requires --out');
const profile = flags.profile ?? 'editable';
if (profile !== 'editable' && profile !== 'runtime')
throw new Error('Unknown export profile');
const target = flags.target;
if (target !== undefined && target !== 'three') throw new Error('Unknown export target');
if (target !== undefined && profile !== 'runtime')
throw new Error('--target requires --profile runtime');
const compression = flags.compression;
if (compression !== undefined && compression !== 'meshopt' && compression !== 'none')
throw new Error('--compression must be meshopt or none');
if (compression !== undefined && target !== 'three')
throw new Error('--compression requires --target three');
const maxLodFlag = flags['max-lod'];
if (maxLodFlag !== undefined && !/^\d+$/.test(maxLodFlag))
throw new Error('--max-lod must be a non-negative integer, such as 0 for LOD0 only');
if (maxLodFlag !== undefined && target !== 'three')
throw new Error('--max-lod requires --target three');
const maxLod = maxLodFlag === undefined ? undefined : Number(maxLodFlag);
const bitsFlag = flags['position-bits'];
if (
bitsFlag !== undefined &&
bitsFlag !== 'float' &&
!(/^\d+$/.test(bitsFlag) && Number(bitsFlag) >= 8 && Number(bitsFlag) <= 16)
)
throw new Error('--position-bits must be an integer from 8 to 16, or float');
if (bitsFlag !== undefined && target !== 'three')
throw new Error('--position-bits requires --target three');
const positionBits =
bitsFlag === undefined || bitsFlag === 'float' ? bitsFlag : Number(bitsFlag);
const draws = flags.draws;
if (draws !== undefined && draws !== 'minimal') throw new Error('--draws must be minimal');
if (draws !== undefined && profile !== 'runtime')
throw new Error('--draws requires --profile runtime');
const drawCellFlag = flags['draw-cell'];
if (drawCellFlag !== undefined && draws === undefined)
throw new Error('--draw-cell requires --draws minimal');
const drawCellSize = drawCellFlag === undefined ? undefined : Number(drawCellFlag);
if (drawCellSize !== undefined && !(drawCellSize > 0))
throw new Error('--draw-cell must be a positive number of metres');
const textures = flags.textures;
if (textures !== undefined && textures !== 'manifest' && textures !== 'external')
throw new Error('Unknown --textures value; use manifest or external');
if (textures !== undefined && profile !== 'runtime')
throw new Error('--textures requires --profile runtime');
if (textures === 'external' && target !== 'three')
throw new Error('--textures external requires --target three');
if (flags.ktx2 && (target !== 'three' || profile !== 'runtime'))
throw new Error('--ktx2 requires --target three with --profile runtime');
const gltfLayout = textures === 'external';
const format =
flags.format ?? (profile === 'runtime' ? (gltfLayout ? 'gltf' : 'glb') : 'bundle');
if (!['bundle', 'glb', 'source', 'gltf'].includes(format))
throw new Error('Unknown export format');
if (format === 'gltf' && !gltfLayout)
throw new Error('gltf format requires --textures external');
const written: { kind: string; path: string; data: Uint8Array; reused?: boolean }[] = [];
let drawGlb: Uint8Array | undefined;
let ktx2Receipt: unknown;
if (profile === 'runtime') {
if (format !== (gltfLayout ? 'gltf' : 'glb'))
throw new Error(
gltfLayout
? '--textures external writes gltf format'
: 'Runtime profile requires GLB format; use editable for source or bundle',
);
const destination = resolve(flags.out);
const extension = gltfLayout ? '.gltf' : '.glb';
if (!destination.toLowerCase().endsWith(extension))
throw new Error(`Runtime output must end in ${extension}`);
const stem = basename(destination).slice(0, -extension.length);
const metadataFileName = `${stem}.kiln-metadata.json`;
const output = await exportAssetGlb(record, {
profile,
metadataFileName,
...(target ? { target } : {}),
...(compression ? { compression } : {}),
...(maxLod !== undefined ? { maxLod } : {}),
...(positionBits !== undefined ? { positionBits } : {}),
...(draws ? { draws } : {}),
...(drawCellSize !== undefined ? { drawCellSize } : {}),
...(textures ? { textures } : {}),
...(gltfLayout ? { gltfFileName: basename(destination) } : {}),
...(flags.ktx2 ? { ktx2Encoder: await createKtx2Encoder() } : {}),
});
if (output.profile !== 'runtime') throw new Error('Expected runtime export');
const metadataPath = resolve(dirname(destination), output.metadata.name);
drawGlb = output.glb;
if (flags.ktx2)
ktx2Receipt = JSON.parse(new TextDecoder().decode(output.metadata.bytes)).delivery?.ktx2;
if (output.layout === 'gltf') {
const directory = dirname(destination);
const files = output.textures.map(({ uri, bytes }) => ({
path: resolve(directory, ...uri.split('/')),
data: bytes,
}));
const buffers = output.buffers.map(({ uri, bytes }) => ({
path: resolve(directory, uri),
data: bytes,
}));
const published = await writeExternalTextureExport(files, [
{ path: metadataPath, data: output.metadata.bytes },
...buffers,
{ path: destination, data: output.gltf.bytes },
]);
written.push(
{ kind: 'gltf', path: destination, data: output.gltf.bytes },
...buffers.map(({ path, data }) => ({ kind: 'bin', path, data })),
{ kind: 'metadata', path: metadataPath, data: output.metadata.bytes },
...files.map(({ path, data }, index) => ({
kind: 'texture',
path,
data,
reused: published[index]!.reused,
})),
);
} else {
await writeNewDestinationsAtomic([
{ path: metadataPath, data: output.metadata.bytes },
{ path: destination, data: output.glb },
]);
written.push(
{ kind: 'glb', path: destination, data: output.glb },
{ kind: 'metadata', path: metadataPath, data: output.metadata.bytes },
);
}
} else {
const bytes =
format === 'bundle'
? await library.exportBundle([record])
: record.files[format === 'glb' ? 'asset.glb' : 'source.kiln.js'];
if (!bytes) throw new Error('Source unavailable');
const destination = resolve(flags.out);
await writeNewDestinationsAtomic([{ path: destination, data: bytes }]);
written.push({ kind: format, path: destination, data: bytes });
}
if (!flags.json)
console.log(
written.map(({ path, reused }) => `${reused ? 'Reused' : 'Saved'} ${path}`).join('\n'),
);
else
console.log(
JSON.stringify(
{
ok: true,
collection,
assetId,
revisionId,
profile,
...(target ? { target } : {}),
...(compression ? { compression } : {}),
...(maxLod !== undefined ? { maxLod } : {}),
...(positionBits !== undefined ? { positionBits } : {}),
...(draws ? { draws } : {}),
...(drawCellSize !== undefined ? { drawCellSize } : {}),
format,
...(ktx2Receipt ? { ktx2: ktx2Receipt } : {}),
...(format !== 'source'
? {
drawDiagnostics: await inspectDrawDiagnostics(
drawGlb ??
written.find(({ kind }) => kind === 'glb')?.data ??
record.files['asset.glb']!,
),
}
: {}),
files: written.map(({ kind, path, data, reused }) => ({
kind,
path,
bytes: data.byteLength,
sha256: `sha256:${createHash('sha256').update(data).digest('hex')}`,
...(reused === undefined ? {} : { reused }),
})),
},
null,
2,
),
);
}
} else if (command === 'textures') {
if (!positional.length) throw new Error('textures requires a file or directory');
const { readdir } = await import('node:fs/promises');
const paths: string[] = [];
for (const path of positional) {
if ((await stat(path)).isDirectory())
for (const entry of (await readdir(path)).sort()) {
if (entry.toLowerCase().endsWith('.glb')) paths.push(resolve(path, entry));
}
else paths.push(resolve(path));
}
// Bounded so pointing this at a whole tree fails fast instead of reading it all in.
if (paths.length > TEXTURE_REPORT_LIMIT)
throw new Error(`textures reads at most ${TEXTURE_REPORT_LIMIT} assets at once`);
const assets: { name: string; bytes: Uint8Array }[] = [];
for (const path of paths) assets.push({ name: basename(path), bytes: await fileBytes(path) });
const { textureSharingReport } = await import('./texture-sharing');
const report = await textureSharingReport(assets);
if (flags.json) console.log(JSON.stringify({ ok: true, ...report }, null, 2));
else {
const count = (value: number) => value.toLocaleString('en-US');
const share = report.assetBytes
? ` (${((100 * report.duplicateImageBytes) / report.assetBytes).toFixed(1)}% of ${count(report.assetBytes)} delivered bytes)`
: '';
console.log(
`${count(report.assets)} assets · ${count(report.embeddedImages)} embedded images · ${count(report.distinctImages)} distinct · ${count(report.duplicateImageBytes)} duplicated bytes${share}`,
);
for (const { name, reason } of report.skipped) console.log(`Skipped ${name}: ${reason}`);
if (!report.duplicateImageBytes)
console.log('Every image is carried once: nothing to share across this set.');
else {
console.log(
'Share each image once with --textures external, or name their identities for a host with --textures manifest (docs/export-profiles.md#runtime-textures-manifest-and-shared-files):',
);
const shared = report.images.filter((image) => image.copies > 1);
// Names are abbreviated here; --json carries every hash and every asset in full.
for (const image of shared.slice(0, 10)) {
const names = image.assets.slice(0, 3).join(', ');
const rest = image.assets.length - 3;
const size = image.width === undefined ? '' : `${image.width}x${image.height} `;
console.log(
` ${image.sha256.slice('sha256:'.length, 'sha256:'.length + 12)} ${count(image.bytes)} B ${size}${image.mimeType} · ${image.copies} copies · saves ${count(image.bytes * (image.copies - 1))} B · ${names}${rest > 0 ? ` +${count(rest)} more` : ''}`,
);
}
if (shared.length > 10)
console.log(` ... and ${count(shared.length - 10)} more shared images (--json for all)`);
}
}
} else if (command === 'import') {
const file = positional[0];
if (!file) throw new Error('import requires a ZIP or GLB file');
const bytes = await fileBytes(file);
const assets = file.toLowerCase().endsWith('.glb')
? [await library.save(collection, { name: flags.name ?? basename(file, '.glb'), glb: bytes })]
: await library.import(collection, decodeAssetBundle(bytes));
const directory = library.directory(collection);
console.log(
JSON.stringify(
{
collection,
directory,
assets: assets.map((manifest) => ({
...manifest,
path: library.revisionDirectory(collection, manifest.assetId, manifest.revisionId),
})),
},
null,
2,
),
);
} else if (command === 'view') {
let target = library;
let standalone: { name: string; bytes: Uint8Array } | undefined;
const file = positional[0];
if (file) {
if ((await stat(file)).isDirectory()) {
const { FileAssetLibrary } = await import('./assets-node');
target = new FileAssetLibrary({ project: resolve(file) });
} else standalone = { name: basename(file), bytes: await fileBytes(file) };
}
const port = flags.port === undefined ? 4318 : Number(flags.port);
if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error('Invalid port');
if ((flags.asset && !flags.revision) || (!flags.asset && flags.revision))
throw new Error('view requires --asset and --revision together');
const root = localWorkspaceRoot();
const reviewSources: NonNullable<Parameters<typeof startAssetViewer>[1]>['reviewSources'] = {};
const { realpath } = await import('node:fs/promises');
const currentRoot = await realpath(root);
for (const path of observeWorkspaces) {
if (!(await stat(path)).isDirectory())
throw new Error('Observation source must be a directory');
const canonical = await realpath(path);
if (canonical === currentRoot) continue;
const id = `w_${createHash('sha256').update(canonical).digest('hex').slice(0, 16)}`;
reviewSources[id] = { label: basename(canonical), review: new FileLiveReview(canonical) };
}
const viewer = await startAssetViewer(target, {
port,
standalone,
workspace: new FileWorkspace(root),
liveReview: new FileLiveReview(root),
reviewSources,
});
const viewerUrl = standalone
? `${viewer.url}?open=standalone`
: flags.asset && flags.revision
? assetViewerHref(viewer.url, {
collection,
assetId: flags.asset,
revisionId: flags.revision,
})
: viewer.url;
console.log(viewerUrl);
console.log('Kiln viewer · local files · Ctrl+C to stop');
}
return 0;
}