@seeed-studio/sensecraft-cli 0.3.1 → 0.3.2

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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@seeed-studio/sensecraft-cli",
3
- "version": "0.3.1",
3
+ "version": "0.3.2",
4
4
  "description": "SenseCAP / SenseCraft AI cloud CLI (devices, apps, models, files, cloud deploy)",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -6,9 +6,10 @@ description: >-
6
6
  unpublish/delete apps. Use when the user mentions 应用广场, Application Store,
7
7
  app BOM, deploy tool-blocks, or SenseCraft app upload.
8
8
  Requires Access Key (`auth init --kind sensecap`). Not for SenseCAP devices.
9
- When the user hands over a Markdown file to turn into an app, follow
10
- docs/md-to-app.md: split it into deployment.blocks (content is HTML, not raw
11
- Markdown) and publish with app create / app publish. There is no import-md command.
9
+ When the user hands over a Markdown file to turn into an app, run
10
+ `app create --from-md` or `app update --from-md` (see docs/md-to-app.md).
11
+ That compiles editor HTML before the write. `app doc compile` only previews.
12
+ There is no import-md command.
12
13
  ---
13
14
 
14
15
  # SenseCraft Apps (Application Plaza)
@@ -41,6 +42,7 @@ Child skill: [`create-app/SKILL.md`](create-app/SKILL.md) — manifest-driven ap
41
42
  | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
42
43
  | Auth `--kind sensecap` | **Implemented** (`auth init --kind sensecap`; `app` uses `{ai-host}/openapi` Basic) |
43
44
  | `app list` / `app view` / `app fields` / `app blocks` / `app activity list` | **Implemented**. Plaza hot list is `--public --sort popular` |
45
+ | `app doc compile` | **Implemented**. Markdown → editor `deployment.blocks`. No auth, no network. `app create --from-md` / `app update --from-md` compile then write. `--from-json` fills video, file-link, and image HTML, and rejects raw Markdown in text-block `content` |
44
46
  | `app create` / `update` / `publish` / `unpublish` / `withdraw` / `delete` | **Implemented** (L2 = `--yes`; publish also `--agree-declaration`; **`create` never needs `--yes`**, even with full `--from-json`). `withdraw` is review-only (`be_public=2`); `unpublish` is for an already public app |
45
47
  | `app like` / `unlike` / `collect` / `uncollect` / `mark-deploy` / `clone` | **Implemented** (L2 = `--yes`) |
46
48
  | Cover / attachment upload | `file upload --path <img> --type 1 --app-id <id> --yes` (prepends cover, **5 MB**). Unlinked: `file upload --type 1 --for-app` when building a new app payload. |
@@ -81,6 +83,14 @@ sensecraft-cli app update --id <app_id> --activity-id 1 --yes
81
83
 
82
84
  `activity_id` is an optional positive integer. List ids with `app activity list`. Omit it to leave existing activity tags unchanged. `tags` is ignored. A bad id fails the whole edit (`11202`); an unknown or inactive activity also fails the whole edit (`25000` `Activity does not exist or has expired`). If this update sets `--activity-id` and the JSON does not set `allow_clone`, CLI writes `allow_clone=1` unless the sketch is already `1`.
83
85
 
86
+ ### Leave an activity (L2)
87
+
88
+ ```bash
89
+ sensecraft-cli app update --id <app_id> --cancel-activity-id 1 --yes
90
+ ```
91
+
92
+ `cancel_activity_id` is an optional positive integer sent as a JSON number. It does not change `allow_clone` and is not checked against `app activity list`. Omit it to leave participation unchanged. Do not send the same id as `activity_id` in one update.
93
+
84
94
  ### Publish / unpublish / delete (L2)
85
95
 
86
96
  ```bash
@@ -90,7 +100,7 @@ sensecraft-cli app unpublish --id <app_id> --yes # privacy=0 private / withdr
90
100
  sensecraft-cli app delete --id <app_id> --yes # private only (be_public=0)
91
101
  ```
92
102
 
93
- `app publish` matches Console 「发布确认」: show https://sensecraft.seeed.cc/legal/en/declaration and warn that review locks editing; only then pass `--agree-declaration --yes`. Missing either flag → non-zero. API body is still only `{app_id, privacy:2}` (agreement is client-side, like Console `warrantyAccepted`).
103
+ `app publish` matches Console 「发布确认」: show https://sensecraft.seeed.cc/legal/en/declaration and warn that review locks editing; only then pass `--agree-declaration --yes`. Missing either flag → non-zero. API body is still only `{app_id, privacy:2}` (agreement is client-side, like Console `warrantyAccepted`). stdout includes `detail_url`: the creator-center page (`/view-application/<id>-<slug>?from=user-center&tab=custom`). Give the user that URL. Do **not** invent `https://test-app.seeed.cc/application/detail/<id>` — that is the plaza page and does not open the private draft.
94
104
 
