Skip to content

fix: CLI 1.2.0, shared readable workspace, gRPC reference docs - #9

Merged
flik-lab merged 22 commits into
mainfrom
fix/cli-1.2.0
Nov 18, 2026
Merged

flik-lab merged 22 commits into
mainfrom
fix/cli-1.2.0

Conversation

@flik-lab

Copy link
Copy Markdown
Owner

Summary

Fixes for the 1.2.0 CLI, a readable workspace layout that the CLI and the desktop app share, and gRPC docs that read like an API reference.

CLI

  • The portable CLI bundles the dependencies of nested packages (for example the protobufjs 7 inside @grpc/proto-loader), so gateway commands no longer fail with Cannot find module '@protobufjs/aspromise'.
  • Saved requests run with their own timeoutMs and transport mode; --timeout and --transport still override them.
  • gRPC-web server streams use grpc-web-text and are decoded frame by frame as they arrive.
  • example:run --all takes --collection and matches --request against the request an example is linked to.
  • The gateway honours stream loops, matches proto method names, and gateway:list lists profiles.
  • The Windows launcher passes arguments containing spaces unchanged (CreateProcessW with Windows quoting rules).
  • The Windows CLI installs to %LOCALAPPDATA%\Layang-CLI. The desktop app's Squirrel installer empties %LOCALAPPDATA%\Layang, which deleted the CLI. Installing removes the pre-1.2 location and its PATH entry.

Workspace

  • Workspace files are named after their entities. An id suffix is added only when two distinct ids share a name.
  • The desktop app keeps request fields its editor does not show (assertions, default environment, transport, native target, extensions).
  • The desktop app never autosaves over files changed outside it. The save is refused (WORKSPACE_CHANGED_EXTERNALLY) and the workspace is reloaded from disk.
  • Saved requests on a collection request are that request's examples (<request>.examples/<name>.example.yml, with an optional mock.scenario).

Docs

  • New docs/published/grpc/openapi.yaml: one POST /<package.Service>/<Method> per RPC, with named examples, gRPC status responses and x-grpc extensions.
  • gRPC requests render as a reference page with these sections: Request, Response, Examples, Status codes, Run it, Proto Reference. Descriptions come from proto leading comments (AIP-192), and types resolve within their package.
  • docs:build applies the same documentation settings rules as the desktop app.

Test plan

  • pnpm test passes: 638 pass, 2 skipped, 0 fail. Typecheck is clean; lint shows only the warnings already on main.
  • pnpm run cli:dist smoke check passes, including a name with spaces through the native launcher.
  • Installed the desktop app and CLI on Windows from this branch. On a real gRPC mock workspace, example:run --all --collection "FE Main Display" passes 9/9, and layang ui opens the workspace without changing it.
  • The desktop docs preview matches docs:build output.

🤖 Generated with Claude Code

