File size: 3,319 Bytes
3806142
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
dbc2744
3806142
 
 
 
 
 
 
 
 
 
 
 
 
3da9c98
 
dbc2744
3806142
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3da9c98
3806142
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
# SpaceForge β€” Architecture Spec (MVP)

## Goal
Paste a Hugging Face Space URL β†’ analyze runtime/SDK β†’ choose packaging target(s) β†’
build downloadable artifacts. Clear distinction: **Local** / **Hybrid** / **Hosted Wrapper**.

## Stack
- **Deploy**: Hugging Face Space, Docker SDK (`cpu-basic`)
- **Backend**: Python 3.11 + FastAPI (serves `/api/*` + built frontend static)
- **Frontend**: React 18 + TypeScript + Vite (UI English, i18n-ready; German chat copy elsewhere)
- **Auth to Hub**: public Spaces need no token; private Spaces accept user-supplied `HF_TOKEN` (never logged; docs use `[ERSATZ_KEY]`)

## Delivery modes (never mislabel)
| Mode | Meaning | Targets |
|------|---------|---------|
| **Local** | Runs offline / as installed app (or generated project you build locally) | Tauri project zip, AppImage/Windows stubs (project-only in HF) |
| **Hybrid** | Local shell + embedded remote Space (iframe / API proxy) | PWA, browser extensions, HTML widget |
| **Hosted Wrapper** | Thin client that always needs the live Space URL | **Android Capacitor** debug APK (or project zip fallback) |

Extensions / PWA / HTML widget are **Hybrid** (or Hosted Wrapper if they only iframe).  
Tauri generator is **Local project** β€” we ship source + scripts, **not** a claimed binary unless built.

## API
- `POST /api/analyze` `{ url, hf_token? }` β†’ Space metadata + recommended targets
- `POST /api/build` `{ url, targets[], options?, hf_token? }` β†’ `{ build_id }`
- `GET /api/build/{id}` β†’ status / artifacts
- `GET /api/build/{id}/logs` β†’ text logs
- `GET /api/build/{id}/download?target=` β†’ zip/xpi
- `DELETE /api/build/{id}` β†’ cleanup

## Converters (`Converter` interface)
`html_widget`, `pwa`, `firefox_ext`, `chromium_ext`, `tauri`, **`android` (Capacitor project)** β€” full MVP.  
Stubs: `linux_appimage`, `windows_portable` β†’ clear "project-only / not in HF env".
Android prefers a **debug .apk** when SDK is in the Docker image; falls back to project zip. Never claims Local offline model APK.

## Security
- Builds under `/tmp/spaceforge/{id}` or `/data/builds/{id}` with TTL cleanup
- Zip-slip protection, path validation, size/timeouts
- No untrusted code exec in main process; no privileged Docker
- Secrets never logged

## File tree
```
spaceforge/
β”œβ”€β”€ SPEC.md
β”œβ”€β”€ RESULT.md
β”œβ”€β”€ README.md
β”œβ”€β”€ README_HF.md          # Space card README with YAML frontmatter
β”œβ”€β”€ Dockerfile
β”œβ”€β”€ .dockerignore
β”œβ”€β”€ requirements.txt
β”œβ”€β”€ backend/
β”‚   β”œβ”€β”€ app/
β”‚   β”‚   β”œβ”€β”€ main.py
β”‚   β”‚   β”œβ”€β”€ config.py
β”‚   β”‚   β”œβ”€β”€ api/routes.py
β”‚   β”‚   β”œβ”€β”€ providers/huggingface.py
β”‚   β”‚   β”œβ”€β”€ converters/
β”‚   β”‚   β”‚   β”œβ”€β”€ base.py
β”‚   β”‚   β”‚   β”œβ”€β”€ registry.py
β”‚   β”‚   β”‚   β”œβ”€β”€ html_widget.py
β”‚   β”‚   β”‚   β”œβ”€β”€ pwa.py
β”‚   β”‚   β”‚   β”œβ”€β”€ firefox_ext.py
β”‚   β”‚   β”‚   β”œβ”€β”€ chromium_ext.py
β”‚   β”‚   β”‚   β”œβ”€β”€ tauri.py
β”‚   β”‚   β”‚   β”œβ”€β”€ mobile/android.py
β”‚   β”‚   β”‚   └── stubs.py
β”‚   β”‚   β”œβ”€β”€ security/zipsafe.py
β”‚   β”‚   └── services/builds.py
β”‚   └── tests/
β”œβ”€β”€ frontend/             # Vite React TS
β”œβ”€β”€ templates/            # Generator templates
└── scripts/cleanup_ttl.py
```