Console: enrol a phone and remove an enrolled one

オープン
#1,133 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
4/5
見積もり時間
3〜5日
初心者へのやさしさ
48/100
issue の種類
機能追加
明瞭さ
明確に書かれている
活発さ
活発
技術スタック
typescript

調査の方向性

Start with ui/AGENTS.md and the existing action flow in ui/src/model/actions.ts, ui/src/state/actions.ts, and ui/src/ds/confirm-dialog.tsx. Then trace the worker and device menus, ⌘K search, and the tests named in the technical spec, including e2e/console/actions.spec.ts. Done means both device actions work only in worker mode across the listed surfaces, the required form and daemon feedback behave as specified, and the website copy is corrected.

索引モデルが issue の本文から書いたものです。

説明

platform:android platform:ios task:draft

Part of #1131.

Scope

On a worker's console, an operator can enrol a phone plugged into the worker, by its platform and id, and remove an enrolled phone that is not in use. Both go through the routes that exist (POST /v1/devices, DELETE /v1/devices/{id}). On a gateway, or before the console knows the daemon's mode, neither is offered. The task also adds the console's device action list that #1135 extends, its first form (the Enrol dialog), and fixes the website lines that say the console cannot act.

In short

On a worker, the Devices tab's ⋯ menu on a phone, the phone's drawer and ⌘K offer Remove phone, and the worker's ⋯ menu on the Fleet table, the worker page's actions and ⌘K offer Enrol phone…. Enrol phone… opens a dialog with Platform (iOS or Android) and Phone id; its Enrol button stays disabled while the id is empty. The console does not check the id further: the daemon does, and a refusal shows its message in the error toast. The result is a toast, and the list changes once the daemon's event arrives; a removed phone's row then reads deleted, as every deleted device's row does today.

flowchart LR
  P["Fleet row ⋯, worker page, ⌘K (worker mode)"] --> E["Enrol phone… dialog (new)"]
  E --> A["POST /v1/devices"]
  R["Phone row ⋯, drawer, ⌘K (new)"] --> C[Confirm: Remove iPhone 15?]
  C --> D["DELETE /v1/devices/{udid}"]
  A --> T[Toast]
  D --> T