muhammad.fithraturrahman and others added 22 commits November 11, 2026 21:26
Add canonical scenario storage and delivery controls, harden Electron IPC and transports, improve large-workspace indexing, and publish readable protocol references.
The standalone CLI copied hoisted packages only, so protobufjs 7 under
@grpc/proto-loader lost its @protobufjs/* dependencies and gateway/proto
commands failed with "Cannot find module '@protobufjs/aspromise'".
Packages are now resolved from the requiring package's node_modules chain.
The release script verifies the bundled dependency closure and runs
schema:import, mock:check and gateway:list against the packaged binary.
…files

- Web Access mock streams follow loop/maxLoops like the native mock
  instead of ending after one pass.
- Scenarios match the proto method name (PascalCase); 1.1.x camelCase
  names keep matching.
- gateway:list normalizes profiles, so profiles without upstreams work.
- YAML: a colon separates key and value only when followed by whitespace,
  so unquoted URLs stay plain values.
- The drain test waits for completion instead of a fixed 15 ms, which is
  shorter than one Windows timer tick under load.
Files and folders were named <slug>--<hash> (and gRPC scenarios by two
SHA-256 prefixes), which is hard to review in git. Paths are now built
from entity names, and an id suffix is added only when siblings share a
name:

  mocks/grpc/scenarios/<package.Service>/<Method>/<scenario-id>.scenario.yml
  collections/<collection>/<folder>/<request>.grpc.yml
  gateways/<name>.gateway.yml
  protos/<library>/revisions/<label>

Workspaces written by earlier builds are renamed on the next save or
workspace:format; hash-named scenario files move to their readable path
the first time the scenario repository opens the workspace.
- layang run uses a request's timeoutMs and transport.mode unless
  --timeout or --transport is given; the target follows the transport.
- gRPC-Web server streams use grpc-web-text and are read frame by frame,
  so streams through Layang's own gateway work, an endless stream ends at
  the deadline with the messages received (DEADLINE_EXCEEDED), and
  --max-messages stops it with OK.
- A desktop tab opened from a saved request is not a second run item, so
  --collection/--request see each saved request once.
Opening a workspace rebuilt every collection request from the fields the
editor knows and saved it back, which dropped assertions,
defaults.environment and transport.mode from CLI-authored requests. The
normalizer now keeps them (plus formFields, nativeTargetRef and
extensions), and opening a request uses its saved transport, environment
and assertions. REST defaults (auth: none, bodyType: json) are no longer
written into gRPC/WebSocket requests.
- docs:build writes docs/published/grpc/openapi.yaml: OpenAPI 3.1 with
  POST /<package.Service>/<Method>, schemas from the proto messages,
  x-grpc details, and each saved example as a request/response example
  pair (named alike; errors under default with x-grpc-status).
- An example can name the gRPC mock scenario that answers it
  (example.mock.scenario); docs show it next to the example.
- Examples stored next to a request (requestRef.id) appear in that
  request's docs and run with that request; the desktop app keeps the
  link and the mock scenario when it saves.
- example:run --all accepts --collection, --request matches the request
  name, and example:create stores the example with the selected request
  and accepts --set mock=<scenario>.
- Empty example documentation fields are not written.
The CLI rendered docs/settings.yml as written while the desktop app
normalizes it (include* switches apply only in "custom" sections mode),
so the two could publish different pages. docs:build now uses the same
normalized settings.
The app reloads external changes only after seeing the same revision
twice (~5 s); an autosave in that window wrote its older snapshot and
deleted or reverted files the CLI, Git or an editor had just written
(for example an example created by layang example:create).

The main process records the folder revision when it opens or writes a
workspace and refuses a save when the folder changed since; the renderer
drops that snapshot and reloads at once. docs/build-manifest.yml is
generated output and no longer counts as a change.
One request per RPC now holds every scenario. On a collection request
the Saved requests menu saves, loads, renames and deletes that request's
examples (<request>.examples/), so they run with layang example:run and
appear in the docs; overwriting an example keeps its expectations and
mock link. Loose tabs keep the workspace-wide saved-requests/.

The Examples tab lists the open request's own examples, new examples are
linked to the open request, and loading one fills that request's tab
instead of opening a separate method tab.
Request pages follow the API's structure (Diataxis reference) with
descriptions from proto comments (AIP-192): request and response field
tables with types and enum values, named examples, a status-code table,
layang commands to run them, and a proto excerpt with only the RPC and
the types it uses. The desktop Docs preview and docs:build render the
same page.

- Leading // comments of any length, /** */ blocks and trailing comments
  document rpcs, messages, fields and enum values.
- Types resolve per package, so two packages' SetMessageRequest no longer
  show whichever file was parsed last (fixes field tables and OpenAPI).
- No placeholder text: without a proto comment a request has no summary
  instead of "Call <method>.", the index labels streams correctly
  instead of Unary, and saving no longer creates <request>.<kind>.md
  placeholder files (untouched ones are removed, edited ones kept).
_wspawnv joins arguments with spaces without quoting, so the bundled
node received --collection "FE Main Display" as three arguments (and
lost empty ones); filters, names and messages with spaces silently
matched nothing. The launcher now builds the command line with the
CommandLineToArgvW quoting rules and runs node with CreateProcessW,
waiting for its exit code; Ctrl+C still reaches node through the shared
console. The release smoke check imports a schema named "smoke schema"
and fails if it does not come back whole.
%LOCALAPPDATA%\Layang belongs to the desktop app's Squirrel installer,
which empties it on every install, so installing or updating the
desktop app deleted the CLI at %LOCALAPPDATA%\Layang\CLI. The CLI now
installs to %LOCALAPPDATA%\Layang-CLI (or LAYANG_CLI_HOME). The installer
removes a CLI left at the old location and its PATH entry, keeps the new
directory first on PATH, and replaces app/ and runtime/ of a previous
version instead of copying over them.
Ubuntu runners block unprivileged user namespaces, so Chromium uses the
SUID sandbox helper and aborts unless it is owned by root with mode 4755.
Direct: electron 42.11.18, next 16.4.6, protobufjs 8.8.1, @grpc/grpc-js
1.14.7, @grpc/proto-loader 0.8.1, @electron-forge 7.11.2, postcss 8.5.33,
wait-on 9.5.1, concurrently 9.2.5, tailwindcss 4.3.5. Transitive packages
with a fixed release on their current line are pinned through pnpm
overrides (undici, axios, tar, shell-quote, sharp, protobufjs 7, ...).

protobufjs 8.8 uses TextDecoder when it loads, so the worker test's VM
sandbox now provides the TextDecoder and TextEncoder a Web Worker has.
extract-zip (@electron/packager), picomatch (fast-glob in Forge) and
image-size (appdmg, fixed only in an incompatible 2.x) run only when the
desktop app is packaged and never ship in the app or the CLI.
The compact split layout suite had no tests left; only its unused
helpers remained.
@flik-lab
flik-lab merged commit 108eccb into main Nov 18, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant