Files
archived-orca/src/cli/root-help-text-secondary.ts
Jinwoo Hong 4fabde28b1 feat(cli): one enclosing-workspace rule, --environment local, copyable addresses, and --parent-environment (#39733)
* feat(cli): one enclosing-workspace rule, --environment local, and copyable workspace addresses

current/active and cwd inference now pick the innermost workspace of either kind (worktree or
folder workspace); at equal depth the caller terminal's own workspace wins, otherwise the choice
is refused as ambiguous. --environment local names this machine's own Orca over an ambient
ORCA_ENVIRONMENT or pairing code. worktree ps/show/current print an environment: line and an
address: line (JSON environment, address, addressUnavailable, parent) that always carries its
--environment, and name a parent's environment only when it is verified.

* test: answer the folder catalog read in agent launch cwd tests

* feat(cli): worktree rm refuses current/active and names the selector to pass

Removal needs an explicit workspace, as git worktree remove needs a path. The refusal runs before
rm decides between a worktree and a folder workspace, and reports what current resolves to now
(one selector, the ambiguous choices, or none) in text and as invalid_argument data.

* fix(cli): keep the remote-environment guidance when rm refuses current

* fix(cli): surface folder-catalog failures for omitted targets; no address for a duplicated folder parent

* fix(cli): surface a worktree-list failure for omitted browser and terminal targets too

* test(cli): folder rm refuses current/active before the folder removal path

* fix(cli): refuse a cwd owner whose folder host can't be derived instead of skipping it

* fix(cli): compare cwd owners by filesystem identity, refuse every equal-path tie, surface worktree-list failures

Paths on the caller's own filesystem compare by realpath (reusing resolveRealPathSync), so /tmp
and /private/tmp aliases find the deeper owner in both the folder prefilter and ranking; other
hosts' paths stay lexical. Equal-depth owners with different repo registrations now refuse without
a caller instead of picking by catalog order. An omitted target no longer swallows worktree.list
method_not_found; only the optional folder reads fall back.

* fix(cli): read the realpath helper from shared so the packaged CLI ships it

* refactor(cli): move the catalog row type and unresolved-owner refusal out of the selection/catalog cycle

* fix(cli): resolve every caller-filesystem workspace path, not only basename matches

A workspace registered through a differently named symlink was skipped by the basename gate.
Containment now realpaths cwd and each row on the caller's own filesystem once per command,
shared by the folder prefilter and ranking; folder hosts are derived first so another host's
paths are never resolved locally.

* test: answer the folder catalog read in the ambiguous orchestration-check caller test

* feat(cli): --parent-environment names where a worktree's parent lives

worktree create and worktree set take --parent-environment <local|saved id|name>
next to --parent-worktree. The parent is resolved in that environment only, and
sent to the child as a verified cross-store ref after the child's cross-machine
capability check. Without the flag, the parent stays in the child's environment;
active/current always mean this machine's own Orca.

Preflight failures happen before any change: environment_not_paired,
environment_unavailable, LINEAGE_PARENT_NOT_FOUND / LINEAGE_PARENT_AMBIGUOUS
naming the searched environment, and incompatible_runtime with data.environment
and data.requires.

* fix(cli): parent lookup errors name and list the environment searched

LINEAGE_PARENT_AMBIGUOUS and LINEAGE_PARENT_NOT_FOUND now always carry
data.environment and a listing command for the environment the parent was
looked up in, for parents in another environment and in the child's own. Steps
inherited from the runtime listed the caller's default route instead.

* docs(cli): a local address names the Orca that printed it
2026-11-08 04:08:07 -05:00

196 lines
14 KiB
TypeScript

export const ROOT_HELP_TEXT_SECONDARY = [
' uncheck Uncheck a checkbox by --element ref',
' focus Focus an element by --element ref',
' clear Clear an input by --element ref',
' drag Drag --from ref to --to ref',
' upload Upload --files to a file input or picker button by --element ref',
' dblclick Double-click element by --element ref',
' forward Navigate forward in browser history',
' scrollintoview Scroll --element into view',
' get Get element property (--what: text, html, value, url, title)',
' is Check element state (--what: visible, enabled, checked)',
' inserttext Insert text without key events',
' mouse move Move mouse to --x --y coordinates',
' mouse down Press mouse button',
' mouse up Release mouse button',
' mouse wheel Scroll wheel --dy [--dx]',
' find Find element by locator (--locator role|text|label --value <v>)',
' set device Emulate device (--name "iPhone 12")',
' set offline Toggle offline mode (--state on|off)',
' set headers Set HTTP headers (--headers \'{"key":"val"}\')',
' set credentials Set HTTP auth (--user <u> --pass <p>)',
' set media Set --color-scheme dark|light and --reduced-motion reduce|no-preference',
' clipboard read Read clipboard contents',
' clipboard write Write --text to clipboard',
' dialog accept Accept browser dialog (--text for prompt response)',
' dialog dismiss Dismiss browser dialog',
' storage local get Get localStorage value by --key',
' storage local set Set localStorage --key --value',
' storage local clear Clear localStorage',
' storage session get Get sessionStorage value by --key',
' storage session set Set sessionStorage --key --value',
' storage session clear Clear sessionStorage',
' download Download file via --selector to --path',
' highlight Highlight --selector on page',
' exec Run any agent-browser command (--command "...")',
'',
'Common Commands:',
' orca open [--json]',
' orca serve [--port <port>] [--bind <ip>] [--pairing-address <host>] [--allow-public | --refuse-public] [--mobile-pairing] [--no-pairing] [--grant-desktop-control] [--project-root <path>] [--recipe-json] [--supervise] [--json]',
' orca status [--json]',
' orca diagnostics memory [--json]',
' orca agent-context [--json]',
' orca search <query> [--scope conversation|all] [--fresh] [--limit <n>] [--cursor <c>] [--agent <id>] [--path <p>] [--since <iso>] [--sort relevance|newest] [--debug] [--json]',
' orca search --index-status [--json]',
' orca account add [--agent claude|codex] [--json]',
' orca account list [--json]',
' orca account select --agent claude --account <id|email|system> [--json]',
' orca host list [--json]',
' orca host rm --host ssh:<target-id> [--json]',
' orca environment add --name <name> --pairing-code <code> [--json]',
' orca environment list [--json]',
' orca environment show --environment <selector> [--json]',
' orca environment rm --environment <selector> [--json]',
' orca worktree list [--repo <selector>] [--limit <n>] [--json]',
' orca worktree create --name <name> [--repo <selector>|--project <id-or-name> [--host <host>]|--project-host-setup <id>] [--agent <id>] [--prompt <text>] [--model <id>] [--effort <level>] [--setup run|skip|inherit] [--base-branch <ref>] [--issue <number>] [--pr <number>] [--linear-issue <identifier-or-url>] [--gitlab-issue <number-or-url>] [--gitlab-mr <number-or-url>] [--comment <text>] [--parent-worktree <selector> [--parent-environment <environment>]] [--no-parent] [--run-hooks] [--activate] [--json]',
' orca worktree show --worktree <selector> [--json]',
' orca worktree activate --worktree <selector> [--json]',
' orca worktree current [--json]',
' orca worktree set --worktree <selector> [--display-name <name>] [--issue <number|null>] [--pr <number|null>] [--linear-issue <identifier-or-url|null>] [--gitlab-issue <number-or-url|null>] [--gitlab-mr <number-or-url|null>] [--comment <text>] [--workspace-status <id>] [--unread|--read] [--parent-worktree <selector> [--parent-environment <environment>]|--no-parent] [--json]',
' orca worktree rm --worktree <selector> [--force] [--run-hooks] [--allow-failed-archive-hook] [--json]',
' orca worktree ps [--limit <n>] [--agent-wait] [--json]',
' orca ports [--worktree <selector>] [--all] [--json]',
' orca file open <path> [--line <n> [--column <n>]] [--worktree <selector>] [--focus] [--json]',
' orca file diff <path> [--staged] [--worktree <selector>] [--focus] [--json]',
' orca file open-changed [--mode edit|diff|both] [--worktree <selector>] [--focus] [--json]',
' orca terminal list [--worktree <selector>] [--limit <n>] [--include-visual-layouts] [--json]',
' orca terminal show [--terminal <handle>] [--json]',
' orca terminal read [--terminal <handle>] [--cursor <n>] [--limit <n>] [--screen] [--json]',
' orca terminal send [--terminal <handle>] [--text <text>] [--enter] [--interrupt] [--wait-submit <seconds>] [--retry-request <id>] [--json]',
' orca terminal wait [--terminal <handle>] --for exit|tui-idle [--timeout-ms <ms>] [--json]',
' orca agent launch --agent <id> [--worktree <selector>] [--prompt <text>] [--model <id>] [--effort <level>] [--focus] [--json]',
' orca terminal create [--worktree <selector>] [--title <name>] [--command <text>] [--shell <shell>] [--focus] [--json]',
' orca terminal split [--terminal <handle>] [--direction horizontal|vertical] [--command <text>] [--retry-split <leafId>] [--json]',
' orca terminal switch [--terminal <handle>] [--json]',
' orca terminal close ([--terminal <handle>] [--tab] | --worktree <selector> --all) [--json]',
' orca project list [--json]',
' orca project setups [--project <id>] [--host <host>] [--json]',
' orca project setup-existing-folder --project <id> --host <host> --path <path> [--kind git|folder] [--display-name <name>] [--json]',
' orca project setup-clone --project <id> --host <host> --url <clone-url> --destination <path> [--display-name <name>] [--json]',
' orca project setup-create --project <id> --host <host> [--setup-id <id>] [--path <path>] [--kind git|folder] [--display-name <name>] [--worktree-base-path <path>] [--git-username <name>] [--state ready|not-set-up|setting-up|error|unsupported] [--method imported-existing-folder|cloned|provisioned] [--json]',
' orca project setup-update --setup <setup-id> [--host <host>] [--display-name <name>] [--path <path>] [--worktree-base-path <path>] [--git-username <name>] [--kind git|folder] [--state ready|not-set-up|setting-up|error|unsupported] [--method legacy-repo|imported-existing-folder|cloned|provisioned] [--json]',
' orca project setup-delete --setup <setup-id> [--host <host>] [--force] [--json]',
' orca repo list [--json]',
' orca repo add --path <path> [--kind git|folder] [--json]',
' orca repo show --repo <selector> [--json]',
' orca repo set --repo <selector> --external-worktree-visibility show|hide|inherit [--json]',
' orca repo set-base-ref --repo <selector> --ref <ref> [--json]',
' orca repo search-refs --repo <selector> --query <text> [--limit <n>] [--json]',
'',
'Selectors:',
' --repo <selector> Registered repo selector such as id:<id>, name:<name>, or path:<path>',
' --worktree <selector> Worktree selector such as identity:<identity>, id:<repo-id>::<path>, folder:<id> (where the command takes folder workspaces), name:<displayName>, branch:<branch>, issue:<number>, path:<path>, or active/current',
' --terminal <handle> Runtime-issued terminal handle returned by `orca terminal list --json`',
' --parent-worktree <selector> Parent worktree selector such as identity:<identity>, id:<repo-id>::<path>, folder:<id>, name:<displayName>, branch:<branch>, issue:<number>, path:<path>, or active/current',
" --parent-environment <environment> Environment holding --parent-worktree: local or a saved id/name (default: the worktree's own)",
' --no-parent Force no parent lineage for unrelated worktree creation/update',
'',
'Terminal Send Options:',
' --text <text> Text to send to the terminal',
' --enter Append Enter after sending text',
' --interrupt Send as an interrupt-style input when supported',
' --wait-submit <seconds> Observe this accepted prompt without resending it',
' --retry-request <id> Resume the same durable prompt request after an ambiguous transport failure',
'',
'Terminal List Options:',
' --include-visual-layouts Include tab and pane topology in JSON output',
'',
'Wait Options:',
' --for exit Wait until the target terminal exits',
' --timeout-ms <ms> Maximum wait time before timing out',
'',
'Output Options:',
' --json Emit machine-readable JSON instead of human text',
' --pairing-code <code> Connect to a remote Orca runtime using an orca://pair?... code',
" --environment <selector> Connect using a saved environment id or name; `local` is this machine's own Orca",
' --help Show this help message',
'',
'Behavior:',
' Most commands require a running Orca runtime. If Orca is not open yet, run `orca open` first.',
' Remote runtime access can also be supplied with ORCA_PAIRING_CODE or ORCA_ENVIRONMENT.',
' Use selectors for discovery and handles for repeated live terminal operations.',
'',
'Agent Sessions And Worktrees:',
' Start agents with `worktree create --agent` (new checkout) or `agent launch` (existing',
' worktree). Both open a chat or a terminal per your Chat | CLI choice, and take --model/--effort.',
' orca agent launch --agent codex --model gpt-6-astra --effort high',
'',
'Browser Workflow:',
' 1. Create or navigate: orca tab create --url https://example.com',
' orca goto --url https://example.com',
' 2. Inspect the page: orca snapshot',
' (Returns an accessibility tree with element refs like e1, e2, e3)',
' For concurrent workflows, prefer: orca tab list --json',
' then reuse tabs[].browserPageId with --page <id> on later commands.',
' 3. Interact: orca click --element e2',
' orca fill --element e5 --value "search query"',
' orca keypress --key Enter',
' 4. Re-inspect: orca snapshot',
' (Element refs change after navigation — always re-snapshot before interacting)',
'',
'Browser Options:',
' --element <ref> Element ref from snapshot (e.g. @e3)',
' --url <url> URL to navigate to',
' --value <text> Value to fill or select',
' --input <text> Text to type at current focus (no element needed)',
' --expression <js> JavaScript expression to evaluate',
' --key <key> Key to press (Enter, Tab, Escape, Control+a, etc.)',
' --direction <dir> Scroll direction: up or down',
' --amount <pixels> Scroll distance in pixels (default: viewport height)',
' --index <n> Tab index (from `tab list`)',
' --page <id> Stable browser page id (preferred for concurrent workflows)',
' --expect-url <url> Fail before acting unless the page is at this exact absolute URL',
' --profile <id> Browser profile id',
" --show-profile Include the tab's browser profile in text output",
' --format <png|jpeg> Screenshot image format',
' --from <ref> Drag source element ref',
' --to <ref> Drag target element ref',
' --files <path,...> Comma-separated file paths for upload',
' --timeout <ms> Wait timeout in milliseconds',
" --worktree <selector> Scope commands to a specific worktree's browser tabs",
'',
'Examples:',
' $ orca open',
' $ orca status --json',
' $ orca diagnostics memory --json',
' $ orca repo list',
' $ orca worktree create --name agent-task --agent codex --prompt "hi"',
' $ orca worktree create --repo name:orca --name cli-test-1 --issue 273',
' $ orca worktree create --repo name:orca --name linear-task --linear-issue https://linear.app/stably/issue/STA-335/test-issue',
' $ orca worktree create --name linear-task --linear-issue STA-335',
' $ orca worktree show --worktree branch:Jinwoo-H/cli',
' $ orca worktree current',
' $ orca worktree set --worktree active --comment "waiting on review"',
' $ orca worktree set --worktree active --linear-issue null',
" $ orca worktree set --worktree active --gitlab-mr '!77'",
' $ orca worktree set --worktree active --gitlab-issue https://gitlab.example.com/group/project/-/issues/42',
' $ orca worktree ps --limit 10',
' $ orca file open-changed --mode diff',
' $ orca file open src/App.tsx',
' $ orca terminal create --worktree active --command "codex"',
' $ orca terminal list --worktree path:/Users/me/orca/workspaces/orca/cli-test-1 --json',
' $ orca terminal send --terminal term_123 --text "hi" --enter',
' $ orca terminal wait --terminal term_123 --for exit --timeout-ms 60000 --json',
' $ orca tab current --json',
' $ orca tab show --page page_123 --json',
' $ orca tab create --url https://example.com --profile work',
' $ orca tab profile clone --page page_123 --profile work --json',
' $ orca snapshot',
' $ orca click --element e3',
' $ orca fill --element e5 --value "hello"',
' $ orca goto --url https://example.com/login',
' $ orca keypress --key Enter',
' $ orca eval --expression "document.title"',
' $ orca tab list --json'
].join('\n')