Desktop app for designing parametric 3D models in CadQuery together with the coding agent of your choice
TypeScript 3d-modeling3d-printing3d-printing-toolsagentagentic-aiai-cadcadcadqueryclaude-codecodexelectronfemllmmacdmakeropencodeparametric-designpythonsteptext-to-cad
App: bridge.json für soma render, Skill „Shell environment“
Kai-Jungsthoefeldf57741c265d
diff --git a/app/resources/skills/shell-environment.md b/app/resources/skills/shell-environment.mdnew file mode 100644index 0000000..869888a--- /dev/null+++ b/app/resources/skills/shell-environment.md@@ -0,0 +1,41 @@+---+title: Shell environment+name: Shell environment+summary: What to do when soma or pip is not found, soma says the shell lacks the app's environment, or umlauts in files look garbled.+order: 8+category: Way of working+default: on-demand+when: `soma` or `pip` is not found, `soma build` says the shell lacks the environment of the app's terminals, or umlauts in files look garbled (ä, ü)+topics: Why it happens; Running soma; Installing packages; Reading files in Windows PowerShell+---+# Skill: Shell environment++## Why it happens++The app's terminals put `soma`, `pip` and the model's own Python environment on the PATH. Some agents run their+commands somewhere else, for example in a background service that kept the environment of another program. Then+`soma` is missing or another `pip` answers. The working folder is still the model's folder, so call everything+through the model's environment directly.++## Running soma++- Windows: `.soma\env\Scripts\python.exe -m soma build` (same for every other `soma` command).+- macOS and Linux: `.soma/env/bin/python -m soma build`.+- If that file is missing, tell the user. Do not create an environment yourself.+- `soma render` still works: it finds the running app on its own. If it reports that the app is not running, tell the+ user to open the model in SOMA.++## Installing packages++Only `.soma\env\Scripts\python.exe -m pip install <package>` (macOS and Linux: `.soma/env/bin/python -m pip install+<package>`). Never a `pip` or `python` from the PATH: the package would land outside the model, and `soma build` would+not find it or record it in `requirements.txt`.++## Reading files in Windows PowerShell++Windows PowerShell 5.1 reads files without a byte order mark as ANSI, so umlauts turn into `ä`, `ü`. The file is+fine, only the reading is wrong.++- Read with `Get-Content -Encoding UTF8 <file>`.+- Never copy garbled text into an edit: it would break the file.+- Do not write files with `Set-Content` or `Out-File` (ANSI or a byte order mark). Use your own file editing tool.diff --git a/app/src/main/bridge.ts b/app/src/main/bridge.tsindex 94dae69..cd39627 100644--- a/app/src/main/bridge.ts+++ b/app/src/main/bridge.ts@@ -1,10 +1,19 @@import crypto from 'node:crypto';+import fs from 'node:fs';import http from 'node:http';+import path from 'node:path';+import { userDataDir } from './paths';/*** Verbindung von `soma` im Terminal zur App (E58), etwa für `soma render`: ein HTTP-Dienst nur auf 127.0.0.1, mit einem* zufälligen Port und einem Schlüssel je App-Start. Beides bekommen nur die Terminals der App als Umgebungsvariablen* (SOMA_APP, SOMA_APP_TOKEN). Andere Programme kennen den Schlüssel nicht, Anfragen ohne ihn werden abgelehnt.+ *+ * Manche Agenten führen ihre Befehle nicht in der Shell aus, in der sie gestartet wurden: Codex etwa über einen+ * Hintergrunddienst, der die Umgebung des Programms behält, aus dem er zuerst gestartet wurde (z. B. VS Code), und+ * Variablen mit TOKEN im Namen filtert Codex ohnehin heraus. Deshalb stehen beide zusätzlich in `bridge.json` in den+ * App-Daten, neben `workspaces/`: `soma` findet die Datei vom Arbeitsordner aus. Nie im Projekt, so kann der Schlüssel+ * weder in Git noch in die Modelldatei geraten.*/export type BridgeHandler = (route: string, body: unknown) => Promise<{ status: number; body: unknown }>;@@ -25,12 +34,31 @@ export function startBridge(handler: BridgeHandler): Promise<void> {const a = srv.address();port = typeof a === 'object' && a ? a.port : 0;server = srv;+ writeBridgeFile();resolve();});});}-export function stopBridge(): void { server?.close(); server = null; port = 0; }+export function stopBridge(): void { server?.close(); server = null; port = 0; removeBridgeFile(); }++const bridgeFile = () => path.join(userDataDir(), 'bridge.json');++/** Nur eine Erleichterung: Scheitert das Schreiben, bleiben die Umgebungsvariablen. */+function writeBridgeFile(): void {+ try {+ fs.mkdirSync(userDataDir(), { recursive: true });+ fs.writeFileSync(bridgeFile(), JSON.stringify({ app: `127.0.0.1:${port}`, token, pid: process.pid }), { mode: 0o600 });+ } catch (e) { console.error('[soma] Could not write bridge.json:', e); }+}++/** Nur die eigene: Eine zweite laufende App kann die Datei inzwischen überschrieben haben. */+function removeBridgeFile(): void {+ try {+ const cur = JSON.parse(fs.readFileSync(bridgeFile(), 'utf8')) as { token?: string };+ if (cur.token === token) fs.rmSync(bridgeFile(), { force: true });+ } catch { /* keine Datei oder unlesbar: nichts zu tun */ }+}/** Umgebungsvariablen für Terminals: Adresse und Schlüssel, leer ohne laufenden Dienst. */export function bridgeEnv(): Record<string, string> {diff --git a/app/test/animation.mjs b/app/test/animation.mjsindex dc28df0..642fc86 100644--- a/app/test/animation.mjs+++ b/app/test/animation.mjs@@ -207,8 +207,22 @@ try {await domClick('btn-measure');// 6) soma render: Fehler der Verbindung- r = soma(['render'], { env: { ...process.env, PYTHONUTF8: '1', SOMA_APP: '', SOMA_APP_TOKEN: '' } });- check('Ohne die Umgebung der App: verständliche Meldung', r.status === 1 && r.stderr.includes('needs the running app'), r.stderr);+ // Ohne die Umgebung der Terminals (Codex führt Befehle über einen Dienst mit fremder Umgebung aus): bridge.json in den App-Daten+ const noEnv = { ...process.env, PYTHONUTF8: '1', PYTHONIOENCODING: 'utf-8', SOMA_APP: '', SOMA_APP_TOKEN: '', SOMA_PROJECT: '' };+ let bj = null;+ try { bj = JSON.parse(fs.readFileSync(path.join(dir, '..', '..', 'bridge.json'), 'utf8')); } catch { /* fehlt */ }+ check('bridge.json neben workspaces/: dieselbe Adresse und derselbe Schlüssel wie in den Terminals', bj?.app === bridge.SOMA_APP && bj?.token === bridge.SOMA_APP_TOKEN, JSON.stringify(bj));+ r = soma(['render', '--size', '320x200', '--out', 'renders/ohne-umgebung.png'], { env: noEnv });+ check('Ohne die Umgebung der App: soma render findet die App über bridge.json', r.status === 0 && fs.existsSync(path.join(dir, 'renders', 'ohne-umgebung.png')), r.stdout + r.stderr);+ const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'soma-ausserhalb-'));+ r = soma(['render', '--project', outside], { env: noEnv });+ check('Ohne Umgebung und außerhalb der Arbeitsordner: verständliche Meldung', r.status === 1 && r.stderr.includes('needs the running app'), r.stderr);+ cleanup(outside);+ r = soma(['build'], { env: noEnv });+ check('soma build mit fremder Umgebung: Hinweis auf python -m soma, pip und den Skill', r.status === 0 && r.stdout.includes("does not have the environment of the app's terminals")+ && r.stdout.includes('-m pip install') && r.stdout.includes('shell-environment.md'), r.stdout + r.stderr);+ r = soma(['build'], { env: { ...env, SOMA_PROJECT: dir } });+ check('soma build in der Umgebung der Terminals: kein Hinweis', r.status === 0 && !r.stdout.includes('Note:'), r.stdout + r.stderr);r = soma(['render'], { env: { ...env, SOMA_APP_TOKEN: 'x'.repeat(48) } });check('Falscher Schlüssel: abgelehnt', r.status === 1 && r.stderr.includes('Wrong key'), r.stderr);const other = fs.mkdtempSync(path.join(os.tmpdir(), 'soma-anderes-'));diff --git a/app/test/skills.mjs b/app/test/skills.mjsindex bf47549..e24c306 100644--- a/app/test/skills.mjs+++ b/app/test/skills.mjs@@ -60,13 +60,13 @@ try {/** Die beiden Listen des Abschnitts: Immer vor „Read when relevant“, Bei Bedarf danach. */const always = () => (block() ?? '').split('### Read when relevant')[0];const demand = () => (block() ?? '').split('### Read when relevant')[1] ?? '';- const DEMAND_NEW = 'soma-app,3d-printing,resin-powder,cnc,laser,sheet-metal,tolerances,joints,strength,assemblies,analysis,animation,fem,drawings';+ const DEMAND_NEW = 'shell-environment,soma-app,3d-printing,resin-powder,cnc,laser,sheet-metal,tolerances,joints,strength,assemblies,analysis,animation,fem,drawings';// 1) Panel: die mitgelieferten Skills nach Kategorien und `order`await ev(() => document.querySelector('#rail [data-panel="skills"]').click());await waitFor('Skills geladen', () => window.__t.skills().skills.length >= 3, 10000);let s = await st();- const ORDER = 'design-workflow,cadquery,parametric,soma-app,3d-printing,resin-powder,cnc,laser,sheet-metal,tolerances,joints,standard-parts,strength,assemblies,analysis,animation,fem,drawings';+ const ORDER = 'design-workflow,cadquery,parametric,shell-environment,soma-app,3d-printing,resin-powder,cnc,laser,sheet-metal,tolerances,joints,standard-parts,strength,assemblies,analysis,animation,fem,drawings';const heads = await ev(() => [...document.querySelectorAll('#skills-list .sk-cat')].map((h) => h.textContent).join(','));check('Panel „Skills": Überschriften Way of working, Manufacturing, Design knowledge, Check and present, darunter die Skills nach `order`',s.skills.map((x) => x.id).join(',') === ORDER && heads === 'Way of working,Manufacturing,Design knowledge,Check and present'@@ -92,7 +92,7 @@ try {&& always().includes('- `.soma/skills/parametric.md`: Parametric models') && !always().includes('3d-printing')&& demand().includes('- `.soma/skills/3d-printing.md`: 3D printing (FDM). Read when the parts will be 3D printed on a filament printer (FDM).')&& DEMAND_NEW.split(',').every((id) => demand().includes(`.soma/skills/${id}.md`))- && (await g('ls-files', '.soma/skills')).split('\n').length === 18+ && (await g('ls-files', '.soma/skills')).split('\n').length === 19&& (await ev(() => window.__t.saveState())).dirtyFiles === 0, `${String((await ev(() => window.__t.saveState())).dirtyFiles)} | ${String(block()).slice(0, 200)}`);// Anleitung (E83): Skill „Using the app“ bei Bedarf, Bilder in .soma/help/ (nicht im Verlauf), Hilfe-Fenster aus derselben Quelleconst helpPngs = fs.readdirSync(path.join(APP, 'resources', 'help')).filter((n) => n.endsWith('.png'));@@ -375,12 +375,12 @@ try {const fdm2 = fs.readFileSync(path.join(p2.dir, '.soma', 'skills', '3d-printing.md'), 'utf8');const ka2 = fs.readFileSync(path.join(p2.dir, '.soma', 'skills', 'design-workflow.md'), 'utf8');check('Neues Modell nach der Vorgabe: immer Sauber modellieren, Parametrik, 3D-Druck, Normteile, Laser aus, Konstruktionsablauf bei Bedarf, Standardwerte statt 55° und PETG',- JSON.stringify(pj2.skills) === '["cadquery","parametric","3d-printing","standard-parts"]' && pj2.skills_on_demand.join(',') === 'design-workflow,soma-app,resin-powder,cnc,sheet-metal,tolerances,joints,strength,assemblies,analysis,animation,fem,drawings'+ JSON.stringify(pj2.skills) === '["cadquery","parametric","3d-printing","standard-parts"]' && pj2.skills_on_demand.join(',') === 'design-workflow,shell-environment,soma-app,resin-powder,cnc,sheet-metal,tolerances,joints,strength,assemblies,analysis,animation,fem,drawings'&& !pj2.skill_settings && fdm2.includes('Overhangs up to 45°') && fdm2.includes('| Material | PLA |') && !fdm2.includes('On demand') && ka2.includes('> **On demand:**')&& !fs.existsSync(path.join(p2.dir, '.soma', 'skills', 'laser.md'))&& norm(fs.readFileSync(path.join(p2.dir, 'AGENTS.md'), 'utf8')).includes('- `.soma/skills/3d-printing.md`: 3D printing (FDM)\n'), JSON.stringify(pj2));await waitFor('Speicherstand neu', () => window.__t.saveState() && !window.__t.saveState().unsaved, 10000).catch(() => {});- check('Neues Modell: Skills im Startcommit, nichts ungespeichert', (await exec(['ls-files', '.soma/skills'], p2.dir)).stdout.trim().split('\n').length === 17+ check('Neues Modell: Skills im Startcommit, nichts ungespeichert', (await exec(['ls-files', '.soma/skills'], p2.dir)).stdout.trim().split('\n').length === 18&& (await ev(() => window.__t.saveState())).dirtyFiles === 0, String((await ev(() => window.__t.saveState())).dirtyFiles));// 11) Einstellungen (E78): eigene Skills anlegen, mitgelieferte bearbeiten und zurücksetzen, löschen, importieren@@ -401,7 +401,7 @@ try {await ev(() => document.querySelector('#st-nav [data-sec="skills"]').click());await waitFor('Reiter Skills', () => window.__t.settings().section === 'skills' && window.__t.settings().skills.length >= 18, 10000);let us = await ust();- check('Einstellungen: alle mitgelieferten Skills nach Kategorien, keiner gewählt, Hintergrund gesperrt', us.skills.length === 18 && us.skills.every((s) => s.source === 'builtin') && us.selected === null+ check('Einstellungen: alle mitgelieferten Skills nach Kategorien, keiner gewählt, Hintergrund gesperrt', us.skills.length === 19 && us.skills.every((s) => s.source === 'builtin') && us.selected === null&& us.list.includes('3D printing (FDM)') && /way of working/i.test(us.list) && await ev(() => {// Echte Klicks: Das Fenster selbst darf nicht gesperrt sein, der Knopf liegt oben (Treffertest)const b = document.getElementById('btn-st-new').getBoundingClientRect();diff --git a/app/test/unit.mjs b/app/test/unit.mjsindex 465ecb3..2673498 100644--- a/app/test/unit.mjs+++ b/app/test/unit.mjs@@ -200,10 +200,10 @@ try {const SKD = { bundled: path.join(APP, 'resources', 'skills'), user: path.join(tmp, 'keine-eigenen-skills') };const dm = defaultModes(SKD, {});check('Neue Modelle: ohne Vorgabe des Nutzers Arbeitsweise (mit Parametrik) und Normteile immer, alle übrigen bei Bedarf', dm.always.join(',') === 'design-workflow,cadquery,parametric,standard-parts'- && dm.demand.join(',') === 'soma-app,3d-printing,resin-powder,cnc,laser,sheet-metal,tolerances,joints,strength,assemblies,analysis,animation,fem,drawings', JSON.stringify(dm));+ && dm.demand.join(',') === 'shell-environment,soma-app,3d-printing,resin-powder,cnc,laser,sheet-metal,tolerances,joints,strength,assemblies,analysis,animation,fem,drawings', JSON.stringify(dm));const dm2 = defaultModes(SKD, { 'design-workflow': 'demand', tolerances: 'always', '3d-printing': 'always', laser: 'off' });check('Neue Modelle: Vorgabe des Nutzers geht vor, in der Reihenfolge des Panels, „Aus“ fehlt ganz', dm2.always.join(',') === 'cadquery,parametric,3d-printing,tolerances,standard-parts'- && dm2.demand.join(',') === 'design-workflow,soma-app,resin-powder,cnc,sheet-metal,joints,strength,assemblies,analysis,animation,fem,drawings', JSON.stringify(dm2));+ && dm2.demand.join(',') === 'design-workflow,shell-environment,soma-app,resin-powder,cnc,sheet-metal,joints,strength,assemblies,analysis,animation,fem,drawings', JSON.stringify(dm2));// Bei Bedarf (E55): Hinweis unter der ersten Überschrift, Werte als Standard der App, vom Nutzer gesetzte mit Namenconst rd = renderSkill(SRC, {}, 'demand');check('Bei Bedarf: Hinweis direkt unter der Überschrift, mit Leerzeilen, Werte als Standard der App, NOTES.md', rd.includes('# Skill\n\n> **On demand:**')