vamp-mcp 0.2.0 → 0.2.4

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.

Potentially problematic release.


This version of vamp-mcp might be problematic. Click here for more details.

Files changed (134) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +144 -107
  3. package/THIRD_PARTY_NOTICES.md +32 -27
  4. package/bin/vamp-mcp.mjs +37 -37
  5. package/notices/mcp-virtualbox-LICENSE +21 -21
  6. package/notices/mcp-virtualbox-PROVENANCE.json +37 -37
  7. package/package.json +51 -17
  8. package/runtime/backends/common/Test-Environment.ps1 +7 -6
  9. package/runtime/backends/common/guest-install.json +58 -0
  10. package/runtime/backends/common/guest_install.py +57 -0
  11. package/runtime/backends/common/host-support.cjs +16 -0
  12. package/runtime/backends/common/packer.cjs +16 -0
  13. package/runtime/backends/hyperv/scripts/Manage-Desktop.ps1 +40 -67
  14. package/runtime/backends/hyperv/scripts/Send-InstallerBoot.ps1 +25 -0
  15. package/runtime/backends/kvm/debian-preseed.cfg +35 -35
  16. package/runtime/backends/library/registry.py +77 -77
  17. package/runtime/backends/library/replay.py +154 -154
  18. package/runtime/backends/packer/answer_media.py +16 -0
  19. package/runtime/backends/packer/deploy-hyperv.ps1 +10 -0
  20. package/runtime/backends/packer/drivers.py +49 -0
  21. package/runtime/backends/packer/hyperv-network.ps1 +10 -0
  22. package/runtime/backends/packer/images.py +75 -0
  23. package/runtime/backends/packer/osinfo.py +113 -0
  24. package/runtime/backends/packer/policy.json +15 -0
  25. package/runtime/backends/packer/runner.py +224 -0
  26. package/runtime/backends/packer/templates.py +118 -0
  27. package/runtime/backends/packer/toolchain.py +80 -0
  28. package/runtime/backends/remote_ssh/server.mjs +310 -93
  29. package/runtime/backends/virtualbox/desktop.cjs +37 -0
  30. package/runtime/backends/virtualbox/display.py +101 -101
  31. package/runtime/backends/virtualbox/history.py +139 -139
  32. package/runtime/backends/virtualbox/mouse_click.py +15 -15
  33. package/runtime/backends/virtualbox/mouse_move.py +18 -18
  34. package/runtime/backends/virtualbox/profiles.json +46 -46
  35. package/runtime/backends/virtualbox/provision.py +238 -197
  36. package/runtime/backends/virtualbox/recording_listener.py +29 -29
  37. package/runtime/backends/virtualbox/recordings.py +39 -39
  38. package/runtime/backends/virtualbox/requirements.txt +7 -7
  39. package/runtime/backends/virtualbox/rpas/debian_first_boot/manifest.json +1 -1
  40. package/runtime/backends/virtualbox/rpas/debian_first_boot/run.robot +13 -13
  41. package/runtime/backends/virtualbox/rpas/debian_first_boot/workflow.py +75 -75
  42. package/runtime/backends/virtualbox/rpas/observe/manifest.json +7 -7
  43. package/runtime/backends/virtualbox/rpas/observe/run.robot +13 -13
  44. package/runtime/backends/virtualbox/rpas/observe/workflow.py +14 -14
  45. package/runtime/backends/virtualbox/server.mjs +288 -237
  46. package/runtime/backends/virtualbox/setup_windows_sdk.py +58 -58
  47. package/runtime/backends/virtualbox/shares.py +68 -68
  48. package/runtime/backends/virtualbox/snapshots.py +53 -53
  49. package/runtime/backends/virtualbox/transfers.py +89 -89
  50. package/runtime/backends/virtualbox/vnc.py +61 -61
  51. package/runtime/guest_keys.py +13 -13
  52. package/runtime/guest_setup/http/debian-preseed.cfg +39 -0
  53. package/runtime/guest_setup/http/postdeb.sh +50 -3
  54. package/runtime/guest_setup/http/postwin.ps1 +53 -28
  55. package/runtime/guest_setup/http/setup-all.ps1 +25 -25
  56. package/runtime/guest_setup/http/setup-win.cmd +7 -7
  57. package/runtime/guest_setup/http/setup.ps1 +44 -29
  58. package/runtime/guest_setup/kvm/setup-windows.ps1 +52 -52
  59. package/runtime/guest_setup/recorder/README.txt +12 -12
  60. package/runtime/guest_setup/recorder/RECORDER-LICENSE +674 -674
  61. package/runtime/guest_setup/recorder/RECORDING-GUIDE.txt +31 -31
  62. package/runtime/guest_setup/recorder/apply-display.py +41 -41
  63. package/runtime/guest_setup/recorder/configure-debian-mirrors.py +62 -62
  64. package/runtime/guest_setup/recorder/configure-gdm.py +23 -0
  65. package/runtime/guest_setup/recorder/configure-session.ps1 +14 -0
  66. package/runtime/guest_setup/recorder/gnome-display.py +60 -60
  67. package/runtime/guest_setup/recorder/install-display-startup.py +67 -39
  68. package/runtime/guest_setup/recorder/install-hypervisor-drivers.ps1 +34 -0
  69. package/runtime/guest_setup/recorder/install-resolution-shortcut.ps1 +36 -0
  70. package/runtime/guest_setup/recorder/postwin.cmd +10 -10
  71. package/runtime/guest_setup/recorder/prepare-recording.py +30 -30
  72. package/runtime/guest_setup/recorder/requirements-recorder.txt +2 -2
  73. package/runtime/guest_setup/recorder/session-policy.py +22 -0
  74. package/runtime/guest_setup/recorder/set-resolution-registry.ps1 +40 -0
  75. package/runtime/guest_setup/recorder/setup-user.py +53 -53
  76. package/runtime/guest_setup/recorder/setup-win.cmd +4 -60
  77. package/runtime/guest_setup/recorder/setup.ps1 +112 -81
  78. package/runtime/guest_setup/recorder/setup.sh +1 -0
  79. package/runtime/guest_setup/recorder/vamp-recorder.py +148 -148
  80. package/runtime/guest_setup/recorder/verify-recorder.py +4 -4
  81. package/runtime/guest_setup/recorder/windows-display.py +76 -76
  82. package/runtime/guest_setup/requirements.txt +2 -2
  83. package/runtime/guest_setup/setup-all.ps1 +35 -35
  84. package/runtime/guest_setup/vault/Install-VCRuntime.ps1 +26 -26
  85. package/runtime/guest_setup/vault/setup-guest-vault.ps1 +148 -148
  86. package/runtime/recording_converter.py +230 -230
  87. package/runtime/requirements-mcp.txt +11 -11
  88. package/runtime/rpas/README.md +161 -161
  89. package/runtime/rpas/captcha_handoff/manifest.json +27 -27
  90. package/runtime/rpas/captcha_handoff/run.robot +16 -16
  91. package/runtime/rpas/captcha_handoff/workflow.py +11 -11
  92. package/runtime/rpas/common.resource +26 -26
  93. package/runtime/rpas/debian_update/manifest.json +27 -27
  94. package/runtime/rpas/debian_update/run.robot +17 -17
  95. package/runtime/rpas/debian_update/workflow.py +13 -13
  96. package/runtime/rpas/desktop_control/manifest.json +26 -26
  97. package/runtime/rpas/desktop_control/run.robot +27 -27
  98. package/runtime/rpas/desktop_control/workflow.py +51 -51
  99. package/runtime/rpas/firefox_launch/manifest.json +27 -27
  100. package/runtime/rpas/firefox_launch/run.robot +15 -15
  101. package/runtime/rpas/firefox_launch/workflow.py +25 -25
  102. package/runtime/rpas/firefox_naver/manifest.json +27 -27
  103. package/runtime/rpas/firefox_naver/run.robot +21 -21
  104. package/runtime/rpas/firefox_naver/workflow.py +28 -28
  105. package/runtime/rpas/kvm_validation/README.md +11 -11
  106. package/runtime/rpas/kvm_validation/manifest.json +28 -28
  107. package/runtime/rpas/kvm_validation/run.robot +30 -30
  108. package/runtime/rpas/kvm_validation/workflow.py +91 -91
  109. package/runtime/rpas/manifest.schema.json +105 -105
  110. package/runtime/rpas/naver_login/login.robot +25 -25
  111. package/runtime/rpas/naver_login/manifest.json +33 -33
  112. package/runtime/rpas/naver_login/run.robot +20 -20
  113. package/runtime/rpas/naver_login/workflow.py +32 -32
  114. package/runtime/rpas/windows_naver_recorded/README.md +24 -24
  115. package/runtime/rpas/windows_naver_recorded/conversion.json +25 -25
  116. package/runtime/rpas/windows_naver_recorded/manifest.json +28 -28
  117. package/runtime/rpas/windows_naver_recorded/run.robot +37 -37
  118. package/runtime/rpas/windows_naver_recorded/workflow.py +32 -32
  119. package/runtime/scripts/build_recorder_media.py +39 -39
  120. package/runtime/scripts/macos/setup-host.sh +0 -0
  121. package/runtime/scripts/script_server.py +571 -517
  122. package/runtime/skills/vamp-rpa-ui-checks/SKILL.md +26 -0
  123. package/runtime/skills/vamp-rpa-ui-checks/agents/openai.yaml +4 -0
  124. package/runtime/skills/vamp-rpa-ui-checks/references/display.md +12 -0
  125. package/runtime/skills/vamp-rpa-ui-checks/references/user-guide.md +51 -0
  126. package/runtime/skills/vamp-ui-cleanup/SKILL.md +15 -0
  127. package/runtime/skills/vamp-ui-cleanup/agents/openai.yaml +4 -0
  128. package/runtime/skills/vamp-ui-validation/SKILL.md +27 -0
  129. package/runtime/skills/vamp-ui-validation/agents/openai.yaml +4 -0
  130. package/runtime/third_party/mcp-virtualbox/scripts/mouse_click.py +65 -65
  131. package/runtime/third_party/pyautogui-recorder/LICENSE +674 -674
  132. package/runtime/third_party/pyautogui-recorder/PROVENANCE.json +16 -16
  133. package/runtime/third_party/pyautogui-recorder/PyAutoGuiRecorder.py +169 -169
  134. package/runtime/third_party/pyautogui-recorder/README.md +53 -53
