V1 Web PWA · Surface walkthrough

Isis CLI Surface

A per-surface walkthrough of the V1 Web PWA studio surface: layout, states, interactions, data, and cross-references.

walked
8sections3 minread
Markdown source
On this page

Context. surface studio · domain isis · route /studio/isis/cli-surface · auth signed-in + studio entitlement; Studio Isis production boundary hard-blocks this AAA-only route. Automated lane verification uses the explicit localhost-only E2E bypass. · source apps/oshun/web/src/app/studio/isis/cli-surface/page.tsx

Last walked. 2026-07-23 automated desktop Chromium + Pixel 7 mobile walk — production hard-block, localhost-only lane entry, exact BFF catalog and resolution contracts, admin-scope failure, input bounds, request-local disposition, deterministic output, documented-route status, keyboard-accessible result scrolling, touch target, responsive containment, and applicable axe verified

Purpose#

Request-local, non-authoritative preview of deterministic CLI token resolution. The operator supplies both the command registry and query tokens. The resolver classifies each query as exact, alias, unique prefix, ambiguous, or unknown and returns a summary plus candidate names. It does not load a canonical command catalog, execute commands, retain sessions, or create diagnostic, permission, audit, governance, approval, or release evidence.

Exact disposition: request_local_non_authoritative_cli_token_resolution_preview.

Entry points#

  • Sibling quick-action card from /studio/isis/account-protection
  • Embedded as the CLI Surface lane in /studio/isis/cli
  • Studio index (/studio)
  • Direct URL / bookmark (AAA-gated)

Layout regions#

page.tsx mounts ShellLayout active="studio" and three panels.

  • Workspace panel (data-isis-cli-surface-workspace):
    • <h1> "Isis CLI Surface Workspace" (WorkspaceHeading)
    • Honest summary (data-isis-cli-surface-summary)
    • Resolver lane (data-cli-lane, <h2> "Request-local CLI token resolution preview")
    • Resolution Boundary (data-cli-disposition) with four cards: caller-supplied registry, request-only computation, no command execution, and no operational authority
    • Labeled JSON form (data-cli-form) with contract limits and a pending-disabled 44-pixel submit control
    • Result summary and keyboard-focusable horizontally scrollable table
  • Route map panel (data-isis-cli-surface-route-map): one mounted-preview entry and four documented-contract entries
  • Quick-actions panel: links to /studio/isis/account-protection and /studio

States#

  • Loading — data-cli-loading while the catalog contract loads
  • Unauthorized — data-cli-unauthorized on admin-scope 401/403
  • Error — data-cli-error for unavailable, non-2xx, or malformed / authority-inflated catalog responses
  • Ready — exact catalog accepted; boundary and form render
  • Resolving — submit is disabled and labels itself "Resolving…"
  • Result — exact result envelope accepted into data-cli-result
  • Resolution error — local JSON failure, bounded-contract rejection, authorization failure, network failure, or malformed / authority-inflated response in data-cli-resolve-error

Interactions#

Preview resolution (data-cli-form)#

  • Registry and query JSON (data-cli-payload) — caller supplies exactly commands and queries
  • Preview resolution (data-cli-submit) — POSTs the bounded payload to /v1/admin/isis/cli-surface/resolve; it does not execute a command
  • Resolution result (data-cli-result) — query rows expose match type, resolved command, and candidates; the scroll region has a named keyboard focus target

Route map#

  • Mounted preview ×1
  • Documented route shapes without pages or authority ×4

Quick-actions#

  • Open Isis Account Protection workspace → /studio/isis/account-protection
  • Back to Studio workspace index → /studio

Data & contracts#

  • Catalog read: GET /v1/admin/isis/cli-surface
    • exact keys: generatedAt, resolver, limits, disposition
    • explicitly cache-control: no-store
  • Resolution calculation: POST /v1/admin/isis/cli-surface/resolve
    • exact input keys: commands, queries
    • limits: 256 commands, 32 aliases per command, 1,024 queries, 128 characters per whitespace-free token
    • exact success keys: ok, result, disposition
    • deterministic pure calculation; no durable write
    • explicitly cache-control: no-store
  • Persistence / retention: none / request-only
  • Registry authority: caller-supplied; no canonical catalog
  • Execution / state: no command execution, session state, retry, cancellation, diagnostic, trace, permission, or audit control
  • Governance / release: no record or authority
  • Auth: admin-scoped fail-closed per BFF request; AAA-gated Studio route behind the signed-in + studio proxy gate
  • Component sources:
    • apps/oshun/web/src/components/studio/StudioIsisCliSurfaceWorkspace.tsx
    • apps/oshun/web/src/components/studio/StudioIsisCliSurfaceRouteMap.ts
  • Backend sources:
    • apps/oshun/bff/src/routes/admin-isis-cli-surface.ts
    • apps/oshun/bff/src/isis/cli-command-store.ts

Cross-references#

Open questions / known gaps#

  • Scene, export, revision, and governance paths are documented shapes only; they have no pages or operational authority
  • A canonical command catalog, command/session execution service, diagnostic/audit evidence store, governance workflow, and release authority are not bound here