sim-cli-core 0.3.6__tar.gz → 0.3.8__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (134) hide show
  1. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/.github/workflows/publish.yml +46 -46
  2. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/.gitignore +63 -63
  3. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/CLAUDE.md +196 -186
  4. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/CONTRIBUTING.md +25 -25
  5. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/LICENSE +190 -190
  6. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/NOTICE +35 -35
  7. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/PKG-INFO +84 -112
  8. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/README.md +333 -362
  9. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/assets/architecture.svg +89 -89
  10. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/assets/banner.svg +70 -70
  11. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/assets/logo.svg +22 -22
  12. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/docs/DEVELOPMENT.md +116 -114
  13. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/docs/agent-readability.md +193 -188
  14. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/docs/architecture/multi-session-and-config.md +204 -204
  15. sim_cli_core-0.3.8/docs/architecture/skills-layering-plan.md +68 -0
  16. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/docs/architecture/version-compat.md +148 -148
  17. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/docs/plugin-install.md +202 -204
  18. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/pyproject.toml +69 -68
  19. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/src/sim/__init__.py +11 -11
  20. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/src/sim/__main__.py +24 -24
  21. sim_cli_core-0.3.8/src/sim/_plugin_install.py +172 -0
  22. sim_cli_core-0.3.8/src/sim/_skills/sim-cli/SKILL.md +146 -0
  23. sim_cli_core-0.3.8/src/sim/_skills/sim-cli/gui/SKILL.md +239 -0
  24. sim_cli_core-0.3.8/src/sim/_skills/sim-cli/gui/snippets/dismiss_named_dialog.py +19 -0
  25. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/src/sim/_timeout.py +115 -115
  26. sim_cli_core-0.3.8/src/sim/assets.py +309 -0
  27. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/src/sim/cli.py +1407 -1410
  28. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/src/sim/compat.py +430 -433
  29. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/src/sim/config.py +377 -377
  30. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/src/sim/describe.py +367 -325
  31. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/src/sim/driver.py +190 -190
  32. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/src/sim/drivers/__init__.py +155 -155
  33. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/src/sim/gui/LICENSES/ATTRIBUTION.md +24 -24
  34. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/src/sim/gui/__init__.py +230 -230
  35. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/src/sim/gui/_pywinauto_tools.py +452 -452
  36. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/src/sim/gui/_win32_dialog.py +148 -148
  37. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/src/sim/history.py +176 -176
  38. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/src/sim/inspect.py +1124 -1124
  39. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/src/sim/plugins.py +484 -468
  40. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/src/sim/runner.py +195 -195
  41. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/src/sim/server.py +659 -581
  42. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/src/sim/session.py +227 -227
  43. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/src/sim/testing/__init__.py +30 -30
  44. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/src/sim/testing/protocol_conformance.py +264 -264
  45. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/base/test_cli.py +234 -234
  46. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/base/test_compat.py +373 -374
  47. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/base/test_config.py +122 -122
  48. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/base/test_connect.py +26 -26
  49. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/base/test_describe.py +180 -166
  50. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/base/test_driver_discovery.py +135 -135
  51. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/base/test_history.py +98 -98
  52. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/base/test_init_setup.py +204 -203
  53. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/base/test_lint.py +49 -49
  54. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/base/test_lint_public_corpus.py +159 -159
  55. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/base/test_logs.py +100 -100
  56. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/base/test_multi_session.py +233 -233
  57. sim_cli_core-0.3.8/tests/base/test_plugin_install.py +92 -0
  58. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/base/test_plugins.py +159 -158
  59. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/base/test_protocol_conformance.py +212 -212
  60. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/base/test_python_floor_audit.py +127 -127
  61. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/base/test_run.py +127 -127
  62. sim_cli_core-0.3.8/tests/base/test_scan.py +194 -0
  63. sim_cli_core-0.3.8/tests/base/test_session_versions.py +158 -0
  64. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/conftest.py +131 -131
  65. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/execution/calculix_e2e_cantilever_run.py +163 -163
  66. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/execution/coolprop/water_props.py +33 -33
  67. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/execution/elmer_e2e_heat_square.py +171 -171
  68. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/execution/gmsh_e2e_sphere_mesh.py +131 -131
  69. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/execution/lammps_e2e_lj_nvt.py +159 -159
  70. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/execution/meshio_e2e_gmsh_to_vtk.py +105 -105
  71. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/execution/pymfem_e2e_poisson.py +78 -78
  72. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/execution/pyvista_e2e_sphere_stats.py +109 -109
  73. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/execution/scikit_fem_e2e_poisson.py +60 -60
  74. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/execution/scikitrf/short_load.py +32 -32
  75. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/execution/su2_e2e_inviscid_bump.py +113 -113
  76. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/comsol/comsol_good.py +12 -12
  77. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/comsol/comsol_no_client.py +4 -4
  78. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/comsol/comsol_no_import.py +3 -3
  79. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/hypermesh_good.py +13 -13
  80. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/hypermesh_gui.py +7 -7
  81. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/hypermesh_no_import.py +3 -3
  82. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/hypermesh_no_usage.py +3 -3
  83. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/hypermesh_syntax_error.py +4 -4
  84. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/isaac/bad_import_order.py +5 -5
  85. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/isaac/bad_no_close.py +4 -4
  86. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/isaac/bad_no_simapp.py +3 -3
  87. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/isaac/hello_world.py +51 -51
  88. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/isaac/import_franka.py +34 -34
  89. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/isaac/not_isaac.py +2 -2
  90. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/isaac/official_hello_world.py +50 -50
  91. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/isaac/replicator_cubes.py +57 -57
  92. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/isaac/syntax_error.py +2 -2
  93. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/isaac/warehouse_sdg.py +50 -50
  94. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/matlab/matlab_ok.m +2 -2
  95. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/mfem_good.py +14 -14
  96. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/mfem_no_import.py +3 -3
  97. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/mfem_no_mesh.py +3 -3
  98. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/mfem_syntax_error.py +3 -3
  99. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/mock_fail.py +5 -5
  100. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/mock_solver.py +6 -6
  101. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/newton/basic_pendulum.json +34 -34
  102. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/newton/cable_twist.py +75 -75
  103. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/newton/robot_g1.json +42 -42
  104. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/not_simulation.py +2 -2
  105. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/pybamm/pybamm_bad_import.py +4 -4
  106. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/pybamm/pybamm_crate_sweep.py +43 -43
  107. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/pybamm/pybamm_no_solve.py +6 -6
  108. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/pybamm/pybamm_spm_good.py +47 -47
  109. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/skfem_good.py +22 -22
  110. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/skfem_no_import.py +3 -3
  111. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/skfem_no_solve.py +6 -6
  112. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/skfem_syntax_error.py +3 -3
  113. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/gui/test_connect_tools_field.py +91 -87
  114. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/gui/test_gui_facade.py +164 -164
  115. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/inspect/_extract_comsol_Tmax.py +81 -81
  116. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/inspect/test_channel_3_4_5_9.py +401 -401
  117. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/inspect/test_gui_probes.py +331 -331
  118. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/inspect/test_inspect_types.py +164 -164
  119. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/inspect/test_probes.py +244 -244
  120. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/inspect/test_snippet_timeout.py +110 -110
  121. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tools/audit_python_floor.py +339 -339
  122. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tools/extract_driver.py +598 -598
  123. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tools/lint-public-corpus.py +279 -279
  124. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/uv.lock +14 -1
  125. sim_cli_core-0.3.6/docs/architecture/skills-layering-plan.md +0 -306
  126. sim_cli_core-0.3.6/src/sim/_plugin_install.py +0 -352
  127. sim_cli_core-0.3.6/tests/base/test_plugin_install.py +0 -248
  128. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/__init__.py +0 -0
  129. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/base/__init__.py +0 -0
  130. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/drivers/__init__.py +0 -0
  131. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/matlab/empty_model.mdl +0 -0
  132. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/fixtures/matlab/empty_model.slx +0 -0
  133. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/gui/__init__.py +0 -0
  134. {sim_cli_core-0.3.6 → sim_cli_core-0.3.8}/tests/inspect/__init__.py +0 -0
