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.

Setup says when the GPU render service shipped but was never installed (#123)

Matthew Kissingerb81cfd4caed6
diff --git a/.agents/skills/kiln-setup-workspace/SKILL.md b/.agents/skills/kiln-setup-workspace/SKILL.md
index 1295dee9..c49008d0 100644
--- a/.agents/skills/kiln-setup-workspace/SKILL.md
+++ b/.agents/skills/kiln-setup-workspace/SKILL.md
@@ -40,7 +40,7 @@ Hermes needs one user-level registration for the MCP server, because it has no p
Setup asks for render mode `auto`: a GPU service when one answers on port 8000, CPU views otherwise. CPU views are honest about silhouette, proportion and contact and say nothing about colour, metalness or roughness, so without the service no render can confirm a material.
-Offer to run its install. It lives in the engine installation rather than the workspace, and it is a separate package with a native dependency, so its install is its own step and is not covered by installing the engine.
+Run its install unless the user declines; in a headless session, where there is nobody to ask, install it without asking, because a session that starts without it stays on CPU views for its lifetime. It lives in the engine installation rather than the workspace, and it is a separate package with a native dependency, so its install is its own step and is not covered by installing the engine. Setup prints a notice when the service shipped but was never installed.
```bash
cd render-service && npm install
diff --git a/.claude/skills/kiln-setup-workspace/SKILL.md b/.claude/skills/kiln-setup-workspace/SKILL.md
index 1295dee9..c49008d0 100644
--- a/.claude/skills/kiln-setup-workspace/SKILL.md
+++ b/.claude/skills/kiln-setup-workspace/SKILL.md
@@ -40,7 +40,7 @@ Hermes needs one user-level registration for the MCP server, because it has no p
Setup asks for render mode `auto`: a GPU service when one answers on port 8000, CPU views otherwise. CPU views are honest about silhouette, proportion and contact and say nothing about colour, metalness or roughness, so without the service no render can confirm a material.
-Offer to run its install. It lives in the engine installation rather than the workspace, and it is a separate package with a native dependency, so its install is its own step and is not covered by installing the engine.
+Run its install unless the user declines; in a headless session, where there is nobody to ask, install it without asking, because a session that starts without it stays on CPU views for its lifetime. It lives in the engine installation rather than the workspace, and it is a separate package with a native dependency, so its install is its own step and is not covered by installing the engine. Setup prints a notice when the service shipped but was never installed.
```bash
cd render-service && npm install
diff --git a/scripts/create-workspace.mjs b/scripts/create-workspace.mjs
index 1a154843..6018176d 100644
--- a/scripts/create-workspace.mjs
+++ b/scripts/create-workspace.mjs
@@ -13,7 +13,7 @@ import {
writeFile,
} from 'node:fs/promises';
import { createHash } from 'node:crypto';
-import { realpathSync } from 'node:fs';
+import { existsSync, realpathSync } from 'node:fs';
import { spawnSync } from 'node:child_process';
import { dirname, join, resolve, relative, isAbsolute, sep } from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -248,6 +248,23 @@ async function fileHashes(directory, prefix = '') {
}
/** Preflight first; create a complete project in a staging directory before installing it. */
+/**
+ * The GPU render service ships as source in `render-service/` and is a separate
+ * npm project with a native dependency, so installing the engine does not
+ * install it. A fresh clone has the source and no `node_modules`; without a
+ * word at setup, the first authoring session gets CPU views and cannot confirm
+ * a material. Mirrors `localRenderServiceState` in src/render-service-host.ts:
+ * `webgpu` is the install that costs something, `three` catches a half-finished one.
+ */
+export function renderServiceNotice(runtime) {
+ const dir = join(runtime, 'render-service');
+ if (!existsSync(join(dir, 'src/server.mjs')) || !existsSync(join(dir, 'package.json')))
+ return undefined;
+ if (existsSync(join(dir, 'node_modules/webgpu')) && existsSync(join(dir, 'node_modules/three')))
+ return undefined;
+ return `The GPU render service at ${dir} is present but not installed, so every render will be a CPU view and nothing can confirm a material. Run \`npm install\` in that directory before the first authoring session, or continue on CPU views.`;
+}
+
export async function createWorkspace(directory, harness = 'claude', options = {}) {
const root = resolve(directory);
// Version managers can expose Node through a directory link lasting only one shell.
@@ -449,6 +466,8 @@ if (isDirectSetupEntry()) {
if (options.repair && options.skills)
throw new Error('--repair does not change installed skills.');
console.log(quote(await createWorkspace(directory, harness, options)));
+ const notice = renderServiceNotice(await realpath(resolve(installation)));
+ if (notice) console.error(notice);
}
} catch (error) {
console.error(error.message);
diff --git a/skills/kiln-setup-workspace/SKILL.md b/skills/kiln-setup-workspace/SKILL.md
index 1295dee9..c49008d0 100644
--- a/skills/kiln-setup-workspace/SKILL.md
+++ b/skills/kiln-setup-workspace/SKILL.md
@@ -40,7 +40,7 @@ Hermes needs one user-level registration for the MCP server, because it has no p
Setup asks for render mode `auto`: a GPU service when one answers on port 8000, CPU views otherwise. CPU views are honest about silhouette, proportion and contact and say nothing about colour, metalness or roughness, so without the service no render can confirm a material.
-Offer to run its install. It lives in the engine installation rather than the workspace, and it is a separate package with a native dependency, so its install is its own step and is not covered by installing the engine.
+Run its install unless the user declines; in a headless session, where there is nobody to ask, install it without asking, because a session that starts without it stays on CPU views for its lifetime. It lives in the engine installation rather than the workspace, and it is a separate package with a native dependency, so its install is its own step and is not covered by installing the engine. Setup prints a notice when the service shipped but was never installed.
```bash
cd render-service && npm install
diff --git a/src/__tests__/workspace-render-service-notice.test.ts b/src/__tests__/workspace-render-service-notice.test.ts
new file mode 100644
index 00000000..2634dd8c
--- /dev/null
+++ b/src/__tests__/workspace-render-service-notice.test.ts
@@ -0,0 +1,50 @@
+/**
+ * Setup tells a developer when the GPU render service shipped but was never
+ * installed. A fresh clone carries `render-service/src` and no `node_modules`,
+ * and without the notice the first authoring session silently gets CPU views
+ * and can never confirm a material.
+ */
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { afterEach, expect, it } from 'bun:test';
+
+const script = pathToFileURL(resolve(import.meta.dir, '../../scripts/create-workspace.mjs')).href;
+const roots: string[] = [];
+
+afterEach(async () => {
+ await Promise.all(roots.splice(0).map((d) => rm(d, { recursive: true, force: true })));
+});
+
+async function installation(layout: 'none' | 'source-only' | 'installed'): Promise<string> {
+ const root = await mkdtemp(join(tmpdir(), 'kiln-rs-notice-'));
+ roots.push(root);
+ if (layout === 'none') return root;
+ await mkdir(join(root, 'render-service/src'), { recursive: true });
+ await writeFile(join(root, 'render-service/src/server.mjs'), '');
+ await writeFile(join(root, 'render-service/package.json'), '{}');
+ if (layout === 'installed') {
+ await mkdir(join(root, 'render-service/node_modules/webgpu'), { recursive: true });
+ await mkdir(join(root, 'render-service/node_modules/three'), { recursive: true });
+ }
+ return root;
+}
+
+it('names the uninstalled render service and the command that installs it', async () => {
+ const { renderServiceNotice } = await import(script);
+ const runtime = await installation('source-only');
+ const notice = renderServiceNotice(runtime) as string | undefined;
+ expect(notice).toBeDefined();
+ expect(notice).toContain('not installed');
+ expect(notice).toContain('npm install');
+ expect(notice).toContain(join(runtime, 'render-service'));
+ expect(notice).toContain('CPU');
+});
+
+it('says nothing when the service is installed or was never shipped', async () => {
+ const { renderServiceNotice } = await import(script);
+ expect(renderServiceNotice(await installation('installed'))).toBeUndefined();
+ expect(renderServiceNotice(await installation('none'))).toBeUndefined();
+});