95
105
  **Never** send `privacy=1` (ops-approved public). After editing a **published** app, tell the user plaza is unchanged until they confirm `app publish --agree-declaration --yes`.
96
106
 
@@ -115,14 +125,14 @@ Seeed rows need `id`(=SKU). Custom rows omit `id`. No manual custom image upload
115
125
  ```
116
126
  Use `app_scenarios_array` from constants and the two static catalogs; never invent option ids or block shapes.
117
127
  1. Fill required app info (see [reference-app-fields.md](reference-app-fields.md)).
118
- 2. Build intro + stepped deploy + tool-blocks ([reference-tool-blocks.md](reference-tool-blocks.md)).
128
+ 2. Build intro + stepped deploy + tool-blocks ([reference-tool-blocks.md](reference-tool-blocks.md)). When the source is Markdown, run `sensecraft-cli app create --from-md <file>` (add `--from-json` for scene, cover, BOM, and tool-blocks). JSON `deployment.blocks` are appended after the compiled document. `app doc compile --from-md` only previews. Do not leave `**bold**` or list markers in JSON `content`.
119
129
  3. BOM: Seeed SKU rows and/or custom rows ([reference-app-fields.md](reference-app-fields.md#bom-materials))
120
130
  4. **Prefer one-shot create** when JSON is complete (**no `--yes`**):
121
131
  ```bash
122
132
  sensecraft-cli app create --from-json ./app.json
123
133
  # CLI returns app_id + console_url + detail_url (even if update_app body was {}).
124
- # detail_url is https://app.seeed.cc/view-application/<id>-<slug>?tab=custom&from=my-apps
125
- # (test AI host → https://test-app.seeed.cc). from=my-apps loads the sketch cover.
134
+ # detail_url is https://app.seeed.cc/view-application/<id>-<slug>?from=user-center&tab=custom
135
+ # (test AI host → https://test-app.seeed.cc). from=user-center loads the sketch cover.
126
136
  # A non-empty web_link on a list item is the link to give the user.
127
137
  # Restore JSON may have pic_url (list) or images[] (view); CLI writes both.
128
138
  # Show links to the user. NEVER re-run create because stdout looked empty —
@@ -82,6 +82,19 @@ sensecraft-cli app fields
82
82
  sensecraft-cli app blocks
83
83
  ```
84
84
 
85
+ ### `app doc compile`
86
+
87
+ **Status: implemented.** Compiles a Markdown file into editor `deployment.blocks`. No Access Key, no network, no `--sandbox`. Does not upload files and does not insert tool-blocks.
88
+
89
+ ```bash
90
+ sensecraft-cli app doc compile --from-md ./README.md
91
+ # stdin: sensecraft-cli app doc compile --from-md -
92
+ ```
93
+
94
+ Use stdout `deployment` in `app create` / `app update`, or skip this step and pass the file as `app create --from-md` / `app update --from-md`. `suggested_app_name` is the opening `# title`. `suggested_excerpt` is the paragraph under it. `pending_uploads` lists local image/video/file paths that were left out of `content`; upload those, then put the https URL in `src` or `href`.
95
+
96
+ `--from-json` rejects text blocks whose `content` is still Markdown (`**bold**`, `` `code` ``, a leading `#` or list marker). `code` block source is exempt. The same write fills a paragraph that is only a video URL, a remote file link, and a remote image up to the editor's HTML. A video URL inside a sentence is left as text.
97
+
85
98
  ### `app create` / `app update`
86
99
 
87
100
  **Status: implemented.**
@@ -92,8 +105,9 @@ sensecraft-cli app blocks
92
105
 
93
106
  | Flag | Notes |
94
107
  | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
95
- | `--name` | `app_name` only create (empty shell) |
96
- | `--from-json` | JSON path or `-`; must include `app_name` if `--name` omitted. Extra fields → follow-up `update_app` **only on the newly created `app_id`** (cannot target an existing app) |
108
+ | `--name` | `app_name` only create (empty shell). Optional when JSON or the Markdown title provides one |
109
+ | `--from-md` | Markdown path or `-`. Compiled into editor blocks. Fills `app_name` / `excerpt` when omitted. Appends JSON `deployment.blocks` after the document. stdout adds `pending_uploads` and `warnings` |
110
+ | `--from-json` | JSON path or `-`; must include `app_name` if `--name` and `--from-md` omit it. Extra fields → follow-up `update_app` **only on the newly created `app_id`** (cannot target an existing app). Text blocks get editor video, link, and image HTML |
97
111
  | `--sandbox` | sample JSON |