@@ -1,46 +1,46 @@
1
- name: Publish to PyPI
2
-
3
- on:
4
- push:
5
- tags: ["v*"]
6
- workflow_dispatch:
7
-
8
- jobs:
9
- build:
10
- runs-on: ubuntu-latest
11
- steps:
12
- - uses: actions/checkout@v4
13
-
14
- - uses: astral-sh/setup-uv@v5
15
- with:
16
- python-version: "3.12"
17
-
18
- - name: Build sdist + wheel
19
- run: uv build
20
-
21
- - name: Sanity-check artifacts
22
- run: |
23
- uv tool run twine check dist/*
24
- ls -lh dist/
25
-
26
- - uses: actions/upload-artifact@v4
27
- with:
28
- name: dist
29
- path: dist/
30
-
31
- publish:
32
- name: Upload to PyPI (trusted publishing)
33
- needs: build
34
- runs-on: ubuntu-latest
35
- environment:
36
- name: pypi
37
- url: https://pypi.org/p/sim-cli-core
38
- permissions:
39
- id-token: write
40
- steps:
41
- - uses: actions/download-artifact@v4
42
- with:
43
- name: dist
44
- path: dist/
45
-
46
- - uses: pypa/gh-action-pypi-publish@release/v1
1
+ name: Publish to PyPI
2
+
3
+ on:
4
+ push:
5
+ tags: ["v*"]
6
+ workflow_dispatch:
7
+
8
+ jobs:
9
+ build:
10
+ runs-on: ubuntu-latest
11
+ steps:
12
+ - uses: actions/checkout@v4
13
+
14
+ - uses: astral-sh/setup-uv@v5
15
+ with:
16
+ python-version: "3.12"
17
+
18
+ - name: Build sdist + wheel
19
+ run: uv build
20
+
21
+ - name: Sanity-check artifacts
22
+ run: |
23
+ uv tool run twine check dist/*
24
+ ls -lh dist/
25
+
26
+ - uses: actions/upload-artifact@v4
27
+ with:
28
+ name: dist
29
+ path: dist/
30
+
31
+ publish:
32
+ name: Upload to PyPI (trusted publishing)
33
+ needs: build
34
+ runs-on: ubuntu-latest
35
+ environment:
36
+ name: pypi
37
+ url: https://pypi.org/p/sim-cli-core
38
+ permissions:
39
+ id-token: write
40
+ steps:
41
+ - uses: actions/download-artifact@v4
42
+ with:
43
+ name: dist
44
+ path: dist/
45
+
46
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -1,63 +1,63 @@
1
- # Python
2
- __pycache__/
3
- *.py[cod]
4
- *.egg-info/
5
- *.egg
6
- build/
7
- dist/
8
- .pytest_cache/
9
- .ruff_cache/
10
- .mypy_cache/
11
-
12
- # Virtual envs
13
- .venv/
14
- venv/
15
- env/
16
-
17
- # sim runtime artifacts
18
- .sim/
19
-
20
- # IDE
21
- .vscode/
22
- .idea/
23
- *.swp
24
-
25
- # OS
26
- .DS_Store
27
- Thumbs.db
28
-
29
- # Local test output
30
- tests/execution/logs/
31
- *.log
32
-
33
- # Solver run artifacts at repo root (Fluent trace files, ad-hoc screenshots)
34
- /*.trn
35
- /*.png
36
-
37
- # Local Claude Code skills (project-private, do not publish)
38
- .claude/
39
-
40
- # Local/temp files
41
- mylocal.ip
42
- *.sim
43
- __pycache__/
44
- tmp/
45
-
46
- # Solver-runtime temp files (Fluent cleanup scripts / COMSOL tetra scratch / misc .tmp)
47
- /cleanup-fluent-*.bat
48
- /*.tmp
49
-
50
- # LSDYNA runtime outputs — produced by every solver invocation, not fixtures
51
- tests/execution/lsdyna/d3dump[0-9]*
52
- tests/execution/lsdyna/d3hsp
53
- tests/execution/lsdyna/d3plot*
54
- tests/execution/lsdyna/messag
55
- tests/execution/lsdyna/status.out
56
-
57
- # Inspect integration-test outputs (reproducible; do not check in)
58
- tests/inspect/_run_outputs/
59
-
60
- # Local self-reading plan docs (not shipped with PR)
61
- docs/abaqus-plan.md
62
- docs/plans/
63
- docs/superpowers/
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ *.egg
6
+ build/
7
+ dist/
8
+ .pytest_cache/
9
+ .ruff_cache/
10
+ .mypy_cache/
11
+
12
+ # Virtual envs
13
+ .venv/
14
+ venv/
15
+ env/
16
+
17
+ # sim runtime artifacts
18
+ .sim/
19
+
20
+ # IDE
21
+ .vscode/
22
+ .idea/
23
+ *.swp
24
+
25
+ # OS
26
+ .DS_Store
27
+ Thumbs.db
28
+
29
+ # Local test output
30
+ tests/execution/logs/
31
+ *.log
32
+
33
+ # Solver run artifacts at repo root (Fluent trace files, ad-hoc screenshots)
34
+ /*.trn
35
+ /*.png
36
+
37
+ # Local Claude Code skills (project-private, do not publish)
38
+ .claude/
39
+
40
+ # Local/temp files
41
+ mylocal.ip
42
+ *.sim
43
+ __pycache__/
44
+ tmp/
45
+
46
+ # Solver-runtime temp files (Fluent cleanup scripts / COMSOL tetra scratch / misc .tmp)
47
+ /cleanup-fluent-*.bat
48
+ /*.tmp
49
+
50
+ # LSDYNA runtime outputs — produced by every solver invocation, not fixtures
51
+ tests/execution/lsdyna/d3dump[0-9]*
52
+ tests/execution/lsdyna/d3hsp
53
+ tests/execution/lsdyna/d3plot*
54
+ tests/execution/lsdyna/messag
55
+ tests/execution/lsdyna/status.out
56
+
57
+ # Inspect integration-test outputs (reproducible; do not check in)
58
+ tests/inspect/_run_outputs/
59
+
60
+ # Local self-reading plan docs (not shipped with PR)
61
+ docs/abaqus-plan.md
62
+ docs/plans/
63
+ docs/superpowers/
@@ -1,186 +1,196 @@
1
- # CLAUDE.md
2
-
3
- This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
-
5
- ## Project Overview
6
-
7
- **sim** is a unified CLI + HTTP runtime that lets LLM agents (and engineers) launch, drive, and observe CAD/CAE simulations across multiple solvers through one consistent interface. It is the "container runtime for simulations" — agents talk to `sim`, `sim` talks to solvers.
8
-
9
- The runtime supports two execution modes:
10
-
11
- - **One-shot** (`sim run script --solver=X`): subprocess execution, result stored as a numbered run, `sim logs` to browse.
12
- - **Persistent session** (`sim serve` + `sim connect/exec/inspect/disconnect`): a long-lived HTTP server holds a live solver session; agents send code snippets and inspect state without restarting the solver.
13
-
14
- The companion repo `sim-skills/` contains per-solver agent skills, reference docs, demo workflows, and integration tests that drive this runtime.
15
-
16
- ## Commands
17
-
18
- ```bash
19
- # Install
20
- uv pip install -e ".[dev]" # core + pytest + ruff
21
-
22
- # Tests
23
- pytest -q # unit tests (no solver needed)
24
- pytest tests/test_lint.py # single test file
25
- pytest -q -m integration # integration tests (need solvers + sim serve)
26
-
27
- # Lint
28
- ruff check src/sim tests
29
- ruff check --fix src/sim tests
30
-
31
- # CLI
32
- sim serve --host 0.0.0.0 # start HTTP server (default port 7600)
33
- sim --host <ip> connect --solver <name> --mode solver --ui-mode gui
34
- sim --host <ip> exec "solver.settings.mesh.check()"
35
- sim --host <ip> inspect session.summary
36
- sim --host <ip> screenshot -o shot.png
37
- sim --host <ip> disconnect
38
-
39
- sim run script.py --solver pybamm # one-shot mode
40
- sim logs # list runs
41
- sim logs last --field voltage_V # extract a parsed field
42
- sim check <name> # solver availability
43
- sim lint script.py # validate before running
44
- ```
45
-
46
- Environment variables: `SIM_HOST`, `SIM_PORT` (CLI client, also `[server]` in config), `SIM_HOME` (global config + history dir, default `~/.sim/`), `SIM_DIR` (project dir, default `./.sim/`).
47
-
48
- Config files (issue #5): `~/.sim/config.toml` (global) + `.sim/config.toml` (project). Resolution order `env > project > global > default`. With no config files present, behavior is unchanged from pre-config sim. Run `sim config path | show | init` to manage. See `docs/architecture/multi-session-and-config.md` for the full schema.
49
-
50
- ## Architecture
51
-
52
- ### CLI (`src/sim/cli.py`)
53
- Click app with subcommands: `serve`, `check`, `lint`, `run`, `connect`, `exec`, `inspect`, `ps`, `disconnect`, `screenshot`, `logs`. The session-related commands (`connect`/`exec`/`inspect`/`ps`/`disconnect`/`screenshot`) all delegate to `sim.session.SessionClient`, an HTTP client that talks to a running `sim serve`. The non-session commands (`run`, `lint`, `check`, `logs`) work locally without a server.
54
-
55
- ### HTTP server (`src/sim/server.py`)
56
- FastAPI app exposing:
57
- - `POST /connect` — launch a solver, register a new session in `_sessions: dict[str, SessionState]` keyed by session_id
58
- - `POST /exec` — `exec()` a Python snippet against the live `session`/`meshing`/`solver` namespace for the session selected by `X-Sim-Session` header (or the single live session if unambiguous); capture stdout/stderr/return value, append to that session's runs
59
- - `GET /inspect/<name>` — query `session.summary`, `session.mode`, `last.result`, `workflow.summary` (session-scoped)
60
- - `POST /run` — one-shot script execution (no session required)
61
- - `GET /ps` — list of all live sessions + default_session (set only when exactly one live)
62
- - `GET /screenshot` — base64 PNG of the server's desktop
63
- - `POST /disconnect` — tear down the session selected by `X-Sim-Session` (or the sole live session)
64
- - `POST /shutdown` — tear down all sessions, exit the server process
65
-
66
- The server supports multiple concurrent sessions keyed by session_id. Each `SessionState` carries its own `threading.Lock` so exec/inspect against different sessions can run in parallel. A single solver name can only be live once (driver instances are module-level singletons).
67
-
68
- **`sim serve --reload` drops all sessions on any source change under the watched tree.** uvicorn's reload watchdog observes file mtimes in `src/sim/**`; any edit (git pull, scp of a modified driver, even touching an unrelated module) restarts the worker, wiping `_sessions`. Child solver processes (out-of-process GUIs, separately spawned solver binaries) survive the reload because they're spawned separately, but the session handles to them are gone — you have to `connect` again. Driver temp files written into the solver's workspace live outside `src/` so they don't retrigger. Practical rules:
69
-
70
- - Don't edit driver code mid-experiment; finish the run, then edit.
71
- - For long autonomous experiments where you're editing driver code iteratively, launch **without** `--reload` and restart manually when you want the new code picked up.
72
- - Reconnecting after a reload can take tens of seconds for GUI-mode drivers that re-adopt the existing window rather than relaunching it.
73
-
74
- ### Driver protocol (`src/sim/driver.py`)
75
- `DriverProtocol` (a `runtime_checkable` `Protocol`):
76
- - `name: str` — registered driver name
77
- - `detect(script) -> bool` — does this script target this solver?
78
- - `lint(script) -> LintResult` — pre-execution validation, returns `Diagnostic`s
79
- - `connect() -> ConnectionInfo` — package availability + version check
80
- - `parse_output(stdout) -> dict` — extract structured results (convention: last JSON line on stdout)
81
- - `run_file(script) -> RunResult` — one-shot execution
82
-
83
- `LintResult`, `Diagnostic`, `RunResult`, `ConnectionInfo` are dataclasses with `to_dict()` for JSON serialization.
84
-
85
- ### Driver registry (plugin entry points)
86
-
87
- `sim-cli-core` is solver-agnostic and ships with no in-tree solver drivers. Drivers are provided by installed plugin packages that expose the `sim.drivers` entry-point group. Use `sim plugin list` and `sim plugin info <name>` to inspect the plugins visible in the active environment.
88
-
89
- Plugin implementation work belongs in the owning `sim-plugin-<solver>` repository, where the package metadata, `DriverProtocol` implementation, `compatibility.yaml`, bundled skills, and plugin tests live. Do not add solver drivers under `src/sim/drivers/<name>` in this repo.
90
-
91
- A driver may set `supports_session = True` to implement the persistent-session lifecycle (`launch`/`run`/`query`/`disconnect`); the rest are one-shot only. `get_driver(name)` looks up by `.name` attribute and lazily imports the implementation module on first use, so a broken plugin does not crash the CLI.
92
-
93
- ### Execution pipeline — one-shot (`run`)
94
- 1. `cli.run` → `runner.execute_script(script, solver, driver)` → subprocess, captures stdout/stderr/duration
95
- 2. `driver.parse_output(stdout)` → extract structured fields
96
- 3. `history.append({cwd, solver, session_id, run_id, ...})` → single jsonl line in `~/.sim/history.jsonl`
97
- 4. `sim logs <id>` reads back via `history.get_by_id`; `sim logs --solver X --all` filters
98
-
99
- ### Execution pipeline — persistent session (`exec`)
100
- 1. `cli.connect` → HTTP `POST /connect` to server → `driver.launch(...)` → new `SessionState` added to `_sessions`; response carries the session_id which the client stores
101
- 2. `cli.exec` → HTTP `POST /exec` with code + `X-Sim-Session: <id>` → server routes to that session, then `_execute_snippet()` runs `exec(code, namespace)` where `namespace` has `session`, `meshing`/`solver`, `_result`
102
- 3. `cli.inspect <name>` → HTTP `GET /inspect/<name>` (session-scoped) → driver- or session-specific query
103
- 4. `cli.disconnect` → HTTP `POST /disconnect` (session-scoped) → driver-specific teardown, remove from `_sessions`
104
-
105
- Session routing rules: an explicit `X-Sim-Session` header wins (404 if unknown); otherwise the server falls back to the sole live session; otherwise `/exec` returns 400. Clients can also set `SIM_SESSION` env var or pass `sim --session <id> ...` to scope a whole CLI invocation.
106
-
107
- ## Adding or changing a solver driver
108
-
109
- Create or update solver drivers in the owning `sim-plugin-<solver>` repository. A plugin should implement `DriverProtocol`, register the driver through `[project.entry-points."sim.drivers"]` in its `pyproject.toml`, and carry its own compatibility metadata, bundled skills, and tests.
110
-
111
- The core CLI should only change when the shared runtime contract or plugin discovery machinery changes. Before editing driver-facing docs or behavior, inspect the installed environment with `sim plugin list` and `sim plugin info <solver>`, then work in the plugin repo that owns that solver.
112
-
113
- ## Test Layout
114
-
115
- ```
116
- tests/
117
- __init__.py
118
- conftest.py shared fixtures / execution paths
119
- base/ core framework tests (no solver needed)
120
- test_cli.py smoke tests for click commands
121
- test_compat.py skills layering / profile resolution
122
- test_config.py two-tier config resolution
123
- test_connect.py driver.connect() availability checks
124
- test_driver_discovery.py entry-point plugin discovery
125
- test_history.py global run history persistence
126
- test_lint.py lint protocol coverage
127
- test_logs.py sim logs CLI
128
- test_multi_session.py session routing + concurrency
129
- test_run.py one-shot subprocess execution
130
- fixtures/ mock scripts and shared test assets
131
- ```
132
-
133
- Solver plugin tests live in their own plugin repos. Tests in this repo cover the shared CLI/runtime contract and plugin discovery behavior.
134
-
135
- ## Notes
136
-
137
- - Global run history lives in `~/.sim/history.jsonl` (append-only; override dir via `SIM_HOME`); git-ignored
138
- - The server supports multiple concurrent sessions keyed by `X-Sim-Session` header; a solver name can only be live once per server process (driver instances are module-level singletons)
139
- - Project uses `uv` for dependency locking (`uv.lock`)
140
- - Companion knowledge / skills / workflows live in the sibling `sim-skills/` tree, one folder per solver
141
-
142
- ## Releases
143
-
144
- - **PyPI distribution name:** `sim-cli-core` (renamed from `sim-runtime` in Phase 4 — see `src/sim/plugins.py` dual-lookup; `sim-runtime 0.2.1`–`0.2.3` remain on PyPI but are no longer released against). Both names were rejected for `sim-cli` itself, which is too similar to the existing `simcli` placeholder.
145
- - **Console script + import name:** `sim`. The PyPI dist name and the import name intentionally differ; `src/sim/__init__.py` looks up `version("sim-cli-core")` first, falling back to `version("sim-runtime")` for editable installs predating the rename, and `try/except PackageNotFoundError` for source checkouts.
146
- - **Trusted publisher:** GitHub OIDC, repo `svd-ai-lab/sim-cli`, workflow `.github/workflows/publish.yml`, environment `pypi`. Configured at https://pypi.org/manage/project/sim-cli-core/settings/publishing/.
147
- - **Tag format:** `v<MAJOR.MINOR.PATCH>` matching `pyproject.toml` `version` exactly. Always tag from `main` after PR-merging a release branch.
148
- - **Don't skip the clean-venv smoke test before tagging.** 0.2.1 shipped broken (`__init__.py` referenced `version("sim-cli")` after the rename) because no one ran `sim --version` in a fresh venv before pushing the tag. Twine check verifies packaging, not import.
149
-
150
- ## Public-artifact privacy / license safety
151
-
152
- When writing anything that lands in a *public* place — GitHub issues,
153
- PR titles/bodies/comments, public commit messages, public docs — keep
154
- **engineering-relevant** facts and drop **diary-style disclosure**
155
- that ties a specific commercial-software install to a specific
156
- machine or account. The two are easy to confuse.
157
-
158
- **Keep:**
159
- - The bug, the error message, the exit code, the reproducing input.
160
- - Version info that is a genuine reproduction prereq — when a behavior
161
- is gated to a specific release of an open-source dependency, the
162
- version is part of the engineering claim and stays. Use neutral
163
- framing for closed-source dependencies ("a CFD solver release that
164
- changed the boundary-condition API") rather than naming the vendor
165
- and release.
166
- - Platform when behavior is platform-gated (Linux vs Windows
167
- filesystem casing, COM availability, etc.).
168
-
169
- **Drop / replace:**
170
- - Personal usernames and hostnames → "a Windows test host", "a
171
- development machine", or elide.
172
- - Personal IPs (including Tailscale `100.90.x.x`) → elide.
173
- - Personal filesystem paths (`C:\Users\<you>\...`,
174
- `~/Documents/GitHub/...`, `C:\Python<NN>\...`,
175
- `C:\Program Files\<Vendor>\<version>\...`) → "a local clone",
176
- "the editable install", or elide.
177
- - Specific commercial-software *versions tied to a personal machine*
178
- — vendor compliance teams treat these as license-audit signals
179
- even when the version alone would be fine. Replace with neutral
180
- phrasing.
181
- - Tailscale tailnet names, OS account SIDs, MAC/serial numbers.
182
-
183
- Sanitize existing artifacts by editing PR/issue/comment bodies
184
- (`gh pr edit`, `gh issue comment --edit-last`). Avoid force-pushing
185
- to rewrite commit-message history unless the disclosure is severe
186
- *and* the branch is unmerged *and* not being collaborated on.
1
+ # CLAUDE.md
2
+
3
+ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
+
5
+ ## Project Overview
6
+
7
+ **sim** is a unified CLI + HTTP runtime that lets LLM agents (and engineers) launch, drive, and observe CAD/CAE simulations across multiple solvers through one consistent interface. It is the "container runtime for simulations" — agents talk to `sim`, `sim` talks to solvers.
8
+
9
+ The runtime supports two execution modes:
10
+
11
+ - **One-shot** (`sim run script --solver=X`): subprocess execution, result stored as a numbered run, `sim logs` to browse.
12
+ - **Persistent session** (`sim serve` + `sim connect/exec/inspect/disconnect`): a long-lived HTTP server holds a live solver session; agents send code snippets and inspect state without restarting the solver.
13
+
14
+ The shared runtime skill is bundled at `src/sim/_skills/sim-cli/` and synced into agent skill directories by `sim plugin sync-skills`. Per-solver agent skills ship inside their own `sim-plugin-<solver>` packages.
15
+
16
+ ## Commands
17
+
18
+ ```bash
19
+ # Install
20
+ uv pip install -e ".[dev]" # core + pytest + ruff
21
+
22
+ # Tests
23
+ pytest -q # unit tests (no solver needed)
24
+ pytest tests/test_lint.py # single test file
25
+ pytest -q -m integration # integration tests (need solvers + sim serve)
26
+
27
+ # Lint
28
+ ruff check src/sim tests
29
+ ruff check --fix src/sim tests
30
+
31
+ # CLI
32
+ sim serve --host 0.0.0.0 # start HTTP server (default port 7600)
33
+ sim --host <ip> connect --solver <name> --mode solver --ui-mode gui
34
+ sim --host <ip> exec "solver.settings.mesh.check()"
35
+ sim --host <ip> inspect session.summary
36
+ sim --host <ip> screenshot -o shot.png
37
+ sim --host <ip> disconnect
38
+
39
+ sim run script.py --solver pybamm # one-shot mode
40
+ sim logs # list runs
41
+ sim logs last --field voltage_V # extract a parsed field
42
+ sim check <name> # solver availability
43
+ sim lint script.py # validate before running
44
+ ```
45
+
46
+ Environment variables: `SIM_HOST`, `SIM_PORT` (CLI client, also `[server]` in config), `SIM_HOME` (global config + history dir, default `~/.sim/`), `SIM_DIR` (project dir, default `./.sim/`).
47
+
48
+ Config files (issue #5): `~/.sim/config.toml` (global) + `.sim/config.toml` (project). Resolution order `env > project > global > default`. With no config files present, behavior is unchanged from pre-config sim. Run `sim config path | show | init` to manage. See `docs/architecture/multi-session-and-config.md` for the full schema.
49
+
50
+ ## Architecture
51
+
52
+ ### CLI (`src/sim/cli.py`)
53
+ Click app with subcommands: `serve`, `check`, `lint`, `run`, `connect`, `exec`, `inspect`, `ps`, `disconnect`, `screenshot`, `logs`. The session-related commands (`connect`/`exec`/`inspect`/`ps`/`disconnect`/`screenshot`) all delegate to `sim.session.SessionClient`, an HTTP client that talks to a running `sim serve`. The non-session commands (`run`, `lint`, `check`, `logs`) work locally without a server.
54
+
55
+ ### HTTP server (`src/sim/server.py`)
56
+ FastAPI app exposing:
57
+ - `POST /connect` — launch a solver, register a new session in `_sessions: dict[str, SessionState]` keyed by session_id
58
+ - `POST /exec` — `exec()` a Python snippet against the live `session`/`meshing`/`solver` namespace for the session selected by `X-Sim-Session` header (or the single live session if unambiguous); capture stdout/stderr/return value, append to that session's runs
59
+ - `GET /inspect/<name>` — query `session.summary`, `session.mode`, `last.result`, `workflow.summary` (session-scoped)
60
+ - `POST /run` — one-shot script execution (no session required)
61
+ - `GET /ps` — list of all live sessions + default_session (set only when exactly one live)
62
+ - `GET /screenshot` — base64 PNG of the server's desktop
63
+ - `POST /disconnect` — tear down the session selected by `X-Sim-Session` (or the sole live session)
64
+ - `POST /shutdown` — tear down all sessions, exit the server process
65
+
66
+ The server supports multiple concurrent sessions keyed by session_id. Each `SessionState` carries its own `threading.Lock` so exec/inspect against different sessions can run in parallel. A single solver name can only be live once (driver instances are module-level singletons).
67
+
68
+ **`sim serve --reload` drops all sessions on any source change under the watched tree.** uvicorn's reload watchdog observes file mtimes in `src/sim/**`; any edit (git pull, scp of a modified driver, even touching an unrelated module) restarts the worker, wiping `_sessions`. Child solver processes (out-of-process GUIs, separately spawned solver binaries) survive the reload because they're spawned separately, but the session handles to them are gone — you have to `connect` again. Driver temp files written into the solver's workspace live outside `src/` so they don't retrigger. Practical rules:
69
+
70
+ - Don't edit driver code mid-experiment; finish the run, then edit.
71
+ - For long autonomous experiments where you're editing driver code iteratively, launch **without** `--reload` and restart manually when you want the new code picked up.
72
+ - Reconnecting after a reload can take tens of seconds for GUI-mode drivers that re-adopt the existing window rather than relaunching it.
73
+
74
+ ### Driver protocol (`src/sim/driver.py`)
75
+ `DriverProtocol` (a `runtime_checkable` `Protocol`):
76
+ - `name: str` — registered driver name
77
+ - `detect(script) -> bool` — does this script target this solver?
78
+ - `lint(script) -> LintResult` — pre-execution validation, returns `Diagnostic`s
79
+ - `connect() -> ConnectionInfo` — package availability + version check
80
+ - `parse_output(stdout) -> dict` — extract structured results (convention: last JSON line on stdout)
81
+ - `run_file(script) -> RunResult` — one-shot execution
82
+
83
+ `LintResult`, `Diagnostic`, `RunResult`, `ConnectionInfo` are dataclasses with `to_dict()` for JSON serialization.
84
+
85
+ ### Driver registry (plugin entry points)
86
+
87
+ `sim-cli-core` is solver-agnostic and ships with no in-tree solver drivers. Drivers are provided by installed plugin packages that expose the `sim.drivers` entry-point group. Use `sim plugin list` and `sim plugin info <name>` to inspect the plugins visible in the active environment.
88
+
89
+ Plugin implementation work belongs in the owning `sim-plugin-<solver>` repository, where the package metadata, `DriverProtocol` implementation, `compatibility.yaml`, bundled skills, and plugin tests live. Do not add solver drivers under `src/sim/drivers/<name>` in this repo.
90
+
91
+ A driver may set `supports_session = True` to implement the persistent-session lifecycle (`launch`/`run`/`query`/`disconnect`); the rest are one-shot only. `get_driver(name)` looks up by `.name` attribute and lazily imports the implementation module on first use, so a broken plugin does not crash the CLI.
92
+
93
+ ### Execution pipeline — one-shot (`run`)
94
+ 1. `cli.run` → `runner.execute_script(script, solver, driver)` → subprocess, captures stdout/stderr/duration
95
+ 2. `driver.parse_output(stdout)` → extract structured fields
96
+ 3. `history.append({cwd, solver, session_id, run_id, ...})` → single jsonl line in `~/.sim/history.jsonl`
97
+ 4. `sim logs <id>` reads back via `history.get_by_id`; `sim logs --solver X --all` filters
98
+
99
+ ### Execution pipeline — persistent session (`exec`)
100
+ 1. `cli.connect` → HTTP `POST /connect` to server → `driver.launch(...)` → new `SessionState` added to `_sessions`; response carries the session_id which the client stores
101
+ 2. `cli.exec` → HTTP `POST /exec` with code + `X-Sim-Session: <id>` → server routes to that session, then `_execute_snippet()` runs `exec(code, namespace)` where `namespace` has `session`, `meshing`/`solver`, `_result`
102
+ 3. `cli.inspect <name>` → HTTP `GET /inspect/<name>` (session-scoped) → driver- or session-specific query
103
+ 4. `cli.disconnect` → HTTP `POST /disconnect` (session-scoped) → driver-specific teardown, remove from `_sessions`
104
+
105
+ Session routing rules: an explicit `X-Sim-Session` header wins (404 if unknown); otherwise the server falls back to the sole live session; otherwise `/exec` returns 400. Clients can also set `SIM_SESSION` env var or pass `sim --session <id> ...` to scope a whole CLI invocation.
106
+
107
+ ## Adding or changing a solver driver
108
+
109
+ Create or update solver drivers in the owning `sim-plugin-<solver>` repository. A plugin should implement `DriverProtocol`, register the driver through `[project.entry-points."sim.drivers"]` in its `pyproject.toml`, and carry its own compatibility metadata, bundled skills, and tests.
110
+
111
+ The core CLI should only change when the shared runtime contract or plugin discovery machinery changes. Before editing driver-facing docs or behavior, inspect the installed environment with `sim plugin list` and `sim plugin info <solver>`, then work in the plugin repo that owns that solver.
112
+
113
+ **Prefer generic primitives over task-specific ones.** Before adding a new
114
+ driver method purpose-built for one workflow (a resumable-sweep runner, an
115
+ auto-coupling helper, etc.), check whether bounded `run(timeout_s=...)` +
116
+ `health()`/progress inspection + the solver's own retained state already let
117
+ the agent script that workflow step-by-step. Add a new dedicated primitive
118
+ only for a genuine generic gap proven by a real session (missing timeout
119
+ guard, no orphan-process cleanup, no liveness check) — not for workflow
120
+ convenience alone. See `sim-studio-desktop` issues #62/#80 for the HFSS case
121
+ this pattern was drawn from.
122
+
123
+ ## Test Layout
124
+
125
+ ```
126
+ tests/
127
+ __init__.py
128
+ conftest.py shared fixtures / execution paths
129
+ base/ core framework tests (no solver needed)
130
+ test_cli.py smoke tests for click commands
131
+ test_compat.py skills layering / profile resolution
132
+ test_config.py two-tier config resolution
133
+ test_connect.py driver.connect() availability checks
134
+ test_driver_discovery.py entry-point plugin discovery
135
+ test_history.py global run history persistence
136
+ test_lint.py lint protocol coverage
137
+ test_logs.py sim logs CLI
138
+ test_multi_session.py session routing + concurrency
139
+ test_run.py one-shot subprocess execution
140
+ fixtures/ mock scripts and shared test assets
141
+ ```
142
+
143
+ Solver plugin tests live in their own plugin repos. Tests in this repo cover the shared CLI/runtime contract and plugin discovery behavior.
144
+
145
+ ## Notes
146
+
147
+ - Global run history lives in `~/.sim/history.jsonl` (append-only; override dir via `SIM_HOME`); git-ignored
148
+ - The server supports multiple concurrent sessions keyed by `X-Sim-Session` header; a solver name can only be live once per server process (driver instances are module-level singletons)
149
+ - Project uses `uv` for dependency locking (`uv.lock`)
150
+ - The shared runtime skill lives at `src/sim/_skills/sim-cli/`; per-solver skills ship in their `sim-plugin-<solver>` packages (synced via `sim plugin sync-skills`)
151
+
152
+ ## Releases
153
+
154
+ - **PyPI distribution name:** `sim-cli-core` (renamed from `sim-runtime` in Phase 4 — see `src/sim/plugins.py` dual-lookup; `sim-runtime 0.2.1`–`0.2.3` remain on PyPI but are no longer released against). Both names were rejected for `sim-cli` itself, which is too similar to the existing `simcli` placeholder.
155
+ - **Console script + import name:** `sim`. The PyPI dist name and the import name intentionally differ; `src/sim/__init__.py` looks up `version("sim-cli-core")` first, falling back to `version("sim-runtime")` for editable installs predating the rename, and `try/except PackageNotFoundError` for source checkouts.
156
+ - **Trusted publisher:** GitHub OIDC, repo `svd-ai-lab/sim-cli`, workflow `.github/workflows/publish.yml`, environment `pypi`. Configured at https://pypi.org/manage/project/sim-cli-core/settings/publishing/.
157
+ - **Tag format:** `v<MAJOR.MINOR.PATCH>` matching `pyproject.toml` `version` exactly. Always tag from `main` after PR-merging a release branch.
158
+ - **Don't skip the clean-venv smoke test before tagging.** 0.2.1 shipped broken (`__init__.py` referenced `version("sim-cli")` after the rename) because no one ran `sim --version` in a fresh venv before pushing the tag. Twine check verifies packaging, not import.
159
+
160
+ ## Public-artifact privacy / license safety
161
+
162
+ When writing anything that lands in a *public* place — GitHub issues,
163
+ PR titles/bodies/comments, public commit messages, public docs — keep
164
+ **engineering-relevant** facts and drop **diary-style disclosure**
165
+ that ties a specific commercial-software install to a specific
166
+ machine or account. The two are easy to confuse.
167
+
168
+ **Keep:**
169
+ - The bug, the error message, the exit code, the reproducing input.
170
+ - Version info that is a genuine reproduction prereq — when a behavior
171
+ is gated to a specific release of an open-source dependency, the
172
+ version is part of the engineering claim and stays. Use neutral
173
+ framing for closed-source dependencies ("a CFD solver release that
174
+ changed the boundary-condition API") rather than naming the vendor
175
+ and release.
176
+ - Platform when behavior is platform-gated (Linux vs Windows
177
+ filesystem casing, COM availability, etc.).
178
+
179
+ **Drop / replace:**
180
+ - Personal usernames and hostnames → "a Windows test host", "a
181
+ development machine", or elide.
182
+ - Personal IPs (including Tailscale `100.90.x.x`) → elide.
183
+ - Personal filesystem paths (`C:\Users\<you>\...`,
184
+ `~/Documents/GitHub/...`, `C:\Python<NN>\...`,
185
+ `C:\Program Files\<Vendor>\<version>\...`) → "a local clone",
186
+ "the editable install", or elide.
187
+ - Specific commercial-software *versions tied to a personal machine*
188
+ — vendor compliance teams treat these as license-audit signals
189
+ even when the version alone would be fine. Replace with neutral
190
+ phrasing.
191
+ - Tailscale tailnet names, OS account SIDs, MAC/serial numbers.
192
+
193
+ Sanitize existing artifacts by editing PR/issue/comment bodies
194
+ (`gh pr edit`, `gh issue comment --edit-last`). Avoid force-pushing
195
+ to rewrite commit-message history unless the disclosure is severe
196
+ *and* the branch is unmerged *and* not being collaborated on.