lib/app-commands
Apps-panel command contract, which the dashboard's apps panel speaks.
The UI applies install and remove results optimistically, so every posted
command is tracked here until the server's command watch settles it: a
clean exit comes back as command_done and only clears the running state,
a failure as a command_error system action whose message ends with the
echoed command string, and matching that rolls the optimistic update back. Commands run through a shell on the server, in the environment of
the session the applications use, so ~ in a launch command is the
session user's home.
Which apps are installed is the server's answer, arriving with the server
settings and again as an apps_installed system action when a command
changes it. What is stored locally is a cache of it, so a panel opened before
the server speaks shows the last answer rather than nothing.
Where the catalog comes from is the server's answer as well (appsCatalog):
the proot-apps repository on GitHub, or, for a session installing from a
proot-apps local repository, that folder's catalog served by the server
under api/apps/, so the panel lists exactly what the runner can install.
Interfaces
AppsCatalog
Defined in: lib/app-commands.js:44
Properties
metadata
metadata: string;Defined in: lib/app-commands.js:45
URL of the catalog document (YAML).
icon
icon: (name) => string;Defined in: lib/app-commands.js:46
URL of an entry's icon, from its icon file name.
Parameters
| Parameter | Type |
|---|---|
name | string |
Returns
string
local
local: boolean;Defined in: lib/app-commands.js:47
Whether this server serves it from a local repository.
Variables
INSTALLED_APPS_ROLLBACK_EVENT
const INSTALLED_APPS_ROLLBACK_EVENT: "installedAppsRollback" = "installedAppsRollback";Defined in: lib/app-commands.js:27
Window event dispatched when a failed install or remove is rolled back.
INSTALLED_APPS_SERVER_EVENT
const INSTALLED_APPS_SERVER_EVENT: "installedAppsFromServer" = "installedAppsFromServer";Defined in: lib/app-commands.js:30
Window event dispatched when the server's installed-apps list replaces the stored one.
APP_COMMAND_STATE_EVENT
const APP_COMMAND_STATE_EVENT: "appCommandState" = "appCommandState";Defined in: lib/app-commands.js:33
Window event dispatched whenever the set of running commands changes.
Functions
appsCatalog()
function appsCatalog(serverSettings, tokenize?): AppsCatalog;Defined in: lib/app-commands.js:62
Where the panel reads its catalog, as the server settings say.
A server on a proot-apps local repository publishes apps_local_repo, and
its catalog is read from the server itself, through the session's own
authentication: tokenize (the dashboards' withSessionToken) is applied
to those URLs alone, since the remote catalog is another origin and never
sees a session token.
Parameters
| Parameter | Type | Description |
|---|---|---|
serverSettings | any | The last serverSettings payload. |
tokenize? | (url) => string | Adds the session token to a same-origin URL. |
Returns
pendingAppAction()
function pendingAppAction(app): "install" | "remove" | "update" | "launch";Defined in: lib/app-commands.js:94
The action running for an app, so a list can show it and hold its buttons.
Parameters
| Parameter | Type | Description |
|---|---|---|
app | string | The app name. |
Returns
"install" | "remove" | "update" | "launch"
resolveFinishedAppCommand()
function resolveFinishedAppCommand(command): void;Defined in: lib/app-commands.js:106
Settles a command the server reported finishing cleanly. The optimistic update already holds, so this only stops it reading as still running.
Parameters
| Parameter | Type | Description |
|---|---|---|
command | string | The echoed command string. |
Returns
void
postAppCommand()
function postAppCommand(action, app): void;Defined in: lib/app-commands.js:126
Posts an app command to the core and records it as pending.
Parameters
| Parameter | Type | Description |
|---|---|---|
action | "install" | "remove" | "update" | "launch" | The command to build. |
app | string | The app name the command applies to. |
Returns
void
applyServerInstalledApps()
function applyServerInstalledApps(apps): boolean;Defined in: lib/app-commands.js:146
Adopts the installed-apps list the server reported.
A command still in flight is left alone: its optimistic update is newer than a list read before it ran.
Parameters
| Parameter | Type | Description |
|---|---|---|
apps | string[] | App names the server reports installed; a payload that carries none at all is left to the stored list. |
Returns
boolean
Whether the stored list changed.
readInstalledApps()
function readInstalledApps(): string[];Defined in: lib/app-commands.js:171
Reads the stored installed-apps list.
Returns
string[]
The app names, empty when nothing valid is stored.
writeInstalledApps()
function writeInstalledApps(apps): void;Defined in: lib/app-commands.js:186
Parameters
| Parameter | Type | Description |
|---|---|---|
apps | string[] | The installed-apps list to store. |
Returns
void
resolveFailedAppCommand()
function resolveFailedAppCommand(errMsg): boolean;Defined in: lib/app-commands.js:201
Settles a failed-command notification against the pending map.
A matched launch command older than the failure window is application
lifecycle (the app ran, then exited nonzero), so it is suppressed. A
matched install or remove rolls back the stored installed-apps list and
notifies mounted lists through INSTALLED_APPS_ROLLBACK_EVENT; an
unmatched failure is someone else's command and passes through untouched.
Parameters
| Parameter | Type | Description |
|---|---|---|
errMsg | string | The command_error message. |
Returns
boolean
Whether the notice should be shown.