98
112
 
99
113
  Rejects `be_public=1` / `privacy=1`. Do **not** confuse with `app update` (existing app → L2).
@@ -101,9 +115,9 @@ Rejects `be_public=1` / `privacy=1`. Do **not** confuse with `app update` (exist
101
115
  **Success output:** CLI always prints `app_id`, `console_url`, and `detail_url` on the app site (`https://app.seeed.cc`, or `https://test-app.seeed.cc` when the AI host contains `test-`):
102
116
 
103
117
  - edit: `/application/edit?id=<app_id>`
104
- - my app detail: `/view-application/<app_id>-<slug>?tab=custom&from=my-apps`
118
+ - my app detail: `/view-application/<app_id>-<slug>?from=user-center&tab=custom`
105
119
 
106
- `from=my-apps` loads the sketch (cover/`images`). A public link uses `tab=public&from=application-store` and must not include `from=my-apps`. If a list item has a non-empty `web_link`, give the user that URL instead of `view-application`. Model and legal pages stay on `sensecraft.seeed.cc`.
120
+ `from=user-center` loads the sketch (cover/`images`) and the page back button returns to the creator center. A public link uses `tab=public&from=application-store` and must not include `from=user-center` or `from=my-apps`. If a list item has a non-empty `web_link`, give the user that URL instead of `view-application`. Model and legal pages stay on `sensecraft.seeed.cc`.
107
121
 
108
122
  **Do not retry create blindly:**
109
123
 
@@ -112,6 +126,9 @@ Rejects `be_public=1` / `privacy=1`. Do **not** confuse with `app update` (exist
112
126
  - Prefer updating the existing `app_id` with `app update --yes` over creating a duplicate.
113
127
 
114
128
  ```bash
129
+ # Markdown document. Scene, cover, BOM, and tool-blocks stay in the JSON.
130
+ sensecraft-cli app create --from-md ./README.md --from-json ./app.json
131
+
115
132
  # One-shot full create: deliberately not L2
116
133
  sensecraft-cli app create --from-json ./app.json
117
134
  # Expect app_id + console_url + detail_url; if missing, list before retrying:
@@ -126,8 +143,10 @@ sensecraft-cli app create --name "My App"
126
143
  | Flag | Notes |
127
144
  | --------------- | ---------------------------------------------------------------------------------------------------------- |
128
145
  | `--id` | required |
129
- | `--from-json` | path or `-`; required unless `--activity-id` is set |
146
+ | `--from-json` | path or `-`; optional when `--from-md` or `--activity-id` is set |
147
+ | `--from-md` | Markdown path or `-`. Same compile as create. Does not replace an `app_name` / `excerpt` already in the JSON |
130
148
  | `--activity-id` | optional positive integer. Joins that activity. Omit or pass empty to leave existing activity tags as-is |
149
+ | `--cancel-activity-id` | optional positive integer. Leaves that activity. Does not change `allow_clone` |
131
150
  | `--yes` | after user confirmation |
132
151
  | `--sandbox` | sample JSON |
133
152
 
@@ -147,17 +166,22 @@ sensecraft-cli app update --id <app_id> --from-json ./app.json --yes
147
166
 
148
167
  # Join activity 1. activity_id is sent as a JSON number. tags in JSON is dropped.
149
168
  sensecraft-cli app update --id <app_id> --activity-id 1 --yes
169
+
170
+ # Leave activity 1. cancel_activity_id is sent as a JSON number.
171
+ sensecraft-cli app update --id <app_id> --cancel-activity-id 1 --yes
150
172
  ```
151
173
 
152
174
  `activity_id` must be a positive integer. List ongoing ids with `app activity list` first. If that list succeeds and does not contain the id, CLI does not POST. The server still rejects a bad id with `11202` and a missing or expired activity with `25000` `Activity does not exist or has expired` (the whole edit is discarded). Omitting `activity_id` does not change existing activity tags. `tags` is not read by the server.
153
175
 
176
+ `cancel_activity_id` must be a positive integer. CLI sends it as a JSON number and does not check the ongoing list or change `allow_clone`. Omitting it leaves participation unchanged. The same id cannot be both `activity_id` and `cancel_activity_id`.
177
+
154
178
  When `--activity-id` is set and this JSON does not include `allow_clone`, CLI sets `allow_clone` to `1` unless the sketch is already `1`. That matches the web contest save. An explicit `allow_clone` in the JSON is kept.
155
179
 
156
180
  ### `app publish` / `app unpublish` / `app delete` (L2)
157
181
 
158
182
  **Status: implemented.**
159
183
 
160
- - `publish` → `privacy=2` (submit review). Same path as Console **发布草稿** when the app is already public (`is_sketch` + `be_public=1`). Result may include `draft_publish`. Refused if already `be_public=2` or not owner.
184
+ - `publish` → `privacy=2` (submit review). Same path as Console **发布草稿** when the app is already public (`is_sketch` + `be_public=1`). Result may include `draft_publish`. Refused if already `be_public=2` or not owner. stdout `detail_url` is the creator-center page (`from=user-center`). Give the user that URL. Do not replace it with `/application/detail/<id>` (plaza page, no private draft).
161
185
  - **Publish Declaration (required for `publish` only):** matches Console 「发布确认」`warrantyAccepted`. Before passing `--agree-declaration`, show the user:
162
186
  - Review will lock editing until approval (or `unpublish`)
163
187
  - Declaration URL: https://sensecraft.seeed.cc/legal/en/declaration
@@ -52,7 +52,16 @@ Mine first, ask approval once at the end.
52
52
 
53
53
  The app editor stores a flat `deployment.blocks` array. It does not keep the Markdown file and it does not re-parse Markdown at preview time. There is no `app import-md` command.
54
54
 
55
- Follow [../../../docs/md-to-app.md](../../../docs/md-to-app.md): lift `app_name` / `excerpt` / scene / BOM out of the prose, map headings that are real user actions to `step` blocks (a `h2` is not a step), and write inline formatting as HTML. Then run the same create → update → publish commands as below. `**bold**` inside `content` will display as asterisks.
55
+ When the source is Markdown, pass it on create or update. The CLI compiles editor HTML, fills `app_name` / `excerpt` when the JSON omits them, and truncates an excerpt longer than 300 characters (see `warnings`).
56
+
57
+ ```bash
58
+ sensecraft-cli app create --from-md ./README.md --from-json .sensecraft/sensecraft-app.payload.json
59
+ sensecraft-cli app update --id <app_id> --from-md ./README.md --yes
60
+ ```
61
+
62
+ `--from-json` `deployment.blocks` are appended after the compiled document. Put tool-blocks there; do not repeat the prose. Upload every `pending_uploads` path, then write the returned https URL back into that block on a follow-up update. `app doc compile --from-md` only prints the JSON and does not create an app. JSON text blocks that still contain Markdown markers are rejected. Scene, cover, and BOM are not invented.
63
+
64
+ Follow [../../../docs/md-to-app.md](../../../docs/md-to-app.md) for step headings (`## 步骤:动作`, `## Step: Flash`, `### 1. 动作`) and for which headings stay headings. A plain `h2` is not a step.
56
65
 
57
66
  Contest entry is a later `app update --activity-id <id>`. CLI also writes `"allow_clone": 1` on that update when the sketch is not already `1` and the JSON did not set `allow_clone`. Confirm the id is in `app activity list` first.
58
67
 
@@ -18,6 +18,7 @@ Agent fill-in guide for SenseCraft custom apps (v3). Aligns with Console `infoFo
18
18
  | `introduction` | legacy long text | no | if non-empty, editor may merge into intro blocks — prefer `deployment.blocks` for new content |
19
19
  | `author` | string | recommended on save | current user id/account |
20
20
  | `activity_id` | positive integer | no | Join this activity. Omit or send blank to leave existing activity tags unchanged. CLI sends a JSON number. `0`, negatives, and non-integers are rejected before POST. Server: not a positive integer → `11202` `Request parameters are invalid`; missing / unpublished / deleted / outside start–end → `25000` `Activity does not exist or has expired` (the whole edit is discarded). |
21
+ | `cancel_activity_id` | positive integer | no | Leave this activity. Omit or send blank to leave participation unchanged. CLI sends a JSON number and does not change `allow_clone`. Must not equal `activity_id`. |
21
22
  | `flow_data` / `model_data` | Node-RED sync | only with `node-red` block | `flow_data` must be **JSON string** at top level |
22
23
 
23
24
  ### Create vs update
@@ -29,7 +30,7 @@ Agent fill-in guide for SenseCraft custom apps (v3). Aligns with Console `infoFo
29
30
  - **Update (`app update`)**: always include `app_id` (CLI `--id`).
30
31
  - **Info fields** (`app_name`, `excerpt`, `scene`, `allow_clone`, `allow_commerce`, `images`, `license`, `author`): aiserver often **ignores** a body that only contains `app_name`. CLI **auto-merges** missing info keys from `app view --sketch` before calling `update_app` (does **not** merge `be_public` from user/existing for private apps). If current `be_public=1`, CLI **injects** `be_public=1` like Console info save (plaza unchanged until `app publish`). `be_public=2` refuses update. Agents may pass a sparse rename patch; still **re-read** with `app view` / `app list` after update because success may be `{}`.
31
32
  - **Other sections** (`deployment`, `materials`, …): may be sent alone without forcing an info merge. Full leave-save usually sends info + deployment + materials together.
32
- - **Activity**: `--activity-id <positive integer>` or JSON `activity_id`. Do not send `tags`; the server ignores it and the CLI strips it. A blank `activity_id` is omitted. If `activity_id` is set and this JSON omits `allow_clone`, CLI sets `allow_clone` to `1` when the current sketch is not already `1`.
33
+ - **Activity**: `--activity-id <positive integer>` or JSON `activity_id`. Do not send `tags`; the server ignores it and the CLI strips it. A blank `activity_id` is omitted. If `activity_id` is set and this JSON omits `allow_clone`, CLI sets `allow_clone` to `1` when the current sketch is not already `1`. `--cancel-activity-id <positive integer>` or JSON `cancel_activity_id` leaves that activity and does not change `allow_clone`. Do not send the same id in both fields.
33
34
  - **Rename workflow**: confirm with user (L2) → `app update --id … --from-json '{"app_name":"…"}' --yes` (CLI fills the rest) → verify name via `app view --id … --sketch` or `app list --mine --name …`.
34
35
 
35
36
  ## Visibility / review
@@ -6,9 +6,9 @@ Help the Agent choose the right block and fill `config` safely. Execution on har
6
6
 
7
7
  The editor does **not** render Markdown on read. Preview wraps each block by `type` and treats `content` as HTML or plain text. Raw `**bold**`, `# heading`, or `- item` inside `content` shows up as those characters.
8
8
 
9
- Write inline formatting as HTML: `<strong>`, `<em>`, `<code>`, `<s>`, `<a href="…">`, `<img src="…" alt="…" />`, `<video src="…" controls>`. Do not wrap a `paragraph` in an extra `<p>` — the preview adds it. `code` block `content` is plain source, not HTML.
9
+ Write inline formatting as HTML the editor stores: `<strong>`, `<em>`, `<code>`, `<s>`, links with `target="_blank"`, file links (pdf/zip/bin/…) also with `download` and `doc-file-download-link`, images with `draggable="false"`. A paragraph that is only a video URL becomes `<video controls>` or a `video-embed-wrapper` iframe (YouTube, TikTok, Douyin, Bilibili, Vimeo, Youku, iQiyi). Prefer `app create --from-md` / `app update --from-md` instead of writing that HTML by hand. `--from-json` fills those video, link, and image attributes when they are missing. Do not wrap a `paragraph` in an extra `<p>`. `code` block `content` is plain source, not HTML.
10
10
 
11
- How to split a user Markdown file into these blocks, then create and publish: [../../docs/md-to-app.md](../../docs/md-to-app.md).
11
+ Compile a Markdown file with `sensecraft-cli app doc compile --from-md <file>` when you only want the JSON (no network). `app create --from-md` and `app update --from-md` run that compile and then write. JSON text blocks that still contain Markdown markers are rejected. How the toolbar maps onto blocks: [../../docs/md-to-app.md](../../docs/md-to-app.md).
12
12
 
13
13
  Host binaries (images, videos, firmware) via `file upload` first. A relative path from the Markdown file is not a valid `src`.
14
14
 
@@ -55,7 +55,7 @@ Runs the same check, then opens `console_url` (or prints it). Sandbox never open
55
55
  | Flag | Required | Notes |
56
56
  | ------------- | -------- | --------------------------------------------- |
57
57
  | `--model-id` | one of | Model detail = AI deploy page (click 部署) |
58
- | `--app-id` | one of | App detail; plaza omits `from=my-apps` |
58
+ | `--app-id` | one of | App detail; plaza omits `from=user-center` |
59
59
  | `--print-only`| no | Print URL only |
60
60
  | `--sandbox` | no | Sample JSON; never open a browser |
61
61