chore: 移除 Rust/cargo czdev 死文档,新增 ./czdev wrapper + Python czdev 文档

czdev

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+#
+# czdev — CardputerZero developer CLI (Python).
+#
+# Thin launcher for the pure-Python package in scripts/czdev. It puts the
+# scripts/ directory on PYTHONPATH and runs the package as a module, so the
+# package's relative imports (`from .auth import login`, …) resolve correctly.
+#
+# Commands: login · logout · bump · publish · unpublish
+# Requirements: Python 3, git, dpkg-deb.  (No Rust / cargo toolchain needed.)
+#
+# Usage:
+#   ./czdev --help
+#   ./czdev login
+#   ./czdev publish --deb build/my_app_1.0.1_arm64.deb
+set -euo pipefail
+
+HERE="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "czdev: python3 not found on PATH. Install Python 3 and retry." >&2
+  exit 1
+fi
+
+exec env PYTHONPATH="${HERE}/scripts${PYTHONPATH:+:${PYTHONPATH}}" \
+  python3 -m czdev "$@"

docs/APP_BUILDER_JSON.md

@@ -4,12 +4,16 @@ Every directory in an application repository that should be discovered, built
 and packaged contains one `app-builder.json` at its root. The file plays two
 roles:
 
-1. **Packaging** — feeds the CI `.deb` pipeline (existing behaviour).
-2. **Desktop dev loop** — tells `czdev` how to build and run the app inside the
-   emulator (new fields, optional).
+1. **Packaging** — feeds the CI `.deb` pipeline.
+2. **AppStore listing** — the optional `store` section supplies the metadata
+   that `czdev publish` (and the web portal at
+   [dev.cardputer.cc](https://dev.cardputer.cc)) put on the store page: title,
+   summary, screenshots, categories, icon, …
 
-Fields added for the desktop loop are all optional; a file that only contains
-the packaging fields keeps working exactly as before.
+> The older desktop-emulator fields (`runtime`, `entry`, `event_entry`,
+> `lvgl_version`, `caps`, `assets`) are still accepted for back-compat but are
+> no longer consumed — the Rust `czdev` emulator / `czdev run` loop has been
+> removed. New apps only need the packaging fields plus a `store` section.
 
 ## Full schema
 
@@ -19,69 +23,67 @@ the packaging fields keeps working exactly as before.
   "package_name": "hello_cz",       // Debian package name (lowercase, dash)
   "version":      "0.1",            // SemVer-ish; goes into control file
   "app_name":     "Hello CZ",       // Display name in APPLaunch
-  "bin_name":     "hello_cz",       // Shared-object basename (no lib prefix)
-  "description":  "Desktop dev hello app",
+  "bin_name":     "hello_cz",       // executable / shared-object basename
+  "description":  "Hello app",
 
-  // ── Desktop dev (new, all optional) ──────────────────────────────
-  "runtime":       "lvgl-dlopen",   // "lvgl-dlopen" (default) | "legacy-deb-only"
-  "entry":         "app_main",      // C symbol name, default "app_main"
-  "event_entry":   "app_event",     // optional, default "app_event"
-  "lvgl_version":  "9.5",           // host must match on major.minor
-  "caps": [                         // capabilities the app declares it uses
-    "keyboard",
-    "audio",
-    "network"
-  ],
-  "assets": [                       // paths relative to app dir; copied next
-    "assets/fonts/",                // to the built library under its app dir
-    "assets/sprites/"
-  ]
+  // ── AppStore listing (used by `czdev publish` + web portal) ──────
+  "store": {
+    "summary":     "One-line summary",       // shown in lists
+    "description": "Longer detail-page text",// optional; falls back to summary
+    "categories":  ["Games"],                // optional; up to a few tags
+    "screenshots": ["screenshots/main.png"], // >=1 required; 320×170 PNG(s)
+    "icon":        "packaging/icon.png",      // optional; square PNG
+    "license":     "MIT",                     // optional
+    "source_repo": "https://github.com/you/my_app", // optional
+    "author":      { "github": "you" },       // optional; defaults to uploader
+    "permissions": [],                        // optional; declared permissions
+    "locales":     {}                         // optional; localized title/summary
+  },
+
+  // ── Legacy desktop-emulator fields (optional, no longer consumed) ─
+  "runtime":       "lvgl-dlopen",   // back-compat only
+  "entry":         "app_main",
+  "event_entry":   "app_event",
+  "lvgl_version":  "9.5",
+  "caps":          [],
+  "assets":        []
 }
 ```
 
-## Field reference
+## Packaging fields
 
-| Field | Required | Type | Default | Used by |
+| Field | Required | Type | Default | Notes |
 |---|---|---|---|---|
-| `package_name` | yes | string | — | deb, czdev |
-| `version` | no | string | `"0.1"` | deb |
-| `app_name` | no | string | same as `package_name` | deb, czdev |
-| `bin_name` | yes | string | — | deb, czdev |
-| `description` | no | string | `""` | deb |
-| `runtime` | no | `"lvgl-dlopen"` \| `"legacy-deb-only"` | `"lvgl-dlopen"` | czdev |
-| `entry` | no | string | `"app_main"` | czdev, emulator |
-| `event_entry` | no | string | `"app_event"` | czdev, emulator |
-| `lvgl_version` | no | string | `"9.5"` | czdev (refuses mismatch) |
-| `caps` | no | string[] | `[]` | czdev (future: sandboxing) |
-| `assets` | no | string[] | `[]` | czdev (stage next to lib) |
-
-## Runtime modes
+| `package_name` | yes | string | — | Debian package name (lowercase, dash) |
+| `version` | no | string | `"0.1"` | goes into the control file |
+| `app_name` | no | string | same as `package_name` | display name; also the store title |
+| `bin_name` | yes | string | — | executable / shared-object basename |
+| `description` | no | string | `""` | control-file description |
 
-- **`lvgl-dlopen`** — the app is a shared library that exports the `entry` and
-  optional `event_entry` symbols described in `cz_app.h`. `czdev run` loads it
-  into the emulator via `dlopen` / `LoadLibrary`. This is the default for new
-  apps.
-- **`legacy-deb-only`** — the project is a standalone executable (Framebuffer,
-  SDL, Qt, Python, …). `czdev` skips it during `run`; the CI `.deb` pipeline
-  still produces a package. Use this for examples in
-  `CardputerZero-Examples/` that are not LVGL.
+## Store listing — `store`
 
-Apps that omit `runtime` are treated as `lvgl-dlopen` iff they export
-`app_main`; otherwise `czdev` prints a clear error and suggests setting
-`"runtime": "legacy-deb-only"`.
+Read by `czdev publish` and the web portal to build the AppStore page. At
+least one 320×170 screenshot is required to publish.
 
-## Capabilities (`caps`)
+| Field | Required | Type | Notes |
+|---|---|---|---|
+| `store.summary` | recommended | string | one-line summary shown in lists |
+| `store.description` | no | string | detail-page text; falls back to `summary` |
+| `store.categories` | no | string[] | category tags |
+| `store.screenshots` | **yes** | string[] | ≥1 path, relative to the app dir; **320×170** PNG(s) |
+| `store.icon` | no | string | square PNG path (else the deb's icon is used) |
+| `store.license` | no | string | SPDX id, e.g. `MIT` |
+| `store.source_repo` | no | string | public source URL |
+| `store.author` | no | object | e.g. `{ "github": "you" }`; defaults to the uploader |
+| `store.permissions` | no | string[] | declared permissions (metadata) |
+| `store.locales` | no | object | localized `title` / `summary` per locale |
 
-Reserved vocabulary (enforcement comes later):
+The store title comes from the top-level `app_name`.
 
-| Cap | Means |
-|---|---|
-| `keyboard` | Uses the 44-key physical keyboard / emulator skin |
-| `audio` | Plays audio via ALSA on device, SDL_mixer in emulator |
-| `network` | Reads hostname / IP / Wi-Fi state |
-| `filesystem` | Writes into `/usr/share/APPLaunch` or the emu sandbox |
-| `pty` | Spawns a PTY (terminal-style apps) |
-| `process` | fork/exec of sub-processes |
+## Legacy desktop-emulator fields
 
-Today `caps` is metadata only; a future milestone uses it to decide which
-HAL shims the emulator pre-loads.
+`runtime`, `entry`, `event_entry`, `lvgl_version`, `caps`, `assets` were used by
+the old Rust `czdev` emulator (`czdev run` / `watch`). That loop has been
+removed, so these fields are **no longer consumed** — they are still accepted
+(and passed through by CI discovery) for back-compat, but you can safely omit
+them from new manifests.