@@ -1,58 +1,58 @@
1
- """Install the matching Oracle VirtualBox Python SDK in a Windows host venv."""
2
- import argparse
3
- import hashlib
4
- import json
5
- import os
6
- from pathlib import Path
7
- import re
8
- import shutil
9
- import subprocess
10
- import sys
11
- import urllib.request
12
- import zipfile
13
-
14
- def setup(storage,vboxmanage=None,archive=None,sha256=None):
15
- if sys.platform!='win32':raise RuntimeError('The COM SDK setup is for Windows hosts')
16
- if sys.prefix==sys.base_prefix:raise RuntimeError('Run SDK setup with the isolated host Python venv')
17
- binary=Path(vboxmanage or shutil.which('VBoxManage') or r'C:\Program Files\Oracle\VirtualBox\VBoxManage.exe')
18
- version=subprocess.check_output([str(binary),'--version'],text=True).strip()
19
- match=re.match(r'(\d+\.\d+\.\d+)r(\d+)',version)
20
- if not match:raise RuntimeError('Unrecognized installed VirtualBox version')
21
- release,revision=match.groups()
22
- destination=Path(storage).resolve()/('virtualbox-sdk-'+release+'-'+revision)
23
- destination.mkdir(parents=True,exist_ok=True)
24
- if archive:
25
- package=Path(archive)
26
- if not sha256:raise ValueError('An offline SDK archive requires its expected SHA-256')
27
- expected=sha256.lower()
28
- else:
29
- name=f'VirtualBoxSDK-{release}-{revision}.zip'
30
- base=f'https://download.virtualbox.org/virtualbox/{release}/'
31
- with urllib.request.urlopen(base+'SHA256SUMS',timeout=30) as response:
32
- lines=response.read(1024*1024).decode().splitlines()
33
- expected=next(line.split()[0].lower() for line in lines if line.split()[-1].lstrip('*')==name)
34
- package=destination/'sdk.zip'
35
- if not package.exists() or hashlib.file_digest(package.open('rb'),'sha256').hexdigest()!=expected:
36
- temporary=package.with_suffix('.part')
37
- with urllib.request.urlopen(base+name,timeout=120) as response,temporary.open('wb') as output:
38
- shutil.copyfileobj(response,output)
39
- temporary.replace(package)
40
- with package.open('rb') as stream:
41
- if hashlib.file_digest(stream,'sha256').hexdigest()!=expected:raise ValueError('VirtualBox SDK checksum mismatch')
42
- with zipfile.ZipFile(package) as source:
43
- for info in source.infolist():
44
- if not (destination/info.filename).resolve().is_relative_to(destination):raise ValueError('SDK archive path escapes extraction directory')
45
- source.extractall(destination)
46
- environment={**os.environ,'VBOX_MSI_INSTALL_PATH':str(binary.parent),'VBOX_VERSION':release}
47
- subprocess.run([sys.executable,'-m','pip','install','setuptools','pywin32'],check=True,timeout=180,stdout=sys.stderr)
48
- installer=destination/'sdk/installer/python/vboxapisetup.py'
49
- if not installer.is_file():raise RuntimeError('Matching SDK Python installer was not found')
50
- subprocess.run([sys.executable,str(installer),'install'],cwd=installer.parent,env=environment,check=True,timeout=180,stdout=sys.stderr)
51
- observed=subprocess.check_output([sys.executable,'-c','from vboxapi import VirtualBoxManager; m=VirtualBoxManager(None,None); print(m.getVirtualBox().version)'],env=environment,text=True).strip()
52
- if observed!=release:raise RuntimeError('SDK/COM reported a different VirtualBox version')
53
- return {'status':'installed','virtualbox_version':observed,'sdk_sha256':expected,'python':sys.executable,'sdk_path':str(destination)}
54
-
55
- if __name__=='__main__':
56
- p=argparse.ArgumentParser();p.add_argument('--storage',required=True);p.add_argument('--vboxmanage');p.add_argument('--archive');p.add_argument('--sha256');a=p.parse_args()
57
- try:print(json.dumps(setup(**vars(a))))
58
- except Exception as error:print(json.dumps({'status':'error','error_summary':str(error)}));sys.exit(1)
1
+ """Install the matching Oracle VirtualBox Python SDK in a Windows host venv."""
2
+ import argparse
3
+ import hashlib
4
+ import json
5
+ import os
6
+ from pathlib import Path
7
+ import re
8
+ import shutil
9
+ import subprocess
10
+ import sys
11
+ import urllib.request
12
+ import zipfile
13
+
14
+ def setup(storage,vboxmanage=None,archive=None,sha256=None):
15
+ if sys.platform!='win32':raise RuntimeError('The COM SDK setup is for Windows hosts')
16
+ if sys.prefix==sys.base_prefix:raise RuntimeError('Run SDK setup with the isolated host Python venv')
17
+ binary=Path(vboxmanage or shutil.which('VBoxManage') or r'C:\Program Files\Oracle\VirtualBox\VBoxManage.exe')
18
+ version=subprocess.check_output([str(binary),'--version'],text=True).strip()
19
+ match=re.match(r'(\d+\.\d+\.\d+)r(\d+)',version)
20
+ if not match:raise RuntimeError('Unrecognized installed VirtualBox version')
21
+ release,revision=match.groups()
22
+ destination=Path(storage).resolve()/('virtualbox-sdk-'+release+'-'+revision)
23
+ destination.mkdir(parents=True,exist_ok=True)
24
+ if archive:
25
+ package=Path(archive)
26
+ if not sha256:raise ValueError('An offline SDK archive requires its expected SHA-256')
27
+ expected=sha256.lower()
28
+ else:
29
+ name=f'VirtualBoxSDK-{release}-{revision}.zip'
30
+ base=f'https://download.virtualbox.org/virtualbox/{release}/'
31
+ with urllib.request.urlopen(base+'SHA256SUMS',timeout=30) as response:
32
+ lines=response.read(1024*1024).decode().splitlines()
33
+ expected=next(line.split()[0].lower() for line in lines if line.split()[-1].lstrip('*')==name)
34
+ package=destination/'sdk.zip'
35
+ if not package.exists() or hashlib.file_digest(package.open('rb'),'sha256').hexdigest()!=expected:
36
+ temporary=package.with_suffix('.part')
37
+ with urllib.request.urlopen(base+name,timeout=120) as response,temporary.open('wb') as output:
38
+ shutil.copyfileobj(response,output)
39
+ temporary.replace(package)
40
+ with package.open('rb') as stream:
41
+ if hashlib.file_digest(stream,'sha256').hexdigest()!=expected:raise ValueError('VirtualBox SDK checksum mismatch')
42
+ with zipfile.ZipFile(package) as source:
43
+ for info in source.infolist():
44
+ if not (destination/info.filename).resolve().is_relative_to(destination):raise ValueError('SDK archive path escapes extraction directory')
45
+ source.extractall(destination)
46
+ environment={**os.environ,'VBOX_MSI_INSTALL_PATH':str(binary.parent),'VBOX_VERSION':release}
47
+ subprocess.run([sys.executable,'-m','pip','install','setuptools','pywin32'],check=True,timeout=180,stdout=sys.stderr)
48
+ installer=destination/'sdk/installer/python/vboxapisetup.py'
49
+ if not installer.is_file():raise RuntimeError('Matching SDK Python installer was not found')
50
+ subprocess.run([sys.executable,str(installer),'install'],cwd=installer.parent,env=environment,check=True,timeout=180,stdout=sys.stderr)
51
+ observed=subprocess.check_output([sys.executable,'-c','from vboxapi import VirtualBoxManager; m=VirtualBoxManager(None,None); print(m.getVirtualBox().version)'],env=environment,text=True).strip()
52
+ if observed!=release:raise RuntimeError('SDK/COM reported a different VirtualBox version')
53
+ return {'status':'installed','virtualbox_version':observed,'sdk_sha256':expected,'python':sys.executable,'sdk_path':str(destination)}
54
+
55
+ if __name__=='__main__':
56
+ p=argparse.ArgumentParser();p.add_argument('--storage',required=True);p.add_argument('--vboxmanage');p.add_argument('--archive');p.add_argument('--sha256');a=p.parse_args()
57
+ try:print(json.dumps(setup(**vars(a))))
58
+ except Exception as error:print(json.dumps({'status':'error','error_summary':str(error)}));sys.exit(1)
@@ -1,68 +1,68 @@
1
- """Owner-local recording share and bounded source inspection for MCP."""
2
- import ast
3
- import hashlib
4
- import json
5
- import os
6
- from pathlib import Path
7
- import re
8
- import sys
9
- try:
10
- from .provision import parse
11
- except ImportError:
12
- from provision import parse
13
- try:
14
- from .display import command
15
- except ImportError:
16
- from display import command
17
-
18
-
19
- def folder(vm):
20
- slug=re.sub(r'[^A-Za-z0-9_.-]','_',vm)[:48] or 'vm'
21
- return Path(os.environ.get('VAMP_DATA_DIR',Path.home()/'VAMP'))/'recordings'/(slug+'-'+hashlib.sha256(vm.encode()).hexdigest()[:8])
22
-
23
-
24
- def prepare(vm,run=command):
25
- info=parse(run('showvminfo',vm,'--machinereadable'))
26
- destination=folder(vm).resolve();destination.mkdir(parents=True,exist_ok=True)
27
- # Reuse an existing share only if it refers to this exact directory.
28
- for key,name in info.items():
29
- if key.startswith('SharedFolderName') and name=='VAMPRecords':
30
- pathkey=key.replace('SharedFolderName','SharedFolderPath')
31
- if Path(info.get(pathkey,'')).resolve()!=destination:raise ValueError('VAMPRecords already maps elsewhere; refusing to replace it')
32
- return details(vm,destination,already_configured=True)
33
- args=['sharedfolder','add',vm,'--name','VAMPRecords','--hostpath',str(destination),'--automount']
34
- transient=info.get('VMState')=='running'
35
- if transient:args+=['--transient']
36
- run(*args)
37
- return details(vm,destination,transient=transient)
38
-
39
-
40
- def details(vm,path,**extra):
41
- return {'status':'share_configured','vm':vm,'host_path':str(path),
42
- 'windows_path':r'\\VBOXSVR\VAMPRecords','linux_path':'/media/sf_VAMPRecords',
43
- 'linux_alternative':'~/VAMP-Shared','mount_verified':False,
44
- 'notice':'Guest Additions/shared-folder support is required. A transient running-VM share must be re-added next start/session.',**extra}
45
-
46
-
47
- def inspect(vm,filename=None,offset=0,limit=8000):
48
- destination=folder(vm).resolve()
49
- if not destination.is_dir():return {'status':'share_not_prepared','files':[]}
50
- if filename is None:
51
- files=[{'name':p.name,'bytes':p.stat().st_size,'host_path':str(p)} for p in sorted(destination.iterdir()) if p.is_file() and p.suffix in ('.py','.json')]
52
- return {'status':'observed','host_path':str(destination),'files':files[:50],'total':len(files)}
53
- if Path(filename).name!=filename or not filename.endswith(('.py','.json')):raise ValueError('Choose one recording filename')
54
- target=(destination/filename).resolve()
55
- if target.parent!=destination or not target.is_file() or target.stat().st_size>5_000_000:raise ValueError('Invalid recording or size')
56
- if offset<0 or not 1<=limit<=8000:raise ValueError('Invalid pagination')
57
- source=target.read_text(encoding='utf-8-sig')
58
- if target.suffix=='.py':ast.parse(source)
59
- else:json.loads(source)
60
- return {'status':'read_for_review','host_path':str(target),'source_executed':False,
61
- 'offset':offset,'total_characters':len(source),'source':source[offset:offset+limit],
62
- 'sha256':hashlib.sha256(target.read_bytes()).hexdigest()}
63
-
64
- if __name__=='__main__':
65
- try:
66
- args=json.load(sys.stdin);op=args.pop('action','prepare')
67
- print(json.dumps((prepare if op=='prepare' else inspect)(**args)))
68
- except Exception as exc:print(json.dumps({'status':'failed','error':str(exc)}));sys.exit(1)
1
+ """Owner-local recording share and bounded source inspection for MCP."""
2
+ import ast
3
+ import hashlib
4
+ import json
5
+ import os
6
+ from pathlib import Path
7
+ import re
8
+ import sys
9
+ try:
10
+ from .provision import parse
11
+ except ImportError:
12
+ from provision import parse
13
+ try:
14
+ from .display import command
15
+ except ImportError:
16
+ from display import command
17
+
18
+
19
+ def folder(vm):
20
+ slug=re.sub(r'[^A-Za-z0-9_.-]','_',vm)[:48] or 'vm'
21
+ return Path(os.environ.get('VAMP_DATA_DIR',Path.home()/'VAMP'))/'recordings'/(slug+'-'+hashlib.sha256(vm.encode()).hexdigest()[:8])
22
+
23
+
24
+ def prepare(vm,run=command):
25
+ info=parse(run('showvminfo',vm,'--machinereadable'))
26
+ destination=folder(vm).resolve();destination.mkdir(parents=True,exist_ok=True)
27
+ # Reuse an existing share only if it refers to this exact directory.
28
+ for key,name in info.items():
29
+ if key.startswith('SharedFolderName') and name=='VAMPRecords':
30
+ pathkey=key.replace('SharedFolderName','SharedFolderPath')
31
+ if Path(info.get(pathkey,'')).resolve()!=destination:raise ValueError('VAMPRecords already maps elsewhere; refusing to replace it')
32
+ return details(vm,destination,already_configured=True)
33
+ args=['sharedfolder','add',vm,'--name','VAMPRecords','--hostpath',str(destination),'--automount']
34
+ transient=info.get('VMState')=='running'
35
+ if transient:args+=['--transient']
36
+ run(*args)
37
+ return details(vm,destination,transient=transient)
38
+
39
+
40
+ def details(vm,path,**extra):
41
+ return {'status':'share_configured','vm':vm,'host_path':str(path),
42
+ 'windows_path':r'\\VBOXSVR\VAMPRecords','linux_path':'/media/sf_VAMPRecords',
43
+ 'linux_alternative':'~/VAMP-Shared','mount_verified':False,
44
+ 'notice':'Guest Additions/shared-folder support is required. A transient running-VM share must be re-added next start/session.',**extra}
45
+
46
+
47
+ def inspect(vm,filename=None,offset=0,limit=8000):
48
+ destination=folder(vm).resolve()
49
+ if not destination.is_dir():return {'status':'share_not_prepared','files':[]}
50
+ if filename is None:
51
+ files=[{'name':p.name,'bytes':p.stat().st_size,'host_path':str(p)} for p in sorted(destination.iterdir()) if p.is_file() and p.suffix in ('.py','.json')]
52
+ return {'status':'observed','host_path':str(destination),'files':files[:50],'total':len(files)}
53
+ if Path(filename).name!=filename or not filename.endswith(('.py','.json')):raise ValueError('Choose one recording filename')
54
+ target=(destination/filename).resolve()
55
+ if target.parent!=destination or not target.is_file() or target.stat().st_size>5_000_000:raise ValueError('Invalid recording or size')
56
+ if offset<0 or not 1<=limit<=8000:raise ValueError('Invalid pagination')
57
+ source=target.read_text(encoding='utf-8-sig')
58
+ if target.suffix=='.py':ast.parse(source)
59
+ else:json.loads(source)
60
+ return {'status':'read_for_review','host_path':str(target),'source_executed':False,
61
+ 'offset':offset,'total_characters':len(source),'source':source[offset:offset+limit],
62
+ 'sha256':hashlib.sha256(target.read_bytes()).hexdigest()}
63
+
64
+ if __name__=='__main__':
65
+ try:
66
+ args=json.load(sys.stdin);op=args.pop('action','prepare')
67
+ print(json.dumps((prepare if op=='prepare' else inspect)(**args)))
68
+ except Exception as exc:print(json.dumps({'status':'failed','error':str(exc)}));sys.exit(1)
@@ -1,53 +1,53 @@
1
- """Explicit snapshot lifecycle; never stop or restore a running VM automatically."""
2
- import argparse
3
- import json
4
- from pathlib import Path
5
- import re
6
- import subprocess
7
- import sys
8
- try:
9
- from .provision import executable,parse
10
- except ImportError:
11
- from provision import executable,parse
12
-
13
-
14
- def command(*args):
15
- result=subprocess.run([executable(),*map(str,args)],capture_output=True,text=True,timeout=300)
16
- if result.returncode:
17
- if args[:1]==('snapshot',) and 'does not have any snapshots' in result.stdout+result.stderr:return ''
18
- raise RuntimeError(result.stderr.strip()[:500] or result.stdout.strip()[:500])
19
- return result.stdout
20
-
21
-
22
- def manage(vm,action='list',name=None,confirm_restore=False,initial=False,run=command):
23
- info=parse(run('showvminfo',vm,'--machinereadable'))
24
- result={'vm':vm,'action':action}
25
- if action=='list':
26
- text=run('snapshot',vm,'list','--machinereadable')
27
- return {**result,'status':'observed','snapshots':parse(text),'empty':not bool(text.strip())}
28
- if action=='take':
29
- if not name or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9_. -]{0,79}',name):raise ValueError('Provide a clear snapshot name (1-80 ASCII letters/digits/space/._-)')
30
- if initial and name!='VAMP-initial':raise ValueError('Use snapshot name VAMP-initial when marking a baseline')
31
- existing=run('snapshot',vm,'list','--machinereadable')
32
- if name in parse(existing).values():raise ValueError('Snapshot name already exists; use another name')
33
- args=['snapshot',vm,'take',name,'--description','VAMP explicit session checkpoint; later changes are not included.']
34
- if info.get('VMState')=='running':args+=['--live']
35
- run(*args)
36
- return {**result,'status':'snapshot_created','name':name,'initial':initial,
37
- 'space_notice':'Differencing disks grow with changes; a running-VM snapshot can also store RAM. A snapshot is not an independent backup.'}
38
- if action in ('restore','restore_initial'):
39
- if not confirm_restore:raise ValueError('Ask the user to confirm the exact restore target and loss of later changes first')
40
- if info.get('VMState')!='poweroff':raise ValueError('Restore requires a powered-off VM; explicitly shut it down first, never auto-power-off')
41
- target='VAMP-initial' if action=='restore_initial' else name
42
- if not target:raise ValueError('Choose an exact snapshot name/UUID')
43
- rows=parse(run('snapshot',vm,'list','--machinereadable'))
44
- if target not in rows.values():raise ValueError('Snapshot target does not exist')
45
- run('snapshot',vm,'restore',target)
46
- return {**result,'status':'snapshot_restored','target':target,'vm_started':False,
47
- 'notice':'Changes after the target snapshot are no longer the active state.'}
48
- raise ValueError('Unknown snapshot action')
49
-
50
- if __name__=='__main__':
51
- parser=argparse.ArgumentParser(description=__doc__);parser.parse_args()
52
- try:print(json.dumps(manage(**json.load(sys.stdin))))
53
- except Exception as exc:print(json.dumps({'status':'failed','error':str(exc)}));sys.exit(1)
1
+ """Explicit snapshot lifecycle; never stop or restore a running VM automatically."""
2
+ import argparse
3
+ import json
4
+ from pathlib import Path
5
+ import re
6
+ import subprocess
7
+ import sys
8
+ try:
9
+ from .provision import executable,parse
10
+ except ImportError:
11
+ from provision import executable,parse
12
+
13
+
14
+ def command(*args):
15
+ result=subprocess.run([executable(),*map(str,args)],capture_output=True,text=True,timeout=300)
16
+ if result.returncode:
17
+ if args[:1]==('snapshot',) and 'does not have any snapshots' in result.stdout+result.stderr:return ''
18
+ raise RuntimeError(result.stderr.strip()[:500] or result.stdout.strip()[:500])
19
+ return result.stdout
20
+
21
+
22
+ def manage(vm,action='list',name=None,confirm_restore=False,initial=False,run=command):
23
+ info=parse(run('showvminfo',vm,'--machinereadable'))
24
+ result={'vm':vm,'action':action}
25
+ if action=='list':
26
+ text=run('snapshot',vm,'list','--machinereadable')
27
+ return {**result,'status':'observed','snapshots':parse(text),'empty':not bool(text.strip())}
28
+ if action=='take':
29
+ if not name or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9_. -]{0,79}',name):raise ValueError('Provide a clear snapshot name (1-80 ASCII letters/digits/space/._-)')
30
+ if initial and name!='VAMP-initial':raise ValueError('Use snapshot name VAMP-initial when marking a baseline')
31
+ existing=run('snapshot',vm,'list','--machinereadable')
32
+ if name in parse(existing).values():raise ValueError('Snapshot name already exists; use another name')
33
+ args=['snapshot',vm,'take',name,'--description','VAMP explicit session checkpoint; later changes are not included.']
34
+ if info.get('VMState')=='running':args+=['--live']
35
+ run(*args)
36
+ return {**result,'status':'snapshot_created','name':name,'initial':initial,
37
+ 'space_notice':'Differencing disks grow with changes; a running-VM snapshot can also store RAM. A snapshot is not an independent backup.'}
38
+ if action in ('restore','restore_initial'):
39
+ if not confirm_restore:raise ValueError('Ask the user to confirm the exact restore target and loss of later changes first')
40
+ if info.get('VMState')!='poweroff':raise ValueError('Restore requires a powered-off VM; explicitly shut it down first, never auto-power-off')
41
+ target='VAMP-initial' if action=='restore_initial' else name
42
+ if not target:raise ValueError('Choose an exact snapshot name/UUID')
43
+ rows=parse(run('snapshot',vm,'list','--machinereadable'))
44
+ if target not in rows.values():raise ValueError('Snapshot target does not exist')
45
+ run('snapshot',vm,'restore',target)
46
+ return {**result,'status':'snapshot_restored','target':target,'vm_started':False,
47
+ 'notice':'Changes after the target snapshot are no longer the active state.'}
48
+ raise ValueError('Unknown snapshot action')
49
+
50
+ if __name__=='__main__':
51
+ parser=argparse.ArgumentParser(description=__doc__);parser.parse_args()
52
+ try:print(json.dumps(manage(**json.load(sys.stdin))))
53
+ except Exception as exc:print(json.dumps({'status':'failed','error':str(exc)}));sys.exit(1)
@@ -1,89 +1,89 @@
1
- """Binary exchange through a VM-scoped Guest Additions shared folder."""
2
- import hashlib
3
- import json
4
- import os
5
- from pathlib import Path,PurePosixPath
6
- import re
7
- import shutil
8
- import sys
9
- import uuid
10
- try:
11
- from .display import command
12
- from .provision import parse
13
- except ImportError:
14
- from display import command
15
- from provision import parse
16
-
17
- MAX_BYTES=1024**3
18
-
19
-
20
- def exchange_root(vm):
21
- name=re.sub(r'[^A-Za-z0-9_.-]','_',vm)[:40]+'-'+hashlib.sha256(vm.encode()).hexdigest()[:8]
22
- return (Path(os.environ.get('VAMP_DATA_DIR',Path.home()/'VAMP'))/'exchange'/name).resolve()
23
-
24
-
25
- def safe_path(root,relative):
26
- path=PurePosixPath(relative)
27
- if not relative or path.is_absolute() or '\\' in relative or ':' in relative or any(p in ('..','.') for p in relative.split('/')):
28
- raise ValueError('Use a relative path inside VAMPFiles')
29
- target=(root/path).resolve()
30
- if not target.is_relative_to(root):raise ValueError('Shared file path escapes the exchange directory')
31
- return target
32
-
33
-
34
- def prepare(vm,run=command):
35
- info=parse(run('showvminfo',vm,'--machinereadable'))
36
- root=exchange_root(vm);root.mkdir(parents=True,exist_ok=True)
37
- present=False
38
- for key,value in info.items():
39
- if key.startswith('SharedFolderName') and value=='VAMPFiles':
40
- mapped=Path(info.get(key.replace('SharedFolderName','SharedFolderPath'),'')).resolve()
41
- if mapped!=root:raise ValueError('VAMPFiles is mapped elsewhere; refusing to replace it')
42
- present=True
43
- if not present:
44
- args=['sharedfolder','add',vm,'--name','VAMPFiles','--hostpath',str(root),'--automount']
45
- if info.get('VMState')=='running':args+=['--transient']
46
- run(*args)
47
- return {'status':'share_configured','backend':'virtualbox','vm_name':vm,'host_path':str(root),
48
- 'windows_path':r'\\VBOXSVR\VAMPFiles','linux_path':'/media/sf_VAMPFiles',
49
- 'guest_mount_verified':False,'requires':'VirtualBox Guest Additions shared-folder driver'}
50
-
51
-
52
- def copy_file(source,destination,overwrite):
53
- source=Path(source).resolve(strict=True);destination=Path(destination)
54
- if not source.is_file() or source.stat().st_size>MAX_BYTES:raise ValueError('Choose a file no larger than 1 GiB')
55
- if destination.exists() and not overwrite:raise FileExistsError('Destination exists; overwrite was not requested')
56
- destination.parent.mkdir(parents=True,exist_ok=True)
57
- temporary=destination.with_name('.vamp-transfer-'+uuid.uuid4().hex)
58
- try:
59
- with source.open('rb') as incoming,os.fdopen(os.open(temporary,os.O_WRONLY|os.O_CREAT|os.O_EXCL,0o600),'wb') as outgoing:
60
- count=0;digest=hashlib.sha256()
61
- while chunk:=incoming.read(64*1024):
62
- count+=len(chunk)
63
- if count>MAX_BYTES:raise ValueError('File grew beyond the transfer limit')
64
- digest.update(chunk);outgoing.write(chunk)
65
- outgoing.flush();os.fsync(outgoing.fileno())
66
- if overwrite:os.replace(temporary,destination)
67
- else:os.link(temporary,destination);temporary.unlink()
68
- return {'bytes':count,'sha256':digest.hexdigest()}
69
- finally:temporary.unlink(missing_ok=True)
70
-
71
-
72
- def put(vm,local_path,guest_path,overwrite=False,run=command):
73
- share=prepare(vm,run);target=safe_path(exchange_root(vm),guest_path)
74
- copied=copy_file(local_path,target,overwrite)
75
- return {**share,**copied,'status':'staged','direction':'host_to_guest','relative_path':guest_path,
76
- 'shared_file':str(target),'guest_delivery_verified':False}
77
-
78
-
79
- def get(vm,guest_path,local_path,overwrite=False,run=command):
80
- share=prepare(vm,run);source=safe_path(exchange_root(vm),guest_path)
81
- copied=copy_file(source,Path(local_path).expanduser().resolve(),overwrite)
82
- return {**copied,'status':'copied','backend':'virtualbox','direction':'guest_to_host',
83
- 'local_path':str(Path(local_path).expanduser().resolve()),'shared_source':str(source),'host_copy_verified':True}
84
-
85
- if __name__=='__main__':
86
- try:
87
- values=json.load(sys.stdin);operation=values.pop('action');print(json.dumps({'prepare':prepare,'put':put,'get':get}[operation](**values)))
88
- except Exception as error:
89
- print(json.dumps({'status':'error','error_summary':str(error)[:300]}));sys.exit(1)
1
+ """Binary exchange through a VM-scoped Guest Additions shared folder."""
2
+ import hashlib
3
+ import json
4
+ import os
5
+ from pathlib import Path,PurePosixPath
6
+ import re
7
+ import shutil
8
+ import sys
9
+ import uuid
10
+ try:
11
+ from .display import command
12
+ from .provision import parse
13
+ except ImportError:
14
+ from display import command
15
+ from provision import parse
16
+
17
+ MAX_BYTES=1024**3
18
+
19
+
20
+ def exchange_root(vm):
21
+ name=re.sub(r'[^A-Za-z0-9_.-]','_',vm)[:40]+'-'+hashlib.sha256(vm.encode()).hexdigest()[:8]
22
+ return (Path(os.environ.get('VAMP_DATA_DIR',Path.home()/'VAMP'))/'exchange'/name).resolve()
23
+
24
+
25
+ def safe_path(root,relative):
26
+ path=PurePosixPath(relative)
27
+ if not relative or path.is_absolute() or '\\' in relative or ':' in relative or any(p in ('..','.') for p in relative.split('/')):
28
+ raise ValueError('Use a relative path inside VAMPFiles')
29
+ target=(root/path).resolve()
30
+ if not target.is_relative_to(root):raise ValueError('Shared file path escapes the exchange directory')
31
+ return target
32
+
33
+
34
+ def prepare(vm,run=command):
35
+ info=parse(run('showvminfo',vm,'--machinereadable'))
36
+ root=exchange_root(vm);root.mkdir(parents=True,exist_ok=True)
37
+ present=False
38
+ for key,value in info.items():
39
+ if key.startswith('SharedFolderName') and value=='VAMPFiles':
40
+ mapped=Path(info.get(key.replace('SharedFolderName','SharedFolderPath'),'')).resolve()
41
+ if mapped!=root:raise ValueError('VAMPFiles is mapped elsewhere; refusing to replace it')
42
+ present=True
43
+ if not present:
44
+ args=['sharedfolder','add',vm,'--name','VAMPFiles','--hostpath',str(root),'--automount']
45
+ if info.get('VMState')=='running':args+=['--transient']
46
+ run(*args)
47
+ return {'status':'share_configured','backend':'virtualbox','vm_name':vm,'host_path':str(root),
48
+ 'windows_path':r'\\VBOXSVR\VAMPFiles','linux_path':'/media/sf_VAMPFiles',
49
+ 'guest_mount_verified':False,'requires':'VirtualBox Guest Additions shared-folder driver'}
50
+
51
+
52
+ def copy_file(source,destination,overwrite):
53
+ source=Path(source).resolve(strict=True);destination=Path(destination)
54
+ if not source.is_file() or source.stat().st_size>MAX_BYTES:raise ValueError('Choose a file no larger than 1 GiB')
55
+ if destination.exists() and not overwrite:raise FileExistsError('Destination exists; overwrite was not requested')
56
+ destination.parent.mkdir(parents=True,exist_ok=True)
57
+ temporary=destination.with_name('.vamp-transfer-'+uuid.uuid4().hex)
58
+ try:
59
+ with source.open('rb') as incoming,os.fdopen(os.open(temporary,os.O_WRONLY|os.O_CREAT|os.O_EXCL,0o600),'wb') as outgoing:
60
+ count=0;digest=hashlib.sha256()
61
+ while chunk:=incoming.read(64*1024):
62
+ count+=len(chunk)
63
+ if count>MAX_BYTES:raise ValueError('File grew beyond the transfer limit')
64
+ digest.update(chunk);outgoing.write(chunk)
65
+ outgoing.flush();os.fsync(outgoing.fileno())
66
+ if overwrite:os.replace(temporary,destination)
67
+ else:os.link(temporary,destination);temporary.unlink()
68
+ return {'bytes':count,'sha256':digest.hexdigest()}
69
+ finally:temporary.unlink(missing_ok=True)
70
+
71
+
72
+ def put(vm,local_path,guest_path,overwrite=False,run=command):
73
+ share=prepare(vm,run);target=safe_path(exchange_root(vm),guest_path)
74
+ copied=copy_file(local_path,target,overwrite)
75
+ return {**share,**copied,'status':'staged','direction':'host_to_guest','relative_path':guest_path,
76
+ 'shared_file':str(target),'guest_delivery_verified':False}
77
+
78
+
79
+ def get(vm,guest_path,local_path,overwrite=False,run=command):
80
+ share=prepare(vm,run);source=safe_path(exchange_root(vm),guest_path)
81
+ copied=copy_file(source,Path(local_path).expanduser().resolve(),overwrite)
82
+ return {**copied,'status':'copied','backend':'virtualbox','direction':'guest_to_host',
83
+ 'local_path':str(Path(local_path).expanduser().resolve()),'shared_source':str(source),'host_copy_verified':True}
84
+
85
+ if __name__=='__main__':
86
+ try:
87
+ values=json.load(sys.stdin);operation=values.pop('action');print(json.dumps({'prepare':prepare,'put':put,'get':get}[operation](**values)))
88
+ except Exception as error:
89
+ print(json.dumps({'status':'error','error_summary':str(error)[:300]}));sys.exit(1)