mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-07-26 20:00:08 +00:00
Anso
535023b350
* feat(files): open stack file explorer to every tier
Drop the `requirePaid` guard from the seven stack-file write routes
(download, upload, write-content, delete, mkdir, rename, chmod) and
remove every matching `isPaid` check from the file-explorer frontend.
Stack edit permission (RBAC) continues to gate every write end-to-end.
The file explorer is the primary way a user touches a stack's on-disk
surface; gating it behind a paid tier conflicted with the principle
that Community covers single user-initiated actions while paid tiers
add automation and governance.
* docs(files): treat download as a read action, not a write
Download has no `requirePermission('stack:edit')` on the route and no
`canEdit` gate in the UI, so viewer accounts can download. Update the
top paragraph to list download under reads, and rewrite the
troubleshooting accordion to describe the actual gating (a file must be
selected) instead of asserting a role gate that does not exist.
* test(e2e): align stack-files spec with the new tier rule
The community-tier describe block asserted that the Upload control is
absent and the editor shows a `Read-only` chip; the admin-tier block
skipped on Community via `test.skip(tier !== 'paid')`. Both rules
reflected the previous gate, where writes required a paid tier.
Writes are now gated on the `stack:edit` role, not on the license tier.
Repurpose the community describe to assert that a Community admin
under a mocked community license still sees the Upload control and an
editable Save button. Drop the obsolete tier-skip in the admin describe
so upload, edit, delete, and download exercise on every tier. Update
stale comments to reference the role gate.
193 lines
11 KiB
Plaintext
193 lines
11 KiB
Plaintext
---
|
|
title: Stack File Explorer
|
|
description: Browse, view, edit, upload, rename, and chmod every file inside a stack's directory from the dashboard.
|
|
---
|
|
|
|
The file explorer gives you direct access to everything inside a stack's directory: configuration files, certificates, scripts, static assets, and any other files your containers depend on. It lives on the **Files** tab inside the stack editor, alongside the dedicated `compose.yaml` and `.env` editors.
|
|
|
|
<Frame>
|
|
<img src="/images/stack-file-explorer/overview.png" alt="Files tab open with a populated tree on the left, a YAML file open in the editor on the right, and the Anatomy panel in the background" />
|
|
</Frame>
|
|
|
|
<Note>
|
|
The explorer is scoped to the stack's own directory. You cannot browse other stacks or navigate above the stack root.
|
|
</Note>
|
|
|
|
## Opening the file explorer
|
|
|
|
1. Click any stack in the left sidebar.
|
|
2. Click **edit** in the right-hand Anatomy panel header to open the editor.
|
|
3. Switch to the **Files** tab.
|
|
|
|
The **files** shortcut button next to **edit** in the Anatomy header opens the editor and selects the Files tab in one click.
|
|
|
|
The file explorer is available on every Sencho tier. Read actions (browse, preview, download, inspect permissions) are available to every authenticated account. Write actions (upload, edit, create, rename, change permissions, delete) require **stack edit** permission on your account.
|
|
|
|
## Layout
|
|
|
|
The Files tab splits into two panes. The left pane holds the upload affordance, the new-folder button, and the directory tree. The right pane is the action bar plus the file viewer.
|
|
|
|
<Frame>
|
|
<img src="/images/stack-file-explorer/layout-panes.png" alt="Files tab two-pane layout showing the upload widget and tree on the left and the file viewer on the right" />
|
|
</Frame>
|
|
|
|
## Browsing the directory tree
|
|
|
|
Folders sort before files, and entries within each group sort alphabetically.
|
|
|
|
Click a folder to expand or collapse it. Click a file to open it in the viewer on the right. Symlinks render with a chain icon and behave like files when clicked.
|
|
|
|
**Display cap.** Each directory render is capped at 500 entries. A folder with more than 500 children shows the first 500 alphabetically and appends `Showing 500 of N - refine in shell` at the bottom of the list. For directories with more entries, work from a host shell.
|
|
|
|
## Protected files
|
|
|
|
The amber dot in the tree marks the five canonical stack files: `compose.yaml`, `compose.yml`, `docker-compose.yaml`, `docker-compose.yml`, and `.env`.
|
|
|
|
<Frame>
|
|
<img src="/images/stack-file-explorer/protected-tree-marker.png" alt="File tree with amber dot markers next to compose.yaml and .env" />
|
|
</Frame>
|
|
|
|
Two behaviours follow from the marker:
|
|
|
|
- **Dedicated tab redirect.** Clicking `compose.yaml`, `compose.yml`, or `.env` jumps you to the matching **compose.yaml** or **.env** tab so the save-and-deploy controls stay in front of you. `docker-compose.yaml` and `docker-compose.yml` are still flagged as protected, but they open in the regular file viewer because they are not the canonical Sencho file.
|
|
- **Type-to-confirm delete.** All five protected names require typing the filename to confirm a delete. See the Deleting section below.
|
|
|
|
## Viewing files
|
|
|
|
When you click a text file, its contents appear in the editor on the right. The Monaco editor auto-detects the language from the extension.
|
|
|
|
| File type | Behaviour |
|
|
|-----------|-----------|
|
|
| Text file up to 2 MB | Rendered inline with syntax highlighting. |
|
|
| Text file over 2 MB | Panel with the filename, size, and a **Download** button. |
|
|
| Binary file | Same panel layout, label is `Binary file`. |
|
|
|
|
## Editing and saving
|
|
|
|
When you have stack edit permission, the editor opens in write mode. The toolbar shows the filename and a **Save** button that activates as soon as there are unsaved changes.
|
|
|
|
When you do not, the toolbar shows a `Read-only` chip and the editor refuses input.
|
|
|
|
<Frame>
|
|
<img src="/images/stack-file-explorer/viewer-edit-mode.png" alt="Viewer toolbar showing the filename label and the Save button next to a YAML buffer" />
|
|
</Frame>
|
|
|
|
Click **Save** to write the file to disk. Navigating away from the file before saving discards the unsaved edits.
|
|
|
|
<Warning>
|
|
Editing a file does not restart any containers. If your stack reads the file at runtime (for example, a config file mounted as a volume), restart the relevant service after saving so the container picks up the new content.
|
|
</Warning>
|
|
|
|
## Creating files and folders
|
|
|
|
The toolbar **New folder** button at the top of the tree creates a folder in the currently selected directory (the parent of the file you have open, or the stack root if nothing is open).
|
|
|
|
Right-click any folder for **New File** and **New Folder** entries that scope to the right-clicked folder. These write controls appear only when your account has stack edit permission.
|
|
|
|
<Frame>
|
|
<img src="/images/stack-file-explorer/new-file-dialog.png" alt="New file modal scoped to the nginx folder, with the file name field populated and a Create button" />
|
|
</Frame>
|
|
|
|
Filenames cannot be empty, cannot contain `/` or `\`, and cannot be `.` or `..`. The Create button stays disabled until the input passes validation.
|
|
|
|
## Uploading files
|
|
|
|
The dashed **Upload file** affordance at the top of the tree opens a file picker. Uploads are one file at a time.
|
|
|
|
| Limit | Value |
|
|
|-------|-------|
|
|
| Maximum file size | 25 MB. Uploads above the limit return a 413 error with `TOO_LARGE`. |
|
|
| Target directory | The currently selected directory, or the stack root if no file is open. |
|
|
| Same-name files | Overwritten without prompt. |
|
|
|
|
The upload affordance is hidden for users without stack edit permission.
|
|
|
|
<Tip>
|
|
For bulk transfers or files above 25 MB, use `scp` or `rsync` from your workstation directly to the stack directory on the host.
|
|
</Tip>
|
|
|
|
## Downloading files
|
|
|
|
When a file is selected, the right pane action bar shows **Download**. Files stream straight to your browser. Files that exceed the inline preview limit also expose a Download button inside the oversized-file panel itself.
|
|
|
|
## Renaming
|
|
|
|
Right-click any file or folder and choose **Rename**. The dialog accepts a new name following the same rules as creation.
|
|
|
|
Rename appears only when your account has stack edit permission. The rename is in-place; cross-directory moves are not supported. To move an entry between directories, copy it via the host shell or upload to the new location and delete the original.
|
|
|
|
## Permissions (chmod)
|
|
|
|
Right-click any file and choose **Permissions** to inspect or edit its Unix mode bits. The dialog shows a 3 by 3 grid of `r` / `w` / `x` toggles for Owner, Group, and Other, plus the current octal value.
|
|
|
|
<Frame>
|
|
<img src="/images/stack-file-explorer/permissions-dialog.png" alt="Permissions modal for a file showing the rwx grid for Owner, Group, and Other plus the octal value 644" />
|
|
</Frame>
|
|
|
|
When your account has stack edit permission, the toggles are interactive and the footer adds **Save**. For viewer accounts the dialog opens read-only: the toggles render the current state and the footer shows only **Close**.
|
|
|
|
<Note>
|
|
Permissions are applied with `chmod`. Symlinks may not honour the change depending on the host kernel.
|
|
</Note>
|
|
|
|
## Deleting
|
|
|
|
There are three delete entry points. All three require stack edit permission, and all three open the same confirmation modal.
|
|
|
|
- **Toolbar delete.** With a file open in the viewer, click **Delete** in the right-pane action bar.
|
|
- **Context-menu delete.** Right-click any file or folder in the tree and choose **Delete**.
|
|
- **Non-empty folder delete.** The first attempt is non-recursive. If the folder has contents, the modal switches to `This folder is not empty. Delete everything inside?` with a destructive **Delete all** button.
|
|
|
|
When the entry is one of the five protected names, the modal asks you to type the filename before the destructive button activates.
|
|
|
|
<Frame>
|
|
<img src="/images/stack-file-explorer/delete-protected-confirm.png" alt="Delete confirmation modal for compose.yaml requiring the user to type the filename before the destructive button activates" />
|
|
</Frame>
|
|
|
|
<Warning>
|
|
Deletes are permanent. Sencho does not keep a trash bin or undo history for file operations.
|
|
</Warning>
|
|
|
|
## Context menu reference
|
|
|
|
<Frame>
|
|
<img src="/images/stack-file-explorer/context-menu-folder.png" alt="Right-click menu on a folder showing New File, New Folder, Rename, and Delete entries" />
|
|
</Frame>
|
|
|
|
<Frame>
|
|
<img src="/images/stack-file-explorer/context-menu-file.png" alt="Right-click menu on a file showing Rename, Permissions, and Delete entries" />
|
|
</Frame>
|
|
|
|
| Right-click target | Admin entries (with stack edit) | Viewer entries |
|
|
|---|---|---|
|
|
| Folder | New File, New Folder, Rename, Delete | No write entries |
|
|
| File | Rename, Permissions, Delete | Permissions (read-only) |
|
|
|
|
The Permissions dialog opens for everyone; only users with stack edit permission can save changes.
|
|
|
|
## Troubleshooting
|
|
|
|
<AccordionGroup>
|
|
<Accordion title="File shows as 'Binary file detected' but it is a text file">
|
|
The binary detection heuristic flagged null bytes or a high proportion of non-printable characters in the file's first kilobytes. This can happen with certain encodings, non-UTF-8 byte sequences, or unusual line-ending mixes. Download the file, edit it locally or via a host terminal, then re-upload.
|
|
</Accordion>
|
|
<Accordion title="Upload fails with a 413 error">
|
|
The file exceeds the 25 MB per-file upload limit. Compress or split the file before uploading, or transfer it via `scp` or `rsync` directly to the stack directory on the host.
|
|
</Accordion>
|
|
<Accordion title="Cannot delete a folder">
|
|
The first delete attempt is non-recursive. If the folder is not empty, the dialog switches to `This folder is not empty. Delete everything inside?`. Click **Delete all** to remove the folder and its contents. If the error persists, check whether a running container has an open file handle inside that directory; stop the relevant service and retry.
|
|
</Accordion>
|
|
<Accordion title="File saved but the container still reads the old content">
|
|
The container caches the file at startup, or the mount is configured read-only inside the container. Restart the service after saving so the container picks up the new file.
|
|
</Accordion>
|
|
<Accordion title="Download button is missing">
|
|
The Download button appears in the right-pane action bar only when a file is selected in the tree. Click any text or binary file to open it, and the button activates.
|
|
</Accordion>
|
|
<Accordion title="The tree shows 'Showing 500 of N - refine in shell'">
|
|
Each directory render is capped at 500 entries to keep the tree responsive. The first 500 entries alphabetically are shown. To work with the entries past the cap, drop into a host shell with `cd` into the stack directory.
|
|
</Accordion>
|
|
<Accordion title="Write controls are missing">
|
|
Upload, create, rename, chmod save, and delete require **stack edit** permission. Viewer accounts can browse, preview text files, and inspect permissions in read-only mode.
|
|
</Accordion>
|
|
</AccordionGroup>
|