Words, exactly (<model>, <udid>, <os> (iOS or Android), <version>, <n>, <id> are the daemon's values or what was typed):

Where Text
Remove phone confirm title Remove <model> (<udid>)?
its body Simlock stops leasing it and forgets its app list. Nothing on the phone changes, and you can enrol it again.
its buttons Keep, Remove phone (busy: Removing…)
its success toast Removed <model>
its error toast title Couldn't remove <model>, with the daemon's message below
Enrol dialog title Enrol a phone
its body Plug the phone into this worker and unlock it. Its id is the UDID from xcrun devicectl list devices, or the serial from adb devices -l.
its fields Platform (iOS, Android; iOS first and chosen), Phone id
its buttons Cancel, Enrol (busy: Enrolling…)
its success toast Enrolled <model> (<os> <version>), or Enrolled <model> (<os> <version>) again; description <n> user app recorded. or <n> user apps recorded.
its error toast title Couldn't enrol <id> with the typed id, the daemon's message below, e.g. id: must not contain whitespace or control characters; its Retry sends the same platform and id

Inputs: the feature's Examples table for the phone id.

If this goes wrong, an operator would notice a Remove phone on a phone in use (the daemon then refuses it), or an Enrol phone… missing from one of its surfaces.

Technical spec

Facts

Commit ce8fea85.

# Fact Source
F1 Action ids are a closed union; an action holds label, danger, method, path, confirm, success, outcome, timeoutMs, failure, undo, body ui/src/model/actions.ts:12-51
F2 Worker actions are offered only when the mode is gateway; Remove worker uses typeToConfirm ui/src/model/actions.ts:236-290
F3 useActions().run asks the confirm, calls api.write(method, path, { body, timeoutMs }), toasts the outcome, shows the ApiError's message under the failure title with Retry, nothing on a 401, and keeps an in-flight flag per itemKey ui/src/state/actions.ts:68-123
F4 ApiError carries the status, the daemon's code and its message ui/src/data/api.ts:15-25
F5 A write waits 10 s unless the action names timeoutMs ui/src/data/api.ts:1, :47, :109-112
F6 The confirm host is Base UI's AlertDialog with a title, a body, an optional typed name that keeps the confirm button disabled, and Keep and confirm buttons ui/src/ds/confirm-dialog.tsx:80-137
F7 The mode comes from useDaemonMode() ui/src/state/live.tsx:92
F8 The worker page's actions are useWorkerPageMenu(page) in an ActionBar; the Devices tab's DataTable has no menu; DataTable takes a menu ui/src/screens/fleet/worker-page.tsx:65-73, :138-158; ui/src/state/workers.ts:68-80; ui/src/ds/table.tsx:42-53
F9 The device drawer shows lease actions only, when the device is leased ui/src/screens/fleet/device-drawer.tsx:19-26, :61-64
F10 A device row knows physical, the model, and udid = the phone's driverDeviceId; it keeps the state only as a toned word ui/src/model/worker-page.ts:289-340
F11 The status device shape carries id, spec, state, physical, and driverDeviceId for a phone only src/contract/schemas.ts:209-231
F12 ⌘K's actions are built from workerActions, leaseActions and requestActions in buildResults ui/src/model/search.ts:36-44, :91-115
F13 POST /v1/devices takes { id, platform } (strict), answers { id, driverDeviceId, platform, model, osVersion, class, appCount, reenrolled }; 409 DEVICE_BUSY, 422 DEVICE_NOT_ENROLLABLE and NO_DRIVER, 501 on a gateway src/http/route-declarations.ts:27-42; src/contract/operations.ts:955-969
F14 The daemon refuses a malformed phone id with 400 BAD_REQUEST and a message id: <rule>, e.g. id: must not contain whitespace or control characters, id: must not start with - src/contract/operations.ts:937-953; src/daemon/dispatch.ts:382; src/contract/errors.ts:495-503
F20 The Fleet table's worker rows have a ⋯ menu from useWorkerMenu, which reads workerActions only; the console may import contract values only from version-order.ts and inbox.ts ui/src/screens/fleet/index.tsx:77-85; ui/src/state/workers.ts:62-66; .dependency-cruiser.mjs:29-33
F15 DELETE /v1/devices/{id} unenrols a phone by its driverDeviceId; a phone that is leased is refused leased, reclaiming reclaiming, claimed or in another state than ready, quarantined, absent busy src/http/route-declarations.ts:87-100; src/core/physical-enrollment.ts:122-129, :179-197
F16 Every device. event marks ['workers'] and ['inbox'] stale ui/src/model/stale-keys.ts:36-37
F17 The website says "To drain, undrain or remove a worker, use the CLI", and that the console "only shows; it does not lease, release or fix anything" and "does not fix" Attention items, while the console offers drain, undrain, remove, update and release website/src/content/docs/docs/gateway/fleet-console.mdx:8; website/src/content/docs/docs/worker/console.mdx:10, :182; ui/src/model/actions.ts:62-88, :236-290, :292-295
F18 The model tests build actions directly; the state tests run useActions under a fake api, confirm and notify; the browser lane has "the console acts" ui/src/model/actions.test.ts:1-30; ui/src/state/actions.test.tsx:1-40; e2e/console/actions.spec.ts:78
F19 An emulator's shutdown waits up to 180 s, then 5 s after a kill (the 200 s bound #1135 shares) src/drivers/android/index.ts:87, :131, :2270-2287
Modules touched

Searches: workerActions, useWorkerMenu, ItemAction, ActionConfirm, typeToConfirm, useWorkerPageMenu, DeviceRow, buildResults, DEVICE_COLUMNS in ui/src; "use the CLI", "only shows", "does not fix" in website/.

  • ui/src/model/actions.ts: deviceActions(device, mode) (new; Remove phone), enrolActions(worker, mode) (new; Enrol phone…), the 200 s device write bound, form fields on ActionConfirm, and a failure title and body built from the form's values. deviceActions takes the device's id, state, physical, model, platform name, OS version and, for a phone, its driverDeviceId, so #1135 needs no other input.
  • ui/src/model/worker-page.ts: the row keeps what deviceActions reads (state, platform).
  • ui/src/model/search.ts: ⌘K reads deviceActions for each worker's devices and enrolActions.
  • ui/src/state/actions.ts: run sends the form's values as the body.
  • ui/src/state/workers.ts: the device menu; the Fleet row's and the page's menus add enrolActions. Inbox worker items do not: they are conditions, not workers.
  • ui/src/ds/confirm-dialog.tsx and its CSS: a choice and a text field, a confirm disabled while a required field is empty, a cancel label, a non-danger confirm, and the values handed to the work.
  • ui/src/screens/fleet/worker-page.tsx, device-drawer.tsx: the row menu and the drawer's actions.
  • ui/AGENTS.md (Actions), docs/internal/DESIGN.md (the dialog's form), website/.../worker/console.mdx, gateway/fleet-console.mdx, worker/enrolling-physical-devices.mdx (only this task of #1131 edits that page).
  • e2e/console/actions.spec.ts and its stub answers.
flowchart LR
  screens["screens/fleet *"] --> state["state/workers, state/actions *"]
  state --> model["model/actions, search, worker-page *"]
  screens --> ds["ds/confirm-dialog *"]
  state --> data[data/api]
  data --> daemon["/v1/devices (worker)"]
sequenceDiagram
  participant O as Operator
  participant C as Console
  participant D as Worker daemon
  O->>C: Enrol phone…, iOS, 00008110-001A2B3C4D5E, Enrol
  C->>D: POST /v1/devices { platform: ios, id }
  alt 200
    D-->>C: { model, osVersion, appCount, reenrolled, ... }
    D-->>C: event device.enrolled
    C-->>O: toast Enrolled iPad (iOS 18.5)
  else 422 or 409
    D-->>C: { error: { code, message } }
    C-->>O: error toast Couldn't enrol 00008110-001A2B3C4D5E, the message, Retry
  else no answer in 200 s
    C-->>O: error toast, The daemon did not answer.
  end
Contract and event changes

none. The console calls two routes that exist; no event changes.

Other code on the same state

Searches: the in-flight set (inFlight in ui/src/state/actions.ts: 1 writer), the confirm host (createConfirmer, ConfirmHost: 1 each), and the phone records (enrollment.add, enrollment.remove: the CLI and HTTP; 2 callers).

Component Both act Who wins
The in-flight flag a phone's row, drawer and ⌘K share the itemKey device/<worker id>/<device id> the first; the rest are disabled until it settles
The confirm host one dialog at a time, as today the open one
simlock device add/remove on the worker same records the daemon's claim decides; the loser gets DEVICE_BUSY, or UNKNOWN_DEVICE once the phone is gone, and the console shows its message
#1135 adds delete-device to deviceActions —
Failure modes
Call Outcome What happens Limit, counted from
POST /v1/devices 200 success toast from the answer 200 s from the send
same 400, 409, 422 error toast: Couldn't enrol <id> and the daemon's message, Retry with the same values same
same 401 no toast; the session signs out (F3) same
same no answer error toast: The daemon did not answer. same
DELETE /v1/devices/{udid} 200 Removed <model> 200 s from the send
same 409, or 404 when another remove came first error toast: Couldn't remove <model> and the daemon's message same
same no answer The daemon did not answer. same

The console writes no state. Two clicks at once send one request (the in-flight flag, F3).

Rules in play
  • ADR 0055 §3: "offers none of these when it is gateway or unknown" — mode === "worker" only.
  • ADR 0037 §3: "One list of actions per kind of item, read by every surface" — the row, the drawer and ⌘K read deviceActions; the Fleet row, the worker page and ⌘K read enrolActions.
  • architecture rule 10: one rule in one place — the console does not copy the daemon's phone-id rule; it sends the id and shows the refusal.
  • ADR 0037 §3: "one that cannot [be undone] names exactly what it ends" — the confirm names the phone and its id.
  • ADR 0037 §5: "An error toast shows the daemon's own message".
  • ui/AGENTS.md Layers: "A screen never fetches … never decides what a state means" — offering rules live in model/.
  • documentation rule 9: the console pages change in the same PR.
Tests

Seam: deviceActions, enrolActions and buildResults in ui/src/model/ (modelled on ui/src/model/actions.test.ts), useActions().run (modelled on ui/src/state/actions.test.tsx), and the browser lane's "the console acts" (e2e/console/actions.spec.ts) for the dialog and the drawer.

  • An operator opens a device's menu and sees Remove phone only on an enrolled phone that is not in use, on a worker: mode worker with a phone ready, absent, quarantined (offered, danger, confirm as worded); leased, reclaiming (not offered); mode gateway and unknown (nothing); a simulator (no Remove phone).
  • An operator runs Remove phone and sees a confirm naming the phone, then one DELETE /v1/devices/{udid} and a toast: confirmed and 200 (path with the UDID encoded, timeoutMs 200000, Removed <model>); cancelled (no request); 409 DEVICE_BUSY (Couldn't remove <model> with the daemon's message).
  • An operator sees Enrol phone… on a worker's Fleet row, its page and ⌘K only in worker mode: worker (offered, not danger, itemKey worker/<id>/enrol); gateway and unknown (not offered).
  • An operator opens Enrol phone… and sees the form: Platform with iOS chosen first; Enrol disabled while Phone id is empty and enabled once typed; Cancel closes it and sends nothing; the drawer of an unleased phone offers Remove phone.
  • An operator sends Enrol phone… and sees one POST /v1/devices with the platform and id, then a toast: iOS and Android (body { platform, id }, timeoutMs 200000); enrolled (Enrolled iPad (iOS 18.5), 2 user apps recorded.); enrolled again (… again, 1 user app recorded.); 422 DEVICE_NOT_ENROLLABLE, and 400 BAD_REQUEST for R5CT 1234 (Couldn't enrol <id> with the daemon's message; Retry sends the same body).
  • An operator opens ⌘K on a worker and finds the device actions its menus offer: a phone's Remove phone and the worker's Enrol phone… in worker mode; neither in gateway mode.

Done when

  • pnpm exec vitest run --project unit ui/src/model/actions.test.ts ui/src/model/search.test.ts ui/src/state/actions.test.tsx passes with the Tests lines above, the form's line aside.
  • pnpm test:console --project=chromium e2e/console/actions.spec.ts passes with the form's Tests line and one more test: on a worker, Enrol phone… with a typed id sends one POST /v1/devices and shows the toast, and a phone's row menu offers Remove phone.
  • website/.../gateway/fleet-console.mdx says the console drains, undrains and removes workers; worker/console.mdx lists the actions the console offers (release, cancel, the Inbox fixes, enrol and remove a phone) and no longer says it only shows; worker/enrolling-physical-devices.mdx names the console's Enrol phone… and Remove phone.

Out of scope

  • Delete device on a simulator or emulator (#1135).
  • A list of plugged-in phones to pick from.
  • Device actions on a gateway's console.

Depends on

Written by an agent.

主要言語
TypeScript
スター
705
フォーク
40
平均マージ
12時間 9分
マージ済み PR(30日)
376

環境構築

このプロジェクトには開発コンテナ、Dockerfile、コントリビューションガイドがありません。まず README を読み、一般的な手順ははじめてのコントリビューションガイドを参照してください。

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

callstackincubator/simlock のほかの issue

callstackincubator/simlock の issue をすべて見る

似ている issue

TypeScript の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。