mirror of
https://github.com/shumaiOne/shumai.git
synced 2026-11-19 14:16:29 +00:00
Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
d8c20d6a11 | ||
|
|
8697481d43 | ||
|
|
4ac274cdd4 | ||
|
|
eea844320d | ||
|
|
d255e76806 | ||
|
|
2be1093b91 | ||
|
|
83e902862c | ||
|
|
0a66776067 | ||
|
|
c55804a548 | ||
|
|
97c2939b5e | ||
|
|
0325435125 | ||
|
|
00fa5fed75 | ||
|
|
35a0e82284 | ||
|
|
843a56304c | ||
|
|
1050024fff | ||
|
|
403e209359 | ||
|
|
0359733637 | ||
|
|
2d2ea51668 | ||
|
|
a71723d455 | ||
|
|
ab250a9f0a | ||
|
|
0c0b887b8d | ||
|
|
f304caea00 | ||
|
|
65e2ac1383 | ||
|
|
0dc0bbeb03 | ||
|
|
2ecbd49d18 | ||
|
|
ba3c6dbfee | ||
|
|
49a2d7c380 | ||
|
|
6292f3c792 | ||
|
|
20ad0abeba | ||
|
|
fbff404b9b | ||
|
|
c2348b0e68 | ||
|
|
ff3d71ed3d | ||
|
|
77bd1422d8 | ||
|
|
9529c63c0a | ||
|
|
3b00a42a89 | ||
|
|
f0bdccf713 | ||
|
|
5b7fc04b02 | ||
|
|
687b5a79d8 | ||
|
|
baf30730af | ||
|
|
96539207d0 | ||
|
|
43f95a2fa2 | ||
|
|
0f92a5377f | ||
|
|
4e3e17a547 | ||
|
|
b3cae4f2b0 | ||
|
|
50fbd97953 | ||
|
|
155fb95a0e | ||
|
|
e44938cb8f | ||
|
|
4d61786799 | ||
|
|
76057ccd21 | ||
|
|
47ee794ae4 | ||
|
|
22486b893b | ||
|
|
c2af7494ec | ||
|
|
b7d2748b00 | ||
|
|
3467c0d92b | ||
|
|
22fede0290 | ||
|
|
d87fe43b0f | ||
|
|
7a0ffca629 | ||
|
|
5cf6d31794 | ||
|
|
0d5fe48a3a | ||
|
|
19eed521ae | ||
|
|
e05a23bcc2 | ||
|
|
d957ab2339 | ||
|
|
1fcd7245ea | ||
|
|
176b7f0eab | ||
|
|
f7ed3bafdf | ||
|
|
9f76e61e23 | ||
|
|
7c297895e5 | ||
|
|
0f318b4050 | ||
|
|
1a46f63160 | ||
|
|
6cc90bf973 | ||
|
|
b7271777e0 | ||
|
|
c302c162a0 | ||
|
|
432be04a96 | ||
|
|
6c95d14fb3 | ||
|
|
3263580e89 | ||
|
|
f3da916905 | ||
|
|
fe8d404a44 | ||
|
|
0f9d213b1d | ||
|
|
f952318b34 | ||
|
|
43a2eced75 | ||
|
|
e894457275 | ||
|
|
4b1b64fe2b | ||
|
|
f8beb195dd | ||
|
|
a97996cb59 | ||
|
|
f870ca9b49 | ||
|
|
2e5ff281a8 | ||
|
|
de8decf113 | ||
|
|
dd57fb9ed2 | ||
|
|
9a640632aa | ||
|
|
e61641d7ec | ||
|
|
7ca8ba8b2a | ||
|
|
8805d5799a | ||
|
|
013c4a8156 | ||
|
|
20b5ebeefd | ||
|
|
daa20aed20 | ||
|
|
3564d4d164 | ||
|
|
206763e966 | ||
|
|
4e4da595a6 | ||
|
|
a21a0c9655 | ||
|
|
fc7282581f | ||
|
|
e007054f47 | ||
|
|
a84da8678e | ||
|
|
123a8cb5f4 | ||
|
|
5fe22ac52c | ||
|
|
11d21444cf | ||
|
|
f2b0415580 | ||
|
|
c9d0b476cd | ||
|
|
bf5ac566b6 | ||
|
|
af8f24aa95 | ||
|
|
d98f486c9d | ||
|
|
94ea4c917a | ||
|
|
941bf0fd1b | ||
|
|
59742dde78 |
@@ -24,7 +24,7 @@ jobs:
|
||||
- name: Setup Bun
|
||||
uses: oven-sh/setup-bun@v2
|
||||
with:
|
||||
bun-version: 1.4.2
|
||||
bun-version: 1.4.4
|
||||
|
||||
- name: Install dependencies
|
||||
run: bun install
|
||||
@@ -53,9 +53,6 @@ jobs:
|
||||
echo "Smoke testing shumai..."
|
||||
bun run /tmp/shumai-local-release/node/node_modules/@shumai-one/shumai/bin/shumai-app.js --check
|
||||
|
||||
echo "Smoke testing shumai-agent..."
|
||||
bun run /tmp/shumai-local-release/node/node_modules/@shumai-one/shumai-agent/bin/shumai-agent-app.js --check
|
||||
|
||||
echo "Smoke testing shumai-transcode..."
|
||||
bun run /tmp/shumai-local-release/node/node_modules/@shumai-one/shumai-transcode/bin/shumai-transcode-app.js --check
|
||||
|
||||
@@ -81,7 +78,7 @@ jobs:
|
||||
- name: Setup Bun
|
||||
uses: oven-sh/setup-bun@v2
|
||||
with:
|
||||
bun-version: 1.4.2
|
||||
bun-version: 1.4.4
|
||||
|
||||
- name: Install dependencies
|
||||
run: bun install
|
||||
@@ -126,7 +123,7 @@ jobs:
|
||||
- name: Setup Bun
|
||||
uses: oven-sh/setup-bun@v2
|
||||
with:
|
||||
bun-version: 1.4.2
|
||||
bun-version: 1.4.4
|
||||
|
||||
- name: Install dependencies
|
||||
run: bun install
|
||||
@@ -163,7 +160,7 @@ jobs:
|
||||
- name: Setup Bun
|
||||
uses: oven-sh/setup-bun@v2
|
||||
with:
|
||||
bun-version: 1.4.2
|
||||
bun-version: 1.4.4
|
||||
|
||||
- name: Install dependencies
|
||||
run: bun install
|
||||
|
||||
@@ -0,0 +1,49 @@
|
||||
name: Native CLI
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
branches: [main]
|
||||
push:
|
||||
branches: [main]
|
||||
workflow_call:
|
||||
inputs:
|
||||
source_ref:
|
||||
required: true
|
||||
type: string
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
native:
|
||||
name: CLI (${{ matrix.target }})
|
||||
runs-on: ${{ matrix.runner }}
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
include:
|
||||
- { target: linux-x64, runner: ubuntu-22.04 }
|
||||
- { target: linux-arm64, runner: ubuntu-22.04-arm }
|
||||
- { target: darwin-x64, runner: macos-15-intel }
|
||||
- { target: darwin-arm64, runner: macos-15 }
|
||||
- { target: windows-x64, runner: windows-2022 }
|
||||
- { target: windows-arm64, runner: windows-11-arm }
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
ref: ${{ inputs.source_ref || github.ref }}
|
||||
- uses: oven-sh/setup-bun@v2
|
||||
with:
|
||||
bun-version: 1.4.4
|
||||
- name: Install dependencies
|
||||
run: bun install --frozen-lockfile --ignore-scripts
|
||||
- name: Build CLI archive and installer
|
||||
run: bun run build:cli --target ${{ matrix.target }}
|
||||
- name: Test installed binary and file transfers
|
||||
run: bun run test:cli-release
|
||||
- uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: cli-${{ matrix.target }}
|
||||
path: out/cli-release/shumai-cli-v*
|
||||
if-no-files-found: error
|
||||
retention-days: 7
|
||||
@@ -14,13 +14,30 @@ on:
|
||||
description: 'Source ref to build/publish (defaults to tag)'
|
||||
required: false
|
||||
type: string
|
||||
validate_only:
|
||||
description: 'Build and test without publishing npm packages or a GitHub Release'
|
||||
required: false
|
||||
default: false
|
||||
type: boolean
|
||||
|
||||
permissions: {}
|
||||
|
||||
concurrency:
|
||||
group: npm-release-${{ github.event.inputs.tag || github.ref_name }}
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
cli:
|
||||
uses: ./.github/workflows/cli-native.yaml
|
||||
permissions:
|
||||
contents: read
|
||||
with:
|
||||
source_ref: ${{ inputs.source_ref || inputs.tag || github.ref_name }}
|
||||
|
||||
release:
|
||||
name: Build, Release and Publish
|
||||
runs-on: ubuntu-latest
|
||||
needs: cli
|
||||
permissions:
|
||||
contents: write
|
||||
id-token: write
|
||||
@@ -32,11 +49,12 @@ jobs:
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
ref: ${{ env.SOURCE_REF }}
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Setup Bun
|
||||
uses: oven-sh/setup-bun@v2
|
||||
with:
|
||||
bun-version: 1.4.2
|
||||
bun-version: 1.4.4
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v6
|
||||
@@ -53,12 +71,18 @@ jobs:
|
||||
- name: Install dependencies
|
||||
run: bun install
|
||||
|
||||
- name: Validate release source and version
|
||||
run: bun scripts/publish-cli-release.ts ${{ inputs.validate_only && 'validate-only' || 'validate' }}
|
||||
|
||||
- name: Compile i18n
|
||||
run: bun run i18n:compile
|
||||
|
||||
- name: Lint
|
||||
run: bun run lint
|
||||
|
||||
- name: Format
|
||||
run: bun run format && git diff --exit-code
|
||||
|
||||
- name: Typecheck
|
||||
run: bun run typecheck
|
||||
|
||||
@@ -68,7 +92,18 @@ jobs:
|
||||
- name: Build NPM packages
|
||||
run: bun run build-npm
|
||||
|
||||
- name: Download tested CLI archives
|
||||
uses: actions/download-artifact@v4
|
||||
with:
|
||||
pattern: cli-*
|
||||
path: out/cli-release
|
||||
merge-multiple: true
|
||||
|
||||
- name: Assemble CLI release assets
|
||||
run: bun run build:cli --assemble
|
||||
|
||||
- name: Generate release notes
|
||||
if: ${{ !inputs.validate_only }}
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
run: |
|
||||
@@ -87,29 +122,24 @@ jobs:
|
||||
fi
|
||||
} > /tmp/release-notes.md
|
||||
|
||||
- name: Create GitHub Release
|
||||
- name: Stage draft GitHub Release and CLI assets
|
||||
if: ${{ !inputs.validate_only }}
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
run: |
|
||||
if [ ! -s /tmp/release-notes.md ]; then
|
||||
NOTES_FLAG="--generate-notes"
|
||||
else
|
||||
NOTES_FLAG="--notes-file /tmp/release-notes.md"
|
||||
fi
|
||||
if gh release view "${{ env.RELEASE_TAG }}" >/dev/null 2>&1; then
|
||||
gh release edit "${{ env.RELEASE_TAG }}" \
|
||||
--title "${{ env.RELEASE_TAG }}" \
|
||||
$NOTES_FLAG
|
||||
else
|
||||
gh release create "${{ env.RELEASE_TAG }}" \
|
||||
--title "${{ env.RELEASE_TAG }}" \
|
||||
$NOTES_FLAG
|
||||
fi
|
||||
run: bun scripts/publish-cli-release.ts stage
|
||||
|
||||
- name: Upgrade npm for trusted publishing
|
||||
if: ${{ !inputs.validate_only }}
|
||||
run: |
|
||||
npm install -g npm@11.16.0 --ignore-scripts
|
||||
npm --version
|
||||
|
||||
- name: Publish to NPM
|
||||
if: ${{ !inputs.validate_only }}
|
||||
run: bun run scripts/publish.ts
|
||||
|
||||
- name: Publish completed GitHub Release
|
||||
if: ${{ !inputs.validate_only }}
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
run: bun scripts/publish-cli-release.ts publish
|
||||
|
||||
@@ -4,6 +4,16 @@ on:
|
||||
push:
|
||||
branches: ['main']
|
||||
tags: ['v*']
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
tag:
|
||||
description: 'Docker image tag (e.g. feature-vaapi)'
|
||||
required: false
|
||||
type: string
|
||||
pr:
|
||||
description: 'Pull request number (e.g. 449)'
|
||||
required: false
|
||||
type: string
|
||||
|
||||
jobs:
|
||||
build-and-push:
|
||||
@@ -14,7 +24,10 @@ jobs:
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
id: checkout
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
ref: ${{ inputs.pr && format('refs/pull/{0}/head', inputs.pr) || github.ref }}
|
||||
|
||||
# Set up Docker Buildx
|
||||
- name: Set up Docker Buildx
|
||||
@@ -45,7 +58,11 @@ jobs:
|
||||
crpi-000nkafzu6xvpwsc.cn-hongkong.personal.cr.aliyuncs.com/shumai-one/shumai
|
||||
tags: |
|
||||
type=semver,pattern={{version}}
|
||||
type=ref,event=branch
|
||||
type=ref,event=branch,enable=${{ github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && !inputs.pr && !inputs.tag) }}
|
||||
type=raw,value=pr-${{ inputs.pr }},enable=${{ github.event_name == 'workflow_dispatch' && inputs.pr != '' && inputs.tag == '' }}
|
||||
type=raw,value=${{ inputs.tag }},enable=${{ github.event_name == 'workflow_dispatch' && inputs.tag != '' }}
|
||||
labels: |
|
||||
org.opencontainers.image.revision=${{ steps.checkout.outputs.commit }}
|
||||
|
||||
# Build and push Docker image
|
||||
- name: Build and push Docker image
|
||||
@@ -57,3 +74,31 @@ jobs:
|
||||
provenance: false
|
||||
tags: ${{ steps.meta.outputs.tags }}
|
||||
labels: ${{ steps.meta.outputs.labels }}
|
||||
|
||||
# Extract metadata for Docker (Transcode Worker)
|
||||
- name: Extract metadata for Docker (Transcode Worker)
|
||||
id: meta-transcode
|
||||
uses: docker/metadata-action@v5
|
||||
with:
|
||||
images: |
|
||||
shumaione/shumai-transcode
|
||||
crpi-000nkafzu6xvpwsc.cn-hongkong.personal.cr.aliyuncs.com/shumai-one/shumai-transcode
|
||||
tags: |
|
||||
type=semver,pattern={{version}}
|
||||
type=ref,event=branch,enable=${{ github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && !inputs.pr && !inputs.tag) }}
|
||||
type=raw,value=pr-${{ inputs.pr }},enable=${{ github.event_name == 'workflow_dispatch' && inputs.pr != '' && inputs.tag == '' }}
|
||||
type=raw,value=${{ inputs.tag }},enable=${{ github.event_name == 'workflow_dispatch' && inputs.tag != '' }}
|
||||
labels: |
|
||||
org.opencontainers.image.revision=${{ steps.checkout.outputs.commit }}
|
||||
|
||||
# Build and push Docker image (Transcode Worker)
|
||||
- name: Build and push Docker image (Transcode Worker)
|
||||
uses: docker/build-push-action@v7
|
||||
with:
|
||||
platforms: linux/amd64,linux/arm64
|
||||
context: .
|
||||
file: ./Dockerfile.transcode
|
||||
push: true
|
||||
provenance: false
|
||||
tags: ${{ steps.meta-transcode.outputs.tags }}
|
||||
labels: ${{ steps.meta-transcode.outputs.labels }}
|
||||
|
||||
@@ -25,3 +25,5 @@ code_quality.md
|
||||
# Paraglide JS
|
||||
packages/webui/paraglide
|
||||
|
||||
runner-package.json
|
||||
|
||||
|
||||
@@ -9,3 +9,6 @@ packages/webui/paraglide
|
||||
*.md
|
||||
**/*.md
|
||||
docs/changelog.mdx
|
||||
packages/webui/public
|
||||
**/*.min.*
|
||||
|
||||
|
||||
@@ -10,14 +10,11 @@ Before starting any task, create and switch to a new feature branch:
|
||||
git checkout -b <branch-name>
|
||||
```
|
||||
|
||||
Complete the task on that branch.
|
||||
|
||||
After finishing the work and verifying that all checks pass:
|
||||
|
||||
1. Update `CHANGELOG.md` under `## [Unreleased]` for user-facing changes (see [Changelog Guidelines](#changelog-guidelines)).
|
||||
2. Stage and commit your changes.
|
||||
3. Push the branch to `origin`.
|
||||
4. Open a pull request using the GitHub CLI.
|
||||
2. Stage and commit your changes following [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) (`<type>[optional scope]: <description>` in imperative mood, e.g., `feat(auth): add OAuth login support`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`, and `!` or `BREAKING CHANGE:` for breaking changes).
|
||||
3. Push the branch to `origin` and open a pull request using the GitHub CLI:
|
||||
|
||||
```bash
|
||||
git add .
|
||||
@@ -26,55 +23,15 @@ git push origin <branch-name>
|
||||
gh pr create --title "<pull-request-title>" --body "<pull-request-body>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Commit Messages
|
||||
|
||||
We follow the Conventional Commits specification.
|
||||
|
||||
Commit messages MUST be formatted as:
|
||||
|
||||
```text
|
||||
<type>[optional scope]: <description>
|
||||
|
||||
[optional body]
|
||||
|
||||
[optional footer(s)]
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
feat(auth): add OAuth login support
|
||||
```
|
||||
|
||||
The commit contains the following structural elements, to communicate intent to the consumers of your library:
|
||||
|
||||
1. `fix:` a commit of the type `fix` patches a bug in your codebase.
|
||||
2. `feat:` a commit of the type `feat` introduces a new feature to the codebase.
|
||||
3. `BREAKING CHANGE:` a footer or `!` after the type/scope introduces a breaking API change.
|
||||
4. Additional types are allowed (for example: `docs:`, `refactor:`, `test:`, `chore:`).
|
||||
|
||||
Write commit messages in the imperative mood and keep descriptions concise and specific.
|
||||
|
||||
Reference:
|
||||
https://www.conventionalcommits.org/en/v1.0.0/#summary
|
||||
|
||||
---
|
||||
|
||||
## Changelog Guidelines
|
||||
|
||||
We maintain `CHANGELOG.md` following [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
||||
We maintain `CHANGELOG.md` following [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Before opening a pull request, add an entry under `## [Unreleased]` for any user-facing changes:
|
||||
|
||||
Before opening a pull request, add an entry under `## [Unreleased]` for any user-facing changes:
|
||||
|
||||
- **End-User Friendly**: Make entries easy to understand for end users. For new features, explain what they actually do in plain language without heavy technical jargon. For bug fixes, describe what the bug was in a friendly, relatable way rather than focusing on internal code mechanics, file paths, or private symbols.
|
||||
- **End-User Friendly**: Write in plain language for end users without heavy technical jargon, internal file paths, or private symbols.
|
||||
- **Formatting**: `- **<scope>**: <Description>` (e.g. `- **asset**: Fix an issue where moving a video to trash while it was still transcoding could cause it to lose its trashed status`).
|
||||
- **No PR Numbers**: Do not include PR numbers or links; the release pipeline automatically appends the detailed PR list.
|
||||
- **No PR Numbers**: Do not include PR numbers or links; the release pipeline appends them automatically.
|
||||
- **Internal Changes**: Routine refactors, test additions, or internal chores without external behavior changes may omit changelog updates.
|
||||
|
||||
---
|
||||
|
||||
## Pull Request Template
|
||||
|
||||
```md
|
||||
@@ -92,6 +49,13 @@ Briefly describe what this PR changes and why.
|
||||
- Describe the checks or tests you ran.
|
||||
- Include relevant outputs if applicable.
|
||||
|
||||
## Manual Verification Plan
|
||||
|
||||
- Provide concise instructions for manually verifying this change.
|
||||
- Assume familiarity with the project and existing development workflow.
|
||||
- Skip boilerplate steps (e.g. starting the app, logging in, opening common pages) unless they are part of the change.
|
||||
- Focus on what needs to be verified, including scenarios, edge cases, and expected results.
|
||||
|
||||
## Notes
|
||||
|
||||
Add any additional context, caveats, or follow-up work.
|
||||
@@ -99,7 +63,7 @@ Add any additional context, caveats, or follow-up work.
|
||||
|
||||
## Submission Rules
|
||||
|
||||
- **Strict Requirement**: A submission is considered complete **only** when there is a single final code state in which **all** of the following pass **simultaneously**:
|
||||
- **Strict Requirement**: A submission is complete **only** when there is a single final code state in which **all** of the following pass **simultaneously** (do not submit intermediate states where some checks fail):
|
||||
- `bun run lint`
|
||||
- `bun run format`
|
||||
- `bun run typecheck`
|
||||
@@ -107,392 +71,91 @@ Add any additional context, caveats, or follow-up work.
|
||||
- `bun run test:e2e:app`
|
||||
- `bun run test:e2e:webui`
|
||||
- `bun run test:e2e:workflow`
|
||||
|
||||
- **Backend Testing Mandate**: Every backend feature, service method, workflow, and activity MUST be accompanied by comprehensive tests. Logic-heavy code without corresponding test coverage is considered incomplete.
|
||||
|
||||
- Fixes must be iterated until **no check causes any other check to fail**.
|
||||
|
||||
- **Type Safety**: The use of explicit `any` is strictly forbidden and will result in lint errors. You should use `unknown` instead when the type is not known. If you absolutely must use `any` due to a limitation (e.g. interacting with an untyped 3rd party library), you must add an eslint-disable comment (e.g., `// eslint-disable-next-line @typescript-eslint/no-explicit-any`) and include a comment directly above it clearly explaining _why_ we cannot be type-safe here.
|
||||
- Do **not** submit intermediate states where some checks pass and others fail, even temporarily.
|
||||
|
||||
- **Cleanup Requirement**: Remove all verification related files (scripts, screenshots, `verification/` folder) before submit.
|
||||
|
||||
## Backend Architecture
|
||||
|
||||
The backend is built with:
|
||||
|
||||
- **Runtime**: Bun
|
||||
- **Framework**: Hono
|
||||
- **ORM**: Prisma (with Pgvector18)
|
||||
- **Database**: Pgvector18
|
||||
- **Backend Testing Mandate**: Every backend feature, service method, workflow, and activity MUST have comprehensive tests.
|
||||
- **Type Safety**: Explicit `any` is strictly forbidden. Use `unknown` when the type is unknown. If `any` is unavoidable (e.g., untyped 3rd-party library), add `// eslint-disable-next-line @typescript-eslint/no-explicit-any` with a comment directly above explaining why.
|
||||
- **Cleanup Requirement**: Remove all temporary verification files, scripts, screenshots, and the `verification/` folder before submitting.
|
||||
|
||||
## Workspace Architecture
|
||||
|
||||
The project is a monorepo managed by **Bun Workspaces**. It follows a strictly decoupled architecture where each domain or layer is its own package:
|
||||
**Single-team design**: Each instance has one team, automatically created when the first user signs up.
|
||||
|
||||
- **WebUI (`packages/webui`)**: React-based frontend.
|
||||
- **API (`packages/api`)**: Hono-based HTTP entry point. Handles requests and calls Core services.
|
||||
- **Core (`packages/core`)**: Business logic, services, and infrastructure utilities.
|
||||
- **Database (`packages/db`)**: Prisma client, schema, and migrations.
|
||||
- **DTOs (`packages/dtos`)**: Shared type definitions and Zod schemas used by both API and WebUI.
|
||||
- **Workers**: Specialized packages for background task execution:
|
||||
- `@shumai/workflow-core`: Common workflow engine logic.
|
||||
- `@shumai/agent`: AI agent workflows and activities.
|
||||
- `@shumai/transcode`: Media processing workflows and activities.
|
||||
The project is a Bun Workspaces monorepo (Bun runtime, Hono API, Prisma + Pgvector18 DB, React + Tailwind CSS + Shadcn UI frontend):
|
||||
|
||||
### Layered Communication Rules
|
||||
- **`packages/webui`**: React frontend (`bun run dev` runs on port 3000).
|
||||
- **`packages/api`**: Hono HTTP entry point and MCP server.
|
||||
- **`packages/core`**: Business logic, services, operations, and asset readers.
|
||||
- **`packages/db`**: Prisma client, schema, and migrations.
|
||||
- **`packages/dtos`**: Shared Zod schemas and TypeScript types (do not append `Dto` suffix to type names).
|
||||
- **`packages/operations`**: Shared Operation definitions (`@shumai/operations`) used by agent tools, MCP, and `apps/cli`.
|
||||
- **Workers**: `@shumai/workflow-core` (DBOS engine), `@shumai/agent` (AI agent workflows/activities), and `@shumai/transcode` (media workflows/activities).
|
||||
|
||||
1. **API Layer** calls **Core Layer**. Do not access the database directly in the API layer.
|
||||
2. **Core Layer** calls **Database Layer** and other Core services.
|
||||
3. **DTO Layer** is imported by all layers to ensure end-to-end type safety.
|
||||
4. **No Direct DB Leak**: Do not return Prisma objects directly from the API; always map them to DTOs.
|
||||
### Layered Communication & Code Patterns
|
||||
|
||||
## Dependency Management
|
||||
1. **API → Core → DB**: API routes (`packages/api/src/`) call Core services (`packages/core/src/`), which call `@shumai/db`. Never access `prisma` directly in the API layer, and never return raw Prisma objects from API routes (always map to DTOs).
|
||||
2. **Services**: Define service logic as instance methods on a class and export a singleton instance (check existing services in `packages/core/src/`).
|
||||
3. **Hono Routes**: Always chain `.get()` / `.post()` on a Hono instance using `zValidator` and export the chained route as default to preserve Hono RPC type inference (check `packages/api/src/`).
|
||||
4. **Operations First**: If an Operation exists for an action, API routes must call it via `runOperation` instead of re-implementing permission checks and audit logging. UI-only routes keep calling services directly.
|
||||
5. **Dependencies & Imports**:
|
||||
- Declare runtime `dependencies` in each package's local `package.json` (`workspace:*` for internal packages). Keep root `package.json` strictly for shared `devDependencies` and scripts.
|
||||
- Never edit `package.json` manually to add dependencies; run `bun add <package> --filter <workspace>` from the root without an explicit version.
|
||||
- Use absolute workspace imports across packages (e.g., `@shumai/db`, `@shumai/core/src/...`). When adding a new package, add its path mappings to the root `tsconfig.json`.
|
||||
|
||||
We follow Bun's monorepo conventions for dependency management:
|
||||
## Operations & Asset Readers
|
||||
|
||||
1. **Self-Contained Packages**: Every workspace package MUST declare its own runtime `dependencies` in its local `package.json`. Do not rely on dependencies being available via the root.
|
||||
2. **Shared DevDependencies**: Common development tools (e.g., `typescript`, `eslint`, `vitest`, `prettier`, `prisma`) MUST be declared in the root `package.json` to ensure version consistency across the workspace.
|
||||
3. **Local DevDependencies**: Tools specific to a single package (e.g., `@vitejs/plugin-react` for `webui`) should be declared in that package's local `package.json`.
|
||||
4. **Workspace Imports**: Use `workspace:*` for internal package dependencies.
|
||||
5. **Clean Root**: The root `package.json` must not contain runtime `dependencies`. It is reserved for shared `devDependencies` and workspace-wide `scripts`.
|
||||
6. **Adding Packages**: Never edit `package.json` manually to add new dependencies. Always use `bun add` (e.g., `bun add <package> --filter <workspace>`) from the root without specifying an explicit version, letting Bun resolve the correct version.
|
||||
### Operations
|
||||
|
||||
## TypeScript Configuration
|
||||
An **Operation** is defined once and exposed across built-in agent tools, the MCP server, and `shumai-cli`. Check existing definitions in `packages/operations/src/` and implementations in `packages/core/src/operations/`.
|
||||
|
||||
We use a root-level `tsconfig.json` to manage path mappings for the entire workspace. This ensures that imports across packages resolve correctly during typechecking and in the IDE.
|
||||
- **Definition (`packages/operations/src/**`)**: Keep free of server dependencies (no `@shumai/core` or `@shumai/db`). Every Zod input/output field must have `.describe()`. Object input fields must be listed in `cli.flatten` or `cli.omit`.
|
||||
- **Implementation (`packages/core/src/operations/**`)**: Use `implementOperation(definition, { authz, prepare?, execute, audit? })`.
|
||||
- `authz` returns all required permissions (checked before any side effect).
|
||||
- `execute` calls Core services only (**importing `prisma` in Operations is forbidden by lint**).
|
||||
- `audit` resolves team/project from the affected asset, never trusting caller input.
|
||||
- Outputs must be DTOs matching the output schema.
|
||||
- **Register & Run**: Register in both `packages/operations/src/registry.ts` and `packages/core/src/operations/registry.ts`. Execute only via `runOperation(op, { userId, via, agentId? }, input)`.
|
||||
- **Surface Extensions**: For surface-specific parameters or rendering, check `packages/agent/src/operation-extensions/`, `packages/api/src/mcp-extensions/`, and `apps/cli/src/operations/extensions/`.
|
||||
|
||||
1. **Path Mappings**: All workspace packages MUST have an entry in the `paths` object in the root `tsconfig.json`.
|
||||
```json
|
||||
"paths": {
|
||||
"@shumai/core": ["packages/core/src/index.ts"],
|
||||
"@shumai/core/src/*": ["packages/core/src/*"]
|
||||
}
|
||||
```
|
||||
2. **Package tsconfig**: Each package should have its own `tsconfig.json` that extends the root configuration and defines its specific `include`/`exclude` rules.
|
||||
3. **Cross-Package Resolution**: When adding a new package, you MUST update the root `tsconfig.json` path mappings to ensure it can be imported by other packages.
|
||||
### Asset Readers
|
||||
|
||||
### Service Layer Patterns
|
||||
`read_asset` is backed by readers in `packages/core/src/asset-read/readers/` registered in `packages/core/src/asset-read/registry.ts` (order matters: first matching reader wins). To add or modify a reader, check existing readers in `packages/core/src/asset-read/readers/` and option schemas in `packages/operations/src/asset/read-asset.ts`. Use `badRequest(...)` for invalid input and return storage keys in `ReadResult`.
|
||||
|
||||
- **Instance Methods**: Define service logic as instance methods on a class, not static methods.
|
||||
- **Singleton Export**: Export a singleton instance of the service class.
|
||||
```typescript
|
||||
export class MyService {
|
||||
async doSomething() { ... }
|
||||
}
|
||||
export const myService = new MyService()
|
||||
```
|
||||
- **Usage**: Import and use the exported instance.
|
||||
```typescript
|
||||
import { myService } from '@shumai/core/src/services/myService'
|
||||
await myService.doSomething()
|
||||
```
|
||||
## Frontend Rules (`packages/webui`)
|
||||
|
||||
### Hono API Definitions
|
||||
- **System Colors**: Prefer semantic design tokens (`bg-background`, `text-foreground`, `text-muted-foreground`, etc.) over hardcoded Tailwind colors for light/dark theme support.
|
||||
- **Route Code-Splitting**: Split all routes into `[route].tsx` (route definition and loaders) and `[route].lazy.tsx` (UI component and heavy imports).
|
||||
- **Radix / Shadcn UI**: Set `modal={false}` on `<DropdownMenu>` when triggering a `Dialog` or `AlertDialog` from inside it to prevent focus-trap UI freezes. Use `ScrollArea` (`@/ui/components/ui/scroll-area`) for scrollable containers.
|
||||
- **Pagination & Infinite Scroll**: Use `useInfiniteQuery` + `react-intersection-observer` with default `limit: 20` and the API's `total` field. Backend list APIs use `paginateQuery` from `packages/core/src/pagination.ts` (default `limit: 20`).
|
||||
- **Internationalization (i18n)**: Hardcoded UI text is strictly forbidden. Add `snake_case` keys to both `packages/webui/messages/en.json` and `packages/webui/messages/zh.json`, run `bun run i18n:compile` (or `bun run i18n:watch`), and import `m` from `@/ui/paraglide/messages.js`.
|
||||
|
||||
- **Route Chaining**: Always define API routes using method chaining on a Hono instance. This ensures that the type definitions for inputs and outputs are correctly inferred and preserved in the exported type.
|
||||
- **Export Pattern**: Export the chained route instance as the default export.
|
||||
```typescript
|
||||
const app = new Hono()
|
||||
const route = app
|
||||
.get('/', ...)
|
||||
.post('/', ...)
|
||||
export default route
|
||||
```
|
||||
- **Type Safety**: Use `zValidator` for request validation (query, json, form) to ensure full end-to-end type safety with the Hono RPC client.
|
||||
## Database & Prisma (`packages/db`)
|
||||
|
||||
## Frontend Architecture
|
||||
- **Schema & Config**: Schema at `packages/db/prisma/schema.prisma`, config at `prisma.config.ts`, generated client at `packages/db/src/generated/prisma`.
|
||||
- **ULIDs & Sorting**: All models (except key-value stores like `Setting`) must use `@default(ulid())`. Do not manually generate DB IDs in application code. Order all list queries by `orderBy: { id: 'desc' }` (do not sort by unindexed `createdAt`).
|
||||
- **Strict JSON Typing**: Annotate `Json` columns with `/// [TypeName]` in `schema.prisma` and define the type under the global `PrismaJson` namespace in `packages/db/src/prisma-json-types.ts`. Use type guards/narrowing instead of `as any`.
|
||||
- **Migrations**:
|
||||
- Commands: `bun --bun run prisma migrate dev`, `bun --bun run prisma migrate deploy`, `bun --bun run prisma generate`.
|
||||
- Never hand-write DDL migration files; always generate them via `prisma migrate dev` (use `--create-only` for custom data migration SQL).
|
||||
- **Never run `prisma migrate reset --force`** automatically. If migrations are out of sync or require a reset, stop and ask the user.
|
||||
|
||||
The frontend is built with:
|
||||
## DBOS Workflows & Activities
|
||||
|
||||
- **Runtime**: Bun (Bundler & Runner)
|
||||
- **Framework**: React
|
||||
- **Styling**: Tailwind CSS + Shadcn UI (Components)
|
||||
Check existing workflows and activities in `packages/agent/src/{workflows,activities}`, `packages/transcode/src/{workflows,activities}`, and `packages/workflow-core/src/`.
|
||||
|
||||
### UI Rules
|
||||
|
||||
- **Prefer System Colors**: Always prefer using semantic system color design tokens (e.g., `bg-background`, `text-foreground`, `text-sidebar-primary`, `text-muted-foreground`, etc.) over hardcoded color utilities (e.g., `bg-blue-50`, `text-emerald-600`, `bg-emerald-500`). This ensures seamless compatibility with light and dark themes.
|
||||
|
||||
### Route Code-Splitting
|
||||
|
||||
To optimize initial bundle size, all routes must be code-split into `[route].tsx` (lightweight route definition and loaders) and `[route].lazy.tsx` (UI component and heavy imports).
|
||||
|
||||
### Development
|
||||
|
||||
- **Run Dev**: `bun run dev` (Runs on port 3000)
|
||||
|
||||
|
||||
## Testing
|
||||
|
||||
We use **Vitest** for testing (via `bun run test`). **Do not use `bun test`** as it uses Bun's native test runner which is not compatible with this project's test suite.
|
||||
|
||||
### Bug Fixes
|
||||
|
||||
- **Mandatory Reproduction**: When fixing a backend bug, you MUST first write a test case that reproduces the bug (demonstrates the failure) before applying the fix. This ensures the bug is truly understood and prevents future regressions.
|
||||
|
||||
### Test Maintenance Rule
|
||||
|
||||
- **Do not delete tests** unless the feature or code being tested is permanently removed from the codebase.
|
||||
- When refactoring code, you must also refactor the corresponding tests to ensure they pass with the new implementation.
|
||||
- This ensures we maintain regression coverage and do not silently break features.
|
||||
|
||||
### Service Tests
|
||||
|
||||
- Located in `packages/core/src/**/*.test.ts`.
|
||||
- For comprehensive testing against a real database instance, we use `Testcontainers` alongside a `PrismaTestingHelper` which wraps each test within an automatic PostgreSQL transaction rollback boundary.
|
||||
- All service tests must use `setupTestDbHooks()` from `@shumai/db` to initialize the database boundaries for each test suite inside the `describe` block. This automatically registers `beforeEach` and `afterEach` hooks to manage transaction state.
|
||||
- Import `prisma` from `@shumai/db` directly to interact with the database in tests. The testing helper automatically proxies it.
|
||||
|
||||
```typescript
|
||||
import { describe, it, expect } from 'vitest'
|
||||
import { prisma, setupTestDbHooks } from '@shumai/db'
|
||||
import { teamService } from '@shumai/core/src/team/team'
|
||||
|
||||
describe('TeamService', () => {
|
||||
setupTestDbHooks()
|
||||
|
||||
it('works with db', async () => {
|
||||
const user = await prisma.user.create({
|
||||
data: { name: 'Test User', password: 'pw' },
|
||||
})
|
||||
const team = await teamService.ensureDefaultTeam()
|
||||
expect(team).toBeDefined()
|
||||
expect(team.name).toBe('Default Team')
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
The `bunfig.toml` is configured to run `setup-tests.ts` automatically as a preload step. This initializes the `Testcontainers` PostgreSQL instance and applies migrations before the tests begin running.
|
||||
|
||||
### API Tests
|
||||
|
||||
- Located in `packages/api/src/**/*.test.ts`.
|
||||
- Mock the Service layer using `vi.spyOn(service, 'method')` or `vi.mock('@shumai/core/src/team/team')`.
|
||||
- Verify that the API calls the Service methods correctly.
|
||||
|
||||
```typescript
|
||||
import { describe, it, expect, vi } from 'vitest'
|
||||
import { teamService } from '@shumai/core/src/team/team'
|
||||
import app from './team'
|
||||
|
||||
describe('Team API', () => {
|
||||
it('calls service', async () => {
|
||||
const mockEnsureDefaultTeam = vi
|
||||
.spyOn(teamService, 'ensureDefaultTeam')
|
||||
.mockResolvedValue({ id: '1', name: 'Default Team' } as any)
|
||||
|
||||
// ... test logic ...
|
||||
|
||||
expect(mockEnsureDefaultTeam).toHaveBeenCalled()
|
||||
mockEnsureDefaultTeam.mockRestore()
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
### Workflow E2E Tests
|
||||
|
||||
- Located in `packages/e2e/workflow/**/*.test.ts`.
|
||||
- Run via `bun run test:e2e:workflow` (which executes tests against both `local` and `temporal` executors dynamically).
|
||||
- **Mandatory test coverage**: When creating or updating workflows or activities, you MUST create or update the corresponding E2E tests.
|
||||
- **Mocking**: Mock ONLY AI API calls. Do not mock S3, databases, or media/transcode extraction services.
|
||||
- Mock the AI response by spying on `AgentHarness.prototype.prompt`:
|
||||
|
||||
### Web App E2E Tests
|
||||
|
||||
- Located in `apps/web/e2e/**/*.spec.ts`, organized by domain under `tests/<domain>/` (e.g. `auth`, `project`).
|
||||
- Run via `bun run test:e2e:app`.
|
||||
- **Fixtures**: Use the `owner`, `project`, and `file` fixtures for setup — they seed data through API calls/DB (no slow UI setup). You can add more fixtures if necessary.
|
||||
- **Documentation**: Every test case MUST be documented in [`apps/web/e2e/README.md`](apps/web/e2e/README.md). Add or update the corresponding entry in the README whenever you add, rename, or remove a spec.
|
||||
|
||||
## Prisma Configuration & Migrations
|
||||
|
||||
- Schema: `packages/db/prisma/schema.prisma`
|
||||
- Generated Client: `packages/db/src/generated/prisma`
|
||||
- Config: `prisma.config.ts` (Required for Prisma 7+)
|
||||
|
||||
### Strict JSON Typing
|
||||
|
||||
We use `prisma-json-types-generator` to enforce strict type-safety for Prisma `Json` columns, rather than typing them as generic `JsonValue`.
|
||||
|
||||
- **Defining Types**: In `packages/db/prisma/schema.prisma`, annotate the JSON column with a triple-slash comment specifying the type name from `packages/db/src/prisma-json-types.ts`:
|
||||
```prisma
|
||||
model WorkflowTask {
|
||||
/// [WorkflowTaskPayload]
|
||||
payload Json?
|
||||
}
|
||||
```
|
||||
- **Declaring Types**: All typed JSON shapes must be defined in `packages/db/src/prisma-json-types.ts` under the global `PrismaJson` namespace:
|
||||
```typescript
|
||||
declare global {
|
||||
namespace PrismaJson {
|
||||
export type WorkflowTaskPayload = Record<string, unknown> | TaskSpec | AiTaskPayload
|
||||
}
|
||||
}
|
||||
```
|
||||
- **Usage**: When accessing these columns on the Prisma client (e.g. `task.payload`), the field will automatically be typed as the declared shape (e.g., `PrismaJson.WorkflowTaskPayload | null`).
|
||||
- **Accessing Properties**: When working with union types or custom structures in the JSON payload, use proper narrowing or type guards instead of casting to `any`. Direct `as any` casting should be avoided.
|
||||
|
||||
### Migration Workflow
|
||||
|
||||
- Development: Use `bun --bun run prisma migrate dev` to create and apply migrations during development.
|
||||
- Production: Use `bun --bun run prisma migrate deploy` to apply pending migrations in production environments.
|
||||
- **No Manual DDL Creation**: Never hand-write **schema (DDL) migration** files or directories. Always generate them with Prisma CLI (`bun --bun run prisma migrate dev --create-only` to create a template, then edit it if needed, or `bun --bun run prisma migrate dev` to apply) so Prisma correctly tracks migration metadata and checksums.
|
||||
- **Data Migrations Are Allowed**: Pure **data migration** SQL (no schema change) may be written by hand, but it MUST live inside a migration generated via `bun --bun run prisma migrate dev --create-only` so it is tracked and applied automatically.
|
||||
- **No Automatic Dev DB Reset**: Do not run `prisma migrate reset --force` or commands that force-reset the database automatically. If migrations become out of sync or a reset is required, stop executing, report the situation to the user, and present suggested manual cleanup/reset steps for the user to execute.
|
||||
|
||||
### Commands
|
||||
|
||||
- Generate Client: `bun --bun run prisma generate`
|
||||
- Apply Migrations (Dev): `bun --bun run prisma migrate dev`
|
||||
- Deploy Migrations (Prod): `bun --bun run prisma migrate deploy`
|
||||
|
||||
## ID Generation & Sorting
|
||||
|
||||
- **ULID Default**: All models (except key-value stores like `Setting`) must use `@default(ulid())` for the `id` field in `schema.prisma`.
|
||||
|
||||
```prisma
|
||||
model Example {
|
||||
id String @id @default(ulid())
|
||||
}
|
||||
```
|
||||
|
||||
- **No Manual Assignment**: Do not manually generate or assign ULIDs in application code (e.g., `packages/core/src/*.ts`) for creating database records. Let Prisma handle it via the schema default.
|
||||
- Exception: File names generated by `FileService` may still use `ulid()` internally, but this is separate from the database ID.
|
||||
- **Sorting**: All list APIs must order results by `id` descending (`orderBy: { id: 'desc' }`) to ensure consistent, time-based sorting (since ULIDs are sortable). Do not sort by `createdAt` as it is not indexed.
|
||||
|
||||
## Infinite Scroll & Pagination
|
||||
|
||||
- **Frontend**: For paginated APIs (which contain `pageInfo` and `total` fields), the UI MUST use an auto infinite scroll style design using `useInfiniteQuery` from `@tanstack/react-query` and `react-intersection-observer`. Use the `total` count from the API response instead of counting the results locally.
|
||||
- The default `limit` should be **20**.
|
||||
- **Backend**:
|
||||
- Most list APIs support cursor pagination using opaque tokens (via `hyrumtoken` logic) using the `paginateQuery` helper function.
|
||||
- Pass `PaginationParams` containing `first` (limit) and `after` (cursor).
|
||||
- The default `limit` should be **20**.
|
||||
- Always use the `paginateQuery` helper function from `packages/core/src/pagination.ts` for consistent cursor pagination.
|
||||
|
||||
## Temporal Workflow & Activities
|
||||
|
||||
We use a custom workflow engine that supports both **Local** (polling-based) and **Temporal** (production-grade) execution.
|
||||
|
||||
### Architecture
|
||||
|
||||
1. **Workflows**: Orchestrate multiple activities. They must be deterministic and compatible with Temporal's V8 isolate. Defined in worker packages (e.g., `@shumai/agent/src/workflows`, `@shumai/transcode/src/workflows`).
|
||||
2. **Activities**: Perform the actual work (DB updates, API calls, media processing). Grouped by domain in worker packages (e.g., `@shumai/agent/src/activities`, `@shumai/transcode/src/activities`).
|
||||
3. **Executors**:
|
||||
- `LocalExecutor` (in `@shumai/workflow-core`): Polls the database for `pending` tasks and executes them directly.
|
||||
- `TemporalExecutor` (in `@shumai/workflow-core`): Submits tasks to a Temporal cluster.
|
||||
4. **Automatic Submission**: New `WorkflowTask` records are automatically submitted to the `WorkflowService` via a Prisma Client Extension defined in `@shumai/db`.
|
||||
|
||||
### Dynamic Registration
|
||||
|
||||
To avoid circular dependencies, workflows and activities are dynamically registered onto the `LocalExecutor` registry at bootstrap time via initializer functions (e.g., `initAgentWorkflows()`, `initTranscodeWorkflows()`).
|
||||
|
||||
### Non-Retryable Error Handling
|
||||
|
||||
To prevent Temporal from indefinitely retrying fatal, expected business validation failures (e.g., missing records, invalid configurations, missing parameters), **never throw standard `Error` objects from workflow or activity logic.** Instead, throw a non-retryable `ApplicationFailure`.
|
||||
|
||||
**Mandatory Requirement**: You **MUST** set `nonRetryable: true` in the options object passed to `ApplicationFailure.create`. Standard errors or `ApplicationFailure` objects without `nonRetryable: true` will cause Temporal to retry the activity or workflow indefinitely.
|
||||
|
||||
- **Workflow Boundary**: In workflows, import `ApplicationFailure` from `@temporalio/workflow`:
|
||||
```typescript
|
||||
import { ApplicationFailure } from '@temporalio/workflow'
|
||||
throw ApplicationFailure.create({ message: 'agentId missing in payload', nonRetryable: true })
|
||||
```
|
||||
- **Activity Boundary**: In activities, import `ApplicationFailure` from `@temporalio/activity`:
|
||||
```typescript
|
||||
import { ApplicationFailure } from '@temporalio/activity'
|
||||
throw ApplicationFailure.create({
|
||||
message: 'no autofill agent found for team',
|
||||
nonRetryable: true,
|
||||
})
|
||||
```
|
||||
|
||||
### Temporal Workflow Patterns
|
||||
|
||||
- **Definition**: Define workflows as exported async functions.
|
||||
```typescript
|
||||
export async function myWorkflow(task: WorkflowTask): Promise<void> {
|
||||
const { activityA, activityB } = getActivities()
|
||||
await activityA({ ... })
|
||||
await activityB({ ... })
|
||||
}
|
||||
```
|
||||
- **Environment Compatibility**: Always use `getActivities()` from `@shumai/workflow-core` to ensure the code works in both Local and Temporal environments.
|
||||
- **Activity Access**: Activities should be accessed via `getActivities()` within a workflow. Do not call services directly inside a workflow function to maintain Temporal compatibility.
|
||||
- **Queue Redirection**: Production Temporal workers use worker-specific unique queues for data locality (e.g., local disk access) and consistent state.
|
||||
- Every workflow MUST first call `getAgentWorkerQueueActivity` or `getTranscodeWorkerQueueActivity` via the shared domain queue (e.g., `TaskQueueAgent` or `TaskQueueTranscode`) to obtain the specific queue name for that worker instance.
|
||||
- ALL subsequent activities (including shared DB activities like updating task status) MUST be executed on that specific discovered queue.
|
||||
- The shared domain worker ONLY registers the queue discovery activities. All other activities (shared and domain-specific) are registered on the specific worker.
|
||||
|
||||
### Activity Patterns
|
||||
|
||||
- **Implementation**: Activities _can_ and _should_ call other services (e.g., `aiService`, `transcodeService`) or interact with the database directly. Database (Prisma) queries or updates are allowed in all activity types (e.g., agent or transcode) for simplicity.
|
||||
|
||||
## Import conventions
|
||||
|
||||
- When importing across workspace packages, always use absolute workspace imports (e.g. `import { prisma } from '@shumai/db'`, `import { teamService } from '@shumai/core/src/team/team'`).
|
||||
- **DTO Naming**: Do not append the `Dto` suffix to types or interfaces (e.g. use `JoinRequest` instead of `JoinRequestDto`).
|
||||
|
||||
## Radix UI / Shadcn UI Patterns
|
||||
|
||||
- **Modal Overlays**: When triggering a dialog (e.g., `Dialog`, `AlertDialog`) from inside a `DropdownMenu`, you must set `modal={false}` on the `<DropdownMenu>` component. Failing to do so will cause the UI to freeze due to conflicting focus management between the two modal components.
|
||||
- **Scrollable Content**: Always use the Shadcn `ScrollArea` component (`@/ui/components/ui/scroll-area`) for scrollable content containers to ensure consistent custom scrollbar UI across the application.
|
||||
- **Patterns**: Workflows are exported async functions registered at bootstrap (`initAgentWorkflows`, `initTranscodeWorkflows`) and auto-enqueued when `WorkflowTask` records are created. Wrap activity functions with `defineStep` from `@shumai/workflow-core` (activities may call services or query `prisma` directly).
|
||||
- **Non-Retryable Errors**: Never throw standard `Error` objects for fatal validation or business failures in workflows/activities. Always throw `ApplicationFailure.create({ message: '...', nonRetryable: true })` from `@shumai/workflow-core`.
|
||||
- **Durable Step File Exchange**: Save intermediate files passed across steps to S3, fetch them in consuming steps via `ensureLocalMediaFile` (never assume local `/tmp` persists across steps), and clean up temporary S3 files in a `finally` block.
|
||||
|
||||
## Logging
|
||||
|
||||
We use **pino** for logging. Always use **structured logging** to ensure logs are easily searchable and machine-readable.
|
||||
Use structured **pino** logging via `import { logger } from '@shumai/core/src/logger'`. Pass metadata object first and message string second: `logger.info({ userId, projectId }, 'Project deleted')`.
|
||||
|
||||
- **Import**: `import { logger } from '@shumai/core/src/logger'`
|
||||
- **Usage**: Pass an object as the first argument containing the metadata, and a string as the second argument for the descriptive message.
|
||||
```typescript
|
||||
logger.info({ userId: user.id, projectId }, 'Project deleted successfully')
|
||||
```
|
||||
- **Levels**: Use appropriate levels: `debug`, `info`, `warn`, `error`.
|
||||
## Testing
|
||||
|
||||
## Internationalization (i18n)
|
||||
Use **Vitest** via `bun run test` (**never** use `bun test`).
|
||||
|
||||
All user-facing text in the WebUI (`packages/webui`) MUST be internationalized using **Paraglide JS**. Hardcoded text in UI components is strictly forbidden.
|
||||
|
||||
### Message Definition
|
||||
|
||||
1. Define your English message strings in [packages/webui/messages/en.json](packages/webui/messages/en.json).
|
||||
2. Define the corresponding Chinese translation strings in [packages/webui/messages/zh.json](packages/webui/messages/zh.json).
|
||||
3. Keys should use `snake_case`.
|
||||
|
||||
Example (`en.json`):
|
||||
|
||||
```json
|
||||
{
|
||||
"my_key": "My English Text"
|
||||
}
|
||||
```
|
||||
|
||||
### Compilation
|
||||
|
||||
When you add or update translation keys, you must compile them to regenerate the type-safe functions:
|
||||
|
||||
```bash
|
||||
# Compile once (generates type-safe TS/JS functions on disk)
|
||||
bun run i18n:compile
|
||||
|
||||
# Watch and recompile on change during development
|
||||
bun run i18n:watch
|
||||
```
|
||||
|
||||
### Usage in Components
|
||||
|
||||
Import the compiled message namespace `m` and call it as a function:
|
||||
|
||||
```typescript
|
||||
import { m } from '@/ui/paraglide/messages.js'
|
||||
|
||||
export function MyComponent() {
|
||||
return (
|
||||
<div>
|
||||
<h1>{m.my_key()}</h1>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Always use the absolute workspace alias path `@/ui/paraglide/messages.js` (or `runtime.js` for runtime features) when importing Paraglide outputs.
|
||||
- **Bug Fixes**: Always write a test case that reproduces the bug (demonstrates failure) before applying a backend fix.
|
||||
- **Test Maintenance**: Never delete tests unless the tested feature is permanently removed; update existing tests when refactoring.
|
||||
- **Service & Operation Tests (`packages/core/src/**/*.test.ts`)**: Call `setupTestDbHooks()` from `@shumai/db` inside `describe` for per-test PostgreSQL transaction rollback, and use `prisma` from `@shumai/db`. Every Operation requires real-DB tests covering success, permission denial (no side effects), and audit entries.
|
||||
- **API Tests (`packages/api/src/**/*.test.ts`)**: Mock Core services using `vi.spyOn` or `vi.mock`.
|
||||
- **Workflow E2E Tests (`packages/e2e/workflow/**/*.test.ts`)**: Run via `bun run test:e2e:workflow`. Mandatory when adding/updating workflows or activities. Mock **only** AI API calls (spy on `AgentHarness.prototype.prompt`); do not mock S3, DB, or media/transcode services.
|
||||
- **Web App E2E Tests (`apps/web/e2e/**/*.spec.ts`)**: Run via `bun run test:e2e:app`. Use `owner`, `project`, and `file` fixtures for setup, and document every added, renamed, or removed spec in `apps/web/e2e/README.md`.
|
||||
|
||||
+199
@@ -12,6 +12,205 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
||||
|
||||
### Changed
|
||||
|
||||
## [0.7.0] - 2026-11-18
|
||||
|
||||
### Added
|
||||
|
||||
- **i18n**: Add Korean as a display language, selectable on the sign-up page and in team settings.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **cli**: Fix release publication failing to find staged standalone downloads.
|
||||
|
||||
### Changed
|
||||
|
||||
- **agent**: ⚠️ **Breaking Change**: Replaced the built-in server-side Bash sandbox with external Runners and removed the team-level sandbox domain allowlist settings. The Bash tool is now disabled by default. If your Agent or Skills require Bash execution, you'll need to set up and connect an external Runner using shumai-cli. The Shumai CLI includes built-in sandbox support, allowing you to configure filesystem access and network domain allowlists for Bash execution directly on the Runner. See [Agent Runners](https://docs.shumai.one/using-shumai/agent-sandbox) for setup instructions and configuration details. The Docker Compose configuration has also been updated to improve security following the removal of the server-side sandbox. We strongly recommend upgrading to the latest Shumai image and updating your Docker Compose file to apply these security improvements.
|
||||
- **cli**: Show copyable commands and shell configuration instructions when the standalone CLI installation directory is missing from PATH.
|
||||
|
||||
## [0.6.6] - 2026-11-13
|
||||
|
||||
### Added
|
||||
|
||||
- **project**: Support creating new projects via the built-in agent, MCP server, and CLI (`shumai-cli project create`).
|
||||
- **cli**: Add standalone downloads and one-line installers for macOS, Linux, and Windows without requiring Node.js or Bun, with verified downloads, version selection, and upgrade support.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **storage**: Remove empty local folders left behind after generating video search embeddings.
|
||||
|
||||
### Changed
|
||||
|
||||
- **agent**: Upgrade the agent runtime and automatically migrate existing conversations, keep thread histories independent, prevent duplicate history during simultaneous mentions, improve session log scrolling and readability, and fix authentication for OpenAI and custom providers. Agents now run with the main server; standalone agent workers are no longer supported.
|
||||
|
||||
## [0.6.5] - 2026-11-07
|
||||
|
||||
### Added
|
||||
|
||||
### Fixed
|
||||
|
||||
### Changed
|
||||
|
||||
- **file-browser**: ⚠️ **Behavior Change**: Align asset selection and click behavior with Frame.io: single-clicking file or folder cards on public share links always opens or enters the asset even when already selected, clicking an already-selected card in workspace file lists preserves multi-selection, checkboxes independently toggle individual items without clearing other selections, and Shift-click range selection is supported on public share links
|
||||
|
||||
## [0.6.4] - 2026-11-05
|
||||
|
||||
### Added
|
||||
|
||||
- **storage**: Add optional archive storage support (`local` folder/NAS or `s3` with configurable storage class and Glacier restore) allowing editors and owners to archive and restore original files while keeping previews, proxy streams, comments, and metadata available in main storage
|
||||
- **storage**: Add team-level automatic asset archival based on age policies (creation time or last modified time) with configurable post-restore grace periods, an hourly background scanning worker, and a dedicated Storage settings page displaying read-only archive backend status and policy configurations
|
||||
|
||||
### Fixed
|
||||
|
||||
- **security**: ⚠️ Several security improvements and access control hardenings. Upgrading to this release is strongly recommended.
|
||||
- **mcp**: Gracefully disable MCP OAuth 2.1 with an error log when deploying on remote HTTP IP addresses without breaking the main server or API token MCP access
|
||||
- **web**: Add immutable cache headers and conditional 304 Not Modified support for production JavaScript and CSS chunks to prevent unnecessary refetches on page reload
|
||||
|
||||
### Changed
|
||||
|
||||
- **file-browser**: Replace the legacy combined "Copy name and download link" action with a context-aware Copy submenu in file browser context menus and card action dropdowns, enabling users to copy image, asset names, in-app links, download links, IDs, Markdown links and storage paths(team-owner only)
|
||||
|
||||
## [0.6.3] - 2026-11-01
|
||||
|
||||
### Added
|
||||
|
||||
- **upload**: Allow users to cancel running upload tasks directly from the upload tasks sidebar with a confirmation dialog, preserving already completed files while discarding incomplete assets
|
||||
- **upload**: Improve upload resilience during network drops, device sleep, and transient gateway errors by adding state-based exponential backoff retries and extending upload link expiration to 12 hours
|
||||
|
||||
### Fixed
|
||||
|
||||
- **upload**: Display a clear diagnostic error toast when remote file uploads fail due to an unconfigured or localhost S3 storage endpoint
|
||||
|
||||
### Changed
|
||||
|
||||
- **upload**: ⚠️ **Important Behavior Change**: Uploading files now appear in their correct sorted position in the file list, following the current sort setting, instead of being pinned to the top and jumping into place after the upload finishes. Cards no longer move when an upload completes. Note that if you sort by name, an uploading file may land outside your current view. Local uploads also show remaining time and transfer speed (e.g. `8m left (390.88 KB/s)`), and other users viewing the folder see `[User] is uploading...`.
|
||||
- **agent**: ⚠️ **Important Behavior Change**: Autofill and Embedding agents will no longer post completion comments when finishing successfully to prevent clutter in asset comment feeds. Comments are now only posted if a task encounters an error.
|
||||
|
||||
## [0.6.2] - 2026-10-29
|
||||
|
||||
### Added
|
||||
|
||||
* **mcp**: Add a built-in MCP server supporting OAuth 2.1 and API tokens, allowing external AI agents (such as Claude Code, Cursor, or Kiro) to browse projects, manage and upload files, inspect media contents (images, video frames, PDF pages, 3D models, and text), search assets, manage review comments, update metadata, and organize version stacks
|
||||
* **cli**: Add `shumai-cli` commands to download files (`download`), view and render media contents (`read`, `render`), search and copy files (`search`, `copy`), manage review comments (`comment`), view and update metadata (`field ls`, `meta set`), organize version stacks (`version`), and view folder instructions (`instructions`)
|
||||
* **agent**: The built-in agent can now list accessible projects, search files by name, meaning, or metadata, read and post review comments, update metadata, copy files, stack and unstack versions, and read folder instructions (`AGENTS.md`), with configurable permissions per agent
|
||||
|
||||
### Fixed
|
||||
|
||||
|
||||
### Changed
|
||||
|
||||
|
||||
## [0.6.1] - 2026-10-24
|
||||
|
||||
### Added
|
||||
|
||||
* **dashboard**: Add Workflow Tasks section to the Team Dashboard allowing team owners to monitor background workflow jobs, inspect execution payloads and outputs, and stop in-flight tasks
|
||||
|
||||
### Fixed
|
||||
|
||||
* **metadata**: Fix an issue where clicking to edit a metadata field on a card or list row inadvertently selected the file, and prevent expanded text overlays or date pickers from being clipped by container borders
|
||||
|
||||
### Changed
|
||||
|
||||
* **deps**: Upgrade Bun to 1.4.4
|
||||
|
||||
## [0.6.0] - 2026-10-20
|
||||
|
||||
### Added
|
||||
|
||||
* **deploy**: Add dedicated `shumaione/shumai-transcode` Docker image and a complete AWS EKS deployment example (`eks/`) featuring KEDA queue-driven autoscaling, idle-timeout auto-drain worker mode, and Scale-to-Zero On-Demand Graviton5 instances for media processing
|
||||
* **storage**: Support configuring a separate public endpoint (`AWS_PUBLIC_ENDPOINT_URL_S3`) for browser-facing presigned URLs while preserving internal cluster endpoints for backend workers
|
||||
|
||||
### Fixed
|
||||
|
||||
* **transcode**: Fix an issue where PDF, 3D model, and image background transcode workflows could fail with missing temporary file errors if a worker restarted or recovered midway through processing
|
||||
* **webui**: Improve file list and detail loading with matching skeleton layouts, a persistent sidebar carousel to eliminate layout shift, and smoothed video poster previews
|
||||
|
||||
### Changed
|
||||
|
||||
* **workflow**: Migrate the background workflow engine to DBOS, unifying all-in-one and dedicated worker deployments using the existing PostgreSQL database without requiring a separate Temporal cluster
|
||||
|
||||
## [0.5.3] - 2026-10-16
|
||||
|
||||
### Added
|
||||
|
||||
* **cli**: Add administrative `shumai regenerate-embeddings` command to regenerate multimodal vector embeddings for all existing media files across active teams
|
||||
* **docker**: Provide three Docker Compose deployment tiers (Lite, with Embedding Server, and Full) with recommended memory specifications
|
||||
* **agent**: Save video chunk embeddings incrementally to the database as each chunk finishes, preserving completed progress on failure and resuming from where it left off on retry
|
||||
* **agent**: Add support for local LiteRT-LM Gemma Embedding 2 (`gemma-embedding-2-openai`) provider and environment-enforced read-only embedding agents with automatic 768-dimensional vector search indexing
|
||||
|
||||
### Fixed
|
||||
|
||||
### Changed
|
||||
|
||||
* **search**: Display search results in a responsive card grid with interactive hover video sprite scrubbing, semantic match chunk time range previews, and new-tab opening on click
|
||||
* **search**: Significantly improve semantic search response times by generating query text embeddings directly with in-memory caching instead of dispatching background tasks
|
||||
|
||||
## [0.5.2] - 2026-10-13
|
||||
|
||||
### Added
|
||||
|
||||
* **3d asset**: Add support for 3D model files (.glb, .gltf, .obj, .fbx, .stl, .dae, .usd, .usda, .usdc, .usdz) with automated turntable video rendering, hover sprite scrubbing, and an interactive 3D turntable viewer featuring 360° ruler scrubbing and degree-based markup comments
|
||||
* **kanban**: Related assets on a task are now clickable, taking you directly to that file or folder in its project
|
||||
* **settings**: Add an Integrations section to Team Settings with dedicated configuration for Gotenberg Document Converter, supporting connection testing and environment variable override protection
|
||||
|
||||
### Fixed
|
||||
|
||||
* **transcode**: Fix an issue where portrait photos from cameras and phones appeared sideways in thumbnails, previews, watermarked share links and annotated snapshots, and were listed with their width and height swapped
|
||||
|
||||
### Changed
|
||||
|
||||
## [0.5.1] - 2026-10-06
|
||||
|
||||
### Added
|
||||
|
||||
* **notification**: Notification cards are now clickable, taking you directly to the relevant file
|
||||
* **transcode**: Add hardware decoding and GPU scaling support for NVIDIA NVENC, Intel QuickSync Video (QSV), Rockchip (RKMPP), and VA-API (Intel and AMD GPUs), significantly speeding up video proxy and HLS rendition generation across supported platforms. Set `SHUMAI_HW_DECODE=false` to turn hardware decoding off
|
||||
* **transcode**: Add `dcraw_emu` fallback to generate WebP previews for camera RAW files without embedded JPEG previews
|
||||
|
||||
### Fixed
|
||||
|
||||
### Changed
|
||||
|
||||
|
||||
## [0.5.0] - 2026-10-02
|
||||
|
||||
### Added
|
||||
|
||||
* **transcode**: Add configurable target resolution ladders (480p, 720p, 1080p, 1440p, 2160p) for MP4 Multi Resolutions transcoding in team settings, with unified resolution matching and lowest-resolution fallback for both MP4 and HLS
|
||||
* **transcode**: Add HLS live streaming with fMP4/CMAF adaptive bitrate ladders (480p, 720p, 1080p, 1440p, 2160p), configurable in Transcode Settings, with automatic quality switching, manual resolution selection in the video viewer, seamless rendition switching, and full watermarking support for shared links
|
||||
* **transcode**: Add basic camera RAW image support for popular camera formats (including Sony ARW, Canon CR2/CR3, Nikon NEF, Adobe DNG, Fujifilm RAF, and Panasonic RW2), extracting high-quality embedded JPEG previews and automatically applying camera orientation for fast thumbnail and proxy generation
|
||||
|
||||
### Fixed
|
||||
|
||||
- **asset**: Fix an issue where media files remained stuck in a perpetual "Preparing..." state when transcoding failed, by displaying a clear failed status and error details in the file list and file viewer
|
||||
|
||||
* **transcode**: Fix an issue where videos or audio-only files containing attached cover art or picture streams could cause transcoding to fail during poster generation or select a single static image instead of the video
|
||||
|
||||
* **webui**: Fix inconsistent video resolution labels across download menus, mobile file headers, and the video player by correctly deriving resolutions from the video's short side, including portrait videos and 480p videos
|
||||
|
||||
* **trash**: Fix an issue where the "Empty Trash" confirmation dialog would close immediately instead of showing a loading state while files were being permanently deleted
|
||||
|
||||
### Changed
|
||||
|
||||
* **settings**: Redesign team Video Transcoding settings with dedicated cards for Transcode Policy, Hardware Acceleration, and FFmpeg Threads, clearly explaining MP4 and HLS playback vs download behavior and storage implications
|
||||
* **settings**: Rename AI Settings group to Team AI Settings in settings navigation
|
||||
|
||||
## [0.4.9] - 2026-09-28
|
||||
|
||||
### Added
|
||||
|
||||
- **notification**: You can now receive notifications via email, with batched digest emails and configurable team-level SMTP settings
|
||||
- **transcode**: Add VA-API hardware acceleration support for Linux hosts and Docker environments with Intel and AMD GPUs, featuring automatic DRI render node discovery, variable bitrate control, and structured transcoding observability logs
|
||||
- **transcode**: Add automatic fallback to software transcoding (libx264) when hardware-accelerated video encoding encounters GPU resolution constraints or runtime driver errors
|
||||
- **docker**: Add modular hardware-accelerated transcoding presets matching Immich's compose configuration via `hwaccel.transcoding.yaml` with support for NVENC, QuickSync, RKMPP, and VA-API
|
||||
|
||||
### Fixed
|
||||
|
||||
### Changed
|
||||
|
||||
- **transcode**: Improve video poster selection using intelligent scene detection and color variance filtering to automatically skip black frames, fade-ins, and blank intros in favor of representative video content
|
||||
- **transcode**: Optimize video sprite generation for large and long videos using a concurrent fast-seek pool and image compositing, avoiding full-video decoding while preserving instant single-pass generation for short clips
|
||||
|
||||
## [0.4.8] - 2026-09-24
|
||||
|
||||
### Added
|
||||
|
||||
+24
-13
@@ -1,6 +1,6 @@
|
||||
#syntax=docker/dockerfile:1.7-labs
|
||||
# Stage 1: Builder
|
||||
FROM oven/bun:1.4.2 AS builder
|
||||
FROM oven/bun:1.4.4 AS builder
|
||||
|
||||
WORKDIR /app
|
||||
|
||||
@@ -8,7 +8,6 @@ WORKDIR /app
|
||||
COPY package.json bun.lock ./
|
||||
COPY --parents packages/*/package.json ./
|
||||
COPY --parents apps/*/package.json ./
|
||||
COPY patches/ ./patches/
|
||||
|
||||
# Install dependencies (including devDependencies for build tools)
|
||||
RUN bun install --frozen-lockfile
|
||||
@@ -28,13 +27,11 @@ RUN bun run build.ts
|
||||
RUN bun run scripts/extract-runtime-deps.ts
|
||||
|
||||
# Stage 2: Runner
|
||||
FROM oven/bun:1.4.2 AS runner
|
||||
FROM oven/bun:1.4.4 AS runner
|
||||
|
||||
# Install ffmpeg/ffprobe
|
||||
COPY --from=mwader/static-ffmpeg:8.1 /ffmpeg /usr/local/bin/
|
||||
COPY --from=mwader/static-ffmpeg:8.1 /ffprobe /usr/local/bin/
|
||||
ENV NODE_ENV=production
|
||||
|
||||
# Install system dependencies for sandbox runtime and agent
|
||||
# Install system dependencies and Jellyfin-FFmpeg (with VA-API support)
|
||||
RUN apt-get update && apt-get install -y --no-install-recommends \
|
||||
python3 \
|
||||
make \
|
||||
@@ -49,18 +46,31 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
|
||||
ripgrep \
|
||||
procps \
|
||||
lsof \
|
||||
socat \
|
||||
ca-certificates \
|
||||
bubblewrap \
|
||||
gosu \
|
||||
poppler-utils \
|
||||
imagemagick \
|
||||
fonts-noto-cjk \
|
||||
libraw-bin \
|
||||
libimage-exiftool-perl \
|
||||
&& . /etc/os-release \
|
||||
&& TARGETARCH=$(dpkg --print-architecture) \
|
||||
&& FFMPEG_VERSION="8.1.2-5" \
|
||||
&& curl -fsSL -o /tmp/jellyfin-ffmpeg.deb "https://github.com/jellyfin/jellyfin-ffmpeg/releases/download/v${FFMPEG_VERSION}/jellyfin-ffmpeg8_${FFMPEG_VERSION}-${VERSION_CODENAME}_${TARGETARCH}.deb" \
|
||||
&& apt-get install -y --no-install-recommends /tmp/jellyfin-ffmpeg.deb \
|
||||
&& rm -f /tmp/jellyfin-ffmpeg.deb \
|
||||
&& ldconfig /usr/lib/jellyfin-ffmpeg/lib \
|
||||
&& ln -sf /usr/lib/jellyfin-ffmpeg/ffmpeg /usr/local/bin/ffmpeg \
|
||||
&& ln -sf /usr/lib/jellyfin-ffmpeg/ffprobe /usr/local/bin/ffprobe \
|
||||
&& ln -sf /usr/lib/jellyfin-ffmpeg/ffmpeg /usr/bin/ffmpeg \
|
||||
&& ln -sf /usr/lib/jellyfin-ffmpeg/ffprobe /usr/bin/ffprobe \
|
||||
&& apt-get clean \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# Set up working directory and make it owned by the bun user
|
||||
RUN mkdir -p /app/data && chown -R bun:bun /app
|
||||
# Set up working directory and make it owned by the bun user, ensure video/render group access
|
||||
RUN usermod -a -G video,render bun 2>/dev/null || true \
|
||||
&& mkdir -p /app/data \
|
||||
&& chown -R bun:bun /app
|
||||
|
||||
# Switch to the non-root bun user
|
||||
USER bun
|
||||
@@ -83,9 +93,10 @@ USER root
|
||||
COPY scripts/docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
|
||||
RUN chmod +x /usr/local/bin/docker-entrypoint.sh
|
||||
|
||||
# Expose "bun index.js" as "shumai" CLI command (and alias "shuami")
|
||||
# Expose "bun index.js" as "shumai" CLI command (and the transcode worker command)
|
||||
RUN printf '#!/bin/sh\nexec bun /app/index.js "$@"\n' > /usr/local/bin/shumai \
|
||||
&& chmod +x /usr/local/bin/shumai \
|
||||
&& printf '#!/bin/sh\nexec bun /app/transcode-worker.js "$@"\n' > /usr/local/bin/shumai-transcode \
|
||||
&& chmod +x /usr/local/bin/shumai /usr/local/bin/shumai-transcode \
|
||||
&& ln -s /usr/local/bin/shumai /usr/local/bin/shuami
|
||||
|
||||
ENTRYPOINT ["docker-entrypoint.sh"]
|
||||
|
||||
@@ -0,0 +1,81 @@
|
||||
#syntax=docker/dockerfile:1.7-labs
|
||||
# Stage 1: Builder
|
||||
FROM oven/bun:1.4.4 AS builder
|
||||
|
||||
WORKDIR /app
|
||||
|
||||
# Copy package files
|
||||
COPY package.json bun.lock ./
|
||||
COPY --parents packages/*/package.json ./
|
||||
COPY --parents apps/*/package.json ./
|
||||
|
||||
# Install dependencies (including devDependencies for build tools)
|
||||
RUN bun install --frozen-lockfile
|
||||
|
||||
# Copy source code
|
||||
COPY . .
|
||||
|
||||
# Build transcode worker bundle
|
||||
RUN bun run build.ts transcode
|
||||
|
||||
# Generate runner-package.json for the runner stage
|
||||
RUN bun run scripts/extract-runtime-deps.ts
|
||||
|
||||
# Stage 2: Runner
|
||||
FROM oven/bun:1.4.4 AS runner
|
||||
|
||||
ENV NODE_ENV=production
|
||||
|
||||
# Install transcoding system dependencies and Jellyfin-FFmpeg (with VA-API/hardware acceleration support)
|
||||
RUN apt-get update && apt-get install -y --no-install-recommends \
|
||||
curl \
|
||||
ca-certificates \
|
||||
gosu \
|
||||
poppler-utils \
|
||||
imagemagick \
|
||||
fonts-noto-cjk \
|
||||
libraw-bin \
|
||||
libimage-exiftool-perl \
|
||||
&& . /etc/os-release \
|
||||
&& TARGETARCH=$(dpkg --print-architecture) \
|
||||
&& FFMPEG_VERSION="8.1.2-5" \
|
||||
&& curl -fsSL -o /tmp/jellyfin-ffmpeg.deb "https://github.com/jellyfin/jellyfin-ffmpeg/releases/download/v${FFMPEG_VERSION}/jellyfin-ffmpeg8_${FFMPEG_VERSION}-${VERSION_CODENAME}_${TARGETARCH}.deb" \
|
||||
&& apt-get install -y --no-install-recommends /tmp/jellyfin-ffmpeg.deb \
|
||||
&& rm -f /tmp/jellyfin-ffmpeg.deb \
|
||||
&& ldconfig /usr/lib/jellyfin-ffmpeg/lib \
|
||||
&& ln -sf /usr/lib/jellyfin-ffmpeg/ffmpeg /usr/local/bin/ffmpeg \
|
||||
&& ln -sf /usr/lib/jellyfin-ffmpeg/ffprobe /usr/local/bin/ffprobe \
|
||||
&& ln -sf /usr/lib/jellyfin-ffmpeg/ffmpeg /usr/bin/ffmpeg \
|
||||
&& ln -sf /usr/lib/jellyfin-ffmpeg/ffprobe /usr/bin/ffprobe \
|
||||
&& apt-get clean \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# Set up working directory and make it owned by the bun user, ensure video/render group access
|
||||
RUN usermod -a -G video,render bun 2>/dev/null || true \
|
||||
&& mkdir -p /app/data \
|
||||
&& chown -R bun:bun /app
|
||||
|
||||
# Switch to the non-root bun user
|
||||
USER bun
|
||||
WORKDIR /app
|
||||
|
||||
# Install runtime dependencies with exact matching versions extracted from the builder stage
|
||||
COPY --chown=bun:bun --from=builder /app/runner-package.json ./package.json
|
||||
RUN bun install
|
||||
|
||||
# Copy build artifacts
|
||||
COPY --chown=bun:bun --from=builder /app/dist ./
|
||||
|
||||
# Switch back to root at the end so the container runs the entrypoint as root
|
||||
USER root
|
||||
COPY scripts/docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
|
||||
RUN chmod +x /usr/local/bin/docker-entrypoint.sh
|
||||
|
||||
# Expose "bun transcode-worker.js" as "shumai-transcode" CLI command
|
||||
RUN printf '#!/bin/sh\nexec bun /app/transcode-worker.js "$@"\n' > /usr/local/bin/shumai-transcode \
|
||||
&& chmod +x /usr/local/bin/shumai-transcode
|
||||
|
||||
ENTRYPOINT ["docker-entrypoint.sh"]
|
||||
|
||||
# Default command: start transcode worker
|
||||
CMD ["shumai-transcode"]
|
||||
@@ -12,11 +12,11 @@
|
||||
<a href="https://hub.docker.com/r/shumaione/shumai"><img alt="Docker pulls" src="https://img.shields.io/docker/pulls/shumaione/shumai" /></a>
|
||||
<a href="https://github.com/shumaiOne/shumai/releases"><img alt="GitHub latest release" src="https://img.shields.io/github/v/release/shumaiOne/shumai" /></a>
|
||||
<a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-blue" /></a>
|
||||
<a target="_blank" href="https://deepwiki.com/shumaiOne/shumai"><img alt="Ask DeepWiki" src="https://deepwiki.com/badge.svg" /></a>
|
||||
<a target="_blank" href="https://deepwiki.com/shumaiOne/shumai"><img alt="Ask DeepWiki" src="https://img.shields.io/badge/Ask-DeepWiki-6E56CF" /></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a target="_blank" href="https://shumai.one/">Website</a> | <a target="_blank" href="https://docs.shumai.one/getting-started/overview">Docs</a> | <a target="_blank" href="https://staging.shumai.one">Demo</a> | <a target="_blank" href="https://discord.gg/sUzhujK6DD">Discord</a> | <a target="_blank" href="README_CN.md">中文</a>
|
||||
<a target="_blank" href="https://shumai.one/">Website</a> | <a target="_blank" href="https://docs.shumai.one/getting-started/overview">Docs</a> | <a target="_blank" href="https://staging.shumai.one">Demo</a> | <a target="_blank" href="https://shumai.discourse.group/">Discourse Forum</a> | <a target="_blank" href="README_CN.md">中文</a>
|
||||
</p>
|
||||
|
||||

|
||||
@@ -26,15 +26,20 @@
|
||||
Shumai is an open-source Frame.io alternative built for creative teams to collaborate and share media with ease:
|
||||
|
||||
* **S3-Compatible & Local Storage**: Store and serve creative assets securely using the local filesystem or any S3-compatible storage service, including AWS S3, Cloudflare R2, and MinIO.
|
||||
* **Archive Storage & Auto-Archival**: Offload original master media files to secondary local storage or cold S3 storage—manually or automatically via team lifecycle policies—to save on storage costs while keeping proxies for instant browsing and playback. See [Archive Storage documentation](https://docs.shumai.one/configuration/archive-storage).
|
||||
* **Frame-by-Frame Annotations & Comments**: Leave precise feedback with frame-specific drawing tools and timestamped comments on both video and image assets.
|
||||
* **Secure Sharing & Collections**: Create private share links and curated media collections for clients, stakeholders, and collaborators.
|
||||
* **Granular Access Control**: Manage workspace permissions with team-level and project-level role-based access control.
|
||||
* **Distributed Transcoding via Temporal**: Offload resource-intensive video transcoding to a background worker pool orchestrated by Temporal.
|
||||
* **Durable Workflows via DBOS**: Run background tasks and AI agent workflows orchestrated reliably by DBOS on PostgreSQL with automatic recovery and fault tolerance.
|
||||
* **Scalable Deployment on Docker or Kubernetes**: Horizontally autoscale video transcoding on multiple instances. See [EKS Deployment Example](eks/README.md).
|
||||
* **Custom Asset Metadata**: Define dynamic metadata fields tailored to your production pipeline.
|
||||
* **Share Link Watermarking**: Protect shared media with customizable text and image watermarks, and save watermark as reusable templates.
|
||||
* **Wide File Format Support**: Preview common creative file formats, including images (with PSD support), videos, audio, and documents, while allowing any file type to be uploaded and stored.
|
||||
* **3D Asset Turntable Previews**: Generate interactive 3D model turntable previews and videos for formats like GLB, FBX, OBJ, STL, USD, and DAE using [turntable-renderer](https://docs.shumai.one/using-shumai/3d-asset-support).
|
||||
* **Office & Document PDF Proxying via Gotenberg**: Convert Word, PowerPoint, Excel, Markdown, HTML, and CSV documents to high-quality PDF proxies for in-browser previewing using [Gotenberg](https://docs.shumai.one/using-shumai/gotenberg).
|
||||
* **Semantic Search**: Find assets by visual or conceptual meaning using vector embeddings. See [documentation](https://docs.shumai.one/using-shumai/semantic-search).
|
||||
* **NLE Export & Premiere Pro Plugin (Experimental)**: Export timestamped review comments to your favorite non-linear editor (Premiere Pro XML, DaVinci Resolve EDL, Final Cut Pro, Avid Media Composer) or use the experimental Premiere Pro UXP plugin to import media assets and auto-sync comments directly to sequence timeline markers. See [documentation](https://docs.shumai.one/using-shumai/nle-and-premiere).
|
||||
* **Built-in MCP Server & CLI**: Connect external AI agents to Shumai via `/mcp` or manage projects, assets, comments, and metadata from the terminal with `shumai-cli`.
|
||||
|
||||
But Shumai goes beyond being a Frame.io alternative. With modern models like GPT-Image-2 and Seedance 2.5, AI can already handle a surprising amount of creative work. That means you can create or update videos and images from a simple prompt without having to jump back into Photoshop, Premiere or Houdini. That is why Shumai includes a powerful agent system:
|
||||
|
||||
@@ -46,7 +51,6 @@ But Shumai goes beyond being a Frame.io alternative. With modern models like GPT
|
||||
* **Model Context Protocol (MCP)**: Connect agents to external tools and APIs through remote MCP servers, with OAuth authentication and per-agent MCP access.
|
||||
* **Isolated Sandbox Execution**: Run agent-submitted scripts safely in a sandboxed environment.
|
||||
* **AI Metadata Autofill**: Automatically fill in custom metadata for new assets.
|
||||
* **Semantic Search**: Find assets by visual or conceptual meaning using vector embeddings (Gemini Embedding 2).
|
||||
* **Resource Quotas**: Set usage limits on AI tokens, costs, and tool execution per member, role, or team-wide, with real-time tracking.
|
||||
|
||||
Here is a short demo video showing what the Shumai agent can do:
|
||||
@@ -68,11 +72,13 @@ The ultimate goal is an **agentic Kanban**, where agents and team members can wo
|
||||
> * **For Images:** Shumai generates a high-quality WebP proxy at the exact same resolution as your original file for optimized viewing.
|
||||
> * **For Videos:** It generates at least one proxy video (depending on your transcoding settings), alongside a sprite image and a small preview video (capped at 1600 frames) to enable fast timeline scrubbing and lightning-quick previews.
|
||||
|
||||
---
|
||||
Have feedback or ideas? [Share them with us](https://github.com/shumaiOne/shumai/issues/328), and if you find Shumai useful, please give us a ⭐ or recommend Shumai to someone who might find it useful, it really helps!
|
||||
|
||||
|
||||
|
||||
## Installation
|
||||
|
||||
Below is a quickstart guide for running Shumai with local storage. For advanced configuration options (including S3-compatible storage and Temporal workflow orchestration), see our [Documentation](https://docs.shumai.one/getting-started/overview).
|
||||
Below is a quickstart guide for running Shumai with local storage. For advanced configuration options (including S3-compatible storage and distributed worker orchestration), see our [Documentation](https://docs.shumai.one/getting-started/overview).
|
||||
|
||||
### Option 1: Docker Compose
|
||||
|
||||
@@ -82,14 +88,47 @@ Docker Compose is the fastest way to get Shumai running. You do not need to clon
|
||||
```bash
|
||||
mkdir shumai && cd shumai
|
||||
```
|
||||
2. Download the `docker-compose.yaml` file:
|
||||
```bash
|
||||
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.yaml
|
||||
```
|
||||
3. Configure environment variables (optional):
|
||||
2. Download your preferred `docker-compose.yaml` configuration based on your needs and available RAM:
|
||||
|
||||
* `SHUMAI_SERVER_PORT` controls the port the Shumai server listens on. The default is `3000`.
|
||||
* By default, Shumai uses the bundled local storage service in this Docker Compose setup. To use an external S3-compatible storage instead, configure the environment variables for your S3 provider. Here are examples for AWS S3 and Cloudflare R2:
|
||||
* **Lite (Suggested RAM: 2 GB+)**: Minimal deployment containing Shumai and PostgreSQL database.
|
||||
```bash
|
||||
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.yaml
|
||||
```
|
||||
|
||||
* **With Embedding Server (Suggested RAM: 4 GB+)**: Adds local multimodal semantic search powered by `shumaiOne/embedding-server` (`EmbeddingGemma 2 740M`).
|
||||
```bash
|
||||
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.embedding.yaml
|
||||
```
|
||||
|
||||
* **Full (Suggested RAM: 8 GB+)**: All-in-one setup including `embedding-server`, `turntable-renderer` (3D previews), and `Gotenberg` (document PDF proxying).
|
||||
```bash
|
||||
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.full.yaml
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> By default, the Docker Compose setups use CPU software transcoding. If your server has a GPU (NVIDIA NVENC, Intel QuickSync, AMD/Intel VA-API, or Rockchip RKMPP) and you want to enable GPU hardware acceleration, check the [Hardware Transcoding Guide](https://docs.shumai.one/configuration/hardware-transcoding).
|
||||
3. Configure environment variables:
|
||||
|
||||
* `BETTER_AUTH_URL`: The public base URL of your Shumai server (e.g., `https://shumai.example.com` or `http://12.34.56.78:3000`). It is used for:
|
||||
* **Password reset links**: Generates CLI and user password reset URLs (`{BETTER_AUTH_URL}/reset-password?token=...`).
|
||||
* **Email notification deep links**: Default base URL for notification emails (if `APP_URL` is unset).
|
||||
* **Session cookie security**: Determines whether to issue session cookies with `Secure` flags and `__Secure-` prefixes for HTTPS deployments.
|
||||
* **MCP OAuth 2.1 & discovery**: Sets the OAuth resource identifier (`{BETTER_AUTH_URL}/mcp`), discovery endpoints (`/.well-known/...`), and default redirect URI for outbound MCP OAuth.
|
||||
|
||||
> [!NOTE]
|
||||
> **Email/password Web UI login** works over plain HTTP/IP even if `BETTER_AUTH_URL` is omitted. However, setting it is strongly recommended for production, custom domains, or HTTPS deployments. Note that remote deployments must use HTTPS for MCP OAuth 2.1 (RFC 9728); if an HTTP IP address or domain is used, MCP OAuth 2.1 is gracefully disabled while the Web UI and MCP API tokens remain functional.
|
||||
* `BETTER_AUTH_SECRET`: A random secret key used to sign session cookies, JWTs, and presigned file upload/download URLs (in local storage mode). A default placeholder is included in the template for instant local trials, but **you must generate a unique secret for production or public deployments** (e.g., run `openssl rand -base64 32`).
|
||||
* `AWS_ENDPOINT_URL_S3`: By default, `AWS_ENDPOINT_URL_S3` is set to `http://localhost:{SHUMAI_SERVER_PORT}`. When you use local storage (the default storage backend with `STORAGE_BACKEND: local`) and expose Shumai on a remote server, custom domain, or custom host/port combination, set `AWS_ENDPOINT_URL_S3` to the external URL that client browsers will use to upload and download files.
|
||||
|
||||
For example, if you change the port mapping in `docker-compose.yaml` from `3000:3000` to `12345:3000` and deploy on a server with IP address `12.34.56.78`, set:
|
||||
|
||||
```yaml
|
||||
AWS_ENDPOINT_URL_S3: http://12.34.56.78:12345
|
||||
```
|
||||
|
||||
This value must be reachable from client browsers and should include the externally exposed port.
|
||||
* `SHUMAI_SERVER_PORT`: Controls the port the Shumai server listens on. The default is `3000`.
|
||||
* **External S3 Storage**: By default, Shumai uses the bundled local storage service in this Docker Compose setup. To use an external S3-compatible storage instead, configure the environment variables for your S3 provider. Here are examples for AWS S3 and Cloudflare R2:
|
||||
|
||||
**AWS S3 Example:**
|
||||
```yaml
|
||||
@@ -109,204 +148,46 @@ Docker Compose is the fastest way to get Shumai running. You do not need to clon
|
||||
S3_SECRET_ACCESS_KEY: your-secret-access-key
|
||||
AWS_ENDPOINT_URL_S3: https://<account-id>.r2.cloudflarestorage.com
|
||||
```
|
||||
* By default, `AWS_ENDPOINT_URL_S3` is set to: `http://localhost:{SHUMAI_SERVER_PORT}`, if you use local storage and expose Shumai on a custom host/port combination, set `AWS_ENDPOINT_URL_S3` to the external URL that browsers will use to upload files.
|
||||
|
||||
For example, if you change the port mapping in `docker-compose.yaml` from `3000:3000` to `12345:3000` and deploy on a server with IP address `12.34.56.78`, set:
|
||||
|
||||
```
|
||||
AWS_ENDPOINT_URL_S3: http://12.34.56.78:12345
|
||||
```
|
||||
|
||||
This value must be reachable from client browsers and should include the externally exposed port.
|
||||
|
||||
5. Start the services in detached mode:
|
||||
4. Start the services in detached mode:
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
6. Open your browser and access Shumai at `http://localhost:3000` (or `http://<your-server-ip>:3000` for remote deployments).
|
||||
5. Open your browser and access Shumai at `http://localhost:3000` (or `http://<your-server-ip>:3000` for remote deployments).
|
||||
|
||||
### Option 2: Install via NPM / Package Manager
|
||||
#### **Scaling Transcode Workers (Parallel Processing)**
|
||||
|
||||
Shumai is published as `@shumai-one/shumai` on NPM. This option allows you to run Shumai globally or locally.
|
||||
By default, the Docker Compose deployment transcodes videos one-by-one. This is by design, as video transcoding is compute-intensive and can saturate available CPU or GPU resources.
|
||||
|
||||
#### Step 1: Start PostgreSQL with pgvector
|
||||
However, when uploading large batches (e.g., 100+ videos at once) or massive raw camera files that take hours to process and block subsequent uploads, you can scale transcoding throughput across additional machines. Each machine still processes tasks sequentially, but adding more worker instances increases overall parallel capacity.
|
||||
|
||||
Shumai requires PostgreSQL with the `pgvector` extension. Start a pre-configured database container using Docker:
|
||||
Shumai makes this seamless with a dedicated [`shumaione/shumai-transcode`](https://hub.docker.com/r/shumaione/shumai-transcode) Docker image:
|
||||
|
||||
```bash
|
||||
docker run --name shumai_postgres \
|
||||
-e POSTGRES_USER=shumai \
|
||||
-e POSTGRES_PASSWORD=shumai_password \
|
||||
-e POSTGRES_DB=shumai_db \
|
||||
-p 5432:5432 \
|
||||
-d pgvector/pgvector:pg18
|
||||
```
|
||||
1. **Connect**: Launch a temporary machine and ensure network access to your PostgreSQL database and storage backend (e.g., S3 or shared storage).
|
||||
2. **Start the worker**: Run the container with matching database and storage credentials:
|
||||
|
||||
#### Step 2: Create a workspace folder
|
||||
```bash
|
||||
docker run -d --name shumai_transcode_worker \
|
||||
-e DATABASE_URL="postgres://shumai:shumai_password@<postgres-host>:5432/shumai_db?sslmode=disable" \
|
||||
-e STORAGE_BACKEND="s3" \
|
||||
-e S3_BUCKET="your-bucket-name" \
|
||||
-e AWS_ENDPOINT_URL_S3="https://s3.us-east-1.amazonaws.com" \
|
||||
-e S3_ACCESS_KEY_ID="your-access-key-id" \
|
||||
-e S3_SECRET_ACCESS_KEY="your-secret-access-key" \
|
||||
shumaione/shumai-transcode:latest
|
||||
```
|
||||
|
||||
Create a dedicated directory to store your environment configuration and media files (which are saved in a `./data` directory by default):
|
||||
The worker will automatically attach to the task queue and begin processing pending transcode jobs in parallel with your primary instance.
|
||||
|
||||
```bash
|
||||
mkdir shumai && cd shumai
|
||||
```
|
||||
3. **Stop anytime**: Once the transcoding backlog finishes (or whenever you no longer need the extra compute), simply stop or remove the worker:
|
||||
|
||||
#### Step 3: Install Platform-Specific Dependencies
|
||||
```bash
|
||||
docker stop shumai_transcode_worker
|
||||
```
|
||||
|
||||
#### Linux
|
||||
There is no downtime or impact on the main Shumai application.
|
||||
|
||||
Shumai requires the following system packages on Linux:
|
||||
|
||||
- **`ffmpeg`** – Used for media transcoding and metadata extraction.
|
||||
- **`poppler`** (`poppler-utils`) – Used for PDF page image extraction and PDF sprite preview generation (`pdftoppm`).
|
||||
- **`imagemagick`** – Used for PSD format transcoding and color profile conversion to sRGB.
|
||||
- **`bubblewrap`**, **`socat`**, and **`ripgrep`** – Required by the AI agent sandbox (`anthropic-experimental/sandbox-runtime`) for process isolation, networking, and workspace search.
|
||||
|
||||
Install all required packages with one command:
|
||||
|
||||
> Ubuntu/Debian
|
||||
```bash
|
||||
sudo apt install -y ffmpeg poppler-utils imagemagick bubblewrap socat ripgrep
|
||||
```
|
||||
|
||||
> Fedora
|
||||
```bash
|
||||
sudo dnf install -y ffmpeg poppler-utils ImageMagick bubblewrap socat ripgrep
|
||||
```
|
||||
|
||||
> Arch Linux
|
||||
```bash
|
||||
sudo pacman -S --noconfirm ffmpeg poppler imagemagick bubblewrap socat ripgrep
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> **Ubuntu 24.04+** restricts unprivileged user namespaces by default. This prevents `anthropic-experimental/sandbox-runtime` from using `bubblewrap` for sandbox isolation.
|
||||
>
|
||||
> To temporarily allow user namespaces:
|
||||
>
|
||||
> ```bash
|
||||
> sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
|
||||
> ```
|
||||
>
|
||||
> Alternatively, configure an AppArmor profile that grants the required `userns` permission to the relevant binaries.
|
||||
|
||||
---
|
||||
|
||||
#### macOS
|
||||
|
||||
Shumai requires:
|
||||
|
||||
- **`ffmpeg`** – Used for media transcoding and metadata extraction.
|
||||
- **`poppler`** – Used for PDF page image extraction and PDF sprite preview generation (`pdftoppm`).
|
||||
- **`imagemagick`** – Used for PSD format transcoding and color profile conversion to sRGB.
|
||||
- **`ripgrep`** – Required by the AI agent sandbox (`anthropic-experimental/sandbox-runtime`).
|
||||
|
||||
Install the required packages with Homebrew:
|
||||
|
||||
```bash
|
||||
brew install ffmpeg poppler imagemagick ripgrep
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### Windows (alpha)
|
||||
|
||||
> [!WARNING]
|
||||
> Windows support in anthropic-experimental/sandbox-runtime is **alpha and the design is in flux**.
|
||||
>
|
||||
> The current implementation provides:
|
||||
> - Network egress filtering via the **Windows Filtering Platform (WFP)**.
|
||||
> - File read/write denial via **ACL stamping**.
|
||||
>
|
||||
> However, it is **not a security boundary against a deliberately adversarial sandboxed process**.
|
||||
>
|
||||
> The sandbox implementation will be substantially revised in a future release, where sandboxed processes will run under a dedicated sandbox user account.
|
||||
|
||||
Shumai requires:
|
||||
|
||||
- **`ffmpeg`** – Used for media transcoding and metadata extraction.
|
||||
- **`imagemagick`** – Used for PSD format transcoding and color profile conversion to sRGB.
|
||||
|
||||
Install required packages using your preferred package manager:
|
||||
|
||||
**winget**
|
||||
```powershell
|
||||
winget install Gyan.FFmpeg ImageMagick.ImageMagick
|
||||
```
|
||||
|
||||
**Chocolatey**
|
||||
```powershell
|
||||
choco install ffmpeg imagemagick
|
||||
```
|
||||
|
||||
#### Step 4: Install Shumai globally
|
||||
|
||||
Install Shumai globally using your preferred package manager:
|
||||
|
||||
```bash
|
||||
# NPM
|
||||
npm install -g @shumai-one/shumai
|
||||
|
||||
# PNPM
|
||||
pnpm add -g @shumai-one/shumai
|
||||
|
||||
# Bun
|
||||
bun add -g @shumai-one/shumai
|
||||
```
|
||||
|
||||
#### Step 5: Configure Environment Variables
|
||||
|
||||
Create a `.env` file in your workspace folder (`shumai/`) and add the following configuration:
|
||||
|
||||
```env
|
||||
DATABASE_URL=postgresql://shumai:shumai_password@localhost:5432/shumai_db?schema=public
|
||||
BETTER_AUTH_SECRET=ySxs7DxzHDZBbeeHNPEwBuspYwipBqz5Gk5XdBjNhWw=
|
||||
STORAGE_BACKEND=local
|
||||
SHUMAI_SERVER_PORT=3000
|
||||
AWS_ENDPOINT_URL_S3=http://localhost:3000
|
||||
# Optional: base URL for MCP OAuth redirects (defaults to BETTER_AUTH_URL)
|
||||
MCP_OAUTH_REDIRECT_BASE_URL=http://localhost:3000
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> `SHUMAI_SERVER_PORT` sets the port the server starts on, while `AWS_ENDPOINT_URL_S3` is used by the browser to build file upload URLs.
|
||||
> If deploying on a remote server (e.g. `http://123.456.7.8`) with a mapped port (e.g. `12345:3000` in docker-compose), set `AWS_ENDPOINT_URL_S3` to `http://123.456.7.8:12345`.
|
||||
> `MCP_OAUTH_REDIRECT_BASE_URL` is only needed when MCP servers use OAuth: the authorization redirect URI defaults to `{BETTER_AUTH_URL}/api/mcp/oauth/callback`; set it to an externally reachable URL if the app is served behind a proxy.
|
||||
|
||||
#### Step 6: Run Shumai
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **For Bun Users:** Since the published package binaries contain a `#!/usr/bin/env node` shebang, running the global command directly (e.g., `shumai`) will execute under Node.js. If you installed with Bun and want to run under the Bun runtime, you must prefix all commands with `bun run --bun` (e.g., `bun run --bun shumai`, `bun run --bun shumai -d`, `bun run --bun shumai stop`).
|
||||
|
||||
Start the application from your workspace folder:
|
||||
|
||||
```bash
|
||||
shumai
|
||||
```
|
||||
|
||||
Alternatively, you can run and manage Shumai in daemon mode:
|
||||
|
||||
- **Start in daemon mode**:
|
||||
```bash
|
||||
shumai -d
|
||||
```
|
||||
- **Stop Shumai**:
|
||||
```bash
|
||||
shumai stop
|
||||
```
|
||||
- **Restart Shumai**:
|
||||
```bash
|
||||
shumai restart
|
||||
```
|
||||
- **Show/tail logs**:
|
||||
```bash
|
||||
shumai logs
|
||||
```
|
||||
|
||||
On startup, Shumai will automatically run database migrations and start the web server at `http://localhost:3000`.
|
||||
|
||||
---
|
||||
|
||||
### Option 3: Run from Source (Development)
|
||||
### Option 2: Run from Source (Development)
|
||||
|
||||
To set up Shumai locally for development:
|
||||
|
||||
@@ -316,8 +197,24 @@ To set up Shumai locally for development:
|
||||
cd shumai
|
||||
bun install
|
||||
```
|
||||
2. Start the `pgvector` database container (as described in **Option 2, Step 1**).
|
||||
3. Create a `.env` file at the root of the workspace using the configuration from **Option 2, Step 5**.
|
||||
2. Start the `pgvector` database container:
|
||||
```bash
|
||||
docker run --name shumai_postgres \
|
||||
-e POSTGRES_USER=shumai \
|
||||
-e POSTGRES_PASSWORD=shumai_password \
|
||||
-e POSTGRES_DB=shumai_db \
|
||||
-p 5432:5432 \
|
||||
-d pgvector/pgvector:pg18
|
||||
```
|
||||
3. Create a `.env` file at the root of the workspace:
|
||||
```env
|
||||
DATABASE_URL=postgresql://shumai:shumai_password@localhost:5432/shumai_db?schema=public
|
||||
BETTER_AUTH_SECRET=ySxs7DxzHDZBbeeHNPEwBuspYwipBqz5Gk5XdBjNhWw=
|
||||
BETTER_AUTH_URL=http://localhost:3000
|
||||
STORAGE_BACKEND=local
|
||||
SHUMAI_SERVER_PORT=3000
|
||||
AWS_ENDPOINT_URL_S3=http://localhost:3000
|
||||
```
|
||||
4. Generate i18n translation files:
|
||||
```bash
|
||||
bun run i18n:compile
|
||||
@@ -333,10 +230,37 @@ To set up Shumai locally for development:
|
||||
bun run dev
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> Looking to install Shumai globally via NPM or your package manager? See our [NPM Installation Guide](https://docs.shumai.one/getting-started/quickstart).
|
||||
|
||||
---
|
||||
|
||||
## Command Line Interface (CLI)
|
||||
|
||||
Shumai provides a Command Line Interface (CLI) tool to manage projects, folders, and assets, upload files/folders, and create new versions directly from your terminal.
|
||||
|
||||
Install the standalone CLI on macOS/Linux without Node.js or Bun:
|
||||
|
||||
```sh
|
||||
curl -fsSL https://github.com/shumaiOne/shumai/releases/latest/download/install.sh | sh
|
||||
```
|
||||
|
||||
On Windows:
|
||||
|
||||
```powershell
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://github.com/shumaiOne/shumai/releases/latest/download/install.ps1 | iex"
|
||||
```
|
||||
|
||||
The npm installation remains available: `npm install -g @shumai-one/shumai-cli` (Node.js 22.12+).
|
||||
|
||||
For more details on installation and usage, see the [CLI Readme](apps/cli/README.md).
|
||||
|
||||
## MCP Server
|
||||
|
||||
Shumai includes a built-in MCP server at `/mcp`, so external agents such as Claude Code, Cursor, or Kiro can browse and organize your projects with OAuth or an API token. See the [MCP server guide](docs/developer/mcp-server.mdx) for setup.
|
||||
|
||||
---
|
||||
|
||||
## Community
|
||||
|
||||
Thanks to [LINUX DO](https://linux.do/) for providing a community for open-source discussions and feedback.
|
||||
|
||||
+170
-260
@@ -5,46 +5,51 @@
|
||||
<h1 align="center">Shumai</h1>
|
||||
|
||||
<p align="center">
|
||||
<strong>为创意工作打造的开源协作平台。</strong>
|
||||
<strong>开源版 阅流 / 分秒帧 - 专为创意与视频团队打造的审片与管理平台。</strong>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="https://hub.docker.com/r/shumaione/shumai"><img alt="Docker pulls" src="https://img.shields.io/docker/pulls/shumaione/shumai" /></a>
|
||||
<a href="https://github.com/shumaiOne/shumai/releases"><img alt="GitHub latest release" src="https://img.shields.io/github/v/release/shumaiOne/shumai" /></a>
|
||||
<a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-blue" /></a>
|
||||
<a target="_blank" href="https://deepwiki.com/shumaiOne/shumai"><img alt="Ask DeepWiki" src="https://deepwiki.com/badge.svg" /></a>
|
||||
<a target="_blank" href="https://deepwiki.com/shumaiOne/shumai"><img alt="Ask DeepWiki" src="https://img.shields.io/badge/Ask-DeepWiki-6E56CF" /></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a target="_blank" href="https://shumai.one/">官方网站</a> | <a target="_blank" href="https://docs.shumai.one/getting-started/overview">文档</a> | <a target="_blank" href="https://staging.shumai.one">在线演示</a> | <a target="_blank" href="README.md">English</a>
|
||||
<a target="_blank" href="https://shumai.one/">官方网站</a> | <a target="_blank" href="https://docs.shumai.one/getting-started/overview">文档(英文)</a> | <a target="_blank" href="https://staging.shumai.one">在线演示</a> | <a target="_blank" href="https://shumai.discourse.group/">Discourse 论坛</a> | <a target="_blank" href="README.md">English</a>
|
||||
</p>
|
||||
|
||||

|
||||
|
||||
## 功能
|
||||
|
||||
Shumai 是一个开源的 Frame.io 替代方案,专为创意团队打造,让大家能更轻松地协作、审片和分享素材:
|
||||
Shumai 是一个专为广告,短剧,漫剧等各类创意团队打造的开源协作管理平台,功能上类似阅流和分秒帧,提供了协作、审片和分享等各种功能:
|
||||
|
||||
* **支持 S3 和本地存储**:你可以把创意素材安全地存到本地文件系统,或者任意兼容 S3 的存储服务里,比如 AWS S3、Cloudflare R2、MinIO 等。
|
||||
* **逐帧标注和评论**:支持按帧进行精确反馈,可以直接在视频和图片素材上画重点、写评论,还能留下时间戳。
|
||||
* **安全分享和合集管理**:可以生成私密分享链接,也能整理成精选合集,方便给客户、同事和合作方查看。
|
||||
* **支持 S3 和本地存储**:你可以把创意素材安全地存放在本地硬盘或者任意兼容 S3 的存储服务里,比如 阿里云 OSS 或 MinIO 等。
|
||||
* **冷归档存储**:支持将原始大文件移至冷存储(如本地挂载的 NAS、AWS S3 Glacier、Google Cloud Storage Coldline 等归档存储类型)以节省主存储成本,同时保留主存储中的预览图、代理流和元数据,不影响网页浏览与即时播放。详情请参阅[归档存储文档](https://docs.shumai.one/configuration/archive-storage)。
|
||||
* **帧级别标注和评论**:支持按帧进行精确反馈,同时支持直接在视频上进行标注,让团队成员能更精确地Get到你的想法。
|
||||
* **安全的分享**:可以生成私密分享链接,同时还支持给分享的图片/视频添加自定义水印,并将水印配置保存为模板以便重复使用。方便给客户、同事和合作方查看。
|
||||
* **细粒度权限控制**:支持按团队、项目设置角色权限,方便管理不同成员的访问范围。
|
||||
* **基于 Temporal 的分布式转码**:把吃资源的视频转码任务交给后台 worker 池处理,由 Temporal 统一调度。
|
||||
* **基于 DBOS 的持久化工作流**:视频转码任务由 DBOS 统一持久化编排与调度,具备自动恢复和容错能力。
|
||||
* **Docker/K8s 弹性扩缩容部署**:支持在多个实例上横向自动扩缩容视频转码工作负载。详见 [EKS 部署示例](eks/README.md)。
|
||||
* **自定义素材元数据**:可以按你的制作流程,自由定义动态元数据字段。
|
||||
* **分享链接水印**:通过可自定义的文字和图片水印保护共享媒体,并将水印配置保存为模板以便重复使用。
|
||||
* **丰富的文件格式支持**:支持预览常见创意文件格式,包括图片(支持 PSD)、视频、音频和文档,同时可上传和存储任意类型的文件。
|
||||
* **基于 Gotenberg 的文档 PDF 转码代理**:通过集成 [Gotenberg](https://docs.shumai.one/using-shumai/gotenberg) 支持将 Word、PowerPoint、Excel、Markdown、HTML 和 CSV 文档高质量转换为 PDF 代理文件进行在线预览。
|
||||
* **非编剪辑导出与 Premiere 插件(实验性)**:支持将时间戳审阅评论导出至常用非编软件(Premiere Pro XML、DaVinci Resolve EDL、Final Cut Pro、Avid Media Composer),或使用实验性的 Premiere Pro 原生 UXP 插件导入媒体素材并将评论自动同步为时间轴标记。详见[相关文档](https://docs.shumai.one/using-shumai/nle-and-premiere)。
|
||||
* **3D 素材预览**:通过集成 [turntable-renderer](https://docs.shumai.one/using-shumai/3d-asset-support) 支持给 GLB、FBX、OBJ、STL、USD 和 DAE 等 3D 模型生成高质量的交互式转盘预览。
|
||||
* **Office 与文档在线预览**:通过集成 [Gotenberg](https://docs.shumai.one/using-shumai/gotenberg),自动将 Word、PPT、Excel、Markdown、HTML 和 CSV 高质量转换为 PDF,直接在浏览器里丝滑预览。
|
||||
* **语义搜索**:支持按画面内容或概念含义搜索素材,详见[相关文档](https://docs.shumai.one/using-shumai/semantic-search)。
|
||||
* **非编剪辑导出与 Premiere 插件(测试版)**:支持将时间戳审阅评论导出至常用非编软件(Premiere Pro XML、DaVinci Resolve EDL、Final Cut Pro、Avid Media Composer),或使用实验性的 Premiere Pro 原生 UXP 插件导入媒体素材并将评论自动同步为时间轴标记。详见[相关文档](https://docs.shumai.one/using-shumai/nle-and-premiere)。
|
||||
* **内置 MCP 服务端与 CLI 工具**:支持通过 `/mcp` 将外部 AI Agent 接入 Shumai,或使用 `shumai-cli` 在终端中管理项目、素材、评论与元数据。
|
||||
|
||||
但 Shumai 不仅仅只满足于 Frame.io 的开源替代。随着 GPT-Image-2、Seedance 2.5 这类强大模型的问世,AI已经生成产品级的图片/视频。很多时候,你只要给一句提示词,就能直接生成或修改图片和视频,而不用再打开 Photoshop、Premiere 或者 Houdini。也正因为这样,Shumai 才把 AI Agent 做成了核心能力:
|
||||
Shumai 不仅仅只满足于「阅流」和「分秒帧」的开源替代。随着 GPT-Image-2、Seedance 2.5 这类强大视频/图片生成模型的问世,AI已经能够生成产品级的创意素材。只需要一句提示词,AI就能直接生成或修改图片和视频,而不用再打开 Photoshop、Premiere 或者 Houdini。因此Shumai也添加了Agent相关功能:
|
||||
|
||||
* **Agent 就像团队成员**:你可以在素材评论区里直接用 `@` 提到 AI Agent,像拉一个真实同事进来一起看稿一样。
|
||||
> **AI 功能完全可选。** 你完全可以把 Shumai 当作纯粹的开源版「阅流 / 分秒帧」来用;如果团队不需要 AI,直接忽略即可。
|
||||
|
||||
* **Agent 是你的团队成员**:你可以在素材评论区里直接用 `@` 提到 AI Agent,像拉一个真实同事进来一起看稿一样。
|
||||
* **Agent 也能当你的私聊助手**:你可以单独和它聊天,让它帮你查东西、做任务。
|
||||
* **自定义技能和工具**:你可以给 Agent 接上自己的脚本、工具和自动化能力。
|
||||
* **Model Context Protocol (MCP) 支持**:通过远程 MCP 服务端为 Agent 接入外部工具与 API,支持 OAuth 鉴权与按 Agent 独立分配访问权限。
|
||||
* **自定义技能和工具**:你可以给 Agent 添加自己的脚本、工具和自动化能力。
|
||||
* **接入外部 MCP 工具 (Model Context Protocol)**:通过远程 MCP 服务端为 Agent 接入外部工具与 API,支持 OAuth 鉴权与按 Agent 独立分配访问权限。
|
||||
* **沙箱隔离执行**:Agent 生成的脚本会在隔离环境里运行,更安全。
|
||||
* **AI 自动补全元数据**:新素材上传后,系统可以自动帮你补一些元数据。
|
||||
* **语义搜索**:支持按画面内容或语义找素材,底层用的是向量 embedding(Gemini Embedding 2)。
|
||||
* **AI 自动打标与补全元数据**:新素材上传后,AI 可根据画面内容自动识别并填写自定义元数据字段,省去手动归档打标的麻烦。
|
||||
* **资源配额**:支持按成员、角色或全团队对 AI Token、成本和工具调用设置使用上限与实时用量监控。
|
||||
|
||||
下面是一个简短的 demo 视频,展示了 Shumai Agent 能做什么:
|
||||
@@ -64,15 +69,17 @@ Shumai 也将项目管理融入了创意工作流程。 内置的看板可以帮
|
||||
> * **图片:** 会生成一份与原图分辨率完全一致的高质量 WebP 转码版本,在保证画质的同时提升浏览性能。
|
||||
> * **视频:** 会根据转码配置生成至少一个代理视频,同时生成雪碧图(Sprite)和一段最长 1600 帧的低分辨率转码视频,用于实现快速拖动时间轴和即时视频预览。
|
||||
|
||||
如果你有任何反馈或想法,欢迎在 [Issue #329](https://github.com/shumaiOne/shumai/issues/329) 中和我们交流。如果 Shumai 对你有帮助,希望能给我们点个 ⭐,或者安利给身边做视频/创意的朋友。
|
||||
|
||||
---
|
||||
|
||||
## 安装指南
|
||||
|
||||
以下是使用本地存储运行 Shumai 的快速上手指南。如需了解高级配置(包括 S3 兼容存储配置、Temporal 工作流编排等),请参阅我们的[官方文档](https://docs.shumai.one/getting-started/overview)。
|
||||
以下是使用本地存储的快速安装指南。如需了解高级配置(包括 S3 兼容存储配置、分布式 worker 编排等),请参阅我们的[官方文档](https://docs.shumai.one/getting-started/overview)。
|
||||
|
||||
### 方案一:使用 Docker Compose(推荐)
|
||||
<details>
|
||||
|
||||
|
||||
<summary>复制这个提示词,让agent帮你安装</summary>
|
||||
|
||||
```
|
||||
@@ -90,54 +97,75 @@ https://gh-proxy.com/https://raw.githubusercontent.com/shumaiOne/shumai/main/REA
|
||||
```
|
||||
</details>
|
||||
|
||||
使用 Docker Compose 是运行 Shumai 最快的方式。您无需克隆仓库,也不需要手动安装依赖包。请确保电脑上已安装 [Docker](https://docs.docker.com/get-docker/) 和 [Docker Compose](https://docs.docker.com/compose/install/),然后按照以下步骤操作:
|
||||
使用 Docker Compose 是运行 Shumai 最快的方式。你无需克隆仓库,也不需要手动安装依赖包。请确保电脑上已安装 [Docker](https://docs.docker.com/get-docker/) 和 [Docker Compose](https://docs.docker.com/compose/install/),然后按照以下步骤操作:
|
||||
|
||||
1. 创建并进入一个新目录,用于存放配置文件和数据卷:
|
||||
1. 创建一个新文件夹,用于存放配置文件和数据:
|
||||
```bash
|
||||
mkdir shumai && cd shumai
|
||||
|
||||
```
|
||||
|
||||
2. 下载 `docker-compose.yaml` 配置文件:
|
||||
```bash
|
||||
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose-aliyun.yaml
|
||||
2. 根据你的需求和机器可用内存,下载对应的 `docker-compose.yaml` 配置文件(注意所有镜像都是阿里云源,想要使用dockerhub源请参考不带aliyun的compose文件):
|
||||
|
||||
```
|
||||
* **轻量版(建议内存:2 GB+)**:包含 Shumai 核心应用与 PostgreSQL 数据库。
|
||||
```bash
|
||||
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose-aliyun.yaml
|
||||
```
|
||||
|
||||
* **集成语义搜索版(建议内存:4 GB+)**:新增基于 `shumaiOne/embedding-server` (`EmbeddingGemma 2 740M`) 的本地多模态语义搜索能力。
|
||||
```bash
|
||||
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose-aliyun.embedding.yaml
|
||||
```
|
||||
|
||||
* **完整版(建议内存:8 GB+)**:一站式全功能版本,包含 `embedding-server`、`turntable-renderer`(3D 模型交互转盘预览)与 `Gotenberg`(文档与表格 PDF 代理转码)。
|
||||
```bash
|
||||
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose-aliyun.full.yaml
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> 默认的 Docker Compose 配置使用基于 CPU 的软件转码。如果你的服务器支持硬件加速(NVIDIA NVENC、Intel QuickSync、AMD/Intel VA-API 或 Rockchip RKMPP),请参考 [硬件加速转码配置文档](https://docs.shumai.one/configuration/hardware-transcoding)。
|
||||
|
||||
|
||||
3. 配置环境变量(可选):
|
||||
* `SHUMAI_SERVER_PORT` 用于控制 Shumai 服务监听的端口,默认值为 `3000`。
|
||||
* 默认情况下,该 Docker Compose 部署会自动启用集成的本地存储。若想切换至外部 S3 兼容存储,请在 `environment` 中配置 S3 提供商的环境变量。以下是 AWS S3 和 Cloudflare R2 的配置示例:
|
||||
3. 配置环境变量:
|
||||
* `BETTER_AUTH_URL`:Shumai 服务的外部公开访问基础地址(例如 `https://shumai.example.com` 或 `http://12.34.56.78:3000`),主要用于:
|
||||
* **密码重置链接**:生成 CLI 及管理员重置密码链接(`{BETTER_AUTH_URL}/reset-password?token=...`)。
|
||||
* **邮件通知跳转链接**:作为通知邮件中深度跳转链接的基础地址(若未配置 `APP_URL` 则回退至此)。
|
||||
* **会话 Cookie 安全标记**:根据是否以 `https://` 开头决定是否为浏览器会话 Cookie 启用 `Secure` 属性和 `__Secure-` 前缀。
|
||||
* **MCP OAuth 2.1 与元数据发现**:配置 MCP OAuth 资源标识符(`{BETTER_AUTH_URL}/mcp`)、元数据发现端点,以及外部 MCP OAuth 的默认重定向地址。
|
||||
|
||||
**AWS S3 示例:**
|
||||
```yaml
|
||||
STORAGE_BACKEND: s3
|
||||
S3_BUCKET: your-bucket-name
|
||||
S3_ACCESS_KEY_ID: your-access-key-id
|
||||
S3_SECRET_ACCESS_KEY: your-secret-access-key
|
||||
AWS_ENDPOINT_URL_S3: https://s3.us-east-1.amazonaws.com
|
||||
```
|
||||
> [!NOTE]
|
||||
> **Web UI 的邮箱/密码基础登录**在私有 IP 或局域网 HTTP 环境下即使未配置该变量也可正常使用。但在生产环境、绑定域名或启用 HTTPS 时强烈建议配置。注意:MCP OAuth 2.1 依赖 HTTPS(本地 loopback 除外);若远程部署使用 HTTP,系统会优雅禁用 MCP OAuth 2.1 并记录日志,Web UI 与基于 API Token 的 MCP 访问不受影响。
|
||||
* `BETTER_AUTH_SECRET`:用于对浏览器会话 Cookie、JWT 以及本地存储模式下的预签名上传/下载链接进行 HMAC 签名加密的随机密钥。模板中提供了一个默认占位值以便本地快速体验,**但在生产或公开部署环境中务必生成独立的随机密钥**(例如通过命令 `openssl rand -base64 32` 生成)。
|
||||
* `AWS_ENDPOINT_URL_S3`:默认情况下指向 `http://localhost:{SHUMAI_SERVER_PORT}`。当你使用本地存储(即默认配置 `STORAGE_BACKEND: local`)并在远程服务器、自定义域名或自定义端口上公开访问 Shumai 时,请将 `AWS_ENDPOINT_URL_S3` 设置为客户端浏览器上传和下载文件所使用的外部 URL。
|
||||
|
||||
**Cloudflare R2 示例:**
|
||||
```yaml
|
||||
STORAGE_BACKEND: s3
|
||||
S3_BUCKET: your-bucket-name
|
||||
S3_REGION: auto
|
||||
S3_ACCESS_KEY_ID: your-access-key-id
|
||||
S3_SECRET_ACCESS_KEY: your-secret-access-key
|
||||
AWS_ENDPOINT_URL_S3: https://<account-id>.r2.cloudflarestorage.com
|
||||
```
|
||||
例如,如果你将 `docker-compose.yaml` 中的端口映射从 `3000:3000` 修改为了 `12345:3000`,且服务部署在 IP 为 `12.34.56.78` 的服务器上,请进行如下设置:
|
||||
|
||||
```yaml
|
||||
AWS_ENDPOINT_URL_S3: http://12.34.56.78:12345
|
||||
```
|
||||
|
||||
* 默认情况下 `AWS_ENDPOINT_URL_S3` 指向 `http://localhost:{SHUMAI_SERVER_PORT}`。如果您使用本地存储,但希望在自定义的主机名或端口上公开访问 Shumai,请务必将 `AWS_ENDPOINT_URL_S3` 修改为浏览器访问该服务时所使用的外部 URL。
|
||||
例如,如果您将 `docker-compose.yaml` 中的端口映射从 `3000:3000` 修改为了 `12345:3000`,且服务部署在 IP 为 `12.34.56.78` 的服务器上,请进行如下设置:
|
||||
```
|
||||
AWS_ENDPOINT_URL_S3: http://12.34.56.78:12345
|
||||
此地址必须能够从客户端浏览器正常访问,且必须包含对外暴露的实际端口号。
|
||||
* `SHUMAI_SERVER_PORT` 用于控制 Shumai 服务监听的端口,默认值为 `3000`。
|
||||
* **外部 S3 存储**:默认情况下,该 Docker Compose 部署会自动启用集成的本地存储。若想切换至外部 S3 兼容存储,请在 `environment` 中配置 S3 提供商的环境变量。以下是 AWS S3 和 Cloudflare R2 的配置示例:
|
||||
|
||||
```
|
||||
**AWS S3 示例:**
|
||||
```yaml
|
||||
STORAGE_BACKEND: s3
|
||||
S3_BUCKET: your-bucket-name
|
||||
S3_ACCESS_KEY_ID: your-access-key-id
|
||||
S3_SECRET_ACCESS_KEY: your-secret-access-key
|
||||
AWS_ENDPOINT_URL_S3: https://s3.us-east-1.amazonaws.com
|
||||
```
|
||||
|
||||
|
||||
此地址必须能够从客户端浏览器正常访问,且必须包含对外暴露的实际端口号。
|
||||
**Cloudflare R2 示例:**
|
||||
```yaml
|
||||
STORAGE_BACKEND: s3
|
||||
S3_BUCKET: your-bucket-name
|
||||
S3_REGION: auto
|
||||
S3_ACCESS_KEY_ID: your-access-key-id
|
||||
S3_SECRET_ACCESS_KEY: your-secret-access-key
|
||||
AWS_ENDPOINT_URL_S3: https://<account-id>.r2.cloudflarestorage.com
|
||||
```
|
||||
|
||||
|
||||
4. 在后台启动所有服务:
|
||||
@@ -147,233 +175,91 @@ https://gh-proxy.com/https://raw.githubusercontent.com/shumaiOne/shumai/main/REA
|
||||
```
|
||||
|
||||
|
||||
5. 打开浏览器,访问 `http://localhost:3000` 即可开始使用(若是远程部署,请访问 `http://<您的服务器IP>:3000`)。
|
||||
5. 打开浏览器,访问 `http://localhost:3000` 即可开始使用(若是远程部署,请访问 `http://<你的服务器IP>:3000`)。
|
||||
|
||||
### 方案二:通过 NPM / 包管理器安装
|
||||
#### **扩展转码 Worker(并行处理)**
|
||||
|
||||
通过 NPM 上的 `@shumai-one/shumai` 进行安装。
|
||||
默认情况下,Docker Compose 部署会按顺序逐个处理视频转码任务。这是出于系统设计考虑,因为视频转码属于计算密集型任务,容易耗尽可用的 CPU 或 GPU 资源。
|
||||
|
||||
#### 第一步:启动带 pgvector 支持的 PostgreSQL
|
||||
但在批量上传(例如一次性上传 100+ 个视频)或处理需要耗费数小时的大型原始视频素材时,长时间的转码任务可能会阻塞后续文件的处理。此时,你可以通过增加额外的机器来横向扩展转码吞吐量。每台机器依然按顺序执行任务,但增加 worker 实例能够显著提升整体的并行处理能力。
|
||||
|
||||
Shumai 依赖支持 `pgvector` 扩展的 PostgreSQL 数据库。您可以使用 Docker 快速启动一个预配置好的数据库容器:
|
||||
Shumai 提供了独立的转码 Worker 镜像(支持 Docker Hub 与阿里云镜像源):
|
||||
|
||||
```bash
|
||||
docker run --name shumai_postgres \
|
||||
-e POSTGRES_USER=shumai \
|
||||
-e POSTGRES_PASSWORD=shumai_password \
|
||||
-e POSTGRES_DB=shumai_db \
|
||||
-p 5432:5432 \
|
||||
-d docker.m.daocloud.io/pgvector/pgvector:pg18
|
||||
1. **连接准备**:启动一台临时机器,确保其能够正常访问你的 PostgreSQL 数据库和存储。
|
||||
2. **启动 Worker**:配置相同的数据库与存储连接凭据并运行容器:
|
||||
|
||||
```
|
||||
**阿里云镜像(国内推荐):**
|
||||
```bash
|
||||
docker run -d --name shumai_transcode_worker \
|
||||
-e DATABASE_URL="postgres://shumai:shumai_password@<postgres-host>:5432/shumai_db?sslmode=disable" \
|
||||
-e STORAGE_BACKEND="s3" \
|
||||
-e S3_BUCKET="your-bucket-name" \
|
||||
-e AWS_ENDPOINT_URL_S3="https://s3.us-east-1.amazonaws.com" \
|
||||
-e S3_ACCESS_KEY_ID="your-access-key-id" \
|
||||
-e S3_SECRET_ACCESS_KEY="your-secret-access-key" \
|
||||
crpi-000nkafzu6xvpwsc.cn-hongkong.personal.cr.aliyuncs.com/shumai-one/shumai-transcode:latest
|
||||
```
|
||||
|
||||
#### 第二步:创建工作区目录
|
||||
Worker 启动后会自动接入任务队列,并与主实例并行消费并处理积压的转码任务。
|
||||
|
||||
创建一个专属目录用来存放环境配置和媒体文件(媒体文件默认会保存在 `./data` 目录下):
|
||||
3. **随时停止**:当转码队列处理完毕(或不再需要额外的算力)时,只需停止或移除 Worker 容器:
|
||||
|
||||
```bash
|
||||
mkdir shumai && cd shumai
|
||||
```bash
|
||||
docker stop shumai_transcode_worker
|
||||
```
|
||||
|
||||
```
|
||||
主 Shumai 服务的运行不会受到任何影响,不需要停机。
|
||||
|
||||
#### 步骤 3:安装平台依赖
|
||||
### 方案二:源码编译运行(开发环境)
|
||||
|
||||
#### Linux
|
||||
|
||||
在 Linux 上运行 Shumai 需要安装以下系统依赖:
|
||||
|
||||
- **`ffmpeg`** —— 用于媒体转码和元数据提取。
|
||||
- **`poppler`** (`poppler-utils`) —— 用于 PDF 页面图像提取和 PDF 雪碧图预览生成 (`pdftoppm`)。
|
||||
- **`imagemagick`** —— 用于 PSD 格式图像转码和 sRGB 色彩空间转换。
|
||||
- **`bubblewrap`**、**`socat`** 和 **`ripgrep`** —— AI Agent 沙箱(`anthropic-experimental/sandbox-runtime`)所需,用于进程隔离、网络通信和工作区搜索。
|
||||
|
||||
可以使用以下命令一次性安装所有依赖:
|
||||
|
||||
> Ubuntu/Debian
|
||||
```bash
|
||||
sudo apt install -y ffmpeg poppler-utils imagemagick bubblewrap socat ripgrep
|
||||
```
|
||||
|
||||
> Fedora
|
||||
```bash
|
||||
sudo dnf install -y ffmpeg poppler-utils ImageMagick bubblewrap socat ripgrep
|
||||
```
|
||||
|
||||
> Arch Linux
|
||||
```bash
|
||||
sudo pacman -S --noconfirm ffmpeg poppler imagemagick bubblewrap socat ripgrep
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> **Ubuntu 24.04+** 默认限制非特权用户创建 User Namespace,这会导致 `anthropic-experimental/sandbox-runtime` 无法使用 `bubblewrap` 提供沙箱隔离。
|
||||
>
|
||||
> 如需临时启用 User Namespace,请执行:
|
||||
>
|
||||
> ```bash
|
||||
> sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
|
||||
> ```
|
||||
>
|
||||
> 或者,配置 AppArmor Profile,为相关可执行文件授予所需的 `userns` 权限。
|
||||
|
||||
---
|
||||
|
||||
#### macOS
|
||||
|
||||
在 macOS 上运行 Shumai 需要:
|
||||
|
||||
- **`ffmpeg`** —— 用于媒体转码和元数据提取。
|
||||
- **`poppler`** —— 用于 PDF 页面图像提取和 PDF 雪碧图预览生成 (`pdftoppm`)。
|
||||
- **`imagemagick`** —— 用于 PSD 格式图像转码和 sRGB 色彩空间转换。
|
||||
- **`ripgrep`** —— AI Agent 沙箱(`anthropic-experimental/sandbox-runtime`)所需。
|
||||
|
||||
使用 Homebrew 安装所需依赖:
|
||||
|
||||
```bash
|
||||
brew install ffmpeg poppler imagemagick ripgrep
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### Windows(Alpha)
|
||||
|
||||
> [!WARNING]
|
||||
> anthropic-experimental/sandbox-runtime 的 Windows 支持目前仍处于 **Alpha** 阶段,整体设计仍在持续调整中。
|
||||
>
|
||||
> 当前实现提供了以下能力:
|
||||
> - 通过 **Windows Filtering Platform (WFP)** 实现网络出口(egress)过滤。
|
||||
> - 通过 **ACL Stamping** 实现文件读写权限限制。
|
||||
>
|
||||
> **但这并不能作为针对恶意沙箱进程的安全边界(security boundary)**。
|
||||
>
|
||||
> 未来版本将对沙箱机制进行重大调整,届时沙箱进程将运行在独立的沙箱用户账户下。
|
||||
|
||||
在 Windows 上运行 Shumai 需要:
|
||||
|
||||
- **`ffmpeg`** —— 用于媒体转码和元数据提取。
|
||||
- **`imagemagick`** —— 用于 PSD 格式图像转码和 sRGB 色彩空间转换。
|
||||
|
||||
使用你偏好的包管理器安装所需依赖:
|
||||
|
||||
**winget**
|
||||
```powershell
|
||||
winget install Gyan.FFmpeg ImageMagick.ImageMagick
|
||||
```
|
||||
|
||||
**Chocolatey**
|
||||
```powershell
|
||||
choco install ffmpeg imagemagick
|
||||
```
|
||||
|
||||
#### 第四步:全局安装 Shumai
|
||||
|
||||
使用您常用的包管理器进行全局安装:
|
||||
|
||||
```bash
|
||||
# 使用 NPM
|
||||
npm install -g @shumai-one/shumai
|
||||
|
||||
# 使用 PNPM
|
||||
pnpm add -g @shumai-one/shumai
|
||||
|
||||
# 使用 Bun
|
||||
bun add -g @shumai-one/shumai
|
||||
|
||||
```
|
||||
|
||||
#### 第五步:配置环境配置
|
||||
|
||||
在刚才创建的工作区目录(`shumai/`)下新建一个 `.env` 文件,并填入以下配置:
|
||||
|
||||
```env
|
||||
DATABASE_URL=postgresql://shumai:shumai_password@localhost:5432/shumai_db?schema=public
|
||||
BETTER_AUTH_SECRET=ySxs7DxzHDZBbeeHNPEwBuspYwipBqz5Gk5XdBjNhWw=
|
||||
STORAGE_BACKEND=local
|
||||
SHUMAI_SERVER_PORT=3000
|
||||
AWS_ENDPOINT_URL_S3=http://localhost:3000
|
||||
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> `SHUMAI_SERVER_PORT` 用于设置 Web 服务的启动端口,而 `AWS_ENDPOINT_URL_S3` 供浏览器端构建文件上传链接。
|
||||
> 如果您部署在远程服务器(如 `http://123.456.7.8`)并且做了端口映射(如 Docker 中的 `12345:3000`),请将 `AWS_ENDPOINT_URL_S3` 设置为 `http://123.456.7.8:12345`。
|
||||
|
||||
#### 第六步:启动 Shumai
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Bun 用户特别提示:** 由于发布的包二进制文件包含 `#!/usr/bin/env node` 头部声明(Shebang),直接在终端执行全局命令(例如 `shumai`)默认会通过 Node.js 运行。如果您是用 Bun 安装的并且希望调用 Bun 运行时,请在所有命令前加上 `bun run --bun` 前缀(例如:`bun run --bun shumai`、`bun run --bun shumai -d`、`bun run --bun shumai stop`)。
|
||||
|
||||
在您的工作区目录下执行以下命令启动应用:
|
||||
|
||||
```bash
|
||||
shumai
|
||||
|
||||
```
|
||||
|
||||
您也可以让 Shumai 在后台以守护进程(Daemon)模式运行和管理:
|
||||
|
||||
* **后台模式启动**:
|
||||
```bash
|
||||
shumai -d
|
||||
|
||||
```
|
||||
|
||||
|
||||
* **停止服务**:
|
||||
```bash
|
||||
shumai stop
|
||||
|
||||
```
|
||||
|
||||
|
||||
* **重启服务**:
|
||||
```bash
|
||||
shumai restart
|
||||
|
||||
```
|
||||
|
||||
|
||||
* **查看并跟踪实时日志**:
|
||||
```bash
|
||||
shumai logs
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
启动时,Shumai 会自动执行数据库迁移(Migration)并在 `http://localhost:3000` 拉起 Web 服务。
|
||||
|
||||
---
|
||||
|
||||
### 方案三:源码编译运行(开发环境)
|
||||
|
||||
如果您希望在本地参与 Shumai 的开发,请按以下步骤配置开发环境:
|
||||
如果你希望在本地参与 Shumai 的开发,请按以下步骤配置开发环境:
|
||||
|
||||
1. 克隆代码仓库并安装依赖项:
|
||||
```bash
|
||||
git clone [https://github.com/shumaiOne/shumai.git](https://github.com/shumaiOne/shumai.git)
|
||||
cd shumai
|
||||
bun install
|
||||
```bash
|
||||
git clone https://github.com/shumaiOne/shumai.git
|
||||
cd shumai
|
||||
bun install
|
||||
```
|
||||
|
||||
```
|
||||
2. 启动 `pgvector` 数据库容器:
|
||||
```bash
|
||||
docker run --name shumai_postgres \
|
||||
-e POSTGRES_USER=shumai \
|
||||
-e POSTGRES_PASSWORD=shumai_password \
|
||||
-e POSTGRES_DB=shumai_db \
|
||||
-p 5432:5432 \
|
||||
-d docker.m.daocloud.io/pgvector/pgvector:pg18
|
||||
```
|
||||
|
||||
3. 在项目根目录下创建一个 `.env` 文件,填入以下基础配置:
|
||||
```env
|
||||
DATABASE_URL=postgresql://shumai:shumai_password@localhost:5432/shumai_db?schema=public
|
||||
BETTER_AUTH_SECRET=ySxs7DxzHDZBbeeHNPEwBuspYwipBqz5Gk5XdBjNhWw=
|
||||
BETTER_AUTH_URL=http://localhost:3000
|
||||
STORAGE_BACKEND=local
|
||||
SHUMAI_SERVER_PORT=3000
|
||||
AWS_ENDPOINT_URL_S3=http://localhost:3000
|
||||
```
|
||||
|
||||
2. 启动 `pgvector` 数据库容器(参考**方案二中的第一步**)。
|
||||
3. 参照**方案二中的第五步**,在项目根目录下创建一个 `.env` 文件。
|
||||
4. 生成多语言国际化(i18n)代码:
|
||||
```bash
|
||||
bun run i18n:compile
|
||||
```
|
||||
> [!TIP]
|
||||
> 在前端开发过程中,可以在单独的终端窗口中运行 `bun run i18n:watch`,在修改 `packages/webui/messages/` 下的翻译文案时自动重新编译。
|
||||
```bash
|
||||
bun run i18n:compile
|
||||
```
|
||||
> [!TIP]
|
||||
> 在前端开发过程中,可以在单独的终端窗口中运行 `bun run i18n:watch`,在修改 `packages/webui/messages/` 下的翻译文案时自动重新编译。
|
||||
|
||||
5. 执行数据库结构迁移:
|
||||
```bash
|
||||
bun run db:migrate
|
||||
```
|
||||
```bash
|
||||
bun run db:migrate
|
||||
```
|
||||
|
||||
6. 启动本地开发服务器:
|
||||
```bash
|
||||
bun run dev
|
||||
```
|
||||
```bash
|
||||
bun run dev
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> 如需通过 NPM 或包管理器全局安装运行 Shumai,请参考[官方 NPM 安装指南](https://docs.shumai.one/getting-started/quickstart)。
|
||||
|
||||
|
||||
|
||||
@@ -381,6 +267,30 @@ bun run dev
|
||||
|
||||
## 命令行工具 (CLI)
|
||||
|
||||
Shumai 自带一个功能完备的命令行工具(CLI),支持您直接在终端里高效管理项目、文件夹、资产,批量上传文件/目录,以及快速创建新版本。
|
||||
Shumai 自带一个功能完备的命令行工具(CLI),支持你直接在终端里高效管理项目、文件夹、素材,批量上传文件/目录,以及快速创建新版本。
|
||||
|
||||
关于 CLI 的安装与详细使用指南,请参阅 [CLI Readme](https://www.google.com/search?q=apps/cli/README.md)。
|
||||
macOS/Linux 可直接安装独立 CLI,无需安装 Node.js 或 Bun:
|
||||
|
||||
```sh
|
||||
curl -fsSL https://github.com/shumaiOne/shumai/releases/latest/download/install.sh | sh
|
||||
```
|
||||
|
||||
Windows 用户可使用 PowerShell:
|
||||
|
||||
```powershell
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://github.com/shumaiOne/shumai/releases/latest/download/install.ps1 | iex"
|
||||
```
|
||||
|
||||
仍可通过 npm 安装:`npm install -g @shumai-one/shumai-cli`(需要 Node.js 22.12 或更高版本)。
|
||||
|
||||
关于 CLI 的安装与详细使用指南,请参阅 [CLI Readme](apps/cli/README.md)。
|
||||
|
||||
## MCP 服务器
|
||||
|
||||
Shumai 内置 MCP 服务器(地址为 `/mcp`),Claude Code、Cursor、Kiro 等外部智能体可以使用 API 令牌连接,浏览并整理你的项目。配置方法请参阅 [MCP 服务器指南](docs/developer/mcp-server.mdx)。
|
||||
|
||||
---
|
||||
|
||||
## 社区
|
||||
|
||||
感谢 [LINUX DO](https://linux.do/) 提供开源交流社区,欢迎佬友交流使用体验与改进建议。
|
||||
|
||||
+1
-1
@@ -3,7 +3,7 @@
|
||||
## Reporting a Vulnerability
|
||||
|
||||
Please report security vulnerabilities **privately**. Do not open a public issue,
|
||||
pull request or Discord message for a suspected vulnerability, as that discloses it
|
||||
pull request, or public forum post for a suspected vulnerability, as that discloses it
|
||||
to everyone before a fix exists.
|
||||
|
||||
Use **[GitHub private vulnerability reporting](https://github.com/shumaiOne/shumai/security/advisories/new)**
|
||||
|
||||
@@ -1,14 +0,0 @@
|
||||
{
|
||||
"name": "@shumai/agent-app",
|
||||
"version": "0.4.8",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"bin": {
|
||||
"shumai-agent": "./src/index.ts"
|
||||
},
|
||||
"dependencies": {
|
||||
"@shumai/agent": "workspace:*",
|
||||
"@shumai/core": "workspace:*",
|
||||
"@shumai/workflow-core": "workspace:*"
|
||||
}
|
||||
}
|
||||
@@ -1,39 +0,0 @@
|
||||
import { loadEnvConfig } from '@shumai/core/src/env-loader'
|
||||
loadEnvConfig(process.cwd(), process.env.NODE_ENV !== 'production')
|
||||
|
||||
import { workflowService } from '@shumai/workflow-core'
|
||||
import { TaskQueueAgent } from '@shumai/workflow-core'
|
||||
import { initAgentWorkflows } from '@shumai/agent'
|
||||
import { sandboxService } from '@shumai/core'
|
||||
import { handleDaemonCommands } from '@shumai/core/src/utils/daemon'
|
||||
|
||||
if (process.argv.includes('--check')) {
|
||||
console.log('✅ Agent worker evaluated successfully!')
|
||||
process.exit(0)
|
||||
}
|
||||
|
||||
async function run() {
|
||||
// Initialize workflows and activities
|
||||
initAgentWorkflows()
|
||||
await sandboxService.ensureInitialized().catch((err) => {
|
||||
console.error('Failed to eagerly initialize sandbox in agent worker:', err)
|
||||
})
|
||||
|
||||
console.log('🚀 Starting Agent Worker...')
|
||||
|
||||
const options: { workflowBundle?: unknown; workflowsPath?: string } = {}
|
||||
if (process.env.NODE_ENV === 'production') {
|
||||
// @ts-ignore: Bun temporal plugin macro
|
||||
const { default: workflowBundle } = await import('./workflows.ts:::workflow')
|
||||
options.workflowBundle = workflowBundle
|
||||
} else {
|
||||
options.workflowsPath = new URL('./workflows.ts', import.meta.url).pathname
|
||||
}
|
||||
|
||||
await workflowService.startWorkers(TaskQueueAgent, options)
|
||||
}
|
||||
|
||||
handleDaemonCommands('shumai-agent', run).catch((err) => {
|
||||
console.error(err)
|
||||
process.exit(1)
|
||||
})
|
||||
@@ -1,4 +0,0 @@
|
||||
export * from '@shumai/agent/src/workflows/agent-autofill'
|
||||
export * from '@shumai/agent/src/workflows/agent-chat'
|
||||
export * from '@shumai/agent/src/workflows/agent-embedding'
|
||||
export * from '@shumai/agent/src/workflows/query-embedding-for-search'
|
||||
+247
-6
@@ -2,13 +2,71 @@
|
||||
|
||||
A Command Line Interface (CLI) tool for interacting with your Shumai instance.
|
||||
|
||||
The CLI allows you to view projects, list folder contents, create folders, upload files and directories, and create new versions of existing files directly from the terminal.
|
||||
The CLI allows you to view projects, list folder contents, create folders, upload files and directories, create new versions of existing files, and look at images, video frames, and document pages directly from the terminal.
|
||||
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
The CLI package is bundled inside the Shumai workspace.
|
||||
### Standalone executable
|
||||
|
||||
Install the CLI without Node.js or Bun. The installers download a platform-specific executable from GitHub Releases and verify its SHA-256 checksum.
|
||||
|
||||
**macOS / Linux:**
|
||||
|
||||
```sh
|
||||
curl -fsSL https://github.com/shumaiOne/shumai/releases/latest/download/install.sh | sh
|
||||
```
|
||||
|
||||
**Windows (PowerShell):**
|
||||
|
||||
```powershell
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://github.com/shumaiOne/shumai/releases/latest/download/install.ps1 | iex"
|
||||
```
|
||||
|
||||
| Platform | Architectures | Requirements |
|
||||
| --- | --- | --- |
|
||||
| macOS | Apple Silicon, Intel | macOS 13 or later |
|
||||
| Linux | ARM64, x64 | glibc 2.17 or later; kernel 5.6+ recommended |
|
||||
| Windows | ARM64, x64 | Windows 10 version 1809 or later |
|
||||
|
||||
Native builds use Bun 1.4.4's runtime; x64 CPUs need SSE4.2. See [Bun's system requirements](https://bun.com/docs/installation). Alpine/musl is not included in these native downloads. Native downloads are available for releases containing the installer assets; use npm for earlier releases.
|
||||
|
||||
On macOS/Linux the default directory is `~/.local/bin`. If it is missing from your current PATH, the installer prints a command to run in your current Bash/Zsh terminal:
|
||||
|
||||
```sh
|
||||
export PATH="$HOME/.local/bin:$PATH"
|
||||
```
|
||||
|
||||
To keep the CLI available in future terminals, add the same export line to `~/.bashrc` (Bash) or `~/.zshrc` (Zsh). For Bash login shells, use your existing login profile, such as `~/.bash_profile` or `~/.profile`. Open a new terminal after saving. If you already added it, you do not need to add it again. For a custom installation directory, use the exact command printed by the installer.
|
||||
|
||||
On Windows the installer uses `%LOCALAPPDATA%\Shumai\bin` and updates the user PATH. Open a new terminal afterward. Administrator access is not required.
|
||||
|
||||
Re-run the installer to upgrade. To pin a version, roll back, or choose an installation directory, download the installer and pass its options (replace `X.Y.Z` with a release containing native binaries):
|
||||
|
||||
```sh
|
||||
curl -fsSL https://github.com/shumaiOne/shumai/releases/latest/download/install.sh -o install.sh
|
||||
sh install.sh --version X.Y.Z --install-dir "$HOME/.local/bin"
|
||||
```
|
||||
|
||||
```powershell
|
||||
Invoke-WebRequest https://github.com/shumaiOne/shumai/releases/latest/download/install.ps1 -OutFile install.ps1
|
||||
& .\install.ps1 -Version X.Y.Z -InstallDir "$env:LOCALAPPDATA\Shumai\bin"
|
||||
```
|
||||
|
||||
The installers preserve the existing executable if download or verification fails and refuse to replace unmanaged installations. If an npm installation takes precedence on PATH, uninstall it with `npm uninstall -g @shumai-one/shumai-cli` or adjust PATH.
|
||||
|
||||
To uninstall a native installation, remove `shumai-cli` (`shumai-cli.exe` on Windows) and `.shumai-cli-install` from its installation directory. Remove the PATH entry if it is no longer needed.
|
||||
|
||||
### npm
|
||||
|
||||
The existing npm package continues to run on Node.js 22.12 or later:
|
||||
|
||||
```sh
|
||||
npm install -g @shumai-one/shumai-cli
|
||||
```
|
||||
|
||||
`shumai-cli --version` reports the installed version for either installation method.
|
||||
|
||||
### Environment Setup
|
||||
|
||||
@@ -18,7 +76,8 @@ Before using the CLI, you must set the following environment variables to authen
|
||||
# The endpoint of your Shumai API server (e.g. http://localhost:3000)
|
||||
export SHUMAI_API_SERVER="http://localhost:3000"
|
||||
|
||||
# Your personal API Token (Generate this in the WebUI via Settings -> Developer tab)
|
||||
# Your personal API Token (Generate this in the WebUI via Settings -> API Tokens tab).
|
||||
# The token is shown only once when it is created, so copy it right away.
|
||||
export SHUMAI_API_KEY="your-developer-api-token"
|
||||
|
||||
# Optional: Enable asset deletion capability (disabled by default for safety)
|
||||
@@ -27,10 +86,48 @@ export SHUMAI_ALLOW_DELETE="true"
|
||||
|
||||
---
|
||||
|
||||
## Agent runner
|
||||
|
||||
Create a runner in **Settings → Agent Runners** and copy its one-time key. On macOS, Linux, or Windows, start it in an existing dedicated workspace:
|
||||
|
||||
```sh
|
||||
export SHUMAI_API_SERVER="https://shumai.example.com"
|
||||
export SHUMAI_RUNNER_KEY="your-runner-key"
|
||||
shumai-cli runner start --cwd /path/to/workspace
|
||||
```
|
||||
|
||||
For Windows PowerShell:
|
||||
|
||||
```powershell
|
||||
$env:SHUMAI_API_SERVER = "https://shumai.example.com"
|
||||
$env:SHUMAI_RUNNER_KEY = "your-runner-key"
|
||||
shumai-cli runner start --cwd C:\workspace
|
||||
```
|
||||
|
||||
Use `--url` or `--key` to override those variables. Pass `-v` or `--verbose` to log executed commands, output sizes, and file transfer paths (by default, only lifecycle events, execution IDs, exit status, and durations are printed to stderr). A runner key is separate from `SHUMAI_API_KEY`. The runner stays in the foreground; Ctrl+C stops it and its active commands. Remote servers require HTTPS; localhost and `host.docker.internal` support HTTP for development. No inbound port is opened.
|
||||
|
||||
Commands use `/bin/sh` on macOS and Linux. On Windows, the runner checks for Git Bash in the standard installation directories, then for `bash.exe` on PATH, then falls back to `cmd.exe`. It prints the selected shell at startup and reports it to the agent. Commands run with the local user's permissions unless SRT is requested.
|
||||
|
||||
[Anthropic Sandbox Runtime](https://github.com/anthropics/sandbox-runtime) is bundled with the CLI. Install its platform prerequisites (Linux: bubblewrap, socat, and ripgrep; macOS: ripgrep), then pass its native JSON settings:
|
||||
|
||||
```sh
|
||||
shumai-cli runner start --srt sandbox.json
|
||||
```
|
||||
|
||||
Windows sandboxing uses SRT's alpha Windows support. Use Git Bash if your selected shell is the legacy WSL Bash launcher. Run the one-time SRT setup before starting a sandboxed runner (it requests administrator permission):
|
||||
|
||||
```powershell
|
||||
npx @anthropic-ai/sandbox-runtime windows-install
|
||||
```
|
||||
|
||||
SRT settings are read and validated at startup. Invalid settings or unavailable sandbox prerequisites stop startup; commands never fall back to unrestricted execution. Only shell commands and their children are sandboxed. Runner connections and server-directed file transfers stay outside SRT, and no server domain is automatically allowed. The shared SRT runtime is cleaned up when the runner stops.
|
||||
|
||||
See [Agent Runners](../../docs/using-shumai/agent-sandbox.mdx) for configuration, Docker usage, limits, and security boundaries.
|
||||
|
||||
## Usage
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **For Bun Users:** Since the package binary contains a `#!/usr/bin/env node` shebang, running `shumai-cli` directly will run under Node.js. If you wish to run it using Bun, prefix the command with `bun run --bun` (e.g., `bun run --bun shumai-cli project ls`).
|
||||
> **For npm installations using Bun:** The npm entry point uses `#!/usr/bin/env node`. Use `bun run --bun shumai-cli project ls` to run that package under Bun. Standalone installations already include their runtime.
|
||||
|
||||
Run `shumai-cli` or query specific commands:
|
||||
|
||||
@@ -38,9 +135,17 @@ Run `shumai-cli` or query specific commands:
|
||||
shumai-cli <command> [arguments] [options]
|
||||
```
|
||||
|
||||
Run `shumai-cli --help` to list all commands, and `shumai-cli <command> --help` for a command's arguments and options.
|
||||
|
||||
### Global Options
|
||||
|
||||
- `--json`: Print the raw JSON result instead of human-friendly text, for scripts and tools like `jq`. Example: `shumai-cli ls -p <parentId> --json | jq '.data[].id'`.
|
||||
|
||||
When the output is piped instead of shown in a terminal, tables are printed as tab-separated values without headers.
|
||||
|
||||
### Commands
|
||||
|
||||
#### 1. List Projects
|
||||
#### 1. List and Create Projects
|
||||
|
||||
List all projects you have access to. Returns the project ID, name, and its root folder ID.
|
||||
|
||||
@@ -48,9 +153,15 @@ List all projects you have access to. Returns the project ID, name, and its root
|
||||
shumai-cli project ls
|
||||
```
|
||||
|
||||
Create a new project (returns the project ID and its root folder ID):
|
||||
|
||||
```bash
|
||||
shumai-cli project create "Project Name"
|
||||
```
|
||||
|
||||
#### 2. List Directory Contents
|
||||
|
||||
List direct children (folders and files) of a parent folder.
|
||||
List direct children (folders and files) of a parent folder. Folders are listed first.
|
||||
|
||||
```bash
|
||||
shumai-cli ls -p <parentId>
|
||||
@@ -58,6 +169,9 @@ shumai-cli ls -p <parentId>
|
||||
|
||||
- **Options:**
|
||||
- `-p`, `--parent <id>`: The parent folder ID (required).
|
||||
- `--type <type>`: Only list `file`, `folder`, or `all` (default).
|
||||
- `--first <n>`: Maximum number of items to list (default and maximum: 200).
|
||||
- `--after <cursor>`: Continue a long listing. When more items exist, `ls` prints the cursor to pass here.
|
||||
|
||||
#### 3. Create a New Folder
|
||||
|
||||
@@ -123,6 +237,116 @@ shumai-cli delete <assetId>
|
||||
shumai-cli rm <assetId>
|
||||
```
|
||||
|
||||
#### 9. Read an Asset
|
||||
|
||||
Look at a file: an image, video frames, PDF pages, a 3D model view, or the text of a text file. Prints a summary and a link to each image (links are valid for about an hour), or the file's text.
|
||||
|
||||
```bash
|
||||
# An image, or the 4-view overview of a 3D model
|
||||
shumai-cli read <assetId>
|
||||
# 5 evenly spaced frames between 0s and 30s of a video, downloaded into ./frames
|
||||
shumai-cli read <assetId> --video-start 0 --video-end 30 --video-count 5 --out frames
|
||||
# Pages 1 to 3 of a PDF, or the text of a text file
|
||||
shumai-cli read <assetId> --doc-mode pages --doc-start-page 1 --doc-end-page 3
|
||||
shumai-cli read <assetId> --doc-mode text
|
||||
# A 3D model at 90°
|
||||
shumai-cli read <assetId> --degree 90
|
||||
```
|
||||
|
||||
- **Options:**
|
||||
- `--video-start <s>`, `--video-end <s>`, `--video-count <n>`: Video frames to extract (up to 20).
|
||||
- `--doc-mode <pages|text>`, `--doc-start-page <n>`, `--doc-end-page <n>`: PDF pages to render (up to 20), or `text` to read a text file.
|
||||
- `--degree <deg>`: 3D model angle (0, 15, 30, ..., 345).
|
||||
- `--annotation-id <id>`: Draw a comment's markup on the image, frame, or page.
|
||||
- `-o`, `--out <dir>`: Download the images into a folder and print their paths. With `--json`, each image also gets a `path`.
|
||||
- `--max-wait-seconds <s>`, `--no-wait`: Rendering frames or pages can take a while. `read` waits up to 2 minutes; use these to wait less or return right away. If the render isn't done, `read` prints the `render` command to run next.
|
||||
|
||||
#### 10. Get a Render
|
||||
|
||||
Get the result of a `read` that was still rendering. Takes the same `--out`, `--max-wait-seconds`, and `--no-wait` options as `read`.
|
||||
|
||||
```bash
|
||||
shumai-cli render <taskId> --out frames
|
||||
```
|
||||
|
||||
#### 11. Download Files
|
||||
|
||||
Download up to 50 files at once. By default it saves the web preview version when there is one (for example the transcoded video or the web image), which is smaller; use `--original` for the uploaded file. A version stack downloads its latest version. Folders aren't supported: download the files inside them. Files keep their names; if a name is taken, the new file gets a number, like `clip (2).mp4`.
|
||||
|
||||
```bash
|
||||
shumai-cli download <assetId...> --out ./downloads
|
||||
shumai-cli download <assetId> --original
|
||||
```
|
||||
|
||||
- **Options:**
|
||||
- `-o`, `--out <dir>`: Folder to save the files in (default: the current folder). With `--json`, each file also gets a `path`.
|
||||
- `--original`: Download the original uploaded files instead of the web previews.
|
||||
|
||||
#### 12. Search Files
|
||||
|
||||
Search a folder and all of its subfolders by name, or by meaning with `--semantic` (when AI search is enabled for the team).
|
||||
|
||||
```bash
|
||||
shumai-cli search <query> -p <folderId>
|
||||
shumai-cli search "a calm beach at sunset" -p <folderId> --semantic
|
||||
```
|
||||
|
||||
- **Options:**
|
||||
- `-p`, `--parent <id>`: The folder to search in (required).
|
||||
- `--type <file|folder>`: Search files (default) or folders.
|
||||
- `--first <n>`, `--after <cursor>`: Page through many results.
|
||||
|
||||
#### 13. Copy Assets
|
||||
|
||||
Copy files or folders into another folder of the same team. Prints the IDs of the copies.
|
||||
|
||||
```bash
|
||||
shumai-cli copy <assetId...> -p <parentId> [--with-comments]
|
||||
# or using the short alias:
|
||||
shumai-cli cp <assetId...> -p <parentId>
|
||||
```
|
||||
|
||||
#### 14. Comments
|
||||
|
||||
```bash
|
||||
# List the comments on a file, with their replies
|
||||
shumai-cli comment ls <assetId>
|
||||
# Comment on a file, optionally at a timecode (seconds), or reply to a comment
|
||||
shumai-cli comment add <assetId> "The logo is too small" --at 12.5
|
||||
shumai-cli comment add <assetId> "Fixed in v2" --reply-to <commentId>
|
||||
# Mark a comment as resolved, or unresolved again
|
||||
shumai-cli comment resolve <commentId>
|
||||
shumai-cli comment resolve <commentId> --reopen
|
||||
```
|
||||
|
||||
#### 15. Metadata
|
||||
|
||||
```bash
|
||||
# List a project's metadata fields and their choices
|
||||
shumai-cli field ls <projectId>
|
||||
# Set metadata values on a file, as JSON keyed by field key (select fields take an option id)
|
||||
shumai-cli meta set <assetId> --values '{"status": "approved", "rating": 4}'
|
||||
```
|
||||
|
||||
#### 16. Version Stacks
|
||||
|
||||
```bash
|
||||
# Stack files in the same folder as versions; the first file is the latest
|
||||
shumai-cli version stack <fileId...>
|
||||
# List the versions in a stack, latest first
|
||||
shumai-cli version ls <stackId>
|
||||
# Take a version out of its stack (the file is kept)
|
||||
shumai-cli version unstack <versionId>
|
||||
```
|
||||
|
||||
#### 17. Folder Instructions
|
||||
|
||||
Show a folder's instructions for AI agents (its AGENTS.md).
|
||||
|
||||
```bash
|
||||
shumai-cli instructions <folderId>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Development
|
||||
@@ -132,3 +356,20 @@ To run the CLI in development mode inside the repository source code:
|
||||
```bash
|
||||
bun run apps/cli/src/index.ts project ls
|
||||
```
|
||||
|
||||
### Adding Commands
|
||||
|
||||
Most commands are generated from the shared Operation definitions in `packages/operations` (see "Operations" in `AGENTS.md`). An Operation with the `cli` surface and a `cli` spec becomes a command automatically, with arguments, options, and help text derived from its input schema (key/value inputs such as `meta set --values` take a JSON object). It is also available to Shumai's built-in agent and MCP server. Behavior that needs the local machine, such as downloading files, goes in a CLI extension in `src/operations/extensions/` (extra options, input mapping, and output). Only commands that stream local files (`upload`, `create-version`) are written by hand in `src/program.ts`; the `create_file`, `create_version`, and `complete_upload` Operations are for the agent and MCP only.
|
||||
|
||||
### Building and verifying native releases
|
||||
|
||||
```sh
|
||||
bun run build:cli --target darwin-arm64 # or darwin-x64, linux-arm64, linux-x64, windows-arm64, windows-x64
|
||||
bun run test:cli-release
|
||||
```
|
||||
|
||||
Without `--target`, the build produces all six targets. Output defaults to `out/cli-release`. Set `--out /absolute/path` on either command to change it. Unix archives require `tar`. Creating Windows archives on Unix also requires `zip`. The test exercises installation, runner shell quoting, authenticated API calls, file transfers, and failure recovery. Install Git Bash to run the quoting check on Windows. With SRT configured, pass `--srt /absolute/path/to/settings.json` to repeat the quoting check in the sandbox.
|
||||
|
||||
The Native CLI workflow builds and tests each target on a matching runner. The npm release workflow assembles those tested archives, stages a draft GitHub Release, publishes npm packages, then publishes the completed release. Its `validate_only` dispatch input builds and tests without publishing. Published assets are verified and preserved on retries; draft assets can be replaced while resuming a failed run. Prerelease npm packages use the `next` tag and prerelease GitHub Releases do not become latest.
|
||||
|
||||
Installers use `SHUMAI_CLI_RELEASE_BASE_URL` only when explicitly set, for private mirrors or local testing. It should point to a release download base whose children are `vX.Y.Z/<asset>`. Native executables do not automatically load `.env` or `bunfig.toml`; export the API configuration explicitly as shown above.
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
The Windows Bash discovery and related tests include material adapted from Pi.
|
||||
https://github.com/earendil-works/pi
|
||||
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2025 Mario Zechner
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
+15
-3
@@ -1,17 +1,29 @@
|
||||
{
|
||||
"name": "@shumai/cli",
|
||||
"version": "0.4.8",
|
||||
"version": "0.7.0",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"bin": {
|
||||
"shumai-cli": "./src/index.ts"
|
||||
},
|
||||
"dependencies": {
|
||||
"@anthropic-ai/sandbox-runtime": "0.0.83",
|
||||
"@shumai/api": "workspace:*",
|
||||
"@shumai/core": "workspace:*",
|
||||
"@shumai/dtos": "workspace:*",
|
||||
"@shumai/operations": "workspace:*",
|
||||
"@shumai/tableprinter": "workspace:*",
|
||||
"commander": "15.0.0",
|
||||
"execa": "10.2.1",
|
||||
"hono": "4.13.5",
|
||||
"ulid": "3.0.2"
|
||||
"ulid": "3.0.2",
|
||||
"ws": "8.22.2",
|
||||
"yauzl": "3.4.0",
|
||||
"zod": "4.5.4"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/adm-zip": "0.5.8",
|
||||
"@types/ws": "8.18.2",
|
||||
"@types/yauzl": "3.4.0",
|
||||
"adm-zip": "0.6.1"
|
||||
}
|
||||
}
|
||||
|
||||
+14
-2
@@ -1,7 +1,13 @@
|
||||
import { hc } from 'hono/client'
|
||||
import type { AppType } from '@shumai/api'
|
||||
|
||||
export function getClient() {
|
||||
export interface CliConfig {
|
||||
apiServer: string
|
||||
apiKey: string
|
||||
}
|
||||
|
||||
/** Reads the server URL and API token from the environment, exiting with guidance if missing. */
|
||||
export function getCliConfig(): CliConfig {
|
||||
const apiKey = process.env.SHUMAI_API_KEY
|
||||
const apiServer = process.env.SHUMAI_API_SERVER
|
||||
|
||||
@@ -12,11 +18,17 @@ export function getClient() {
|
||||
|
||||
if (!apiKey) {
|
||||
console.error(
|
||||
'Error: SHUMAI_API_KEY environment variable is not set. Please generate a token in the Settings -> Developer tab.',
|
||||
'Error: SHUMAI_API_KEY environment variable is not set. Please generate a token in the Settings -> API Tokens tab.',
|
||||
)
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
return { apiServer: apiServer.replace(/\/+$/, ''), apiKey }
|
||||
}
|
||||
|
||||
/** Typed REST client, used by commands that are not Operations yet (upload, create-version). */
|
||||
export function getClient() {
|
||||
const { apiServer, apiKey } = getCliConfig()
|
||||
return hc<AppType>(apiServer, {
|
||||
headers: {
|
||||
Authorization: `Bearer ${apiKey}`,
|
||||
|
||||
@@ -1,13 +1,7 @@
|
||||
import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
|
||||
import { projectLs } from './project'
|
||||
import { ls } from './ls'
|
||||
import { mkdir } from './mkdir'
|
||||
import { getClient } from '../client'
|
||||
import { upload } from './upload'
|
||||
import { createVersion } from './create-version'
|
||||
import { rename } from './rename'
|
||||
import { move } from './move'
|
||||
import { deleteAsset } from './delete'
|
||||
import fs from 'node:fs'
|
||||
import http from 'node:http'
|
||||
|
||||
@@ -21,7 +15,7 @@ vi.mock('node:http', () => ({
|
||||
},
|
||||
}))
|
||||
|
||||
describe('CLI Commands', () => {
|
||||
describe('CLI upload commands', () => {
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
let logSpy: any
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
@@ -103,72 +97,6 @@ describe('CLI Commands', () => {
|
||||
}
|
||||
})
|
||||
|
||||
describe('project ls', () => {
|
||||
it('prints list of projects correctly', async () => {
|
||||
mockClient.api.projects.$get.mockResolvedValue({
|
||||
ok: true,
|
||||
json: async () => ({
|
||||
data: [
|
||||
{ id: 'p1', name: 'Proj 1', rootFolder: 'root1' },
|
||||
{ id: 'p2', name: 'Proj 2', rootFolder: 'root2' },
|
||||
],
|
||||
}),
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
} as any)
|
||||
|
||||
await projectLs()
|
||||
|
||||
expect(mockClient.api.projects.$get).toHaveBeenCalledWith({
|
||||
query: { first: '200' },
|
||||
})
|
||||
expect(writeSpy).toHaveBeenCalledWith(expect.stringContaining('Proj 1'))
|
||||
expect(writeSpy).toHaveBeenCalledWith(expect.stringContaining('Proj 2'))
|
||||
})
|
||||
})
|
||||
|
||||
describe('ls', () => {
|
||||
it('queries folders and files and displays table', async () => {
|
||||
mockClient.api.folders[':folderId'].children.$get
|
||||
.mockResolvedValueOnce({
|
||||
ok: true,
|
||||
json: async () => ({
|
||||
data: [{ id: 'subfolder1', name: 'Sub 1', type: 'folder', sizeByte: 0 }],
|
||||
}),
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
} as any)
|
||||
.mockResolvedValueOnce({
|
||||
ok: true,
|
||||
json: async () => ({
|
||||
data: [{ id: 'file1', name: 'doc.pdf', type: 'file', sizeByte: 1024 }],
|
||||
}),
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
} as any)
|
||||
|
||||
await ls('parentId123')
|
||||
|
||||
expect(mockClient.api.folders[':folderId'].children.$get).toHaveBeenCalledTimes(2)
|
||||
expect(writeSpy).toHaveBeenCalledWith(expect.stringContaining('Sub 1'))
|
||||
expect(writeSpy).toHaveBeenCalledWith(expect.stringContaining('doc.pdf'))
|
||||
})
|
||||
})
|
||||
|
||||
describe('mkdir', () => {
|
||||
it('calls POST /folders and prints the folder ID', async () => {
|
||||
mockClient.api.folders.$post.mockResolvedValue({
|
||||
ok: true,
|
||||
json: async () => ({ id: 'new_folder_ulid' }),
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
} as any)
|
||||
|
||||
await mkdir('NewFolder', 'parent_ulid')
|
||||
|
||||
expect(mockClient.api.folders.$post).toHaveBeenCalledWith({
|
||||
json: { name: 'NewFolder', parentId: 'parent_ulid' },
|
||||
})
|
||||
expect(logSpy).toHaveBeenCalledWith('Created folder with ID: new_folder_ulid')
|
||||
})
|
||||
})
|
||||
|
||||
describe('upload', () => {
|
||||
it('uploads a file successfully and confirms the task', async () => {
|
||||
const tempFile = 'temp-test-file.txt'
|
||||
@@ -383,192 +311,4 @@ describe('CLI Commands', () => {
|
||||
}
|
||||
})
|
||||
})
|
||||
|
||||
describe('rename', () => {
|
||||
it('exits with error when assetId or newName is missing', async () => {
|
||||
await expect(rename('', 'new-name')).rejects.toThrow('process.exit(1)')
|
||||
expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('Asset ID is required'))
|
||||
|
||||
await expect(rename('asset-1', '')).rejects.toThrow('process.exit(1)')
|
||||
expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('New name is required'))
|
||||
})
|
||||
|
||||
it('renames a folder when asset type is folder', async () => {
|
||||
mockClient.api.folders[':folderId'].$get.mockResolvedValue({
|
||||
ok: true,
|
||||
json: async () => ({ id: 'f-1', type: 'folder' }),
|
||||
} as unknown as Response)
|
||||
mockClient.api.folders[':folderId'].$put.mockResolvedValue({
|
||||
ok: true,
|
||||
json: async () => ({ id: 'f-1', name: 'Renamed Folder' }),
|
||||
} as unknown as Response)
|
||||
|
||||
await rename('f-1', 'Renamed Folder')
|
||||
|
||||
expect(mockClient.api.folders[':folderId'].$put).toHaveBeenCalledWith({
|
||||
param: { folderId: 'f-1' },
|
||||
json: { name: 'Renamed Folder' },
|
||||
})
|
||||
expect(logSpy).toHaveBeenCalledWith('Renamed asset f-1 to "Renamed Folder"')
|
||||
})
|
||||
|
||||
it('renames a file when asset type is file', async () => {
|
||||
mockClient.api.folders[':folderId'].$get.mockResolvedValue({
|
||||
ok: true,
|
||||
json: async () => ({ id: 'file-1', type: 'file' }),
|
||||
} as unknown as Response)
|
||||
mockClient.api.files[':fileId'].$put.mockResolvedValue({
|
||||
ok: true,
|
||||
json: async () => ({ id: 'file-1', name: 'new.mp4' }),
|
||||
} as unknown as Response)
|
||||
|
||||
await rename('file-1', 'new.mp4')
|
||||
|
||||
expect(mockClient.api.files[':fileId'].$put).toHaveBeenCalledWith({
|
||||
param: { fileId: 'file-1' },
|
||||
json: { name: 'new.mp4' },
|
||||
})
|
||||
expect(logSpy).toHaveBeenCalledWith('Renamed asset file-1 to "new.mp4"')
|
||||
})
|
||||
|
||||
it('exits with error when asset fetch fails', async () => {
|
||||
mockClient.api.folders[':folderId'].$get.mockResolvedValue({
|
||||
ok: false,
|
||||
json: async () => ({ error: 'Asset not found' }),
|
||||
} as unknown as Response)
|
||||
|
||||
await expect(rename('unknown-id', 'name')).rejects.toThrow('process.exit(1)')
|
||||
expect(errorSpy).toHaveBeenCalledWith('Error: Asset not found')
|
||||
})
|
||||
})
|
||||
|
||||
describe('move', () => {
|
||||
it('exits with error when assetIds or parentId is missing', async () => {
|
||||
await expect(move([], 'parent-1')).rejects.toThrow('process.exit(1)')
|
||||
expect(errorSpy).toHaveBeenCalledWith(
|
||||
expect.stringContaining('At least one asset ID is required'),
|
||||
)
|
||||
|
||||
await expect(move(['a-1'], '')).rejects.toThrow('process.exit(1)')
|
||||
expect(errorSpy).toHaveBeenCalledWith(
|
||||
expect.stringContaining('Option -p/--parent <parentId> is required'),
|
||||
)
|
||||
})
|
||||
|
||||
it('successfully moves assets', async () => {
|
||||
mockClient.api.folders[':folderId'].$get.mockResolvedValue({
|
||||
ok: true,
|
||||
json: async () => ({ id: 'parent-1', projectId: 'proj-1' }),
|
||||
} as unknown as Response)
|
||||
mockClient.api.projects[':projectId'].reparent.$post.mockResolvedValue({
|
||||
ok: true,
|
||||
} as unknown as Response)
|
||||
|
||||
await move(['a-1', 'a-2'], 'parent-1')
|
||||
|
||||
expect(mockClient.api.projects[':projectId'].reparent.$post).toHaveBeenCalledWith({
|
||||
param: { projectId: 'proj-1' },
|
||||
json: {
|
||||
assetIds: ['a-1', 'a-2'],
|
||||
newParentId: 'parent-1',
|
||||
},
|
||||
})
|
||||
expect(logSpy).toHaveBeenCalledWith('Moved 2 asset(s) to parent parent-1')
|
||||
})
|
||||
|
||||
it('exits with error when destination parent is not found', async () => {
|
||||
mockClient.api.folders[':folderId'].$get.mockResolvedValue({
|
||||
ok: false,
|
||||
json: async () => ({ error: 'Folder not found' }),
|
||||
} as unknown as Response)
|
||||
|
||||
await expect(move(['a-1'], 'missing-parent')).rejects.toThrow('process.exit(1)')
|
||||
expect(errorSpy).toHaveBeenCalledWith('Error: Folder not found')
|
||||
})
|
||||
})
|
||||
|
||||
describe('deleteAsset', () => {
|
||||
it('exits with error when SHUMAI_ALLOW_DELETE is not set or not true', async () => {
|
||||
delete process.env.SHUMAI_ALLOW_DELETE
|
||||
await expect(deleteAsset(['a-1'])).rejects.toThrow('process.exit(1)')
|
||||
expect(errorSpy).toHaveBeenCalledWith(
|
||||
'Error: Asset deletion is disabled in this environment.',
|
||||
)
|
||||
})
|
||||
|
||||
it('exits with error when assetIds is empty', async () => {
|
||||
process.env.SHUMAI_ALLOW_DELETE = 'true'
|
||||
await expect(deleteAsset([])).rejects.toThrow('process.exit(1)')
|
||||
expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('Asset ID is required'))
|
||||
})
|
||||
|
||||
it('exits with error when more than one asset ID is passed', async () => {
|
||||
process.env.SHUMAI_ALLOW_DELETE = 'true'
|
||||
await expect(deleteAsset(['a-1', 'a-2'])).rejects.toThrow('process.exit(1)')
|
||||
expect(errorSpy).toHaveBeenCalledWith('Error: Can only delete one asset at a time.')
|
||||
})
|
||||
|
||||
it('exits with error when asset is not found', async () => {
|
||||
process.env.SHUMAI_ALLOW_DELETE = 'true'
|
||||
mockClient.api.folders[':folderId'].$get.mockResolvedValue({
|
||||
ok: false,
|
||||
json: async () => ({ error: 'Asset not found' }),
|
||||
} as unknown as Response)
|
||||
|
||||
await expect(deleteAsset(['a-1'])).rejects.toThrow('process.exit(1)')
|
||||
expect(errorSpy).toHaveBeenCalledWith('Error: Asset not found')
|
||||
})
|
||||
|
||||
it('successfully deletes a file when SHUMAI_ALLOW_DELETE is true', async () => {
|
||||
process.env.SHUMAI_ALLOW_DELETE = 'true'
|
||||
mockClient.api.folders[':folderId'].$get.mockResolvedValue({
|
||||
ok: true,
|
||||
json: async () => ({ id: 'a-1', type: 'file' }),
|
||||
} as unknown as Response)
|
||||
mockClient.api.files.$delete.mockResolvedValue({
|
||||
ok: true,
|
||||
} as unknown as Response)
|
||||
|
||||
await deleteAsset(['a-1'])
|
||||
|
||||
expect(mockClient.api.files.$delete).toHaveBeenCalledWith({
|
||||
json: { ids: ['a-1'] },
|
||||
})
|
||||
expect(mockClient.api.folders.$delete).not.toHaveBeenCalled()
|
||||
expect(logSpy).toHaveBeenCalledWith('Deleted asset a-1')
|
||||
})
|
||||
|
||||
it('successfully deletes a folder when SHUMAI_ALLOW_DELETE is 1', async () => {
|
||||
process.env.SHUMAI_ALLOW_DELETE = '1'
|
||||
mockClient.api.folders[':folderId'].$get.mockResolvedValue({
|
||||
ok: true,
|
||||
json: async () => ({ id: 'folder-1', type: 'folder' }),
|
||||
} as unknown as Response)
|
||||
mockClient.api.folders.$delete.mockResolvedValue({
|
||||
ok: true,
|
||||
} as unknown as Response)
|
||||
|
||||
await deleteAsset(['folder-1'])
|
||||
|
||||
expect(mockClient.api.folders.$delete).toHaveBeenCalledWith({
|
||||
json: { ids: ['folder-1'] },
|
||||
})
|
||||
expect(logSpy).toHaveBeenCalledWith('Deleted asset folder-1')
|
||||
})
|
||||
|
||||
it('exits with error when delete API returns an error', async () => {
|
||||
process.env.SHUMAI_ALLOW_DELETE = 'true'
|
||||
mockClient.api.folders[':folderId'].$get.mockResolvedValue({
|
||||
ok: true,
|
||||
json: async () => ({ id: 'a-1', type: 'file' }),
|
||||
} as unknown as Response)
|
||||
mockClient.api.files.$delete.mockResolvedValue({
|
||||
ok: false,
|
||||
json: async () => ({ error: 'Failed to delete' }),
|
||||
} as unknown as Response)
|
||||
|
||||
await expect(deleteAsset(['a-1'])).rejects.toThrow('process.exit(1)')
|
||||
expect(errorSpy).toHaveBeenCalledWith('Error: Failed to delete')
|
||||
})
|
||||
})
|
||||
})
|
||||
|
||||
@@ -1,62 +0,0 @@
|
||||
import { getClient } from '../client'
|
||||
|
||||
export async function deleteAsset(assetIds: string[]) {
|
||||
const isAllowed =
|
||||
process.env.SHUMAI_ALLOW_DELETE === 'true' || process.env.SHUMAI_ALLOW_DELETE === '1'
|
||||
if (!isAllowed) {
|
||||
console.error('Error: Asset deletion is disabled in this environment.')
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
if (!assetIds || assetIds.length === 0) {
|
||||
console.error('Error: Asset ID is required. Usage: shumai-cli delete <assetId>')
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
if (assetIds.length > 1) {
|
||||
console.error('Error: Can only delete one asset at a time.')
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
const assetId = assetIds[0]
|
||||
const client = getClient()
|
||||
|
||||
try {
|
||||
// Inspect asset to determine whether it is a folder or file
|
||||
const getRes = await client.api.folders[':folderId'].$get({
|
||||
param: { folderId: assetId },
|
||||
})
|
||||
|
||||
if (!getRes.ok) {
|
||||
const err = (await getRes.json().catch(() => ({ error: 'Asset not found' }))) as {
|
||||
error?: string
|
||||
}
|
||||
console.error(`Error: ${err.error || 'Asset not found'}`)
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
const asset = await getRes.json()
|
||||
const isFolder = asset.type === 'folder'
|
||||
|
||||
const res = isFolder
|
||||
? await client.api.folders.$delete({
|
||||
json: { ids: [assetId] },
|
||||
})
|
||||
: await client.api.files.$delete({
|
||||
json: { ids: [assetId] },
|
||||
})
|
||||
|
||||
if (!res.ok) {
|
||||
const err = (await res.json().catch(() => ({ error: 'Failed to delete asset' }))) as {
|
||||
error?: string
|
||||
}
|
||||
console.error(`Error: ${err.error || 'Failed to delete asset'}`)
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
console.log(`Deleted asset ${assetId}`)
|
||||
} catch (err) {
|
||||
console.error('Error connecting to API server:', err instanceof Error ? err.message : err)
|
||||
process.exit(1)
|
||||
}
|
||||
}
|
||||
@@ -1,87 +0,0 @@
|
||||
import { newTablePrinter, withTruncate } from '@shumai/tableprinter'
|
||||
import type { AssetInfo } from '@shumai/dtos'
|
||||
import { getClient } from '../client'
|
||||
|
||||
function formatSize(bytes: number): string {
|
||||
if (bytes === 0) return '-'
|
||||
const k = 1024
|
||||
const sizes = ['B', 'KB', 'MB', 'GB', 'TB']
|
||||
const i = Math.floor(Math.log(bytes) / Math.log(k))
|
||||
return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i]
|
||||
}
|
||||
|
||||
export async function ls(parentId: string) {
|
||||
if (!parentId) {
|
||||
console.error('Error: Parent ID (-p/--parent) is required.')
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
const client = getClient()
|
||||
|
||||
try {
|
||||
const [foldersRes, filesRes] = await Promise.all([
|
||||
client.api.folders[':folderId'].children.$get({
|
||||
param: { folderId: parentId },
|
||||
query: { assetType: 'folder', first: '200' },
|
||||
}),
|
||||
client.api.folders[':folderId'].children.$get({
|
||||
param: { folderId: parentId },
|
||||
query: { assetType: 'file', first: '200' },
|
||||
}),
|
||||
])
|
||||
|
||||
if (!foldersRes.ok) {
|
||||
const err = (await foldersRes.json().catch(() => ({ error: 'Unknown error' }))) as {
|
||||
error?: string
|
||||
}
|
||||
console.error(`Error: ${err.error || 'Failed to list folders'}`)
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
if (!filesRes.ok) {
|
||||
const err = (await filesRes.json().catch(() => ({ error: 'Unknown error' }))) as {
|
||||
error?: string
|
||||
}
|
||||
console.error(`Error: ${err.error || 'Failed to list files'}`)
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
const foldersData = await foldersRes.json()
|
||||
const filesData = await filesRes.json()
|
||||
|
||||
const folders = foldersData.data || []
|
||||
const files = filesData.data || []
|
||||
|
||||
const items = [
|
||||
...folders.map((f: AssetInfo) => ({ ...f, typeDisplay: 'folder' as const })),
|
||||
...files.map((f: AssetInfo) => ({ ...f, typeDisplay: 'file' as const })),
|
||||
]
|
||||
|
||||
if (items.length === 0) {
|
||||
console.log('No assets found in this folder.')
|
||||
return
|
||||
}
|
||||
|
||||
const isTty = process.stdout.isTTY
|
||||
const maxWidth = process.stdout.columns || 80
|
||||
const tp = newTablePrinter(process.stdout, isTty, maxWidth)
|
||||
|
||||
tp.addHeader(['ID', 'Name', 'Type', 'Size'])
|
||||
|
||||
for (const item of items) {
|
||||
tp.addField(item.id || '', withTruncate(null))
|
||||
tp.addField(item.name || '')
|
||||
tp.addField(item.typeDisplay, withTruncate(null))
|
||||
tp.addField(
|
||||
item.typeDisplay === 'folder' ? '-' : formatSize(item.sizeByte || 0),
|
||||
withTruncate(null),
|
||||
)
|
||||
tp.endRow()
|
||||
}
|
||||
|
||||
tp.render()
|
||||
} catch (err) {
|
||||
console.error('Error connecting to API server:', err instanceof Error ? err.message : err)
|
||||
process.exit(1)
|
||||
}
|
||||
}
|
||||
@@ -1,32 +0,0 @@
|
||||
import { getClient } from '../client'
|
||||
|
||||
export async function mkdir(name: string, parentId: string) {
|
||||
if (!name) {
|
||||
console.error('Error: Folder name is required.')
|
||||
process.exit(1)
|
||||
}
|
||||
if (!parentId) {
|
||||
console.error('Error: Parent ID (-p/--parent) is required.')
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
const client = getClient()
|
||||
|
||||
try {
|
||||
const res = await client.api.folders.$post({
|
||||
json: { name, parentId },
|
||||
})
|
||||
|
||||
if (!res.ok) {
|
||||
const err = (await res.json().catch(() => ({ error: 'Unknown error' }))) as { error?: string }
|
||||
console.error(`Error: ${err.error || 'Failed to create folder'}`)
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
const created = await res.json()
|
||||
console.log(`Created folder with ID: ${created.id}`)
|
||||
} catch (err) {
|
||||
console.error('Error connecting to API server:', err instanceof Error ? err.message : err)
|
||||
process.exit(1)
|
||||
}
|
||||
}
|
||||
@@ -1,59 +0,0 @@
|
||||
import { getClient } from '../client'
|
||||
|
||||
export async function move(assetIds: string[], parentId: string) {
|
||||
if (!assetIds || assetIds.length === 0) {
|
||||
console.error(
|
||||
'Error: At least one asset ID is required. Usage: shumai-cli move <assetId...> -p <parentId>',
|
||||
)
|
||||
process.exit(1)
|
||||
}
|
||||
if (!parentId) {
|
||||
console.error('Error: Option -p/--parent <parentId> is required.')
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
const client = getClient()
|
||||
|
||||
try {
|
||||
// Fetch destination folder to get its projectId
|
||||
const parentRes = await client.api.folders[':folderId'].$get({
|
||||
param: { folderId: parentId },
|
||||
})
|
||||
|
||||
if (!parentRes.ok) {
|
||||
const err = (await parentRes.json().catch(() => ({ error: 'Parent folder not found' }))) as {
|
||||
error?: string
|
||||
}
|
||||
console.error(`Error: ${err.error || 'Parent folder not found'}`)
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
const parentInfo = await parentRes.json()
|
||||
const projectId = parentInfo.projectId
|
||||
if (!projectId) {
|
||||
console.error('Error: Destination parent folder is not associated with a project.')
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
const res = await client.api.projects[':projectId'].reparent.$post({
|
||||
param: { projectId },
|
||||
json: {
|
||||
assetIds,
|
||||
newParentId: parentId,
|
||||
},
|
||||
})
|
||||
|
||||
if (!res.ok) {
|
||||
const err = (await res.json().catch(() => ({ error: 'Failed to move assets' }))) as {
|
||||
error?: string
|
||||
}
|
||||
console.error(`Error: ${err.error || 'Failed to move assets'}`)
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
console.log(`Moved ${assetIds.length} asset(s) to parent ${parentId}`)
|
||||
} catch (err) {
|
||||
console.error('Error connecting to API server:', err instanceof Error ? err.message : err)
|
||||
process.exit(1)
|
||||
}
|
||||
}
|
||||
@@ -1,42 +0,0 @@
|
||||
import { newTablePrinter } from '@shumai/tableprinter'
|
||||
import { getClient } from '../client'
|
||||
|
||||
export async function projectLs() {
|
||||
const client = getClient()
|
||||
try {
|
||||
const res = await client.api.projects.$get({
|
||||
query: { first: '200' },
|
||||
})
|
||||
|
||||
if (!res.ok) {
|
||||
const err = (await res.json().catch(() => ({ error: 'Unknown error' }))) as { error?: string }
|
||||
console.error(`Error: ${err.error || 'Failed to list projects'}`)
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
const { data: projects } = await res.json()
|
||||
|
||||
if (projects.length === 0) {
|
||||
console.log('No projects found.')
|
||||
return
|
||||
}
|
||||
|
||||
const isTty = process.stdout.isTTY
|
||||
const maxWidth = process.stdout.columns || 80
|
||||
const tp = newTablePrinter(process.stdout, isTty, maxWidth)
|
||||
|
||||
tp.addHeader(['ID', 'Name', 'Root Folder ID'])
|
||||
|
||||
for (const p of projects) {
|
||||
tp.addField(p.id || '')
|
||||
tp.addField(p.name || '')
|
||||
tp.addField(p.rootFolder || '')
|
||||
tp.endRow()
|
||||
}
|
||||
|
||||
tp.render()
|
||||
} catch (err) {
|
||||
console.error('Error connecting to API server:', err instanceof Error ? err.message : err)
|
||||
process.exit(1)
|
||||
}
|
||||
}
|
||||
@@ -1,55 +0,0 @@
|
||||
import { getClient } from '../client'
|
||||
|
||||
export async function rename(assetId: string, newName: string) {
|
||||
if (!assetId) {
|
||||
console.error('Error: Asset ID is required. Usage: shumai-cli rename <assetId> <newName>')
|
||||
process.exit(1)
|
||||
}
|
||||
if (!newName) {
|
||||
console.error('Error: New name is required. Usage: shumai-cli rename <assetId> <newName>')
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
const client = getClient()
|
||||
|
||||
try {
|
||||
// Determine whether asset is a folder or a file
|
||||
const getRes = await client.api.folders[':folderId'].$get({
|
||||
param: { folderId: assetId },
|
||||
})
|
||||
|
||||
if (!getRes.ok) {
|
||||
const err = (await getRes.json().catch(() => ({ error: 'Asset not found' }))) as {
|
||||
error?: string
|
||||
}
|
||||
console.error(`Error: ${err.error || 'Asset not found'}`)
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
const asset = await getRes.json()
|
||||
const isFolder = asset.type === 'folder'
|
||||
|
||||
const updateRes = isFolder
|
||||
? await client.api.folders[':folderId'].$put({
|
||||
param: { folderId: assetId },
|
||||
json: { name: newName },
|
||||
})
|
||||
: await client.api.files[':fileId'].$put({
|
||||
param: { fileId: assetId },
|
||||
json: { name: newName },
|
||||
})
|
||||
|
||||
if (!updateRes.ok) {
|
||||
const err = (await updateRes.json().catch(() => ({ error: 'Failed to rename asset' }))) as {
|
||||
error?: string
|
||||
}
|
||||
console.error(`Error: ${err.error || 'Failed to rename asset'}`)
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
console.log(`Renamed asset ${assetId} to "${newName}"`)
|
||||
} catch (err) {
|
||||
console.error('Error connecting to API server:', err instanceof Error ? err.message : err)
|
||||
process.exit(1)
|
||||
}
|
||||
}
|
||||
+7
-138
@@ -1,140 +1,9 @@
|
||||
import { projectLs } from './commands/project'
|
||||
import { ls } from './commands/ls'
|
||||
import { mkdir } from './commands/mkdir'
|
||||
import { upload } from './commands/upload'
|
||||
import { createVersion } from './commands/create-version'
|
||||
import { rename } from './commands/rename'
|
||||
import { move } from './commands/move'
|
||||
import { deleteAsset } from './commands/delete'
|
||||
import { formatCliError } from './operations/errors'
|
||||
import { createProgram } from './program'
|
||||
|
||||
function printHelp() {
|
||||
console.log(`
|
||||
Usage: shumai-cli <command> [arguments] [options]
|
||||
|
||||
Commands:
|
||||
project ls List all projects (returns id, name, root folder id)
|
||||
ls -p <parentId> List direct children of a parent folder (returns id, name, type, size)
|
||||
mkdir <name> -p <parentId> Create a new folder in a parent folder
|
||||
upload <path> -p <parentId> Upload a local file or folder to a parent folder
|
||||
create-version <path> -p <id> Create a new version of an existing file or version stack
|
||||
rename <assetId> <newName> Rename an existing file or folder
|
||||
move <assetIds...> -p <target> Move one or more assets to a destination parent folder (alias: mv)
|
||||
delete <assetId> Delete a single file or folder (alias: rm)
|
||||
|
||||
Options:
|
||||
-p, --parent <id> The parent folder/asset ID (required for ls, mkdir, upload, create-version, move)
|
||||
-h, --help Show help details
|
||||
`)
|
||||
}
|
||||
|
||||
async function main() {
|
||||
const args = process.argv.slice(2)
|
||||
if (args.length === 0 || args.includes('-h') || args.includes('--help')) {
|
||||
printHelp()
|
||||
process.exit(0)
|
||||
}
|
||||
|
||||
const cmd = args[0]
|
||||
|
||||
let parentId = ''
|
||||
const parentIdx = args.findIndex((a) => a === '-p' || a === '--parent')
|
||||
if (parentIdx !== -1 && parentIdx + 1 < args.length) {
|
||||
parentId = args[parentIdx + 1]
|
||||
}
|
||||
|
||||
const cleanArgs: string[] = []
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
if (args[i] === '-p' || args[i] === '--parent') {
|
||||
i++
|
||||
} else {
|
||||
cleanArgs.push(args[i])
|
||||
}
|
||||
}
|
||||
|
||||
if (cmd === 'project' && cleanArgs[1] === 'ls') {
|
||||
await projectLs()
|
||||
} else if (cmd === 'ls') {
|
||||
if (!parentId) {
|
||||
console.error('Error: Option -p/--parent <parentId> is required.')
|
||||
process.exit(1)
|
||||
}
|
||||
await ls(parentId)
|
||||
} else if (cmd === 'mkdir') {
|
||||
const name = cleanArgs[1]
|
||||
if (!name) {
|
||||
console.error(
|
||||
'Error: Folder name is required. Usage: shumai-cli mkdir <folderName> -p <parentId>',
|
||||
)
|
||||
process.exit(1)
|
||||
}
|
||||
if (!parentId) {
|
||||
console.error('Error: Option -p/--parent <parentId> is required.')
|
||||
process.exit(1)
|
||||
}
|
||||
await mkdir(name, parentId)
|
||||
} else if (cmd === 'upload') {
|
||||
const localPath = cleanArgs[1]
|
||||
if (!localPath) {
|
||||
console.error(
|
||||
'Error: File/folder path is required. Usage: shumai-cli upload <localPath> -p <parentId>',
|
||||
)
|
||||
process.exit(1)
|
||||
}
|
||||
if (!parentId) {
|
||||
console.error('Error: Option -p/--parent <parentId> is required.')
|
||||
process.exit(1)
|
||||
}
|
||||
await upload(localPath, parentId)
|
||||
} else if (cmd === 'create-version') {
|
||||
const localPath = cleanArgs[1]
|
||||
if (!localPath) {
|
||||
console.error(
|
||||
'Error: Local file path is required. Usage: shumai-cli create-version <localPath> -p <parentAssetId>',
|
||||
)
|
||||
process.exit(1)
|
||||
}
|
||||
if (!parentId) {
|
||||
console.error('Error: Option -p/--parent <parentAssetId> is required.')
|
||||
process.exit(1)
|
||||
}
|
||||
await createVersion(localPath, parentId)
|
||||
} else if (cmd === 'rename') {
|
||||
const assetId = cleanArgs[1]
|
||||
const newName = cleanArgs[2]
|
||||
if (!assetId || !newName) {
|
||||
console.error(
|
||||
'Error: Asset ID and new name are required. Usage: shumai-cli rename <assetId> <newName>',
|
||||
)
|
||||
process.exit(1)
|
||||
}
|
||||
await rename(assetId, newName)
|
||||
} else if (cmd === 'move' || cmd === 'mv') {
|
||||
const assetIds = cleanArgs.slice(1)
|
||||
if (assetIds.length === 0) {
|
||||
console.error(
|
||||
'Error: At least one asset ID is required. Usage: shumai-cli move <assetId...> -p <parentId>',
|
||||
)
|
||||
process.exit(1)
|
||||
}
|
||||
if (!parentId) {
|
||||
console.error('Error: Option -p/--parent <parentId> is required.')
|
||||
process.exit(1)
|
||||
}
|
||||
await move(assetIds, parentId)
|
||||
} else if (cmd === 'delete' || cmd === 'rm') {
|
||||
const assetIds = cleanArgs.slice(1)
|
||||
if (assetIds.length === 0) {
|
||||
console.error('Error: Asset ID is required. Usage: shumai-cli delete <assetId>')
|
||||
process.exit(1)
|
||||
}
|
||||
await deleteAsset(assetIds)
|
||||
} else {
|
||||
console.error(`Error: Unknown command "${cmd}". Run "shumai-cli --help" for usage.`)
|
||||
createProgram()
|
||||
.parseAsync(process.argv)
|
||||
.catch((err: unknown) => {
|
||||
console.error(formatCliError(err))
|
||||
process.exit(1)
|
||||
}
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
console.error('Unexpected error:', err)
|
||||
process.exit(1)
|
||||
})
|
||||
})
|
||||
|
||||
@@ -0,0 +1,78 @@
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
|
||||
import { createFolder, listProjects } from '@shumai/operations'
|
||||
import { callOperation } from './call-operation'
|
||||
import { CliError } from './errors'
|
||||
|
||||
describe('callOperation', () => {
|
||||
const env = { ...process.env }
|
||||
const fetchMock = vi.fn<typeof fetch>()
|
||||
|
||||
beforeEach(() => {
|
||||
process.env.SHUMAI_API_SERVER = 'http://shumai.test/'
|
||||
process.env.SHUMAI_API_KEY = 'shumai_token'
|
||||
vi.stubGlobal('fetch', fetchMock)
|
||||
})
|
||||
|
||||
afterEach(() => {
|
||||
process.env = { ...env }
|
||||
vi.unstubAllGlobals()
|
||||
fetchMock.mockReset()
|
||||
})
|
||||
|
||||
const json = (body: unknown, status = 200) =>
|
||||
new Response(JSON.stringify(body), {
|
||||
status,
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
})
|
||||
|
||||
it('posts the input to /api/ops/:name with the token and CLI attribution', async () => {
|
||||
const folder = { id: 'f1', name: 'Renders', type: 'folder', size: 0, projectId: 'p1' }
|
||||
fetchMock.mockResolvedValue(json(folder))
|
||||
|
||||
const output = await callOperation(createFolder, { parent: 'root', name: 'Renders' })
|
||||
|
||||
expect(output).toEqual(folder)
|
||||
const [url, init] = fetchMock.mock.calls[0]
|
||||
expect(url).toBe('http://shumai.test/api/ops/create_folder')
|
||||
expect(init).toMatchObject({
|
||||
method: 'POST',
|
||||
headers: {
|
||||
Authorization: 'Bearer shumai_token',
|
||||
'Content-Type': 'application/json',
|
||||
'x-shumai-client': 'cli',
|
||||
},
|
||||
body: JSON.stringify({ parent: 'root', name: 'Renders' }),
|
||||
})
|
||||
})
|
||||
|
||||
it('throws the server error message', async () => {
|
||||
fetchMock.mockResolvedValue(json({ error: 'User is not a member of the team' }, 403))
|
||||
|
||||
await expect(callOperation(listProjects, {})).rejects.toEqual(
|
||||
new CliError('User is not a member of the team'),
|
||||
)
|
||||
})
|
||||
|
||||
it('falls back to the status when the error body is not JSON', async () => {
|
||||
fetchMock.mockResolvedValue(new Response('Bad gateway', { status: 502 }))
|
||||
|
||||
await expect(callOperation(listProjects, {})).rejects.toThrow('Request failed with status 502')
|
||||
})
|
||||
|
||||
it('reports connection failures', async () => {
|
||||
fetchMock.mockRejectedValue(new TypeError('fetch failed'))
|
||||
|
||||
await expect(callOperation(listProjects, {})).rejects.toMatchObject({
|
||||
message: 'Error connecting to API server: fetch failed',
|
||||
prefixed: true,
|
||||
})
|
||||
})
|
||||
|
||||
it('rejects responses that do not match the output schema', async () => {
|
||||
fetchMock.mockResolvedValue(json({ unexpected: true }))
|
||||
|
||||
await expect(callOperation(listProjects, {})).rejects.toThrow(
|
||||
'Unexpected response from server for list_projects',
|
||||
)
|
||||
})
|
||||
})
|
||||
@@ -0,0 +1,55 @@
|
||||
import type { z } from 'zod'
|
||||
import type { AnyOperationDefinition } from '@shumai/operations'
|
||||
import { getCliConfig } from '../client'
|
||||
import { CliError } from './errors'
|
||||
|
||||
/** Header that attributes invocations to the CLI (`via: cli`) in audit logs. */
|
||||
const CLIENT_HEADER = 'x-shumai-client'
|
||||
|
||||
/** Signature used by generated commands, which only see type-erased definitions. */
|
||||
export type CallOperation = (
|
||||
definition: AnyOperationDefinition,
|
||||
input: Record<string, unknown>,
|
||||
) => Promise<unknown>
|
||||
|
||||
/** Runs an Operation on the server via `POST /api/ops/:name`. */
|
||||
export async function callOperation<TDef extends AnyOperationDefinition>(
|
||||
definition: TDef,
|
||||
input: z.output<TDef['input']>,
|
||||
): Promise<z.output<TDef['output']>> {
|
||||
const { apiServer, apiKey } = getCliConfig()
|
||||
|
||||
let res: Response
|
||||
try {
|
||||
res = await fetch(`${apiServer}/api/ops/${definition.name}`, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
Authorization: `Bearer ${apiKey}`,
|
||||
'Content-Type': 'application/json',
|
||||
[CLIENT_HEADER]: 'cli',
|
||||
},
|
||||
body: JSON.stringify(input),
|
||||
})
|
||||
} catch (err) {
|
||||
throw new CliError(
|
||||
`Error connecting to API server: ${err instanceof Error ? err.message : String(err)}`,
|
||||
{ prefixed: true },
|
||||
)
|
||||
}
|
||||
|
||||
const body: unknown = await res.json().catch(() => undefined)
|
||||
if (!res.ok) {
|
||||
const message =
|
||||
body && typeof body === 'object' && 'error' in body && typeof body.error === 'string'
|
||||
? body.error
|
||||
: `Request failed with status ${res.status}`
|
||||
throw new CliError(message)
|
||||
}
|
||||
|
||||
const parsed = definition.output.safeParse(body)
|
||||
if (!parsed.success) {
|
||||
throw new CliError(`Unexpected response from server for ${definition.name}`)
|
||||
}
|
||||
// safeParse on the generic schema type loses the concrete shape; the schema guarantees it.
|
||||
return parsed.data as z.output<TDef['output']>
|
||||
}
|
||||
@@ -0,0 +1,18 @@
|
||||
/** An expected failure, printed as `Error: <message>` with exit code 1. */
|
||||
export class CliError extends Error {
|
||||
/** When true, the message already carries its own prefix and is printed as-is. */
|
||||
readonly prefixed: boolean
|
||||
|
||||
constructor(message: string, options: { prefixed?: boolean } = {}) {
|
||||
super(message)
|
||||
this.name = 'CliError'
|
||||
this.prefixed = options.prefixed ?? false
|
||||
}
|
||||
}
|
||||
|
||||
export function formatCliError(err: unknown): string {
|
||||
if (err instanceof CliError) {
|
||||
return err.prefixed ? err.message : `Error: ${err.message}`
|
||||
}
|
||||
return `Unexpected error: ${err instanceof Error ? err.message : String(err)}`
|
||||
}
|
||||
@@ -0,0 +1,103 @@
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
|
||||
import { mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises'
|
||||
import { tmpdir } from 'node:os'
|
||||
import * as path from 'node:path'
|
||||
import type { DownloadAssetOutput } from '@shumai/operations'
|
||||
import { CliError } from '../errors'
|
||||
import { downloadAssetExtension, safeFileName, uniquePath } from './download-asset'
|
||||
|
||||
const output: DownloadAssetOutput = {
|
||||
files: [
|
||||
{
|
||||
assetId: 'a-1',
|
||||
name: 'clip.mp4',
|
||||
kind: 'proxy',
|
||||
size: 2048,
|
||||
mimeType: 'video/mp4',
|
||||
url: 'https://files.example/a-1',
|
||||
},
|
||||
{
|
||||
assetId: 'a-2',
|
||||
name: 'clip.mp4',
|
||||
kind: 'original',
|
||||
size: 10,
|
||||
mimeType: 'video/mp4',
|
||||
url: 'https://files.example/a-2',
|
||||
},
|
||||
],
|
||||
}
|
||||
|
||||
describe('download CLI extension', () => {
|
||||
let dir: string
|
||||
let written: string
|
||||
|
||||
beforeEach(async () => {
|
||||
dir = await mkdtemp(path.join(tmpdir(), 'shumai-cli-download-'))
|
||||
written = ''
|
||||
vi.stubGlobal(
|
||||
'fetch',
|
||||
vi.fn(async (url: string) => new Response(`bytes of ${url}`, { status: 200 })),
|
||||
)
|
||||
})
|
||||
|
||||
afterEach(async () => {
|
||||
vi.unstubAllGlobals()
|
||||
await rm(dir, { recursive: true, force: true })
|
||||
})
|
||||
|
||||
const o = () => ({ out: { write: (s: string) => void (written += s) }, isTty: true, columns: 80 })
|
||||
|
||||
it('saves every file, numbering names that are already taken', async () => {
|
||||
await writeFile(path.join(dir, 'clip.mp4'), 'existing')
|
||||
|
||||
await downloadAssetExtension.present(output, { opts: { out: dir }, json: false, output: o() })
|
||||
|
||||
expect((await readdir(dir)).sort()).toEqual(['clip (2).mp4', 'clip (3).mp4', 'clip.mp4'])
|
||||
expect(await readFile(path.join(dir, 'clip.mp4'), 'utf8')).toBe('existing')
|
||||
expect(await readFile(path.join(dir, 'clip (2).mp4'), 'utf8')).toBe(
|
||||
'bytes of https://files.example/a-1',
|
||||
)
|
||||
expect(written).toBe(
|
||||
`Saved ${path.join(dir, 'clip (2).mp4')} (2 KB, proxy)\nSaved ${path.join(dir, 'clip (3).mp4')} (10 B, original)\n`,
|
||||
)
|
||||
})
|
||||
|
||||
it('creates the folder and prints JSON with the saved paths', async () => {
|
||||
const out = path.join(dir, 'nested', 'files')
|
||||
await downloadAssetExtension.present(output, { opts: { out }, json: true, output: o() })
|
||||
|
||||
const printed = JSON.parse(written) as { files: Array<{ path: string; url: string }> }
|
||||
expect(printed.files.map((f) => f.path)).toEqual([
|
||||
path.join(out, 'clip.mp4'),
|
||||
path.join(out, 'clip (2).mp4'),
|
||||
])
|
||||
expect(printed.files[0].url).toBe('https://files.example/a-1')
|
||||
})
|
||||
|
||||
it('fails clearly when a download fails', async () => {
|
||||
vi.stubGlobal(
|
||||
'fetch',
|
||||
vi.fn(async () => new Response('gone', { status: 403 })),
|
||||
)
|
||||
await expect(
|
||||
downloadAssetExtension.present(output, { opts: { out: dir }, json: false, output: o() }),
|
||||
).rejects.toThrow(new CliError('Failed to download "clip.mp4" (status 403).'))
|
||||
})
|
||||
|
||||
it('keeps file names inside the target folder', () => {
|
||||
expect(safeFileName('../../etc/passwd')).toBe('_.._etc_passwd')
|
||||
expect(safeFileName('a\\b.txt')).toBe('a_b.txt')
|
||||
expect(safeFileName('...')).toBe('file')
|
||||
const taken = new Set<string>()
|
||||
expect(uniquePath(dir, 'notes', taken)).toBe(path.join(dir, 'notes'))
|
||||
expect(uniquePath(dir, 'notes', taken)).toBe(path.join(dir, 'notes (2)'))
|
||||
})
|
||||
|
||||
it('maps --original to proxy false', () => {
|
||||
expect(downloadAssetExtension.toInput!({ assetIds: ['a'] }, { original: true })).toEqual({
|
||||
assetIds: ['a'],
|
||||
proxy: false,
|
||||
})
|
||||
expect(downloadAssetExtension.toInput!({ assetIds: ['a'] }, {})).toEqual({ assetIds: ['a'] })
|
||||
})
|
||||
})
|
||||
@@ -0,0 +1,58 @@
|
||||
import { existsSync } from 'node:fs'
|
||||
import { mkdir } from 'node:fs/promises'
|
||||
import * as path from 'node:path'
|
||||
import { Option } from 'commander'
|
||||
import type { DownloadAssetOutput } from '@shumai/operations'
|
||||
import type { CliCommandExtension } from '../generate'
|
||||
import { formatSize } from '../render'
|
||||
import { saveUrlToFile } from './save-url'
|
||||
|
||||
/** A file name that is safe to create inside the target folder (no paths or control chars). */
|
||||
export function safeFileName(name: string): string {
|
||||
const safe = name
|
||||
// eslint-disable-next-line no-control-regex
|
||||
.replace(/[\x00-\x1f\x7f/\\]/g, '_')
|
||||
.replace(/^[\s.]+|[\s.]+$/g, '')
|
||||
return safe || 'file'
|
||||
}
|
||||
|
||||
/** `name.ext`, or `name (2).ext`, `name (3).ext`, ... if taken on disk or in this download. */
|
||||
export function uniquePath(dir: string, name: string, taken: Set<string>): string {
|
||||
const ext = path.extname(name)
|
||||
const stem = ext ? name.slice(0, -ext.length) : name
|
||||
for (let n = 1; ; n++) {
|
||||
const candidate = path.join(dir, n === 1 ? name : `${stem} (${n})${ext}`)
|
||||
if (!taken.has(candidate) && !existsSync(candidate)) {
|
||||
taken.add(candidate)
|
||||
return candidate
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/** `download`: saves each file into `--out` (the current folder by default). */
|
||||
export const downloadAssetExtension: CliCommandExtension = {
|
||||
options: () => [
|
||||
new Option('-o, --out <dir>', 'Folder to save the files in.').default('.'),
|
||||
new Option('--original', 'Download the original uploaded files instead of the web previews.'),
|
||||
],
|
||||
toInput: (input, opts) => (opts.original === true ? { ...input, proxy: false } : input),
|
||||
async present(raw, { opts, json, output: o }) {
|
||||
const output = raw as DownloadAssetOutput
|
||||
const dir = typeof opts.out === 'string' ? opts.out : '.'
|
||||
await mkdir(dir, { recursive: true })
|
||||
const taken = new Set<string>()
|
||||
const saved: string[] = []
|
||||
for (const file of output.files) {
|
||||
const filePath = uniquePath(dir, safeFileName(file.name), taken)
|
||||
await saveUrlToFile(file.url, filePath, file.name)
|
||||
saved.push(filePath)
|
||||
if (!json) {
|
||||
o.out.write(`Saved ${filePath} (${formatSize(file.size)}, ${file.kind})\n`)
|
||||
}
|
||||
}
|
||||
if (json) {
|
||||
const files = output.files.map((file, i) => ({ ...file, path: saved[i] }))
|
||||
o.out.write(`${JSON.stringify({ files }, null, 2)}\n`)
|
||||
}
|
||||
},
|
||||
}
|
||||
@@ -0,0 +1,10 @@
|
||||
import type { CliCommandExtension } from '../generate'
|
||||
import { downloadAssetExtension } from './download-asset'
|
||||
import { getAssetRenderExtension, readAssetExtension } from './read-asset'
|
||||
|
||||
/** CLI-specific behavior for generated commands, by Operation name. */
|
||||
export const cliExtensions: ReadonlyMap<string, CliCommandExtension> = new Map([
|
||||
['read_asset', readAssetExtension],
|
||||
['get_asset_render', getAssetRenderExtension],
|
||||
['download_asset', downloadAssetExtension],
|
||||
])
|
||||
@@ -0,0 +1,98 @@
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
|
||||
import { mkdtemp, readFile, rm } from 'node:fs/promises'
|
||||
import { tmpdir } from 'node:os'
|
||||
import * as path from 'node:path'
|
||||
import type { AssetReadOutput } from '@shumai/operations'
|
||||
import { CliError } from '../errors'
|
||||
import { downloadImages, imageFileName, readAssetExtension } from './read-asset'
|
||||
|
||||
const output: AssetReadOutput = {
|
||||
status: 'ready',
|
||||
summary: 'Rendered 2 page(s) of "deck.pdf" (Pages 1 to 2):',
|
||||
asset: { id: 'doc-1', name: 'deck.pdf', kind: 'document', mediaType: 'application/pdf' },
|
||||
details: [],
|
||||
images: [
|
||||
{ label: 'Page 1', mimeType: 'image/webp', url: 'https://files.example/p1' },
|
||||
{ label: 'Page 2', mimeType: 'image/png', url: 'https://files.example/p2' },
|
||||
],
|
||||
}
|
||||
|
||||
describe('read / render CLI extension', () => {
|
||||
let dir: string
|
||||
let written: string
|
||||
|
||||
beforeEach(async () => {
|
||||
dir = await mkdtemp(path.join(tmpdir(), 'shumai-cli-read-'))
|
||||
written = ''
|
||||
vi.stubGlobal(
|
||||
'fetch',
|
||||
vi.fn(async (url: string) => new Response(`bytes of ${url}`, { status: 200 })),
|
||||
)
|
||||
})
|
||||
|
||||
afterEach(async () => {
|
||||
vi.unstubAllGlobals()
|
||||
await rm(dir, { recursive: true, force: true })
|
||||
})
|
||||
|
||||
const o = () => ({ out: { write: (s: string) => void (written += s) }, isTty: true, columns: 80 })
|
||||
|
||||
it('names files after the asset, position, and label', () => {
|
||||
expect(imageFileName('vid-1', 0, { label: 'Frame at 2.5s', mimeType: 'image/webp' })).toBe(
|
||||
'vid-1-1-frame-at-2.5s.webp',
|
||||
)
|
||||
expect(imageFileName('m-1', 3, { label: 'View at 90°', mimeType: 'image/jpeg' })).toBe(
|
||||
'm-1-4-view-at-90.jpg',
|
||||
)
|
||||
})
|
||||
|
||||
it('downloads every image with --out and prints the saved paths', async () => {
|
||||
const out = path.join(dir, 'pages')
|
||||
await readAssetExtension.present(output, { opts: { out }, json: false, output: o() })
|
||||
|
||||
const first = path.join(out, 'doc-1-1-page-1.webp')
|
||||
const second = path.join(out, 'doc-1-2-page-2.png')
|
||||
expect(await readFile(first, 'utf8')).toBe('bytes of https://files.example/p1')
|
||||
expect(await readFile(second, 'utf8')).toBe('bytes of https://files.example/p2')
|
||||
expect(written).toBe(`${output.summary}\n- Page 1: ${first}\n- Page 2: ${second}\n`)
|
||||
})
|
||||
|
||||
it('adds the saved path to each image in --json mode', async () => {
|
||||
await readAssetExtension.present(output, { opts: { out: dir }, json: true, output: o() })
|
||||
|
||||
const printed = JSON.parse(written) as { images: Array<{ path: string }> }
|
||||
expect(printed.images.map((i) => i.path)).toEqual([
|
||||
path.join(dir, 'doc-1-1-page-1.webp'),
|
||||
path.join(dir, 'doc-1-2-page-2.png'),
|
||||
])
|
||||
})
|
||||
|
||||
it('fails clearly when a download fails', async () => {
|
||||
vi.stubGlobal(
|
||||
'fetch',
|
||||
vi.fn(async () => new Response('gone', { status: 403 })),
|
||||
)
|
||||
await expect(downloadImages(output, dir)).rejects.toThrow(
|
||||
new CliError('Failed to download "Page 1" (status 403).'),
|
||||
)
|
||||
})
|
||||
|
||||
it('does not download anything for a pending render', async () => {
|
||||
await readAssetExtension.present(
|
||||
{ ...output, status: 'pending', images: [], taskId: 't-1', retryAfterSeconds: 5 },
|
||||
{ opts: { out: dir }, json: false, output: o() },
|
||||
)
|
||||
expect(fetch).not.toHaveBeenCalled()
|
||||
expect(written).toContain(`shumai-cli render t-1 --out ${JSON.stringify(dir)}`)
|
||||
})
|
||||
|
||||
it('maps --no-wait to maxWaitSeconds 0', () => {
|
||||
expect(readAssetExtension.toInput!({ assetId: 'a' }, { wait: false })).toEqual({
|
||||
assetId: 'a',
|
||||
maxWaitSeconds: 0,
|
||||
})
|
||||
expect(readAssetExtension.toInput!({ assetId: 'a' }, { wait: true })).toEqual({
|
||||
assetId: 'a',
|
||||
})
|
||||
})
|
||||
})
|
||||
@@ -0,0 +1,116 @@
|
||||
import { mkdir } from 'node:fs/promises'
|
||||
import * as path from 'node:path'
|
||||
import { Option } from 'commander'
|
||||
import type { AssetReadOutput } from '@shumai/operations'
|
||||
import { CliError } from '../errors'
|
||||
import { saveUrlToFile } from './save-url'
|
||||
import type { CliCommandExtension } from '../generate'
|
||||
import type { Output } from '../render'
|
||||
|
||||
const EXTENSIONS: Record<string, string> = {
|
||||
'image/webp': 'webp',
|
||||
'image/png': 'png',
|
||||
'image/jpeg': 'jpg',
|
||||
'image/gif': 'gif',
|
||||
'image/avif': 'avif',
|
||||
}
|
||||
|
||||
function slug(value: string): string {
|
||||
return (
|
||||
value
|
||||
.toLowerCase()
|
||||
.replace(/[^a-z0-9.]+/g, '-')
|
||||
.replace(/^-+|-+$/g, '') || 'image'
|
||||
)
|
||||
}
|
||||
|
||||
/** File name for the n-th image of a read, e.g. `01ABC-1-frame-at-2s.webp`. */
|
||||
export function imageFileName(
|
||||
assetId: string,
|
||||
index: number,
|
||||
image: AssetReadOutput['images'][number],
|
||||
): string {
|
||||
const ext = EXTENSIONS[image.mimeType] ?? image.mimeType.split('/')[1] ?? 'bin'
|
||||
return `${assetId}-${index + 1}-${slug(image.label).replace(/\.+$/, '')}.${ext}`
|
||||
}
|
||||
|
||||
/** Downloads every image of a ready read into `dir`; returns the saved paths in order. */
|
||||
export async function downloadImages(output: AssetReadOutput, dir: string): Promise<string[]> {
|
||||
await mkdir(dir, { recursive: true })
|
||||
const saved: string[] = []
|
||||
for (const [index, image] of output.images.entries()) {
|
||||
if (!image.url) {
|
||||
throw new CliError(`No download link was returned for "${image.label}".`)
|
||||
}
|
||||
const filePath = path.join(dir, imageFileName(output.asset.id, index, image))
|
||||
await saveUrlToFile(image.url, filePath, image.label)
|
||||
saved.push(filePath)
|
||||
}
|
||||
return saved
|
||||
}
|
||||
|
||||
function renderCommand(taskId: string, out: unknown): string {
|
||||
const outArg = typeof out === 'string' ? ` --out ${JSON.stringify(out)}` : ''
|
||||
return `shumai-cli render ${taskId}${outArg}`
|
||||
}
|
||||
|
||||
function writeReady(output: AssetReadOutput, paths: string[] | null, o: Output): void {
|
||||
const lines = [output.summary, ...output.details]
|
||||
output.images.forEach((image, i) => {
|
||||
lines.push(`- ${image.label}: ${paths ? paths[i] : (image.url ?? '')}`)
|
||||
})
|
||||
o.out.write(`${lines.join('\n')}\n`)
|
||||
if (output.text) {
|
||||
o.out.write(`\n${output.text.content}`)
|
||||
if (!output.text.content.endsWith('\n')) o.out.write('\n')
|
||||
if (output.text.truncated) {
|
||||
o.out.write(
|
||||
`\n[Content truncated: showing the first part of a ${output.text.size}-byte file. Run \`shumai-cli download ${output.asset.id}\` to get the whole file.]\n`,
|
||||
)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* `read` and `render`: images are printed as links (valid for about an hour) or downloaded
|
||||
* with `--out`; a render that takes longer than the wait prints the `render` command to run.
|
||||
*/
|
||||
function readExtension(noWaitHelp: string): CliCommandExtension {
|
||||
return {
|
||||
options: () => [
|
||||
new Option('-o, --out <dir>', 'Download the images into this folder and print their paths.'),
|
||||
new Option('--no-wait', noWaitHelp),
|
||||
],
|
||||
toInput: (input, opts) => (opts.wait === false ? { ...input, maxWaitSeconds: 0 } : input),
|
||||
async present(raw, { opts, json, output: o }) {
|
||||
const output = raw as AssetReadOutput
|
||||
if (output.status === 'pending') {
|
||||
if (json) {
|
||||
o.out.write(`${JSON.stringify(output, null, 2)}\n`)
|
||||
return
|
||||
}
|
||||
o.out.write(
|
||||
`${output.summary}\nRun this to get the result: ${renderCommand(output.taskId ?? '', opts.out)}\n`,
|
||||
)
|
||||
return
|
||||
}
|
||||
|
||||
const paths = typeof opts.out === 'string' ? await downloadImages(output, opts.out) : null
|
||||
if (json) {
|
||||
const images = output.images.map((image, i) =>
|
||||
paths ? { ...image, path: paths[i] } : image,
|
||||
)
|
||||
o.out.write(`${JSON.stringify({ ...output, images }, null, 2)}\n`)
|
||||
return
|
||||
}
|
||||
writeReady(output, paths, o)
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
export const readAssetExtension = readExtension(
|
||||
'Return right away with a task ID if the asset needs rendering.',
|
||||
)
|
||||
export const getAssetRenderExtension = readExtension(
|
||||
'Check once and return right away if the render is still running.',
|
||||
)
|
||||
@@ -0,0 +1,32 @@
|
||||
import { createWriteStream } from 'node:fs'
|
||||
import { rm } from 'node:fs/promises'
|
||||
import { Readable } from 'node:stream'
|
||||
import { pipeline } from 'node:stream/promises'
|
||||
import type { ReadableStream as WebReadableStream } from 'node:stream/web'
|
||||
import { CliError } from '../errors'
|
||||
|
||||
/** Streams a download link to `filePath` (large files never sit in memory). */
|
||||
export async function saveUrlToFile(url: string, filePath: string, label: string): Promise<void> {
|
||||
let res: Response
|
||||
try {
|
||||
res = await fetch(url)
|
||||
} catch (err) {
|
||||
throw new CliError(
|
||||
`Failed to download "${label}": ${err instanceof Error ? err.message : String(err)}`,
|
||||
)
|
||||
}
|
||||
if (!res.ok || !res.body) {
|
||||
throw new CliError(`Failed to download "${label}" (status ${res.status}).`)
|
||||
}
|
||||
try {
|
||||
await pipeline(
|
||||
Readable.fromWeb(res.body as unknown as WebReadableStream<Uint8Array>),
|
||||
createWriteStream(filePath),
|
||||
)
|
||||
} catch (err) {
|
||||
await rm(filePath, { force: true })
|
||||
throw new CliError(
|
||||
`Failed to save "${label}" to ${filePath}: ${err instanceof Error ? err.message : String(err)}`,
|
||||
)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,269 @@
|
||||
import { Command, InvalidArgumentError, Option } from 'commander'
|
||||
import { z } from 'zod'
|
||||
import type { AnyOperationDefinition } from '@shumai/operations'
|
||||
import type { CallOperation } from './call-operation'
|
||||
import { CliError } from './errors'
|
||||
import { renderOutput, type Output } from './render'
|
||||
|
||||
/**
|
||||
* CLI-specific behavior for one Operation's command, for things a definition can't describe
|
||||
* (it must stay free of I/O): extra options, input mapping, and output that downloads files.
|
||||
*/
|
||||
export interface CliCommandExtension {
|
||||
/** Extra options only the CLI has; their values are passed to `toInput` and `present`. */
|
||||
options?(): Option[]
|
||||
/** Adjust the Operation input using the command's options. */
|
||||
toInput?(input: Record<string, unknown>, opts: Record<string, unknown>): Record<string, unknown>
|
||||
/** Writes the output, including in `--json` mode. Replaces the default rendering. */
|
||||
present(
|
||||
output: unknown,
|
||||
ctx: { opts: Record<string, unknown>; json: boolean; output: Output },
|
||||
): Promise<void>
|
||||
}
|
||||
|
||||
export interface GenerateDeps {
|
||||
callOperation: CallOperation
|
||||
output: Output
|
||||
/** Whether destructive Operations are allowed (SHUMAI_ALLOW_DELETE). */
|
||||
allowDestructive: () => boolean
|
||||
/** CLI extensions by Operation name. */
|
||||
extensions?: ReadonlyMap<string, CliCommandExtension>
|
||||
}
|
||||
|
||||
type FieldKind =
|
||||
| { type: 'string' }
|
||||
| { type: 'number' }
|
||||
| { type: 'boolean' }
|
||||
| { type: 'enum'; values: string[] }
|
||||
| { type: 'array' }
|
||||
/** A key/value object (`z.record`), passed as a JSON object. */
|
||||
| { type: 'json' }
|
||||
|
||||
interface FieldInfo {
|
||||
name: string
|
||||
kind: FieldKind
|
||||
required: boolean
|
||||
description: string
|
||||
}
|
||||
|
||||
/** Strip optional/nullable/default wrappers to find the field's base schema. */
|
||||
function unwrap(schema: z.ZodType): z.ZodType {
|
||||
let current = schema
|
||||
while (
|
||||
current instanceof z.ZodOptional ||
|
||||
current instanceof z.ZodNullable ||
|
||||
current instanceof z.ZodDefault
|
||||
) {
|
||||
current = current.unwrap() as z.ZodType
|
||||
}
|
||||
return current
|
||||
}
|
||||
|
||||
function describeField(definition: AnyOperationDefinition, name: string): FieldInfo {
|
||||
return describeSchema(definition, name, definition.input.shape[name] as z.ZodType)
|
||||
}
|
||||
|
||||
function describeSchema(
|
||||
definition: AnyOperationDefinition,
|
||||
name: string,
|
||||
schema: z.ZodType,
|
||||
): FieldInfo {
|
||||
const base = unwrap(schema)
|
||||
let kind: FieldKind
|
||||
if (base instanceof z.ZodNumber) kind = { type: 'number' }
|
||||
else if (base instanceof z.ZodBoolean) kind = { type: 'boolean' }
|
||||
else if (base instanceof z.ZodEnum) kind = { type: 'enum', values: base.options.map(String) }
|
||||
else if (base instanceof z.ZodArray) kind = { type: 'array' }
|
||||
else if (base instanceof z.ZodString) kind = { type: 'string' }
|
||||
else if (base instanceof z.ZodRecord) kind = { type: 'json' }
|
||||
else {
|
||||
throw new Error(`${definition.name}.${name}: unsupported input type for the CLI`)
|
||||
}
|
||||
return {
|
||||
name,
|
||||
kind,
|
||||
required: !schema.safeParse(undefined).success,
|
||||
description: schema.description ?? base.description ?? '',
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Input errors name the input path (e.g. `videoConfig.end`). For flattened fields, name the
|
||||
* flag the user typed instead (e.g. `--video-end`).
|
||||
*/
|
||||
function formatInputError(
|
||||
error: z.ZodError,
|
||||
options: ReadonlyArray<{ path: [string] | [string, string]; option: Option }>,
|
||||
): string {
|
||||
const flagFor = (path: PropertyKey[]): string | undefined =>
|
||||
options.find((o) => o.path.length === 2 && o.path[0] === path[0] && o.path[1] === path[1])
|
||||
?.option.long
|
||||
if (!error.issues.some((issue) => flagFor(issue.path))) {
|
||||
return z.prettifyError(error)
|
||||
}
|
||||
return error.issues
|
||||
.map((issue) => {
|
||||
const flag = flagFor(issue.path)
|
||||
return flag ? `✖ ${flag}: ${issue.message}` : z.prettifyError(new z.ZodError([issue]))
|
||||
})
|
||||
.join('\n')
|
||||
}
|
||||
|
||||
function parseNumber(value: string): number {
|
||||
const parsed = Number(value)
|
||||
if (value.trim() === '' || Number.isNaN(parsed)) {
|
||||
throw new InvalidArgumentError('Not a number.')
|
||||
}
|
||||
return parsed
|
||||
}
|
||||
|
||||
function parseJsonObject(value: string): Record<string, unknown> {
|
||||
let parsed: unknown
|
||||
try {
|
||||
parsed = JSON.parse(value)
|
||||
} catch {
|
||||
throw new InvalidArgumentError('Not valid JSON.')
|
||||
}
|
||||
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
|
||||
throw new InvalidArgumentError('Expected a JSON object, e.g. \'{"key": "value"}\'.')
|
||||
}
|
||||
return parsed as Record<string, unknown>
|
||||
}
|
||||
|
||||
function kebab(name: string): string {
|
||||
return name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)
|
||||
}
|
||||
|
||||
/** Find or create the subcommand path, e.g. `project` for `project ls`. */
|
||||
function ensureParent(program: Command, path: readonly string[]): Command {
|
||||
let parent = program
|
||||
for (const segment of path) {
|
||||
parent =
|
||||
parent.commands.find((c) => c.name() === segment) ??
|
||||
parent.command(segment).description(`Manage ${segment}s.`)
|
||||
}
|
||||
return parent
|
||||
}
|
||||
|
||||
/** Registers one command for each definition with a `cli` spec. */
|
||||
export function registerOperationCommands(
|
||||
program: Command,
|
||||
definitions: readonly AnyOperationDefinition[],
|
||||
deps: GenerateDeps,
|
||||
): void {
|
||||
for (const definition of definitions) {
|
||||
const cli = definition.cli
|
||||
if (!cli || !definition.surfaces.includes('cli')) continue
|
||||
|
||||
const parent = ensureParent(program, cli.command.slice(0, -1))
|
||||
const cmd = parent
|
||||
.command(cli.command[cli.command.length - 1])
|
||||
.description(cli.description ?? definition.description)
|
||||
if (cli.aliases) cmd.aliases([...cli.aliases])
|
||||
|
||||
const positional = (cli.positional ?? []).map((name) => describeField(definition, name))
|
||||
for (const field of positional) {
|
||||
const placeholder = field.kind.type === 'array' ? `${field.name}...` : field.name
|
||||
cmd.argument(field.required ? `<${placeholder}>` : `[${placeholder}]`, field.description)
|
||||
}
|
||||
|
||||
const positionalNames = new Set(positional.map((f) => f.name))
|
||||
const omitted = new Set<string>(cli.omit ?? [])
|
||||
const flatten = (cli.flatten ?? {}) as Record<string, string | undefined>
|
||||
// `path` is where the value goes in the input: `[field]` or `[field, subField]`.
|
||||
const options: Array<{ path: [string] | [string, string]; option: Option }> = []
|
||||
const addOption = (
|
||||
path: [string] | [string, string],
|
||||
field: FieldInfo,
|
||||
spellings: readonly string[],
|
||||
) => {
|
||||
const valueHint =
|
||||
field.kind.type === 'boolean'
|
||||
? ''
|
||||
: field.kind.type === 'array'
|
||||
? ` <${field.name}...>`
|
||||
: field.kind.type === 'json'
|
||||
? ` <json>`
|
||||
: ` <${field.name}>`
|
||||
const option = new Option(`${spellings.join(', ')}${valueHint}`, field.description)
|
||||
if (field.kind.type === 'number') option.argParser(parseNumber)
|
||||
if (field.kind.type === 'json') option.argParser(parseJsonObject)
|
||||
if (field.kind.type === 'enum') option.choices(field.kind.values)
|
||||
if (field.required) option.makeOptionMandatory()
|
||||
cmd.addOption(option)
|
||||
options.push({ path, option })
|
||||
return option
|
||||
}
|
||||
|
||||
for (const name of Object.keys(definition.input.shape)) {
|
||||
if (positionalNames.has(name) || omitted.has(name)) continue
|
||||
const prefix = flatten[name]
|
||||
if (prefix !== undefined) {
|
||||
const schema = definition.input.shape[name] as z.ZodType
|
||||
const base = unwrap(schema)
|
||||
if (!(base instanceof z.ZodObject)) {
|
||||
throw new Error(`${definition.name}.${name}: only object fields can be flattened`)
|
||||
}
|
||||
const parentRequired = !schema.safeParse(undefined).success
|
||||
for (const [subName, subSchema] of Object.entries(base.shape)) {
|
||||
const field = describeSchema(definition, `${name}.${subName}`, subSchema as z.ZodType)
|
||||
field.name = subName
|
||||
// Sub-fields are only mandatory when the object itself is.
|
||||
field.required = parentRequired && field.required
|
||||
const flag = prefix ? `--${prefix}-${kebab(subName)}` : `--${kebab(subName)}`
|
||||
addOption([name, subName], field, [flag])
|
||||
}
|
||||
continue
|
||||
}
|
||||
const field = describeField(definition, name)
|
||||
const option = addOption([name], field, cli.flags?.[name] ?? [`--${kebab(name)}`])
|
||||
const cliDefault = (cli.defaults as Record<string, unknown> | undefined)?.[name]
|
||||
if (cliDefault !== undefined) option.default(cliDefault)
|
||||
}
|
||||
|
||||
const extension = deps.extensions?.get(definition.name)
|
||||
for (const option of extension?.options?.() ?? []) cmd.addOption(option)
|
||||
|
||||
cmd.action(async (...args: unknown[]) => {
|
||||
const command = args[args.length - 1] as Command
|
||||
const input: Record<string, unknown> = { ...cli.defaults }
|
||||
positional.forEach((field, i) => {
|
||||
if (args[i] !== undefined) input[field.name] = args[i]
|
||||
})
|
||||
const opts = command.opts()
|
||||
for (const { path, option } of options) {
|
||||
const value = opts[option.attributeName()]
|
||||
if (value === undefined) continue
|
||||
if (path.length === 1) {
|
||||
input[path[0]] = value
|
||||
} else {
|
||||
const parent = (input[path[0]] ?? {}) as Record<string, unknown>
|
||||
input[path[0]] = { ...parent, [path[1]]: value }
|
||||
}
|
||||
}
|
||||
|
||||
if (definition.annotations.destructive && !deps.allowDestructive()) {
|
||||
throw new CliError(
|
||||
`${definition.title} is disabled in this environment. Set SHUMAI_ALLOW_DELETE=true to enable it.`,
|
||||
)
|
||||
}
|
||||
|
||||
const parsed = definition.input.safeParse(
|
||||
extension?.toInput ? extension.toInput(input, opts) : input,
|
||||
)
|
||||
if (!parsed.success) {
|
||||
throw new CliError(formatInputError(parsed.error, options))
|
||||
}
|
||||
|
||||
const output = await deps.callOperation(definition, parsed.data)
|
||||
const json = Boolean(command.optsWithGlobals().json)
|
||||
if (extension) {
|
||||
await extension.present(output, { opts, json, output: deps.output })
|
||||
} else if (json) {
|
||||
deps.output.out.write(`${JSON.stringify(output, null, 2)}\n`)
|
||||
} else {
|
||||
renderOutput(definition, output, deps.output)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,68 @@
|
||||
import { describe, expect, it } from 'vitest'
|
||||
import { z } from 'zod'
|
||||
import { defineOperation, listAssets, renameAsset } from '@shumai/operations'
|
||||
import { formatSize, renderOutput, type Output } from './render'
|
||||
|
||||
function capture(isTty = true): Output & { text: () => string } {
|
||||
let text = ''
|
||||
return { out: { write: (s) => void (text += s) }, isTty, columns: 120, text: () => text }
|
||||
}
|
||||
|
||||
const page = {
|
||||
data: [{ id: 'd1', name: 'Renders', type: 'folder', size: 0, projectId: 'p' }],
|
||||
pageInfo: { hasNextPage: true, endCursor: 'CUR' },
|
||||
total: 2,
|
||||
}
|
||||
|
||||
describe('renderOutput', () => {
|
||||
it('shows the next-page cursor only on a terminal', () => {
|
||||
const tty = capture(true)
|
||||
renderOutput(listAssets, page, tty)
|
||||
expect(tty.text()).toContain('Next page: --after CUR')
|
||||
|
||||
const piped = capture(false)
|
||||
renderOutput(listAssets, page, piped)
|
||||
expect(piped.text()).toBe('d1\tRenders\tfolder\t-\n')
|
||||
})
|
||||
|
||||
it('uses the definition formatter when there is no table renderer', () => {
|
||||
const o = capture()
|
||||
renderOutput(renameAsset, { id: 'a1', name: 'new', type: 'file', size: 1, projectId: null }, o)
|
||||
expect(o.text()).toBe('Renamed asset a1 to "new"\n')
|
||||
})
|
||||
|
||||
it('falls back to tables for lists and key/value lines for objects', () => {
|
||||
const generic = defineOperation({
|
||||
name: 'generic_thing',
|
||||
title: 'Generic',
|
||||
description: 'Generic output.',
|
||||
input: z.object({}),
|
||||
output: z.unknown(),
|
||||
surfaces: ['agent'],
|
||||
annotations: { readOnly: true, destructive: false },
|
||||
})
|
||||
|
||||
const list = capture(false)
|
||||
renderOutput(generic, { data: [{ id: 'x', tags: ['a'] }] }, list)
|
||||
expect(list.text()).toBe('x\t["a"]\n')
|
||||
|
||||
const empty = capture()
|
||||
renderOutput(generic, [], empty)
|
||||
expect(empty.text()).toBe('No results.\n')
|
||||
|
||||
const object = capture()
|
||||
renderOutput(generic, { id: 'x', count: 2, note: null }, object)
|
||||
expect(object.text()).toBe('id: x\ncount: 2\nnote: \n')
|
||||
})
|
||||
})
|
||||
|
||||
describe('formatSize', () => {
|
||||
it.each([
|
||||
[0, '-'],
|
||||
[512, '512 B'],
|
||||
[1536, '1.5 KB'],
|
||||
[5 * 1024 * 1024, '5 MB'],
|
||||
])('formats %d bytes as %s', (bytes, expected) => {
|
||||
expect(formatSize(bytes)).toBe(expected)
|
||||
})
|
||||
})
|
||||
@@ -0,0 +1,121 @@
|
||||
import { newTablePrinter, withTruncate, type Writer } from '@shumai/tableprinter'
|
||||
import type {
|
||||
AnyOperationDefinition,
|
||||
AssetSummary,
|
||||
PageInfo,
|
||||
ProjectSummary,
|
||||
} from '@shumai/operations'
|
||||
|
||||
export interface Output {
|
||||
out: Writer
|
||||
isTty: boolean
|
||||
columns: number
|
||||
}
|
||||
|
||||
export function formatSize(bytes: number): string {
|
||||
if (bytes === 0) return '-'
|
||||
const k = 1024
|
||||
const sizes = ['B', 'KB', 'MB', 'GB', 'TB']
|
||||
const i = Math.floor(Math.log(bytes) / Math.log(k))
|
||||
return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i]
|
||||
}
|
||||
|
||||
function renderAssets(output: { data: AssetSummary[]; pageInfo: PageInfo }, o: Output): void {
|
||||
if (output.data.length === 0) {
|
||||
o.out.write('No assets found in this folder.\n')
|
||||
return
|
||||
}
|
||||
// Folders first, as in the file browser's default listing
|
||||
const items = [...output.data].sort(
|
||||
(a, b) => Number(b.type === 'folder') - Number(a.type === 'folder'),
|
||||
)
|
||||
const tp = newTablePrinter(o.out, o.isTty, o.columns)
|
||||
tp.addHeader(['ID', 'Name', 'Type', 'Size'])
|
||||
for (const item of items) {
|
||||
const isFolder = item.type === 'folder'
|
||||
tp.addField(item.id, withTruncate(null))
|
||||
tp.addField(item.name)
|
||||
tp.addField(isFolder ? 'folder' : 'file', withTruncate(null))
|
||||
tp.addField(isFolder ? '-' : formatSize(item.size), withTruncate(null))
|
||||
tp.endRow()
|
||||
}
|
||||
tp.render()
|
||||
// Piped output is TSV for scripts (use --json for pagination metadata); keep it clean.
|
||||
if (o.isTty && output.pageInfo.hasNextPage && output.pageInfo.endCursor) {
|
||||
o.out.write(`\nMore assets available. Next page: --after ${output.pageInfo.endCursor}\n`)
|
||||
}
|
||||
}
|
||||
|
||||
function renderProjects(output: { data: ProjectSummary[] }, o: Output): void {
|
||||
if (output.data.length === 0) {
|
||||
o.out.write('No projects found.\n')
|
||||
return
|
||||
}
|
||||
const tp = newTablePrinter(o.out, o.isTty, o.columns)
|
||||
tp.addHeader(['ID', 'Name', 'Root Folder ID'])
|
||||
for (const p of output.data) {
|
||||
tp.addField(p.id)
|
||||
tp.addField(p.name)
|
||||
tp.addField(p.rootFolderId ?? '')
|
||||
tp.endRow()
|
||||
}
|
||||
tp.render()
|
||||
}
|
||||
|
||||
/** Table renderers for list Operations; other Operations use their `cli.format` or the fallback. */
|
||||
const tableRenderers = new Map<string, (output: never, o: Output) => void>([
|
||||
['list_assets', renderAssets],
|
||||
['list_projects', renderProjects],
|
||||
])
|
||||
|
||||
function isRecord(value: unknown): value is Record<string, unknown> {
|
||||
return typeof value === 'object' && value !== null && !Array.isArray(value)
|
||||
}
|
||||
|
||||
function cell(value: unknown): string {
|
||||
if (value === null || value === undefined) return ''
|
||||
return typeof value === 'object' ? JSON.stringify(value) : String(value)
|
||||
}
|
||||
|
||||
/** Generic rendering: `{ data: [...] }` and arrays as tables, objects as `key: value` lines. */
|
||||
function renderFallback(output: unknown, o: Output): void {
|
||||
const rows = Array.isArray(output)
|
||||
? output
|
||||
: isRecord(output) && Array.isArray(output.data)
|
||||
? output.data
|
||||
: null
|
||||
if (rows) {
|
||||
if (rows.length === 0) {
|
||||
o.out.write('No results.\n')
|
||||
return
|
||||
}
|
||||
const keys = Object.keys(isRecord(rows[0]) ? rows[0] : { value: rows[0] })
|
||||
const tp = newTablePrinter(o.out, o.isTty, o.columns)
|
||||
tp.addHeader(keys)
|
||||
for (const row of rows) {
|
||||
for (const key of keys) tp.addField(cell(isRecord(row) ? row[key] : row))
|
||||
tp.endRow()
|
||||
}
|
||||
tp.render()
|
||||
return
|
||||
}
|
||||
if (isRecord(output)) {
|
||||
for (const [key, value] of Object.entries(output)) o.out.write(`${key}: ${cell(value)}\n`)
|
||||
return
|
||||
}
|
||||
o.out.write(`${cell(output)}\n`)
|
||||
}
|
||||
|
||||
/** Writes an Operation's output in human-friendly form. */
|
||||
export function renderOutput(definition: AnyOperationDefinition, output: unknown, o: Output): void {
|
||||
const table = tableRenderers.get(definition.name)
|
||||
if (table) {
|
||||
table(output as never, o)
|
||||
return
|
||||
}
|
||||
if (definition.cli?.format) {
|
||||
o.out.write(`${definition.cli.format(output)}\n`)
|
||||
return
|
||||
}
|
||||
renderFallback(output, o)
|
||||
}
|
||||
@@ -0,0 +1,898 @@
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
|
||||
import type { Command } from 'commander'
|
||||
import {
|
||||
copyAssets,
|
||||
createComment,
|
||||
createFolder,
|
||||
createProject,
|
||||
createVersionStack,
|
||||
deleteAsset,
|
||||
downloadAsset,
|
||||
getAssetRender,
|
||||
getFolderInstructions,
|
||||
readAsset,
|
||||
listAssets,
|
||||
listComments,
|
||||
listMetadataFields,
|
||||
listProjects,
|
||||
listVersions,
|
||||
moveAssets,
|
||||
removeVersion,
|
||||
renameAsset,
|
||||
resolveComment,
|
||||
searchAssets,
|
||||
updateAssetMetadata,
|
||||
} from '@shumai/operations'
|
||||
import type { CallOperation } from './operations/call-operation'
|
||||
import { CliError, formatCliError } from './operations/errors'
|
||||
import { createProgram } from './program'
|
||||
import { version } from '../package.json'
|
||||
|
||||
/** Runs the CLI with mocked Operation calls and captures stdout/stderr. */
|
||||
function setup() {
|
||||
let stdout = ''
|
||||
let stderr = ''
|
||||
const callOperation = vi.fn<CallOperation>()
|
||||
const startRunner = vi.fn(async () => {})
|
||||
const program = createProgram({
|
||||
callOperation,
|
||||
startRunner,
|
||||
output: { out: { write: (s) => void (stdout += s) }, isTty: true, columns: 120 },
|
||||
})
|
||||
const configure = (cmd: Command) => {
|
||||
cmd.exitOverride().configureOutput({
|
||||
writeOut: (s) => void (stdout += s),
|
||||
writeErr: (s) => void (stderr += s),
|
||||
})
|
||||
cmd.commands.forEach(configure)
|
||||
}
|
||||
configure(program)
|
||||
return {
|
||||
callOperation,
|
||||
startRunner,
|
||||
run: (...argv: string[]) => program.parseAsync(['node', 'shumai-cli', ...argv]),
|
||||
stdout: () => stdout,
|
||||
stderr: () => stderr,
|
||||
}
|
||||
}
|
||||
|
||||
const folder = { id: 'f-1', name: 'Renders', type: 'folder', size: 0, projectId: 'p-1' }
|
||||
|
||||
const frames = {
|
||||
status: 'ready',
|
||||
summary: 'Extracted 2 frame(s) from "clip.mp4" (0s - 4s):',
|
||||
asset: { id: 'vid-1', name: 'clip.mp4', kind: 'video', mediaType: 'video/mp4' },
|
||||
details: [],
|
||||
images: [
|
||||
{ label: 'Frame at 0s', mimeType: 'image/webp', url: 'https://files.example/0.webp' },
|
||||
{ label: 'Frame at 4s', mimeType: 'image/webp', url: 'https://files.example/4.webp' },
|
||||
],
|
||||
}
|
||||
|
||||
const pendingRead = {
|
||||
status: 'pending',
|
||||
summary: 'Rendering is still in progress for "clip.mp4".',
|
||||
asset: frames.asset,
|
||||
details: [],
|
||||
images: [],
|
||||
taskId: 'task-1',
|
||||
retryAfterSeconds: 5,
|
||||
}
|
||||
|
||||
describe('shumai-cli', () => {
|
||||
it('reports its package version without calling the server', async () => {
|
||||
const cli = setup()
|
||||
await expect(cli.run('--version')).rejects.toMatchObject({ code: 'commander.version' })
|
||||
expect(cli.stdout()).toBe(`${version}\n`)
|
||||
expect(cli.callOperation).not.toHaveBeenCalled()
|
||||
})
|
||||
|
||||
const originalAllowDelete = process.env.SHUMAI_ALLOW_DELETE
|
||||
|
||||
afterEach(() => {
|
||||
if (originalAllowDelete === undefined) delete process.env.SHUMAI_ALLOW_DELETE
|
||||
else process.env.SHUMAI_ALLOW_DELETE = originalAllowDelete
|
||||
})
|
||||
|
||||
describe('project ls', () => {
|
||||
it('lists projects with their root folder', async () => {
|
||||
const cli = setup()
|
||||
cli.callOperation.mockResolvedValue({
|
||||
data: [
|
||||
{ id: 'p1', name: 'Proj 1', teamId: 't1', rootFolderId: 'root1' },
|
||||
{ id: 'p2', name: 'Proj 2', teamId: 't1', rootFolderId: 'root2' },
|
||||
],
|
||||
})
|
||||
|
||||
await cli.run('project', 'ls')
|
||||
|
||||
expect(cli.callOperation).toHaveBeenCalledWith(listProjects, {})
|
||||
expect(cli.stdout()).toContain('Root Folder ID')
|
||||
expect(cli.stdout()).toMatch(/p1\s+Proj 1\s+root1/)
|
||||
expect(cli.stdout()).toContain('Proj 2')
|
||||
})
|
||||
|
||||
it('reports when there are no projects', async () => {
|
||||
const cli = setup()
|
||||
cli.callOperation.mockResolvedValue({ data: [] })
|
||||
|
||||
await cli.run('project', 'ls')
|
||||
|
||||
expect(cli.stdout()).toBe('No projects found.\n')
|
||||
})
|
||||
})
|
||||
|
||||
describe('project create', () => {
|
||||
it('creates a project with positional name and optional --team', async () => {
|
||||
const cli = setup()
|
||||
cli.callOperation.mockResolvedValue({
|
||||
id: 'p-new',
|
||||
name: 'Summer Shoot',
|
||||
teamId: 't1',
|
||||
rootFolderId: 'root-new',
|
||||
})
|
||||
|
||||
await cli.run('project', 'create', 'Summer Shoot')
|
||||
|
||||
expect(cli.callOperation).toHaveBeenCalledWith(createProject, { name: 'Summer Shoot' })
|
||||
expect(cli.stdout()).toBe(
|
||||
'Created project "Summer Shoot" (ID: p-new, rootFolderId: root-new)\n',
|
||||
)
|
||||
|
||||
await cli.run('project', 'create', 'Team Shoot', '-t', 't2', '--json')
|
||||
expect(cli.callOperation).toHaveBeenLastCalledWith(createProject, {
|
||||
name: 'Team Shoot',
|
||||
teamId: 't2',
|
||||
})
|
||||
})
|
||||
})
|
||||
|
||||
describe('ls', () => {
|
||||
it('lists a folder with the maximum page size, folders first', async () => {
|
||||
const cli = setup()
|
||||
cli.callOperation.mockResolvedValue({
|
||||
data: [
|
||||
{ id: 'file1', name: 'doc.pdf', type: 'file', size: 1024, projectId: 'p' },
|
||||
{ id: 'sub1', name: 'Sub 1', type: 'folder', size: 0, projectId: 'p' },
|
||||
],
|
||||
pageInfo: { hasNextPage: false, endCursor: null },
|
||||
total: 2,
|
||||
})
|
||||
|
||||
await cli.run('ls', '-p', 'parentId123')
|
||||
|
||||
expect(cli.callOperation).toHaveBeenCalledWith(listAssets, {
|
||||
parent: 'parentId123',
|
||||
first: 200,
|
||||
})
|
||||
const out = cli.stdout()
|
||||
expect(out.indexOf('Sub 1')).toBeLessThan(out.indexOf('doc.pdf'))
|
||||
expect(out).toMatch(/file1\s+doc\.pdf\s+file\s+1 KB/)
|
||||
expect(out).not.toContain('More assets available')
|
||||
})
|
||||
|
||||
it('passes pagination and type flags and prints the next-page cursor', async () => {
|
||||
const cli = setup()
|
||||
cli.callOperation.mockResolvedValue({
|
||||
data: [{ id: 'sub1', name: 'Sub 1', type: 'folder', size: 0, projectId: 'p' }],
|
||||
pageInfo: { hasNextPage: true, endCursor: 'cur-2' },
|
||||
total: 3,
|
||||
})
|
||||
|
||||
await cli.run('ls', '--parent', 'p1', '--type', 'folder', '--first', '1', '--after', 'cur-1')
|
||||
|
||||
expect(cli.callOperation).toHaveBeenCalledWith(listAssets, {
|
||||
parent: 'p1',
|
||||
type: 'folder',
|
||||
first: 1,
|
||||
after: 'cur-1',
|
||||
})
|
||||
expect(cli.stdout()).toContain('Next page: --after cur-2')
|
||||
})
|
||||
|
||||
it('requires the parent option', async () => {
|
||||
const cli = setup()
|
||||
|
||||
await expect(cli.run('ls')).rejects.toThrow()
|
||||
expect(cli.stderr()).toContain("required option '-p, --parent <parent>' not specified")
|
||||
expect(cli.callOperation).not.toHaveBeenCalled()
|
||||
})
|
||||
|
||||
it('rejects an invalid type and a non-numeric page size', async () => {
|
||||
const cli = setup()
|
||||
|
||||
await expect(cli.run('ls', '-p', 'x', '--type', 'video')).rejects.toThrow()
|
||||
expect(cli.stderr()).toContain('Allowed choices are file, folder, all')
|
||||
|
||||
await expect(cli.run('ls', '-p', 'x', '--first', 'many')).rejects.toThrow()
|
||||
expect(cli.stderr()).toContain('Not a number')
|
||||
expect(cli.callOperation).not.toHaveBeenCalled()
|
||||
})
|
||||
})
|
||||
|
||||
describe('mkdir', () => {
|
||||
it('creates a folder and prints its ID', async () => {
|
||||
const cli = setup()
|
||||
cli.callOperation.mockResolvedValue({ ...folder, id: 'new_folder_ulid' })
|
||||
|
||||
await cli.run('mkdir', 'NewFolder', '-p', 'parent_ulid')
|
||||
|
||||
expect(cli.callOperation).toHaveBeenCalledWith(createFolder, {
|
||||
name: 'NewFolder',
|
||||
parent: 'parent_ulid',
|
||||
})
|
||||
expect(cli.stdout()).toBe('Created folder with ID: new_folder_ulid\n')
|
||||
})
|
||||
|
||||
it('requires a folder name', async () => {
|
||||
const cli = setup()
|
||||
|
||||
await expect(cli.run('mkdir', '-p', 'parent_ulid')).rejects.toThrow()
|
||||
expect(cli.stderr()).toContain("missing required argument 'name'")
|
||||
})
|
||||
})
|
||||
|
||||
describe('rename', () => {
|
||||
it('renames an asset', async () => {
|
||||
const cli = setup()
|
||||
cli.callOperation.mockResolvedValue({ ...folder, name: 'Renamed Folder' })
|
||||
|
||||
await cli.run('rename', 'f-1', 'Renamed Folder')
|
||||
|
||||
expect(cli.callOperation).toHaveBeenCalledWith(renameAsset, {
|
||||
assetId: 'f-1',
|
||||
name: 'Renamed Folder',
|
||||
})
|
||||
expect(cli.stdout()).toBe('Renamed asset f-1 to "Renamed Folder"\n')
|
||||
})
|
||||
|
||||
it('requires both the asset ID and the new name', async () => {
|
||||
const cli = setup()
|
||||
|
||||
await expect(cli.run('rename', 'f-1')).rejects.toThrow()
|
||||
expect(cli.stderr()).toContain("missing required argument 'name'")
|
||||
})
|
||||
})
|
||||
|
||||
describe('move', () => {
|
||||
it.each(['move', 'mv'])('moves assets with %s', async (command) => {
|
||||
const cli = setup()
|
||||
cli.callOperation.mockResolvedValue({
|
||||
movedAssetIds: ['a-1', 'a-2'],
|
||||
newParentId: 'parent-1',
|
||||
})
|
||||
|
||||
await cli.run(command, 'a-1', 'a-2', '-p', 'parent-1')
|
||||
|
||||
expect(cli.callOperation).toHaveBeenCalledWith(moveAssets, {
|
||||
assetIds: ['a-1', 'a-2'],
|
||||
newParentId: 'parent-1',
|
||||
})
|
||||
expect(cli.stdout()).toBe('Moved 2 asset(s) to parent parent-1\n')
|
||||
})
|
||||
|
||||
it('requires at least one asset and a destination', async () => {
|
||||
const cli = setup()
|
||||
|
||||
await expect(cli.run('move', '-p', 'parent-1')).rejects.toThrow()
|
||||
expect(cli.stderr()).toContain("missing required argument 'assetIds'")
|
||||
|
||||
await expect(cli.run('move', 'a-1')).rejects.toThrow()
|
||||
expect(cli.stderr()).toContain("required option '-p, --parent <newParentId>' not specified")
|
||||
})
|
||||
})
|
||||
|
||||
describe('delete', () => {
|
||||
it.each([undefined, 'false'])(
|
||||
'refuses to delete when SHUMAI_ALLOW_DELETE is %s',
|
||||
async (value) => {
|
||||
if (value === undefined) delete process.env.SHUMAI_ALLOW_DELETE
|
||||
else process.env.SHUMAI_ALLOW_DELETE = value
|
||||
const cli = setup()
|
||||
|
||||
const error = await cli.run('delete', 'a-1').catch((err: unknown) => err)
|
||||
|
||||
expect(formatCliError(error)).toBe(
|
||||
'Error: Delete Asset is disabled in this environment. Set SHUMAI_ALLOW_DELETE=true to enable it.',
|
||||
)
|
||||
expect(cli.callOperation).not.toHaveBeenCalled()
|
||||
},
|
||||
)
|
||||
|
||||
it.each([
|
||||
['delete', 'true'],
|
||||
['rm', '1'],
|
||||
])('deletes with %s when SHUMAI_ALLOW_DELETE=%s', async (command, value) => {
|
||||
process.env.SHUMAI_ALLOW_DELETE = value
|
||||
const cli = setup()
|
||||
cli.callOperation.mockResolvedValue({ deletedAssetId: 'a-1' })
|
||||
|
||||
await cli.run(command, 'a-1')
|
||||
|
||||
expect(cli.callOperation).toHaveBeenCalledWith(deleteAsset, { assetId: 'a-1' })
|
||||
expect(cli.stdout()).toBe('Deleted asset a-1\n')
|
||||
})
|
||||
|
||||
it('deletes only one asset at a time', async () => {
|
||||
process.env.SHUMAI_ALLOW_DELETE = 'true'
|
||||
const cli = setup()
|
||||
|
||||
await expect(cli.run('delete', 'a-1', 'a-2')).rejects.toThrow()
|
||||
expect(cli.stderr()).toContain('too many arguments')
|
||||
expect(cli.callOperation).not.toHaveBeenCalled()
|
||||
})
|
||||
})
|
||||
|
||||
describe('read', () => {
|
||||
it('maps flattened reader flags onto the config objects and prints image links', async () => {
|
||||
const cli = setup()
|
||||
cli.callOperation.mockResolvedValue(frames)
|
||||
|
||||
await cli.run(
|
||||
'read',
|
||||
'vid-1',
|
||||
'--video-start',
|
||||
'0',
|
||||
'--video-end',
|
||||
'4',
|
||||
'--video-count',
|
||||
'2',
|
||||
'--annotation-id',
|
||||
'c-1',
|
||||
)
|
||||
|
||||
expect(cli.callOperation).toHaveBeenCalledWith(readAsset, {
|
||||
assetId: 'vid-1',
|
||||
annotationId: 'c-1',
|
||||
videoConfig: { start: 0, end: 4, count: 2 },
|
||||
})
|
||||
expect(cli.stdout()).toBe(
|
||||
[
|
||||
'Extracted 2 frame(s) from "clip.mp4" (0s - 4s):',
|
||||
'- Frame at 0s: https://files.example/0.webp',
|
||||
'- Frame at 4s: https://files.example/4.webp',
|
||||
'',
|
||||
].join('\n'),
|
||||
)
|
||||
})
|
||||
|
||||
it.each([
|
||||
[
|
||||
['--doc-mode', 'pages', '--doc-start-page', '1', '--doc-end-page', '3'],
|
||||
{ docConfig: { mode: 'pages', startPage: 1, endPage: 3 } },
|
||||
],
|
||||
[['--doc-mode', 'text'], { docConfig: { mode: 'text' } }],
|
||||
[['--degree', '90'], { config3d: { degree: 90 } }],
|
||||
[[], {}],
|
||||
])('reads with %j', async (flags, config) => {
|
||||
const cli = setup()
|
||||
cli.callOperation.mockResolvedValue({ ...frames, images: [] })
|
||||
|
||||
await cli.run('read', 'a-1', ...flags)
|
||||
|
||||
expect(cli.callOperation).toHaveBeenCalledWith(readAsset, { assetId: 'a-1', ...config })
|
||||
})
|
||||
|
||||
it('names the flag that is missing from a reader config', async () => {
|
||||
const cli = setup()
|
||||
|
||||
const error = await cli
|
||||
.run('read', 'vid-1', '--video-start', '0', '--video-count', '2')
|
||||
.catch((err: unknown) => err)
|
||||
|
||||
expect(formatCliError(error)).toContain('--video-end')
|
||||
expect(cli.callOperation).not.toHaveBeenCalled()
|
||||
})
|
||||
|
||||
it('prints text content after the summary', async () => {
|
||||
const cli = setup()
|
||||
cli.callOperation.mockResolvedValue({
|
||||
...frames,
|
||||
summary: 'Document "notes.md" (ID: d-1):',
|
||||
images: [],
|
||||
text: {
|
||||
content: '# Notes\nhello',
|
||||
truncated: true,
|
||||
size: 90000,
|
||||
mimeType: 'text/markdown',
|
||||
},
|
||||
})
|
||||
|
||||
await cli.run('read', 'd-1', '--doc-mode', 'text')
|
||||
|
||||
expect(cli.stdout()).toBe(
|
||||
'Document "notes.md" (ID: d-1):\n\n# Notes\nhello\n\n[Content truncated: showing the first part of a 90000-byte file. Run `shumai-cli download vid-1` to get the whole file.]\n',
|
||||
)
|
||||
})
|
||||
|
||||
it('returns right away with --no-wait and prints the render command', async () => {
|
||||
const cli = setup()
|
||||
cli.callOperation.mockResolvedValue(pendingRead)
|
||||
|
||||
await cli.run(
|
||||
'read',
|
||||
'vid-1',
|
||||
'--video-start',
|
||||
'0',
|
||||
'--video-end',
|
||||
'4',
|
||||
'--video-count',
|
||||
'2',
|
||||
'--no-wait',
|
||||
'--out',
|
||||
'frames',
|
||||
)
|
||||
|
||||
expect(cli.callOperation).toHaveBeenCalledWith(readAsset, {
|
||||
assetId: 'vid-1',
|
||||
videoConfig: { start: 0, end: 4, count: 2 },
|
||||
maxWaitSeconds: 0,
|
||||
})
|
||||
expect(cli.stdout()).toBe(
|
||||
'Rendering is still in progress for "clip.mp4".\nRun this to get the result: shumai-cli render task-1 --out "frames"\n',
|
||||
)
|
||||
})
|
||||
|
||||
it('prints the raw output with --json', async () => {
|
||||
const cli = setup()
|
||||
cli.callOperation.mockResolvedValue(frames)
|
||||
|
||||
await cli.run('--json', 'read', 'vid-1')
|
||||
|
||||
expect(JSON.parse(cli.stdout())).toEqual(frames)
|
||||
})
|
||||
})
|
||||
|
||||
describe('render', () => {
|
||||
it('fetches a pending render by task ID', async () => {
|
||||
const cli = setup()
|
||||
cli.callOperation.mockResolvedValue(frames)
|
||||
|
||||
await cli.run('render', 'task-1')
|
||||
|
||||
expect(cli.callOperation).toHaveBeenCalledWith(getAssetRender, { taskId: 'task-1' })
|
||||
expect(cli.stdout()).toContain('- Frame at 4s: https://files.example/4.webp')
|
||||
})
|
||||
|
||||
it('checks once with --no-wait', async () => {
|
||||
const cli = setup()
|
||||
cli.callOperation.mockResolvedValue(pendingRead)
|
||||
|
||||
await cli.run('render', 'task-1', '--no-wait')
|
||||
|
||||
expect(cli.callOperation).toHaveBeenCalledWith(getAssetRender, {
|
||||
taskId: 'task-1',
|
||||
maxWaitSeconds: 0,
|
||||
})
|
||||
expect(cli.stdout()).toContain('Run this to get the result: shumai-cli render task-1\n')
|
||||
})
|
||||
})
|
||||
|
||||
describe('download', () => {
|
||||
it('downloads the web previews by default, or the originals with --original', async () => {
|
||||
const cli = setup()
|
||||
cli.callOperation.mockResolvedValue({ files: [] })
|
||||
|
||||
await cli.run('download', 'a-1', 'a-2')
|
||||
expect(cli.callOperation).toHaveBeenLastCalledWith(downloadAsset, {
|
||||
assetIds: ['a-1', 'a-2'],
|
||||
})
|
||||
|
||||
await cli.run('download', 'a-1', '--original')
|
||||
expect(cli.callOperation).toHaveBeenLastCalledWith(downloadAsset, {
|
||||
assetIds: ['a-1'],
|
||||
proxy: false,
|
||||
})
|
||||
})
|
||||
|
||||
it('requires at least one asset ID and documents its options', async () => {
|
||||
const cli = setup()
|
||||
|
||||
await expect(cli.run('download')).rejects.toThrow()
|
||||
expect(cli.stderr()).toContain("missing required argument 'assetIds'")
|
||||
|
||||
await expect(cli.run('download', '--help')).rejects.toThrow()
|
||||
expect(cli.stdout()).toContain('-o, --out <dir>')
|
||||
expect(cli.stdout()).toContain('--original')
|
||||
expect(cli.stdout()).not.toContain('--proxy')
|
||||
})
|
||||
})
|
||||
|
||||
describe('--json', () => {
|
||||
it('prints the raw Operation output', async () => {
|
||||
const cli = setup()
|
||||
cli.callOperation.mockResolvedValue(folder)
|
||||
|
||||
await cli.run('mkdir', 'Renders', '-p', 'root', '--json')
|
||||
|
||||
expect(JSON.parse(cli.stdout())).toEqual(folder)
|
||||
})
|
||||
|
||||
it('works before the command too', async () => {
|
||||
const cli = setup()
|
||||
cli.callOperation.mockResolvedValue({ data: [] })
|
||||
|
||||
await cli.run('--json', 'project', 'ls')
|
||||
|
||||
expect(JSON.parse(cli.stdout())).toEqual({ data: [] })
|
||||
})
|
||||
})
|
||||
|
||||
describe('errors', () => {
|
||||
it('surfaces server errors for the entry point to print', async () => {
|
||||
const cli = setup()
|
||||
cli.callOperation.mockRejectedValue(new CliError('User is not a member of the team'))
|
||||
|
||||
const error = await cli.run('mkdir', 'x', '-p', 'root').catch((err: unknown) => err)
|
||||
|
||||
expect(formatCliError(error)).toBe('Error: User is not a member of the team')
|
||||
})
|
||||
|
||||
it('validates input against the Operation schema before calling the server', async () => {
|
||||
const cli = setup()
|
||||
|
||||
const error = await cli.run('mkdir', '', '-p', 'root').catch((err: unknown) => err)
|
||||
|
||||
expect(error).toBeInstanceOf(CliError)
|
||||
expect(cli.callOperation).not.toHaveBeenCalled()
|
||||
})
|
||||
|
||||
it('suggests similar commands for typos', async () => {
|
||||
const cli = setup()
|
||||
|
||||
await expect(cli.run('mkidr', 'x')).rejects.toThrow()
|
||||
expect(cli.stderr()).toContain('Did you mean mkdir?')
|
||||
})
|
||||
})
|
||||
|
||||
describe('help', () => {
|
||||
it('lists every command, including generated ones', async () => {
|
||||
const cli = setup()
|
||||
|
||||
await expect(cli.run('--help')).rejects.toThrow()
|
||||
|
||||
const help = cli.stdout()
|
||||
for (const command of [
|
||||
'project',
|
||||
'ls',
|
||||
'mkdir',
|
||||
'rename',
|
||||
'move|mv',
|
||||
'delete|rm',
|
||||
'read',
|
||||
'render',
|
||||
'download',
|
||||
'upload',
|
||||
'create-version',
|
||||
]) {
|
||||
expect(help).toContain(command)
|
||||
}
|
||||
expect(help).toContain('--json')
|
||||
})
|
||||
|
||||
it('documents generated options from the Operation schema', async () => {
|
||||
const cli = setup()
|
||||
|
||||
await expect(cli.run('ls', '--help')).rejects.toThrow()
|
||||
|
||||
const help = cli.stdout()
|
||||
expect(help).toContain('-p, --parent <parent>')
|
||||
expect(help).toContain('The parent folder ID to list assets from.')
|
||||
expect(help).toContain('--type <type>')
|
||||
expect(help).toContain('choices: "file", "folder", "all"')
|
||||
expect(help).toContain('(default: 200)')
|
||||
expect(help).toContain('List the files and folders inside a parent folder.')
|
||||
})
|
||||
|
||||
it('documents flattened reader options for read', async () => {
|
||||
const cli = setup()
|
||||
|
||||
await expect(cli.run('read', '--help')).rejects.toThrow()
|
||||
|
||||
const help = cli.stdout()
|
||||
for (const flag of [
|
||||
'--video-start <start>',
|
||||
'--video-end <end>',
|
||||
'--video-count <count>',
|
||||
'--doc-mode <mode>',
|
||||
'--doc-start-page <startPage>',
|
||||
'--doc-end-page <endPage>',
|
||||
'--degree <degree>',
|
||||
'--annotation-id <annotationId>',
|
||||
'-o, --out <dir>',
|
||||
'--no-wait',
|
||||
]) {
|
||||
expect(help).toContain(flag)
|
||||
}
|
||||
expect(help).not.toContain('--include-content')
|
||||
expect(help).not.toContain('--image')
|
||||
})
|
||||
})
|
||||
|
||||
describe('search', () => {
|
||||
it('searches a folder by name with the maximum page size', async () => {
|
||||
const cli = setup()
|
||||
cli.callOperation.mockResolvedValue({
|
||||
data: [{ id: 'f1', name: 'sunset.png', type: 'file', size: 10, projectId: 'p' }],
|
||||
pageInfo: { hasNextPage: false, endCursor: null },
|
||||
total: 1,
|
||||
})
|
||||
|
||||
await cli.run('search', 'sunset', '-p', 'root-1')
|
||||
|
||||
expect(cli.callOperation).toHaveBeenCalledWith(searchAssets, {
|
||||
parent: 'root-1',
|
||||
query: 'sunset',
|
||||
first: 200,
|
||||
})
|
||||
expect(cli.stdout()).toContain('sunset.png')
|
||||
})
|
||||
|
||||
it('searches by meaning with --semantic', async () => {
|
||||
const cli = setup()
|
||||
cli.callOperation.mockResolvedValue({
|
||||
data: [],
|
||||
pageInfo: { hasNextPage: false, endCursor: null },
|
||||
total: 0,
|
||||
})
|
||||
|
||||
await cli.run('search', 'a calm beach', '-p', 'root-1', '--semantic')
|
||||
|
||||
expect(cli.callOperation).toHaveBeenCalledWith(
|
||||
searchAssets,
|
||||
expect.objectContaining({ query: 'a calm beach', semantic: true }),
|
||||
)
|
||||
})
|
||||
})
|
||||
|
||||
describe('copy', () => {
|
||||
it.each(['copy', 'cp'])('copies assets with %s', async (command) => {
|
||||
const cli = setup()
|
||||
cli.callOperation.mockResolvedValue({ copiedAssetIds: ['c-1', 'c-2'], newParentId: 'f-2' })
|
||||
|
||||
await cli.run(command, 'a-1', 'a-2', '-p', 'f-2', '--with-comments')
|
||||
|
||||
expect(cli.callOperation).toHaveBeenCalledWith(copyAssets, {
|
||||
assetIds: ['a-1', 'a-2'],
|
||||
newParentId: 'f-2',
|
||||
withComments: true,
|
||||
})
|
||||
expect(cli.stdout()).toBe('Copied 2 asset(s) to parent f-2: c-1, c-2\n')
|
||||
})
|
||||
})
|
||||
|
||||
describe('comment', () => {
|
||||
const thread = {
|
||||
id: 'c-1',
|
||||
message: 'Too dark here',
|
||||
author: { id: 'u-1', name: 'Ana' },
|
||||
second: 12.5,
|
||||
hasMarkup: false,
|
||||
attachmentCount: 0,
|
||||
createdAt: '2026-01-01T00:00:00.000Z',
|
||||
resolved: true,
|
||||
replies: [
|
||||
{
|
||||
id: 'c-2',
|
||||
message: 'Fixed in v2',
|
||||
author: { id: 'u-2', name: 'Bo' },
|
||||
second: null,
|
||||
hasMarkup: false,
|
||||
attachmentCount: 0,
|
||||
createdAt: '2026-01-02T00:00:00.000Z',
|
||||
},
|
||||
],
|
||||
}
|
||||
|
||||
it('lists threads with their replies', async () => {
|
||||
const cli = setup()
|
||||
cli.callOperation.mockResolvedValue({
|
||||
data: [thread],
|
||||
pageInfo: { hasNextPage: false, endCursor: null },
|
||||
total: 1,
|
||||
})
|
||||
|
||||
await cli.run('comment', 'ls', 'vid-1')
|
||||
|
||||
expect(cli.callOperation).toHaveBeenCalledWith(listComments, {
|
||||
assetId: 'vid-1',
|
||||
first: 200,
|
||||
})
|
||||
expect(cli.stdout()).toBe(
|
||||
'c-1 @12.5s [resolved] Ana: Too dark here\n ↳ c-2 Bo: Fixed in v2\n',
|
||||
)
|
||||
})
|
||||
|
||||
it('posts a reply at a timecode', async () => {
|
||||
const cli = setup()
|
||||
cli.callOperation.mockResolvedValue({ id: 'c-3', assetId: 'vid-1', replyToId: 'c-1' })
|
||||
|
||||
await cli.run('comment', 'add', 'vid-1', 'Looks good now', '--reply-to', 'c-1', '--at', '3')
|
||||
|
||||
expect(cli.callOperation).toHaveBeenCalledWith(createComment, {
|
||||
assetId: 'vid-1',
|
||||
message: 'Looks good now',
|
||||
replyToId: 'c-1',
|
||||
second: 3,
|
||||
})
|
||||
expect(cli.stdout()).toBe('Posted comment c-3\n')
|
||||
})
|
||||
|
||||
it('resolves and reopens comments', async () => {
|
||||
const cli = setup()
|
||||
cli.callOperation.mockResolvedValueOnce({ commentId: 'c-1', resolved: true })
|
||||
cli.callOperation.mockResolvedValueOnce({ commentId: 'c-1', resolved: false })
|
||||
|
||||
await cli.run('comment', 'resolve', 'c-1')
|
||||
await cli.run('comment', 'resolve', 'c-1', '--reopen')
|
||||
|
||||
expect(cli.callOperation).toHaveBeenNthCalledWith(1, resolveComment, { commentId: 'c-1' })
|
||||
expect(cli.callOperation).toHaveBeenNthCalledWith(2, resolveComment, {
|
||||
commentId: 'c-1',
|
||||
reopen: true,
|
||||
})
|
||||
expect(cli.stdout()).toBe('Comment c-1 is resolved\nComment c-1 is unresolved\n')
|
||||
})
|
||||
})
|
||||
|
||||
describe('meta set', () => {
|
||||
it('passes --values as a JSON object', async () => {
|
||||
const cli = setup()
|
||||
cli.callOperation.mockResolvedValue({ assetId: 'a-1', updatedKeys: ['status', 'rating'] })
|
||||
|
||||
await cli.run('meta', 'set', 'a-1', '--values', '{"status":"approved","rating":4}')
|
||||
|
||||
expect(cli.callOperation).toHaveBeenCalledWith(updateAssetMetadata, {
|
||||
assetId: 'a-1',
|
||||
values: { status: 'approved', rating: 4 },
|
||||
})
|
||||
expect(cli.stdout()).toBe('Updated status, rating on a-1\n')
|
||||
})
|
||||
|
||||
it.each([
|
||||
['{not json', 'Not valid JSON.'],
|
||||
['["status"]', 'Expected a JSON object'],
|
||||
])('rejects --values %s', async (value, message) => {
|
||||
const cli = setup()
|
||||
|
||||
await expect(cli.run('meta', 'set', 'a-1', '--values', value)).rejects.toThrow()
|
||||
expect(cli.stderr()).toContain(message)
|
||||
expect(cli.callOperation).not.toHaveBeenCalled()
|
||||
})
|
||||
})
|
||||
|
||||
describe('field ls', () => {
|
||||
it("lists a project's fields with their choices", async () => {
|
||||
const cli = setup()
|
||||
cli.callOperation.mockResolvedValue({
|
||||
fields: [
|
||||
{
|
||||
key: 'status',
|
||||
name: 'Status',
|
||||
type: 'select',
|
||||
description: '',
|
||||
readOnly: false,
|
||||
creationContext: false,
|
||||
options: [{ id: 'approved', name: 'Approved' }],
|
||||
},
|
||||
{
|
||||
key: 'prompt',
|
||||
name: 'Prompt',
|
||||
type: 'text',
|
||||
description: '',
|
||||
readOnly: false,
|
||||
creationContext: true,
|
||||
},
|
||||
],
|
||||
})
|
||||
|
||||
await cli.run('field', 'ls', 'p-1')
|
||||
|
||||
expect(cli.callOperation).toHaveBeenCalledWith(listMetadataFields, { projectId: 'p-1' })
|
||||
expect(cli.stdout()).toBe(
|
||||
'status Status (select) [approved=Approved]\nprompt Prompt (text, creation)\n',
|
||||
)
|
||||
})
|
||||
})
|
||||
|
||||
describe('version', () => {
|
||||
it('stacks files, lists versions, and unstacks one', async () => {
|
||||
const cli = setup()
|
||||
cli.callOperation.mockResolvedValueOnce({
|
||||
id: 's-1',
|
||||
name: 'cut_v2.mp4',
|
||||
type: 'version_stack',
|
||||
size: 20,
|
||||
projectId: 'p-1',
|
||||
})
|
||||
cli.callOperation.mockResolvedValueOnce({
|
||||
versions: [
|
||||
{
|
||||
id: 'v-2',
|
||||
version: 2,
|
||||
name: 'cut_v2.mp4',
|
||||
current: true,
|
||||
createdAt: '2026-01-02T00:00:00.000Z',
|
||||
creator: null,
|
||||
agent: null,
|
||||
},
|
||||
{
|
||||
id: 'v-1',
|
||||
version: 1,
|
||||
name: 'cut_v1.mp4',
|
||||
current: false,
|
||||
createdAt: '2026-01-01T00:00:00.000Z',
|
||||
creator: null,
|
||||
agent: null,
|
||||
},
|
||||
],
|
||||
})
|
||||
cli.callOperation.mockResolvedValueOnce({ versionId: 'v-1', stackId: 's-1' })
|
||||
|
||||
await cli.run('version', 'stack', 'v-2', 'v-1')
|
||||
await cli.run('version', 'ls', 's-1')
|
||||
await cli.run('version', 'unstack', 'v-1')
|
||||
|
||||
expect(cli.callOperation).toHaveBeenNthCalledWith(1, createVersionStack, {
|
||||
fileIds: ['v-2', 'v-1'],
|
||||
})
|
||||
expect(cli.callOperation).toHaveBeenNthCalledWith(2, listVersions, { stackId: 's-1' })
|
||||
expect(cli.callOperation).toHaveBeenNthCalledWith(3, removeVersion, { versionId: 'v-1' })
|
||||
expect(cli.stdout()).toBe(
|
||||
'Created version stack s-1\n' +
|
||||
'v2 (current) v-2 cut_v2.mp4\nv1 v-1 cut_v1.mp4\n' +
|
||||
'Removed v-1 from version stack s-1\n',
|
||||
)
|
||||
})
|
||||
})
|
||||
|
||||
describe('instructions', () => {
|
||||
it("prints a folder's instructions, or says it has none", async () => {
|
||||
const cli = setup()
|
||||
cli.callOperation.mockResolvedValueOnce({ folderId: 'f-1', content: '# Rules' })
|
||||
cli.callOperation.mockResolvedValueOnce({ folderId: 'f-2', content: null })
|
||||
|
||||
await cli.run('instructions', 'f-1')
|
||||
await cli.run('instructions', 'f-2')
|
||||
|
||||
expect(cli.callOperation).toHaveBeenCalledWith(getFolderInstructions, { folderId: 'f-1' })
|
||||
expect(cli.stdout()).toBe('# Rules\n(This folder has no instructions.)\n')
|
||||
})
|
||||
})
|
||||
|
||||
describe('runner start', () => {
|
||||
it('documents and forwards the -v, --verbose flag', async () => {
|
||||
const cli = setup()
|
||||
await expect(cli.run('runner', 'start', '--help')).rejects.toThrow()
|
||||
expect(cli.stdout()).toContain('-v, --verbose')
|
||||
|
||||
await cli.run('runner', 'start')
|
||||
expect(cli.startRunner).toHaveBeenLastCalledWith({})
|
||||
|
||||
await cli.run('runner', 'start', '-v')
|
||||
expect(cli.startRunner).toHaveBeenLastCalledWith({ verbose: true })
|
||||
|
||||
await cli.run('runner', 'start', '--verbose')
|
||||
expect(cli.startRunner).toHaveBeenLastCalledWith({ verbose: true })
|
||||
})
|
||||
})
|
||||
|
||||
it('has no upload Operation commands: upload and create-version stream local files', () => {
|
||||
const program = createProgram({ callOperation: vi.fn<CallOperation>() })
|
||||
const names = program.commands.map((c) => c.name())
|
||||
expect(names).not.toContain('complete-upload')
|
||||
expect(names.filter((n) => n === 'create-version')).toHaveLength(1)
|
||||
})
|
||||
})
|
||||
|
||||
describe('formatCliError', () => {
|
||||
beforeEach(() => vi.restoreAllMocks())
|
||||
|
||||
it('formats expected and unexpected errors', () => {
|
||||
expect(formatCliError(new CliError('boom'))).toBe('Error: boom')
|
||||
expect(
|
||||
formatCliError(new CliError('Error connecting to API server: x', { prefixed: true })),
|
||||
).toBe('Error connecting to API server: x')
|
||||
expect(formatCliError(new TypeError('bad'))).toBe('Unexpected error: bad')
|
||||
})
|
||||
})
|
||||
@@ -0,0 +1,76 @@
|
||||
import { Command } from 'commander'
|
||||
import { operationDefinitions } from '@shumai/operations'
|
||||
import { createVersion } from './commands/create-version'
|
||||
import { upload } from './commands/upload'
|
||||
import { callOperation, type CallOperation } from './operations/call-operation'
|
||||
import { cliExtensions } from './operations/extensions'
|
||||
import { registerOperationCommands } from './operations/generate'
|
||||
import type { Output } from './operations/render'
|
||||
import { version } from '../package.json'
|
||||
import { startRunner } from './runner/client'
|
||||
import type { RunnerOptions } from './runner/config'
|
||||
|
||||
export interface ProgramOptions {
|
||||
callOperation?: CallOperation
|
||||
output?: Output
|
||||
startRunner?: (options: RunnerOptions) => Promise<void>
|
||||
}
|
||||
|
||||
function isDeleteAllowed(): boolean {
|
||||
const value = process.env.SHUMAI_ALLOW_DELETE
|
||||
return value === 'true' || value === '1'
|
||||
}
|
||||
|
||||
/**
|
||||
* Builds the `shumai-cli` program. Operation commands (ls, mkdir, rename, move, delete,
|
||||
* read, render, project ls, ...) are generated from `@shumai/operations`; upload and create-version stream
|
||||
* local files and are defined here.
|
||||
*/
|
||||
export function createProgram(options: ProgramOptions = {}): Command {
|
||||
const program = new Command()
|
||||
.name('shumai-cli')
|
||||
.description('Command line interface for the Shumai media workspace.')
|
||||
.version(version)
|
||||
.option('--json', 'Print raw JSON output instead of human-friendly text')
|
||||
.showHelpAfterError()
|
||||
.showSuggestionAfterError()
|
||||
|
||||
registerOperationCommands(program, operationDefinitions, {
|
||||
callOperation: options.callOperation ?? callOperation,
|
||||
output: options.output ?? {
|
||||
out: process.stdout,
|
||||
isTty: Boolean(process.stdout.isTTY),
|
||||
columns: process.stdout.columns || 80,
|
||||
},
|
||||
allowDestructive: isDeleteAllowed,
|
||||
extensions: cliExtensions,
|
||||
})
|
||||
|
||||
program
|
||||
.command('runner')
|
||||
.description('Connect a local command runner to Shumai.')
|
||||
.command('start')
|
||||
.description('Run in the foreground using a key created in Settings → Agent Runners.')
|
||||
.option('--url <url>', 'Shumai server URL (or SHUMAI_API_SERVER).')
|
||||
.option('--key <key>', 'Runner key (prefer SHUMAI_RUNNER_KEY to avoid shell history).')
|
||||
.option('--cwd <directory>', 'Runner workspace directory (defaults to the current directory).')
|
||||
.option('--srt <file>', 'Sandbox commands with bundled SRT using this JSON settings file.')
|
||||
.option('-v, --verbose', 'Show command details, output sizes, and file transfer paths.')
|
||||
.action((opts: RunnerOptions) => (options.startRunner ?? startRunner)(opts))
|
||||
|
||||
program
|
||||
.command('upload')
|
||||
.description('Upload a local file or folder to a parent folder.')
|
||||
.argument('<path>', 'Local file or folder to upload.')
|
||||
.requiredOption('-p, --parent <parentId>', 'The parent folder ID to upload into.')
|
||||
.action((localPath: string, opts: { parent: string }) => upload(localPath, opts.parent))
|
||||
|
||||
program
|
||||
.command('create-version')
|
||||
.description('Upload a local file as a new version of an existing file or version stack.')
|
||||
.argument('<path>', 'Local file to upload as the new version.')
|
||||
.requiredOption('-p, --parent <parentId>', 'The file or version stack ID to add a version to.')
|
||||
.action((localPath: string, opts: { parent: string }) => createVersion(localPath, opts.parent))
|
||||
|
||||
return program
|
||||
}
|
||||
@@ -0,0 +1,446 @@
|
||||
import { createServer } from 'node:http'
|
||||
import { mkdtemp, rm } from 'node:fs/promises'
|
||||
import { tmpdir } from 'node:os'
|
||||
import path from 'node:path'
|
||||
import { WebSocketServer, type WebSocket } from 'ws'
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
|
||||
import { runnerToServerMessageSchema, type RunnerToServerMessage } from '@shumai/dtos'
|
||||
import { RunnerClient } from './client'
|
||||
import { RunnerFiles } from './files'
|
||||
import { RunnerShell } from './shell'
|
||||
|
||||
describe('runner WebSocket client', () => {
|
||||
let cwd: string
|
||||
let server: WebSocketServer
|
||||
let runner: RunnerClient
|
||||
let running: Promise<void>
|
||||
let socket: WebSocket
|
||||
let messages: RunnerToServerMessage[]
|
||||
let welcomeInFlight: string[]
|
||||
let connections: number
|
||||
let replacePrevious: boolean
|
||||
let connectRunner: (options?: { verbose?: boolean; log?: (line: string) => void }) => RunnerClient
|
||||
beforeEach(async () => {
|
||||
cwd = await mkdtemp(path.join(tmpdir(), 'shumai-client-test-'))
|
||||
messages = []
|
||||
welcomeInFlight = []
|
||||
connections = 0
|
||||
replacePrevious = false
|
||||
server = new WebSocketServer({ host: '127.0.0.1', port: 0 })
|
||||
await new Promise<void>((resolve) => server.once('listening', resolve))
|
||||
const address = server.address()
|
||||
if (!address || typeof address === 'string') throw new Error('No WebSocket address')
|
||||
server.on('connection', (connection, request) => {
|
||||
expect(request.headers.authorization).toBe('Bearer runner-key')
|
||||
if (replacePrevious) socket.close(4000, 'Replaced by a newer connection')
|
||||
socket = connection
|
||||
connections++
|
||||
connection.on('message', (raw) =>
|
||||
messages.push(runnerToServerMessageSchema.parse(JSON.parse(raw.toString()))),
|
||||
)
|
||||
connection.send(
|
||||
JSON.stringify({
|
||||
type: 'welcome',
|
||||
runnerId: 'runner',
|
||||
runnerName: 'Test',
|
||||
serverTime: Date.now(),
|
||||
inFlightExecutionIds: welcomeInFlight,
|
||||
}),
|
||||
)
|
||||
})
|
||||
connectRunner = (options) => {
|
||||
const files = new RunnerFiles(cwd)
|
||||
return new RunnerClient(
|
||||
{
|
||||
url: new URL(`ws://127.0.0.1:${address.port}/api/runners/ws`),
|
||||
key: 'runner-key',
|
||||
cwd,
|
||||
srt: undefined,
|
||||
verbose: options?.verbose ?? false,
|
||||
},
|
||||
files,
|
||||
new RunnerShell(files),
|
||||
options?.log ?? (() => {}),
|
||||
)
|
||||
}
|
||||
runner = connectRunner()
|
||||
running = runner.run()
|
||||
// Attach an error handler immediately, including for tests exercising terminal errors.
|
||||
void running.catch(() => {})
|
||||
await vi.waitFor(() =>
|
||||
expect(messages.some((message) => message.type === 'reconcile')).toBe(true),
|
||||
)
|
||||
})
|
||||
afterEach(async () => {
|
||||
runner.stop()
|
||||
await running.catch(() => {})
|
||||
for (const connection of server.clients) connection.terminate()
|
||||
await new Promise<void>((resolve) => server.close(() => resolve()))
|
||||
await rm(cwd, { recursive: true, force: true })
|
||||
})
|
||||
const send = (message: unknown) => socket.send(JSON.stringify(message))
|
||||
|
||||
it('responds to heartbeat, executes a command once and streams byte offsets', async () => {
|
||||
expect(messages).toContainEqual(
|
||||
expect.objectContaining({
|
||||
type: 'reconcile',
|
||||
environment: { platform: process.platform, shell: '/bin/sh' },
|
||||
}),
|
||||
)
|
||||
send({ type: 'ping', ts: 123 })
|
||||
const command = {
|
||||
type: 'exec.start',
|
||||
executionId: 'one',
|
||||
command: 'printf "世界"; printf "error" >&2',
|
||||
}
|
||||
send(command)
|
||||
send(command)
|
||||
await vi.waitFor(() =>
|
||||
expect(messages.some((message) => message.type === 'exec.result')).toBe(true),
|
||||
)
|
||||
expect(messages).toContainEqual({ type: 'pong', ts: 123 })
|
||||
expect(messages.filter((message) => message.type === 'exec.result')).toHaveLength(1)
|
||||
const chunks = messages.filter((message) => message.type === 'exec.output')
|
||||
expect(chunks.map((chunk) => chunk.data).join('')).toContain('世界')
|
||||
let offset = 0
|
||||
for (const chunk of chunks) {
|
||||
expect(chunk.offset).toBe(offset)
|
||||
offset += Buffer.byteLength(chunk.data)
|
||||
}
|
||||
})
|
||||
|
||||
it('cancels an active command through the protocol', async () => {
|
||||
send({ type: 'exec.start', executionId: 'cancel', command: 'echo ready; sleep 30' })
|
||||
await vi.waitFor(() =>
|
||||
expect(messages.some((message) => message.type === 'exec.output')).toBe(true),
|
||||
)
|
||||
send({ type: 'exec.cancel', executionId: 'cancel' })
|
||||
await vi.waitFor(() =>
|
||||
expect(messages).toContainEqual(
|
||||
expect.objectContaining({ type: 'exec.result', executionId: 'cancel', aborted: true }),
|
||||
),
|
||||
)
|
||||
})
|
||||
|
||||
it('reconnects and replays output before completing an in-flight command', async () => {
|
||||
send({
|
||||
type: 'exec.start',
|
||||
executionId: 'reconnect',
|
||||
command: 'echo before; sleep 0.2; echo after',
|
||||
})
|
||||
await vi.waitFor(() =>
|
||||
expect(messages.some((message) => message.type === 'exec.output')).toBe(true),
|
||||
)
|
||||
welcomeInFlight = ['reconnect']
|
||||
socket.terminate()
|
||||
messages = []
|
||||
await vi.waitFor(() => expect(connections).toBe(2), { timeout: 5000 })
|
||||
await vi.waitFor(() =>
|
||||
expect(messages.some((message) => message.type === 'reconcile')).toBe(true),
|
||||
)
|
||||
const reconciliation = messages.findIndex((message) => message.type === 'reconcile')
|
||||
expect(
|
||||
messages
|
||||
.slice(0, reconciliation)
|
||||
.filter((message) => message.type === 'exec.output')
|
||||
.map((message) => message.data)
|
||||
.join(''),
|
||||
).toContain('after')
|
||||
expect(messages[reconciliation]).toMatchObject({
|
||||
completedExecutions: [expect.objectContaining({ executionId: 'reconnect', exitCode: 0 })],
|
||||
})
|
||||
})
|
||||
|
||||
it('handles file requests and returns a cached result for a duplicate request', async () => {
|
||||
const request = { type: 'file.stat', executionId: 'stat', srcPath: '.pi/missing' }
|
||||
send(request)
|
||||
await vi.waitFor(() =>
|
||||
expect(messages.some((message) => message.type === 'file.stat.result')).toBe(true),
|
||||
)
|
||||
send(request)
|
||||
await vi.waitFor(() =>
|
||||
expect(messages.filter((message) => message.type === 'file.stat.result')).toHaveLength(2),
|
||||
)
|
||||
expect(messages.at(-1)).toMatchObject({ ok: true, exists: false })
|
||||
})
|
||||
|
||||
it('stops instead of reconnecting when the runner key is revoked', async () => {
|
||||
socket.close(1008, 'revoked')
|
||||
await expect(running).rejects.toThrow('revoked')
|
||||
expect(connections).toBe(1)
|
||||
})
|
||||
|
||||
it('stops the superseded client when a second runner connects with the same key', async () => {
|
||||
replacePrevious = true
|
||||
let replaced: unknown
|
||||
void running.catch((error: unknown) => {
|
||||
replaced = error
|
||||
})
|
||||
const replacement = connectRunner()
|
||||
const replacementRun = replacement.run()
|
||||
void replacementRun.catch(() => {})
|
||||
try {
|
||||
await vi.waitFor(() => expect(replaced).toBeInstanceOf(Error))
|
||||
await expect(running).rejects.toThrow('replaced')
|
||||
expect(connections).toBe(2)
|
||||
} finally {
|
||||
replacement.stop()
|
||||
await replacementRun.catch(() => {})
|
||||
}
|
||||
})
|
||||
|
||||
it('rejects invalid messages and path-like execution IDs', async () => {
|
||||
send({ type: 'exec.start', executionId: '../escape', command: 'echo unsafe' })
|
||||
await expect(running).rejects.toThrow('invalid runner protocol')
|
||||
expect(messages.some((message) => message.type === 'exec.output')).toBe(false)
|
||||
})
|
||||
|
||||
it('logs compact lifecycle, bash, and transfer summaries in default mode', async () => {
|
||||
runner.stop()
|
||||
await running.catch(() => {})
|
||||
const logs: string[] = []
|
||||
messages = []
|
||||
runner = connectRunner({ verbose: false, log: (line) => logs.push(line) })
|
||||
running = runner.run()
|
||||
void running.catch(() => {})
|
||||
await vi.waitFor(() =>
|
||||
expect(messages.some((message) => message.type === 'reconcile')).toBe(true),
|
||||
)
|
||||
|
||||
send({ type: 'exec.start', executionId: '01JTEST0000A8F2', command: 'printf "hello"' })
|
||||
await vi.waitFor(() =>
|
||||
expect(messages.some((message) => message.type === 'exec.result')).toBe(true),
|
||||
)
|
||||
|
||||
send({
|
||||
type: 'exec.start',
|
||||
executionId: '01JTEST0000TOUT',
|
||||
command: 'sleep 5',
|
||||
timeoutSec: 0.1,
|
||||
})
|
||||
await vi.waitFor(() =>
|
||||
expect(
|
||||
messages.some(
|
||||
(message) => message.type === 'exec.result' && message.executionId === '01JTEST0000TOUT',
|
||||
),
|
||||
).toBe(true),
|
||||
)
|
||||
|
||||
send({ type: 'file.stat', executionId: '01JTEST0000STAT', srcPath: '.pi/missing' })
|
||||
await vi.waitFor(() =>
|
||||
expect(messages.some((message) => message.type === 'file.stat.result')).toBe(true),
|
||||
)
|
||||
|
||||
const httpServer = createServer((_request, response) => {
|
||||
response.end('payload')
|
||||
})
|
||||
await new Promise<void>((resolve) => httpServer.listen(0, '127.0.0.1', resolve))
|
||||
try {
|
||||
const httpAddress = httpServer.address()
|
||||
if (!httpAddress || typeof httpAddress === 'string') throw new Error('No HTTP address')
|
||||
send({
|
||||
type: 'file.download',
|
||||
executionId: '01JTEST0000C3D9',
|
||||
url: `http://127.0.0.1:${httpAddress.port}/file`,
|
||||
destPath: '.pi/assets/file.txt',
|
||||
})
|
||||
await vi.waitFor(() =>
|
||||
expect(messages.some((message) => message.type === 'file.download.result')).toBe(true),
|
||||
)
|
||||
} finally {
|
||||
httpServer.closeAllConnections()
|
||||
await new Promise<void>((resolve) => httpServer.close(() => resolve()))
|
||||
}
|
||||
|
||||
expect(
|
||||
logs.some((line) =>
|
||||
/^\d{2}:\d{2}:\d{2} INFO {2}Runner connected: Test \(runner\)$/.test(line),
|
||||
),
|
||||
).toBe(true)
|
||||
expect(
|
||||
logs.some((line) => /^\d{2}:\d{2}:\d{2} INFO {2}Bash started \[a8f2\]$/.test(line)),
|
||||
).toBe(true)
|
||||
expect(
|
||||
logs.some((line) =>
|
||||
/^\d{2}:\d{2}:\d{2} INFO {2}Bash completed \[a8f2\] exit=0 duration=\d+\.\ds$/.test(line),
|
||||
),
|
||||
).toBe(true)
|
||||
expect(
|
||||
logs.some((line) =>
|
||||
/^\d{2}:\d{2}:\d{2} WARN {2}Bash timed out \[tout\] duration=\d+\.\ds$/.test(line),
|
||||
),
|
||||
).toBe(true)
|
||||
expect(
|
||||
logs.some((line) =>
|
||||
/^\d{2}:\d{2}:\d{2} INFO {2}File download completed \[c3d9\] size=7B duration=\d+\.\ds$/.test(
|
||||
line,
|
||||
),
|
||||
),
|
||||
).toBe(true)
|
||||
expect(logs.join('\n')).not.toContain('command=')
|
||||
expect(logs.join('\n')).not.toContain('File stat')
|
||||
expect(logs.join('\n')).not.toContain('.pi/assets/file.txt')
|
||||
})
|
||||
|
||||
it('logs commands, stream sizes, and file paths in verbose mode', async () => {
|
||||
runner.stop()
|
||||
await running.catch(() => {})
|
||||
const logs: string[] = []
|
||||
messages = []
|
||||
runner = connectRunner({ verbose: true, log: (line) => logs.push(line) })
|
||||
running = runner.run()
|
||||
void running.catch(() => {})
|
||||
await vi.waitFor(() =>
|
||||
expect(messages.some((message) => message.type === 'reconcile')).toBe(true),
|
||||
)
|
||||
|
||||
send({
|
||||
type: 'exec.start',
|
||||
executionId: '01JTEST0000B9E1',
|
||||
command: 'printf "hi"; printf "err" >&2',
|
||||
})
|
||||
await vi.waitFor(() =>
|
||||
expect(messages.some((message) => message.type === 'exec.result')).toBe(true),
|
||||
)
|
||||
|
||||
send({ type: 'file.stat', executionId: '01JTEST0000B1A4', srcPath: '.pi/missing' })
|
||||
await vi.waitFor(() =>
|
||||
expect(messages.some((message) => message.type === 'file.stat.result')).toBe(true),
|
||||
)
|
||||
|
||||
const httpServer = createServer((_request, response) => {
|
||||
response.writeHead(500)
|
||||
response.end()
|
||||
})
|
||||
await new Promise<void>((resolve) => httpServer.listen(0, '127.0.0.1', resolve))
|
||||
try {
|
||||
const httpAddress = httpServer.address()
|
||||
if (!httpAddress || typeof httpAddress === 'string') throw new Error('No HTTP address')
|
||||
send({
|
||||
type: 'file.download',
|
||||
executionId: '01JTEST0000E5F1',
|
||||
url: `http://127.0.0.1:${httpAddress.port}/fail`,
|
||||
destPath: '.pi/assets/fail.txt',
|
||||
})
|
||||
await vi.waitFor(() =>
|
||||
expect(messages.some((message) => message.type === 'file.download.result')).toBe(true),
|
||||
)
|
||||
} finally {
|
||||
httpServer.closeAllConnections()
|
||||
await new Promise<void>((resolve) => httpServer.close(() => resolve()))
|
||||
}
|
||||
|
||||
expect(
|
||||
logs.some((line) =>
|
||||
/^\d{2}:\d{2}:\d{2} INFO {2}Bash started \[b9e1\] command="printf \\"hi\\"; printf \\"err\\" >&2"$/.test(
|
||||
line,
|
||||
),
|
||||
),
|
||||
).toBe(true)
|
||||
expect(
|
||||
logs.some((line) =>
|
||||
/^\d{2}:\d{2}:\d{2} INFO {2}Bash completed \[b9e1\] exit=0 duration=\d+\.\ds stdout=2B stderr=3B$/.test(
|
||||
line,
|
||||
),
|
||||
),
|
||||
).toBe(true)
|
||||
expect(
|
||||
logs.some((line) =>
|
||||
/^\d{2}:\d{2}:\d{2} INFO {2}File stat \[b1a4\] path="\.pi\/missing" exists=false$/.test(
|
||||
line,
|
||||
),
|
||||
),
|
||||
).toBe(true)
|
||||
expect(
|
||||
logs.some((line) =>
|
||||
/^\d{2}:\d{2}:\d{2} INFO {2}File download started \[e5f1\] path="\.pi\/assets\/fail\.txt"$/.test(
|
||||
line,
|
||||
),
|
||||
),
|
||||
).toBe(true)
|
||||
expect(
|
||||
logs.some((line) =>
|
||||
/^\d{2}:\d{2}:\d{2} WARN {2}File download failed \[e5f1\] path="\.pi\/assets\/fail\.txt" duration=\d+\.\ds error="Download failed \(HTTP 500\)\."$/.test(
|
||||
line,
|
||||
),
|
||||
),
|
||||
).toBe(true)
|
||||
})
|
||||
|
||||
it.each([false, true])(
|
||||
'logs a single busy rejection without false starts at capacity (verbose=%s)',
|
||||
async (verbose) => {
|
||||
runner.stop()
|
||||
await running.catch(() => {})
|
||||
const logs: string[] = []
|
||||
messages = []
|
||||
runner = connectRunner({ verbose, log: (line) => logs.push(line) })
|
||||
running = runner.run()
|
||||
void running.catch(() => {})
|
||||
await vi.waitFor(() =>
|
||||
expect(messages.some((message) => message.type === 'reconcile')).toBe(true),
|
||||
)
|
||||
|
||||
for (let index = 0; index < 8; index++) {
|
||||
send({
|
||||
type: 'exec.start',
|
||||
executionId: `01JACTIVE00000${index}`,
|
||||
command: 'sleep 30',
|
||||
})
|
||||
}
|
||||
await vi.waitFor(() =>
|
||||
expect(logs.filter((line) => line.includes('Bash started'))).toHaveLength(8),
|
||||
)
|
||||
|
||||
send({
|
||||
type: 'exec.start',
|
||||
executionId: '01JBUSYCMD00B123',
|
||||
command: 'echo rejected',
|
||||
})
|
||||
send({
|
||||
type: 'file.upload',
|
||||
executionId: '01JBUSYFILE0U456',
|
||||
srcPath: '.pi/out.bin',
|
||||
url: 'http://127.0.0.1:9/upload',
|
||||
})
|
||||
|
||||
await vi.waitFor(() => {
|
||||
expect(messages).toContainEqual(
|
||||
expect.objectContaining({
|
||||
type: 'exec.result',
|
||||
executionId: '01JBUSYCMD00B123',
|
||||
error: 'Runner is busy. Try again later.',
|
||||
}),
|
||||
)
|
||||
expect(messages).toContainEqual(
|
||||
expect.objectContaining({
|
||||
type: 'file.upload.result',
|
||||
executionId: '01JBUSYFILE0U456',
|
||||
ok: false,
|
||||
error: 'Runner is busy. Try again later.',
|
||||
}),
|
||||
)
|
||||
})
|
||||
|
||||
const bashLogs = logs.filter((line) => line.includes('[b123]'))
|
||||
const uploadLogs = logs.filter((line) => line.includes('[u456]'))
|
||||
expect(bashLogs).toHaveLength(1)
|
||||
expect(uploadLogs).toHaveLength(1)
|
||||
if (verbose) {
|
||||
expect(bashLogs[0]).toMatch(
|
||||
/^\d{2}:\d{2}:\d{2} WARN {2}Bash rejected \[b123\] command="echo rejected" error="Runner is busy\. Try again later\."$/,
|
||||
)
|
||||
expect(uploadLogs[0]).toMatch(
|
||||
/^\d{2}:\d{2}:\d{2} WARN {2}File upload rejected \[u456\] path="\.pi\/out\.bin" error="Runner is busy\. Try again later\."$/,
|
||||
)
|
||||
} else {
|
||||
expect(bashLogs[0]).toMatch(
|
||||
/^\d{2}:\d{2}:\d{2} WARN {2}Bash rejected \[b123\] \(runner is busy\)$/,
|
||||
)
|
||||
expect(uploadLogs[0]).toMatch(
|
||||
/^\d{2}:\d{2}:\d{2} WARN {2}File upload rejected \[u456\] \(runner is busy\)$/,
|
||||
)
|
||||
}
|
||||
},
|
||||
)
|
||||
})
|
||||
@@ -0,0 +1,461 @@
|
||||
import WebSocket from 'ws'
|
||||
import { setTimeout as delay } from 'node:timers/promises'
|
||||
import {
|
||||
RUNNER_REPLACED_CLOSE_CODE,
|
||||
serverToRunnerMessageSchema,
|
||||
type RunnerExecOutputMessage,
|
||||
type RunnerExecResultMessage,
|
||||
type RunnerToServerMessage,
|
||||
type ServerToRunnerMessage,
|
||||
} from '@shumai/dtos'
|
||||
import { CliError } from '../operations/errors'
|
||||
import { resolveRunnerConfig, type RunnerConfig, type RunnerOptions } from './config'
|
||||
import { RunnerFiles, type FileMessage } from './files'
|
||||
import {
|
||||
createRunnerLogger,
|
||||
formatBytes,
|
||||
formatDuration,
|
||||
formatLogString,
|
||||
shortId,
|
||||
type RunnerLogger,
|
||||
} from './log'
|
||||
import { RunnerShell } from './shell'
|
||||
|
||||
const MAX_REPLAY_BYTES = 1024 * 1024
|
||||
const MAX_COMPLETED = 16
|
||||
const MAX_ACTIVE = 8
|
||||
const RUNNER_BUSY_ERROR = 'Runner is busy. Try again later.'
|
||||
const FILE_OPERATION_KINDS: Record<FileMessage['type'], 'download' | 'upload' | 'stat'> = {
|
||||
'file.download': 'download',
|
||||
'file.upload': 'upload',
|
||||
'file.stat': 'stat',
|
||||
}
|
||||
|
||||
interface Execution {
|
||||
controller: AbortController
|
||||
chunks: RunnerExecOutputMessage[]
|
||||
bytes: number
|
||||
offset: number
|
||||
startedAt: number
|
||||
stdoutBytes: number
|
||||
stderrBytes: number
|
||||
result?: RunnerExecResultMessage
|
||||
}
|
||||
|
||||
export class RunnerClient {
|
||||
private socket?: WebSocket
|
||||
private ready = false
|
||||
private stopped = new AbortController()
|
||||
private executions = new Map<string, Execution>()
|
||||
private transfers = new Map<string, AbortController>()
|
||||
private completedFiles = new Map<string, RunnerToServerMessage>()
|
||||
private pending = new Set<Promise<void>>()
|
||||
private readonly logger: RunnerLogger
|
||||
|
||||
constructor(
|
||||
private readonly config: RunnerConfig,
|
||||
private readonly files: RunnerFiles,
|
||||
private readonly shell: RunnerShell,
|
||||
log: (message: string) => void = console.error,
|
||||
) {
|
||||
this.logger = createRunnerLogger(log, Boolean(config.verbose))
|
||||
}
|
||||
|
||||
async run(signal?: AbortSignal): Promise<void> {
|
||||
const stop = () => this.stop()
|
||||
signal?.addEventListener('abort', stop, { once: true })
|
||||
if (signal?.aborted) this.stop()
|
||||
let attempt = 0
|
||||
try {
|
||||
while (!this.stopped.signal.aborted) {
|
||||
const wasReady = await this.connect()
|
||||
if (this.stopped.signal.aborted) break
|
||||
attempt = wasReady ? 0 : Math.min(attempt + 1, 5)
|
||||
this.logger.warn('Runner disconnected; reconnecting…')
|
||||
await delay(Math.min(1000 * 2 ** attempt, 30_000), undefined, {
|
||||
signal: this.stopped.signal,
|
||||
}).catch(() => {})
|
||||
}
|
||||
} finally {
|
||||
signal?.removeEventListener('abort', stop)
|
||||
this.stop()
|
||||
await Promise.allSettled(this.pending)
|
||||
}
|
||||
}
|
||||
|
||||
stop() {
|
||||
this.stopped.abort()
|
||||
this.ready = false
|
||||
this.socket?.terminate()
|
||||
for (const execution of this.executions.values()) execution.controller.abort()
|
||||
for (const transfer of this.transfers.values()) transfer.abort()
|
||||
}
|
||||
|
||||
private connect(): Promise<boolean> {
|
||||
return new Promise((resolve, reject) => {
|
||||
const socket = new WebSocket(this.config.url, {
|
||||
headers: { authorization: `Bearer ${this.config.key}` },
|
||||
handshakeTimeout: 10_000,
|
||||
maxPayload: 1024 * 1024,
|
||||
perMessageDeflate: false,
|
||||
followRedirects: false,
|
||||
})
|
||||
this.socket = socket
|
||||
let welcomed = false
|
||||
let lastMessage = Date.now()
|
||||
const heartbeat = setInterval(() => {
|
||||
if (Date.now() - lastMessage > (welcomed ? 75_000 : 10_000)) socket.terminate()
|
||||
}, 5_000)
|
||||
socket.on('error', () => {
|
||||
/* Close drives reconnect; never print credential-bearing request errors. */
|
||||
})
|
||||
socket.on('unexpected-response', (_request, response) => {
|
||||
response.destroy()
|
||||
socket.terminate()
|
||||
if ([401, 403, 404, 426].includes(response.statusCode ?? 0))
|
||||
reject(
|
||||
new CliError(
|
||||
`Runner connection rejected (HTTP ${response.statusCode}). Check the server URL and runner key.`,
|
||||
),
|
||||
)
|
||||
})
|
||||
socket.on('close', (code) => {
|
||||
clearInterval(heartbeat)
|
||||
this.ready = false
|
||||
if ((code === 1008 || code === RUNNER_REPLACED_CLOSE_CODE) && !this.stopped.signal.aborted)
|
||||
reject(
|
||||
new CliError('Runner access was revoked or another connection replaced this runner.'),
|
||||
)
|
||||
else resolve(welcomed)
|
||||
})
|
||||
socket.on('message', (raw) => {
|
||||
try {
|
||||
const parsed = serverToRunnerMessageSchema.parse(JSON.parse(raw.toString()))
|
||||
if ('executionId' in parsed && !/^[A-Za-z0-9_-]{1,128}$/.test(parsed.executionId))
|
||||
throw new Error('Invalid execution ID.')
|
||||
lastMessage = Date.now()
|
||||
if (parsed.type === 'welcome') {
|
||||
if (welcomed) throw new Error('Duplicate welcome.')
|
||||
welcomed = true
|
||||
this.ready = true
|
||||
this.reconcile(parsed.inFlightExecutionIds)
|
||||
this.logger.info(`Runner connected: ${parsed.runnerName} (${parsed.runnerId})`)
|
||||
} else {
|
||||
if (!welcomed) throw new Error('Expected welcome before runner requests.')
|
||||
this.handle(parsed)
|
||||
}
|
||||
} catch {
|
||||
reject(new CliError('Server sent an invalid runner protocol message.'))
|
||||
socket.terminate()
|
||||
}
|
||||
})
|
||||
if (this.stopped.signal.aborted) socket.terminate()
|
||||
})
|
||||
}
|
||||
|
||||
private send(message: RunnerToServerMessage) {
|
||||
if (this.ready && this.socket?.readyState === WebSocket.OPEN)
|
||||
this.socket.send(JSON.stringify(message))
|
||||
}
|
||||
|
||||
private reconcile(inFlight: string[]) {
|
||||
const expected = new Set(inFlight)
|
||||
for (const [id, execution] of this.executions) {
|
||||
if (!expected.has(id)) {
|
||||
execution.controller.abort()
|
||||
if (execution.result) this.executions.delete(id)
|
||||
continue
|
||||
}
|
||||
// Replay before results: the server deduplicates chunks by UTF-8 byte offset.
|
||||
for (const chunk of execution.chunks) this.send(chunk)
|
||||
}
|
||||
this.send({
|
||||
type: 'reconcile',
|
||||
environment: this.shell.environment,
|
||||
activeExecutions: [...this.executions]
|
||||
.filter(([id, execution]) => expected.has(id) && !execution.result)
|
||||
.map(([executionId, execution]) => ({ executionId, nextOffset: execution.offset })),
|
||||
completedExecutions: [...this.executions]
|
||||
.filter(([id, execution]) => expected.has(id) && execution.result)
|
||||
.map(([, execution]) => execution.result!),
|
||||
})
|
||||
}
|
||||
|
||||
private handle(message: Exclude<ServerToRunnerMessage, { type: 'welcome' }>) {
|
||||
if (message.type === 'ping') {
|
||||
this.send({ type: 'pong', ts: message.ts })
|
||||
return
|
||||
}
|
||||
if (message.type === 'exec.cancel') {
|
||||
this.executions.get(message.executionId)?.controller.abort()
|
||||
return
|
||||
}
|
||||
if (message.type === 'exec.start') {
|
||||
const previous = this.executions.get(message.executionId)
|
||||
if (previous) {
|
||||
if (previous.result) this.send(previous.result)
|
||||
return
|
||||
}
|
||||
const id = shortId(message.executionId)
|
||||
if (this.activeCount() >= MAX_ACTIVE) {
|
||||
const result: RunnerExecResultMessage = {
|
||||
type: 'exec.result',
|
||||
executionId: message.executionId,
|
||||
exitCode: null,
|
||||
signal: null,
|
||||
timedOut: false,
|
||||
error: RUNNER_BUSY_ERROR,
|
||||
}
|
||||
this.recordCompletedExecution(message.executionId, result)
|
||||
this.logger.warn(
|
||||
this.logger.verbose
|
||||
? `Bash rejected [${id}] command=${formatLogString(message.command)} error=${formatLogString(RUNNER_BUSY_ERROR)}`
|
||||
: `Bash rejected [${id}] (runner is busy)`,
|
||||
)
|
||||
this.send(result)
|
||||
return
|
||||
}
|
||||
const execution: Execution = {
|
||||
controller: new AbortController(),
|
||||
chunks: [],
|
||||
bytes: 0,
|
||||
offset: 0,
|
||||
startedAt: performance.now(),
|
||||
stdoutBytes: 0,
|
||||
stderrBytes: 0,
|
||||
}
|
||||
this.executions.set(message.executionId, execution)
|
||||
this.logger.info(
|
||||
this.logger.verbose
|
||||
? `Bash started [${id}] command=${formatLogString(message.command)}`
|
||||
: `Bash started [${id}]`,
|
||||
)
|
||||
this.track(
|
||||
(async () => {
|
||||
const result = await this.shell.run(
|
||||
message,
|
||||
execution.controller.signal,
|
||||
(stream, data) => {
|
||||
// Small frames keep reconnect replay and WebSocket buffering bounded.
|
||||
for (const part of data.match(/[\s\S]{1,8192}/gu) ?? []) {
|
||||
const chunk: RunnerExecOutputMessage = {
|
||||
type: 'exec.output',
|
||||
executionId: message.executionId,
|
||||
stream,
|
||||
data: part,
|
||||
offset: execution.offset,
|
||||
}
|
||||
const bytes = Buffer.byteLength(part)
|
||||
execution.offset += bytes
|
||||
execution.bytes += bytes
|
||||
if (stream === 'stdout') execution.stdoutBytes += bytes
|
||||
else execution.stderrBytes += bytes
|
||||
execution.chunks.push(chunk)
|
||||
while (execution.bytes > MAX_REPLAY_BYTES) {
|
||||
const removed = execution.chunks.shift()!
|
||||
execution.bytes -= Buffer.byteLength(removed.data)
|
||||
if (!this.ready) execution.controller.abort()
|
||||
}
|
||||
if ((this.socket?.bufferedAmount ?? 0) > MAX_REPLAY_BYTES) {
|
||||
this.ready = false
|
||||
this.socket?.terminate()
|
||||
}
|
||||
this.send(chunk)
|
||||
}
|
||||
},
|
||||
)
|
||||
execution.result = result
|
||||
this.logExecResult(id, execution, result)
|
||||
this.send(result)
|
||||
this.pruneCompletedExecutions()
|
||||
})(),
|
||||
)
|
||||
return
|
||||
}
|
||||
this.handleFile(message)
|
||||
}
|
||||
|
||||
private recordCompletedExecution(executionId: string, result: RunnerExecResultMessage) {
|
||||
this.executions.set(executionId, {
|
||||
controller: new AbortController(),
|
||||
chunks: [],
|
||||
bytes: 0,
|
||||
offset: 0,
|
||||
startedAt: performance.now(),
|
||||
stdoutBytes: 0,
|
||||
stderrBytes: 0,
|
||||
result,
|
||||
})
|
||||
this.pruneCompletedExecutions()
|
||||
}
|
||||
|
||||
private pruneCompletedExecutions() {
|
||||
const completed = [...this.executions].filter(([, value]) => value.result)
|
||||
for (const [completedId] of completed.slice(0, -MAX_COMPLETED))
|
||||
this.executions.delete(completedId)
|
||||
}
|
||||
|
||||
private logExecResult(id: string, execution: Execution, result: RunnerExecResultMessage) {
|
||||
const duration = formatDuration(performance.now() - execution.startedAt)
|
||||
const sizes = this.logger.verbose
|
||||
? ` stdout=${formatBytes(execution.stdoutBytes)} stderr=${formatBytes(execution.stderrBytes)}`
|
||||
: ''
|
||||
if (result.timedOut) {
|
||||
const error =
|
||||
this.logger.verbose && result.error ? ` error=${formatLogString(result.error)}` : ''
|
||||
this.logger.warn(`Bash timed out [${id}] duration=${duration}${sizes}${error}`)
|
||||
return
|
||||
}
|
||||
if (result.aborted) {
|
||||
this.logger.info(`Bash cancelled [${id}] duration=${duration}${sizes}`)
|
||||
return
|
||||
}
|
||||
if (result.error) {
|
||||
const error = this.logger.verbose ? ` error=${formatLogString(result.error)}` : ''
|
||||
this.logger.warn(`Bash failed [${id}] duration=${duration}${sizes}${error}`)
|
||||
return
|
||||
}
|
||||
if (result.exitCode === null && result.signal) {
|
||||
this.logger.warn(`Bash killed [${id}] signal=${result.signal} duration=${duration}${sizes}`)
|
||||
return
|
||||
}
|
||||
this.logger.info(`Bash completed [${id}] exit=${result.exitCode} duration=${duration}${sizes}`)
|
||||
}
|
||||
|
||||
private activeCount() {
|
||||
return (
|
||||
[...this.executions.values()].filter((execution) => !execution.result).length +
|
||||
this.transfers.size
|
||||
)
|
||||
}
|
||||
|
||||
private handleFile(message: FileMessage) {
|
||||
const previous = this.completedFiles.get(message.executionId)
|
||||
if (previous) {
|
||||
this.send(previous)
|
||||
return
|
||||
}
|
||||
if (this.transfers.has(message.executionId)) return
|
||||
const id = shortId(message.executionId)
|
||||
const transferPath = message.type === 'file.download' ? message.destPath : message.srcPath
|
||||
if (this.activeCount() >= MAX_ACTIVE) {
|
||||
const result = this.fileBusy(message)
|
||||
this.recordCompletedFile(message.executionId, result)
|
||||
const kind = FILE_OPERATION_KINDS[message.type]
|
||||
this.logger.warn(
|
||||
this.logger.verbose
|
||||
? `File ${kind} rejected [${id}] path=${formatLogString(transferPath)} error=${formatLogString(RUNNER_BUSY_ERROR)}`
|
||||
: `File ${kind} rejected [${id}] (runner is busy)`,
|
||||
)
|
||||
this.send(result)
|
||||
return
|
||||
}
|
||||
const controller = new AbortController()
|
||||
this.transfers.set(message.executionId, controller)
|
||||
const timer = setTimeout(() => controller.abort(), 120_000)
|
||||
const startedAt = performance.now()
|
||||
if (this.logger.verbose && message.type !== 'file.stat') {
|
||||
const kind = message.type === 'file.download' ? 'download' : 'upload'
|
||||
this.logger.info(`File ${kind} started [${id}] path=${formatLogString(transferPath)}`)
|
||||
}
|
||||
this.track(
|
||||
(async () => {
|
||||
try {
|
||||
const result = await this.files.handle(message, controller.signal)
|
||||
this.recordCompletedFile(message.executionId, result)
|
||||
this.logFileResult(id, transferPath, startedAt, result)
|
||||
this.send(result)
|
||||
} finally {
|
||||
clearTimeout(timer)
|
||||
this.transfers.delete(message.executionId)
|
||||
}
|
||||
})(),
|
||||
)
|
||||
}
|
||||
|
||||
private recordCompletedFile(executionId: string, result: RunnerToServerMessage) {
|
||||
this.completedFiles.set(executionId, result)
|
||||
if (this.completedFiles.size > MAX_COMPLETED)
|
||||
this.completedFiles.delete(this.completedFiles.keys().next().value!)
|
||||
}
|
||||
|
||||
private logFileResult(
|
||||
id: string,
|
||||
transferPath: string,
|
||||
startedAt: number,
|
||||
result: RunnerToServerMessage,
|
||||
) {
|
||||
if (result.type === 'file.stat.result') {
|
||||
if (!this.logger.verbose) return
|
||||
const pathPart = `path=${formatLogString(transferPath)}`
|
||||
if (!result.ok) {
|
||||
this.logger.warn(
|
||||
`File stat failed [${id}] ${pathPart} error=${formatLogString(result.error ?? 'Unknown error')}`,
|
||||
)
|
||||
return
|
||||
}
|
||||
const sizePart = result.exists ? ` size=${formatBytes(result.size ?? 0)}` : ''
|
||||
this.logger.info(`File stat [${id}] ${pathPart} exists=${result.exists}${sizePart}`)
|
||||
return
|
||||
}
|
||||
if (result.type !== 'file.download.result' && result.type !== 'file.upload.result') return
|
||||
const kind = result.type === 'file.download.result' ? 'download' : 'upload'
|
||||
const duration = formatDuration(performance.now() - startedAt)
|
||||
const pathPart = this.logger.verbose ? ` path=${formatLogString(transferPath)}` : ''
|
||||
if (result.ok) {
|
||||
this.logger.info(
|
||||
`File ${kind} completed [${id}]${pathPart} size=${formatBytes(result.size ?? 0)} duration=${duration}`,
|
||||
)
|
||||
return
|
||||
}
|
||||
const errorPart = this.logger.verbose
|
||||
? ` error=${formatLogString(result.error ?? 'Unknown error')}`
|
||||
: ''
|
||||
this.logger.warn(`File ${kind} failed [${id}]${pathPart} duration=${duration}${errorPart}`)
|
||||
}
|
||||
|
||||
private fileBusy(message: FileMessage): RunnerToServerMessage {
|
||||
const result = {
|
||||
executionId: message.executionId,
|
||||
ok: false,
|
||||
error: RUNNER_BUSY_ERROR,
|
||||
}
|
||||
switch (message.type) {
|
||||
case 'file.download':
|
||||
return { ...result, type: 'file.download.result' }
|
||||
case 'file.upload':
|
||||
return { ...result, type: 'file.upload.result' }
|
||||
case 'file.stat':
|
||||
return { ...result, type: 'file.stat.result', exists: false }
|
||||
}
|
||||
}
|
||||
|
||||
private track(task: Promise<void>) {
|
||||
this.pending.add(task)
|
||||
void task.finally(() => this.pending.delete(task)).catch(() => this.stop())
|
||||
}
|
||||
}
|
||||
|
||||
export async function startRunner(options: RunnerOptions) {
|
||||
const config = await resolveRunnerConfig(options)
|
||||
const files = new RunnerFiles(config.cwd)
|
||||
const shell = new RunnerShell(files, config.srt)
|
||||
// SRT resolves relative policy paths against the runner workspace.
|
||||
process.chdir(config.cwd)
|
||||
await shell.initialize()
|
||||
createRunnerLogger(console.error, Boolean(config.verbose)).info(
|
||||
`Runner shell: ${shell.environment.shell}`,
|
||||
)
|
||||
const runner = new RunnerClient(config, files, shell)
|
||||
const controller = new AbortController()
|
||||
const shutdown = () => controller.abort()
|
||||
process.once('SIGINT', shutdown)
|
||||
process.once('SIGTERM', shutdown)
|
||||
try {
|
||||
await runner.run(controller.signal)
|
||||
} finally {
|
||||
process.removeListener('SIGINT', shutdown)
|
||||
process.removeListener('SIGTERM', shutdown)
|
||||
await shell.close()
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,66 @@
|
||||
import { afterEach, describe, expect, it, vi } from 'vitest'
|
||||
import { commandEnv, resolveRunnerConfig } from './config'
|
||||
|
||||
afterEach(() => vi.unstubAllEnvs())
|
||||
|
||||
describe('runner configuration', () => {
|
||||
it('preserves Windows OS settings, normalizes explicit overrides, and excludes credentials', () => {
|
||||
vi.stubEnv('Path', 'C:\\Windows\\System32')
|
||||
vi.stubEnv('SystemRoot', 'C:\\Windows')
|
||||
vi.stubEnv('USERPROFILE', 'C:\\Users\\runner')
|
||||
const env = commandEnv({ PATH: 'C:\\tools', ['shumai_runner_key']: 'secret' })
|
||||
expect(env).toMatchObject({
|
||||
PATH: 'C:\\tools',
|
||||
SystemRoot: 'C:\\Windows',
|
||||
USERPROFILE: 'C:\\Users\\runner',
|
||||
})
|
||||
expect(env).not.toHaveProperty('Path')
|
||||
expect(env).not.toHaveProperty('shumai_runner_key')
|
||||
})
|
||||
it('uses a dedicated runner key and preserves a server path prefix', async () => {
|
||||
vi.stubEnv('SHUMAI_API_SERVER', 'https://example.com/shumai/')
|
||||
vi.stubEnv('SHUMAI_RUNNER_KEY', 'runner-secret')
|
||||
const config = await resolveRunnerConfig({})
|
||||
expect(config.url.href).toBe('wss://example.com/shumai/api/runners/ws')
|
||||
expect(config.key).toBe('runner-secret')
|
||||
expect(config.cwd).toBe(process.cwd())
|
||||
expect(config.verbose).toBe(false)
|
||||
expect((await resolveRunnerConfig({ verbose: true })).verbose).toBe(true)
|
||||
})
|
||||
|
||||
it.each([
|
||||
'http://example.com',
|
||||
'ftp://localhost',
|
||||
'https://user:secret@example.com',
|
||||
'https://example.com/?key=secret',
|
||||
'not a URL',
|
||||
])('rejects unsafe server URL %s', async (url) => {
|
||||
await expect(resolveRunnerConfig({ url, key: 'key' })).rejects.toThrow()
|
||||
})
|
||||
|
||||
it('allows the Docker host development address', async () => {
|
||||
expect(
|
||||
(await resolveRunnerConfig({ url: 'http://host.docker.internal:3000', key: 'key' })).url.href,
|
||||
).toBe('ws://host.docker.internal:3000/api/runners/ws')
|
||||
})
|
||||
|
||||
it('does not accept a personal API token in place of a missing runner key', async () => {
|
||||
vi.stubEnv('SHUMAI_RUNNER_KEY', '')
|
||||
vi.stubEnv('SHUMAI_API_KEY', 'personal-secret')
|
||||
await expect(resolveRunnerConfig({ url: 'https://example.com' })).rejects.toThrow(
|
||||
'SHUMAI_RUNNER_KEY',
|
||||
)
|
||||
})
|
||||
|
||||
it('inherits only baseline environment and explicit skill variables', () => {
|
||||
vi.stubEnv('SHUMAI_RUNNER_KEY', 'runner-secret')
|
||||
vi.stubEnv('SHUMAI_API_KEY', 'personal-secret')
|
||||
vi.stubEnv('AWS_SECRET_ACCESS_KEY', 'aws-secret')
|
||||
vi.stubEnv('BASH_ENV', '/malicious-startup')
|
||||
expect(
|
||||
commandEnv({ SKILL_TOKEN: 'skill-secret', SHUMAI_RUNNER_KEY: 'injected' }),
|
||||
).toMatchObject({ SKILL_TOKEN: 'skill-secret' })
|
||||
for (const name of ['SHUMAI_RUNNER_KEY', 'SHUMAI_API_KEY', 'AWS_SECRET_ACCESS_KEY', 'BASH_ENV'])
|
||||
expect(commandEnv()).not.toHaveProperty(name)
|
||||
})
|
||||
})
|
||||
@@ -0,0 +1,84 @@
|
||||
import { realpath, stat } from 'node:fs/promises'
|
||||
import path from 'node:path'
|
||||
import { CliError } from '../operations/errors'
|
||||
|
||||
export interface RunnerOptions {
|
||||
url?: string
|
||||
key?: string
|
||||
cwd?: string
|
||||
srt?: string
|
||||
verbose?: boolean
|
||||
}
|
||||
|
||||
export interface RunnerConfig {
|
||||
url: URL
|
||||
key: string
|
||||
cwd: string
|
||||
srt?: string
|
||||
verbose?: boolean
|
||||
}
|
||||
|
||||
export async function resolveRunnerConfig(options: RunnerOptions): Promise<RunnerConfig> {
|
||||
const address = options.url ?? process.env.SHUMAI_API_SERVER
|
||||
const key = options.key ?? process.env.SHUMAI_RUNNER_KEY
|
||||
if (!address) throw new CliError('Set SHUMAI_API_SERVER or pass --url.')
|
||||
if (!key?.trim()) throw new CliError('Set SHUMAI_RUNNER_KEY or pass --key with a runner key.')
|
||||
let url: URL
|
||||
try {
|
||||
url = new URL(address)
|
||||
} catch {
|
||||
throw new CliError('Invalid Shumai server URL.')
|
||||
}
|
||||
if (
|
||||
url.username ||
|
||||
url.password ||
|
||||
url.search ||
|
||||
url.hash ||
|
||||
!['http:', 'https:'].includes(url.protocol)
|
||||
) {
|
||||
throw new CliError(
|
||||
'Use an http:// or https:// server URL without credentials, query, or fragment.',
|
||||
)
|
||||
}
|
||||
const localHosts = ['localhost', '127.0.0.1', '[::1]', 'host.docker.internal']
|
||||
if (url.protocol === 'http:' && !localHosts.includes(url.hostname)) {
|
||||
throw new CliError(
|
||||
'Remote runners require HTTPS. HTTP is only supported for local development.',
|
||||
)
|
||||
}
|
||||
url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:'
|
||||
url.pathname = `${url.pathname.replace(/\/+$/, '')}/api/runners/ws`
|
||||
const cwd = await realpath(path.resolve(options.cwd ?? process.cwd()))
|
||||
if (!(await stat(cwd)).isDirectory()) throw new CliError('Runner workspace must be a directory.')
|
||||
return {
|
||||
url,
|
||||
key: key.trim(),
|
||||
cwd,
|
||||
srt: options.srt ? path.resolve(options.srt) : undefined,
|
||||
verbose: Boolean(options.verbose),
|
||||
}
|
||||
}
|
||||
|
||||
/** Commands inherit baseline OS settings and explicitly supplied skill variables, never CLI credentials. */
|
||||
export function commandEnv(extra: Record<string, string> = {}, inherit = true): NodeJS.ProcessEnv {
|
||||
const env: NodeJS.ProcessEnv = {}
|
||||
for (const [key, value] of Object.entries(inherit ? process.env : {})) {
|
||||
if (
|
||||
/^(PATH|PATHEXT|HOME|USER|LOGNAME|LANG|TERM|TMPDIR|TEMP|TMP|SYSTEMROOT|SYSTEMDRIVE|COMSPEC|USERPROFILE|USERNAME|APPDATA|LOCALAPPDATA|PROGRAMDATA|PROGRAMFILES|PROGRAMFILES\(X86\)|LC_.*)$/i.test(
|
||||
key,
|
||||
)
|
||||
)
|
||||
env[key] = value
|
||||
}
|
||||
for (const [key, value] of Object.entries(extra)) {
|
||||
if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
|
||||
throw new Error('Invalid skill environment variable name.')
|
||||
if (['SHUMAI_RUNNER_KEY', 'SHUMAI_API_KEY'].includes(key.toUpperCase())) continue
|
||||
// Windows treats environment names as case-insensitive.
|
||||
for (const existing of Object.keys(env)) {
|
||||
if (existing.toUpperCase() === key.toUpperCase()) delete env[existing]
|
||||
}
|
||||
env[key] = value
|
||||
}
|
||||
return env
|
||||
}
|
||||
@@ -0,0 +1,364 @@
|
||||
import { createHash } from 'node:crypto'
|
||||
import { createServer, type Server } from 'node:http'
|
||||
import { mkdtemp, mkdir, readFile, readdir, rm, stat, symlink, writeFile } from 'node:fs/promises'
|
||||
import { tmpdir } from 'node:os'
|
||||
import path from 'node:path'
|
||||
import AdmZip from 'adm-zip'
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
|
||||
import yauzl from 'yauzl'
|
||||
import { RunnerFiles } from './files'
|
||||
|
||||
describe('runner workspace file transfers', () => {
|
||||
let cwd: string
|
||||
let files: RunnerFiles
|
||||
let server: Server
|
||||
let url: string
|
||||
let body: Buffer
|
||||
let uploaded: Buffer
|
||||
beforeEach(async () => {
|
||||
cwd = await mkdtemp(path.join(tmpdir(), 'shumai-files-test-'))
|
||||
files = new RunnerFiles(cwd)
|
||||
body = Buffer.from('download contents')
|
||||
uploaded = Buffer.alloc(0)
|
||||
server = createServer(async (request, response) => {
|
||||
if (request.method === 'PUT') {
|
||||
const chunks: Buffer[] = []
|
||||
for await (const chunk of request) chunks.push(Buffer.from(chunk))
|
||||
uploaded = Buffer.concat(chunks)
|
||||
response.end()
|
||||
} else if (request.url === '/slow') {
|
||||
const timer = setInterval(() => response.write(Buffer.alloc(65536)), 20)
|
||||
response.once('close', () => clearInterval(timer))
|
||||
} else if (request.url === '/redirect') {
|
||||
response.writeHead(302, { location: '/file' })
|
||||
response.end()
|
||||
} else response.end(body)
|
||||
})
|
||||
await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))
|
||||
const address = server.address()
|
||||
if (!address || typeof address === 'string') throw new Error('Missing test HTTP address')
|
||||
url = `http://127.0.0.1:${address.port}`
|
||||
})
|
||||
afterEach(async () => {
|
||||
server.closeAllConnections()
|
||||
await new Promise<void>((resolve) => server.close(() => resolve()))
|
||||
await rm(cwd, { recursive: true, force: true })
|
||||
})
|
||||
|
||||
const signal = () => new AbortController().signal
|
||||
|
||||
it('downloads, checks SHA-256, stats and uploads actual bytes', async () => {
|
||||
expect(
|
||||
await files.handle(
|
||||
{
|
||||
type: 'file.download',
|
||||
executionId: 'download',
|
||||
url,
|
||||
destPath: '.pi/input/data.bin',
|
||||
expectedHash: createHash('sha256').update(body).digest('hex'),
|
||||
},
|
||||
signal(),
|
||||
),
|
||||
).toMatchObject({ ok: true, size: body.length })
|
||||
expect(await readFile(path.join(cwd, '.pi/input/data.bin'))).toEqual(body)
|
||||
expect(
|
||||
await files.handle(
|
||||
{ type: 'file.stat', executionId: 'stat', srcPath: '.pi/input/data.bin' },
|
||||
signal(),
|
||||
),
|
||||
).toMatchObject({ ok: true, exists: true, isFile: true, size: body.length })
|
||||
expect(
|
||||
await files.handle(
|
||||
{ type: 'file.upload', executionId: 'upload', srcPath: '.pi/input/data.bin', url },
|
||||
signal(),
|
||||
),
|
||||
).toMatchObject({ ok: true, size: body.length, name: 'data.bin' })
|
||||
expect(uploaded).toEqual(body)
|
||||
expect(
|
||||
await files.handle(
|
||||
{ type: 'file.stat', executionId: 'absent', srcPath: '.pi/absent' },
|
||||
signal(),
|
||||
),
|
||||
).toMatchObject({ ok: true, exists: false })
|
||||
})
|
||||
|
||||
it('does not publish mismatched downloads or follow redirects', async () => {
|
||||
expect(
|
||||
await files.handle(
|
||||
{
|
||||
type: 'file.download',
|
||||
executionId: 'bad-hash',
|
||||
url,
|
||||
destPath: '.pi/data',
|
||||
expectedHash: 'bad',
|
||||
},
|
||||
signal(),
|
||||
),
|
||||
).toMatchObject({ ok: false, error: 'Downloaded file hash does not match.' })
|
||||
await expect(readFile(path.join(cwd, '.pi/data'))).rejects.toThrow()
|
||||
expect(
|
||||
await files.handle(
|
||||
{
|
||||
type: 'file.download',
|
||||
executionId: 'redirect',
|
||||
url: `${url}/redirect`,
|
||||
destPath: '.pi/data',
|
||||
},
|
||||
signal(),
|
||||
),
|
||||
).toHaveProperty('ok', false)
|
||||
})
|
||||
|
||||
it.each([
|
||||
'../secret',
|
||||
'/etc/passwd',
|
||||
'.pi/../secret',
|
||||
'.pi/dir/../../secret',
|
||||
'.pi\\secret',
|
||||
'.pi//file',
|
||||
'.pi/a:b',
|
||||
'.pi/a\0b',
|
||||
'.pi/.. /outside',
|
||||
'.pi/folder./file',
|
||||
'.pi/CON.txt',
|
||||
'.pi/nul .txt',
|
||||
'.pi/COM1',
|
||||
'.pi/lpt¹.log',
|
||||
'.pi/CONOUT$',
|
||||
])('rejects unsafe protocol path %s', async (srcPath) => {
|
||||
expect(
|
||||
await files.handle({ type: 'file.stat', executionId: 'unsafe', srcPath }, signal()),
|
||||
).toHaveProperty('ok', false)
|
||||
})
|
||||
|
||||
it('rejects parent and final symlinks, including a replaced .pi root', async () => {
|
||||
await mkdir(path.join(cwd, '.pi'))
|
||||
await writeFile(path.join(cwd, 'secret'), 'secret')
|
||||
await symlink(cwd, path.join(cwd, '.pi/escape'))
|
||||
await symlink(path.join(cwd, 'secret'), path.join(cwd, '.pi/link'))
|
||||
for (const srcPath of ['.pi/escape/secret', '.pi/link']) {
|
||||
expect(
|
||||
await files.handle({ type: 'file.upload', executionId: 'symlink', srcPath, url }, signal()),
|
||||
).toHaveProperty('ok', false)
|
||||
}
|
||||
await rm(path.join(cwd, '.pi'), { recursive: true })
|
||||
await symlink(cwd, path.join(cwd, '.pi'))
|
||||
expect(
|
||||
await files.handle(
|
||||
{ type: 'file.download', executionId: 'root', destPath: '.pi/file', url },
|
||||
signal(),
|
||||
),
|
||||
).toHaveProperty('ok', false)
|
||||
})
|
||||
|
||||
it('extracts skills and safely replaces old contents', async () => {
|
||||
const zip = new AdmZip()
|
||||
zip.addFile('SKILL.md', Buffer.from('# Test skill'))
|
||||
zip.addFile('scripts/run.sh', Buffer.from('echo skill'))
|
||||
body = zip.toBuffer()
|
||||
for (let attempt = 0; attempt < 2; attempt++) {
|
||||
expect(
|
||||
await files.handle(
|
||||
{
|
||||
type: 'file.download',
|
||||
executionId: `zip-${attempt}`,
|
||||
url,
|
||||
destPath: '.pi/skills/test',
|
||||
extractZip: true,
|
||||
},
|
||||
signal(),
|
||||
),
|
||||
).toHaveProperty('ok', true)
|
||||
}
|
||||
expect(await readFile(path.join(cwd, '.pi/skills/test/SKILL.md'), 'utf8')).toBe('# Test skill')
|
||||
})
|
||||
|
||||
it('rejects symlink ZIP entries and zip-slip paths without publishing them', async () => {
|
||||
const zip = new AdmZip()
|
||||
zip.addFile('link', Buffer.from('/etc/passwd'))
|
||||
const entry = zip.getEntry('link')!
|
||||
entry.header.attr = (0o120777 << 16) >>> 0
|
||||
body = zip.toBuffer()
|
||||
expect(
|
||||
await files.handle(
|
||||
{
|
||||
type: 'file.download',
|
||||
executionId: 'zip-link',
|
||||
url,
|
||||
destPath: '.pi/skills/bad',
|
||||
extractZip: true,
|
||||
},
|
||||
signal(),
|
||||
),
|
||||
).toHaveProperty('ok', false)
|
||||
const normal = new AdmZip()
|
||||
normal.addFile('aa/secret', Buffer.from('escape'))
|
||||
body = Buffer.from(
|
||||
normal.toBuffer().toString('latin1').replaceAll('aa/secret', '../secret'),
|
||||
'latin1',
|
||||
)
|
||||
expect(
|
||||
await files.handle(
|
||||
{
|
||||
type: 'file.download',
|
||||
executionId: 'zip-slip',
|
||||
url,
|
||||
destPath: '.pi/skills/bad',
|
||||
extractZip: true,
|
||||
},
|
||||
signal(),
|
||||
),
|
||||
).toHaveProperty('ok', false)
|
||||
await expect(readFile(path.join(cwd, '.pi/skills/bad/link'))).rejects.toThrow()
|
||||
})
|
||||
|
||||
it('preserves executable script permissions and rejects oversized ZIP entries', async () => {
|
||||
const zip = new AdmZip()
|
||||
zip.addFile('run.sh', Buffer.from('#!/bin/sh\necho executable\n'))
|
||||
zip.getEntry('run.sh')!.header.attr = (0o100755 << 16) >>> 0
|
||||
body = zip.toBuffer()
|
||||
expect(
|
||||
await files.handle(
|
||||
{
|
||||
type: 'file.download',
|
||||
executionId: 'exec-zip',
|
||||
url,
|
||||
destPath: '.pi/skills/executable',
|
||||
extractZip: true,
|
||||
},
|
||||
signal(),
|
||||
),
|
||||
).toHaveProperty('ok', true)
|
||||
expect((await stat(path.join(cwd, '.pi/skills/executable/run.sh'))).mode & 0o7777).toBe(0o755)
|
||||
const central = body.indexOf(Buffer.from([0x50, 0x4b, 0x01, 0x02]))
|
||||
body.writeUInt32LE(256 * 1024 * 1024 + 1, central + 24)
|
||||
expect(
|
||||
await files.handle(
|
||||
{
|
||||
type: 'file.download',
|
||||
executionId: 'large-zip',
|
||||
url,
|
||||
destPath: '.pi/skills/large',
|
||||
extractZip: true,
|
||||
},
|
||||
signal(),
|
||||
),
|
||||
).toMatchObject({ ok: false, error: 'Extracted ZIP exceeds 256 MiB.' })
|
||||
})
|
||||
|
||||
it('cancels a streaming download without publishing partial bytes or leaving staging files', async () => {
|
||||
await mkdir(path.join(cwd, '.pi/input'), { recursive: true })
|
||||
await writeFile(path.join(cwd, '.pi/input/data'), 'original')
|
||||
const controller = new AbortController()
|
||||
const transfer = files.handle(
|
||||
{
|
||||
type: 'file.download',
|
||||
executionId: 'stream-cancel',
|
||||
url: `${url}/slow`,
|
||||
destPath: '.pi/input/data',
|
||||
},
|
||||
controller.signal,
|
||||
)
|
||||
await vi.waitFor(async () =>
|
||||
expect(
|
||||
(await readdir(path.join(cwd, '.pi/input'))).some((name) => name.startsWith('.shumai-')),
|
||||
).toBe(true),
|
||||
)
|
||||
controller.abort()
|
||||
expect(await transfer).toHaveProperty('ok', false)
|
||||
expect(await readFile(path.join(cwd, '.pi/input/data'), 'utf8')).toBe('original')
|
||||
expect(await readdir(path.join(cwd, '.pi/input'))).toEqual(['data'])
|
||||
})
|
||||
|
||||
it('cancels extraction without deleting the installed skill or leaving staging trees', async () => {
|
||||
await mkdir(path.join(cwd, '.pi/skills/installed'), { recursive: true })
|
||||
await writeFile(path.join(cwd, '.pi/skills/installed/SKILL.md'), 'original')
|
||||
const zip = new AdmZip()
|
||||
for (let index = 0; index < 2000; index++)
|
||||
zip.addFile(`file-${index}.txt`, Buffer.alloc(32768, 65))
|
||||
body = zip.toBuffer()
|
||||
const controller = new AbortController()
|
||||
const transfer = files.handle(
|
||||
{
|
||||
type: 'file.download',
|
||||
executionId: 'extract-cancel',
|
||||
url,
|
||||
destPath: '.pi/skills/installed',
|
||||
extractZip: true,
|
||||
},
|
||||
controller.signal,
|
||||
)
|
||||
await vi.waitFor(
|
||||
async () => {
|
||||
const temporary = (await readdir(path.join(cwd, '.pi/skills'))).find((name) =>
|
||||
name.startsWith('.shumai-'),
|
||||
)
|
||||
expect(temporary).toBeDefined()
|
||||
expect(
|
||||
(await readdir(path.join(cwd, '.pi/skills', temporary!, 'extracted'))).length,
|
||||
).toBeGreaterThan(0)
|
||||
},
|
||||
{ interval: 5, timeout: 5000 },
|
||||
)
|
||||
controller.abort()
|
||||
expect(await transfer).toHaveProperty('ok', false)
|
||||
expect(await readFile(path.join(cwd, '.pi/skills/installed/SKILL.md'), 'utf8')).toBe('original')
|
||||
expect(await readdir(path.join(cwd, '.pi/skills'))).toEqual(['installed'])
|
||||
}, 10000)
|
||||
|
||||
it('waits for an in-flight ZIP entry read before closing on cancellation', async () => {
|
||||
const zip = new AdmZip()
|
||||
zip.addFile('SKILL.md', Buffer.from('skill'))
|
||||
body = zip.toBuffer()
|
||||
const controller = new AbortController()
|
||||
const pendingRead = Promise.withResolvers<() => void>()
|
||||
const readEntry = yauzl.ZipFile.prototype.readEntry
|
||||
const read = vi.spyOn(yauzl.ZipFile.prototype, 'readEntry').mockImplementationOnce(function (
|
||||
this: yauzl.ZipFile,
|
||||
) {
|
||||
pendingRead.resolve(() => readEntry.call(this))
|
||||
})
|
||||
const close = vi.spyOn(yauzl.ZipFile.prototype, 'close')
|
||||
try {
|
||||
const transfer = files.handle(
|
||||
{
|
||||
type: 'file.download',
|
||||
executionId: 'zip-entry-cancel',
|
||||
url,
|
||||
destPath: '.pi/skills/new',
|
||||
extractZip: true,
|
||||
},
|
||||
controller.signal,
|
||||
)
|
||||
const finishRead = await pendingRead.promise
|
||||
controller.abort()
|
||||
await new Promise<void>((resolve) => setImmediate(resolve))
|
||||
const closedDuringRead = close.mock.calls.length > 0
|
||||
if (!closedDuringRead) finishRead()
|
||||
expect(await transfer).toHaveProperty('ok', false)
|
||||
expect(closedDuringRead).toBe(false)
|
||||
expect(await readdir(path.join(cwd, '.pi/skills'))).toEqual([])
|
||||
} finally {
|
||||
read.mockRestore()
|
||||
close.mockRestore()
|
||||
}
|
||||
})
|
||||
|
||||
it('handles cancelled transfers and refuses uploads of directories', async () => {
|
||||
const controller = new AbortController()
|
||||
controller.abort()
|
||||
expect(
|
||||
await files.handle(
|
||||
{ type: 'file.download', executionId: 'cancelled', url, destPath: '.pi/data' },
|
||||
controller.signal,
|
||||
),
|
||||
).toHaveProperty('ok', false)
|
||||
expect(
|
||||
await files.handle(
|
||||
{ type: 'file.upload', executionId: 'directory', url, srcPath: '.pi/transfers' },
|
||||
signal(),
|
||||
),
|
||||
).toHaveProperty('ok', false)
|
||||
expect(uploaded).toHaveLength(0)
|
||||
})
|
||||
})
|
||||
@@ -0,0 +1,282 @@
|
||||
import { createHash } from 'node:crypto'
|
||||
import { constants, createWriteStream } from 'node:fs'
|
||||
import { lstat, mkdir, mkdtemp, open, rename, rm } from 'node:fs/promises'
|
||||
import path from 'node:path'
|
||||
import { Readable, Transform } from 'node:stream'
|
||||
import { pipeline } from 'node:stream/promises'
|
||||
import yauzl from 'yauzl'
|
||||
import type {
|
||||
RunnerFileDownloadMessage,
|
||||
RunnerFileUploadMessage,
|
||||
RunnerFileStatMessage,
|
||||
RunnerToServerMessage,
|
||||
} from '@shumai/dtos'
|
||||
|
||||
const MAX_FILE_BYTES = 256 * 1024 * 1024
|
||||
const MAX_ZIP_ENTRIES = 10_000
|
||||
export type FileMessage =
|
||||
RunnerFileDownloadMessage | RunnerFileUploadMessage | RunnerFileStatMessage
|
||||
|
||||
function pathParts(value: string): string[] {
|
||||
const parts = value.split('/')
|
||||
if (
|
||||
value.includes('\\') ||
|
||||
value.includes('\0') ||
|
||||
parts.some(
|
||||
(part) =>
|
||||
!part ||
|
||||
part === '.' ||
|
||||
part === '..' ||
|
||||
part.includes(':') ||
|
||||
/[. ]$/.test(part) ||
|
||||
/^(?:con|prn|aux|nul|conin\$|conout\$|com[1-9¹²³]|lpt[1-9¹²³])(?: *\.|$)/i.test(part),
|
||||
)
|
||||
)
|
||||
throw new Error('Invalid workspace path.')
|
||||
return parts
|
||||
}
|
||||
|
||||
function isMissing(error: unknown): boolean {
|
||||
return error instanceof Error && 'code' in error && error.code === 'ENOENT'
|
||||
}
|
||||
|
||||
function transferUrl(address: string): URL {
|
||||
const url = new URL(address)
|
||||
if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password)
|
||||
throw new Error('Invalid transfer URL.')
|
||||
return url
|
||||
}
|
||||
|
||||
export class RunnerFiles {
|
||||
constructor(readonly cwd: string) {}
|
||||
|
||||
/** Basic workspace validation. Concurrent hostile filesystem mutation is outside v1's scope. */
|
||||
private async resolve(relative: string, createParents = false): Promise<string> {
|
||||
const parts = pathParts(relative)
|
||||
if (parts[0] !== '.pi' || parts.length < 2) throw new Error('File paths must stay inside .pi/.')
|
||||
let current = this.cwd
|
||||
for (let index = 0; index < parts.length; index++) {
|
||||
current = path.join(current, parts[index])
|
||||
const parent = index < parts.length - 1
|
||||
if (parent && createParents) await mkdir(current, { recursive: true, mode: 0o700 })
|
||||
try {
|
||||
const info = await lstat(current)
|
||||
if (info.isSymbolicLink() || (parent && !info.isDirectory()))
|
||||
throw new Error('Workspace paths cannot contain symlinks or non-directory parents.')
|
||||
} catch (error) {
|
||||
if (!isMissing(error)) throw error
|
||||
}
|
||||
}
|
||||
return current
|
||||
}
|
||||
|
||||
async createWriter(relative: string) {
|
||||
const file = await open(
|
||||
await this.resolve(relative, true),
|
||||
constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW,
|
||||
0o600,
|
||||
)
|
||||
return {
|
||||
write: async (data: string) => {
|
||||
await file.writeFile(data)
|
||||
},
|
||||
close: () => file.close(),
|
||||
}
|
||||
}
|
||||
|
||||
async handle(message: FileMessage, signal: AbortSignal): Promise<RunnerToServerMessage> {
|
||||
try {
|
||||
signal.throwIfAborted()
|
||||
if (message.type === 'file.download')
|
||||
return {
|
||||
type: 'file.download.result',
|
||||
executionId: message.executionId,
|
||||
ok: true,
|
||||
...(await this.download(message, signal)),
|
||||
}
|
||||
const filename = await this.resolve(message.srcPath)
|
||||
if (message.type === 'file.upload') return await this.upload(message, filename, signal)
|
||||
try {
|
||||
const info = await lstat(filename)
|
||||
return {
|
||||
type: 'file.stat.result',
|
||||
executionId: message.executionId,
|
||||
ok: true,
|
||||
exists: true,
|
||||
isFile: info.isFile(),
|
||||
size: info.size,
|
||||
name: path.basename(filename),
|
||||
}
|
||||
} catch (error) {
|
||||
if (!isMissing(error)) throw error
|
||||
return {
|
||||
type: 'file.stat.result',
|
||||
executionId: message.executionId,
|
||||
ok: true,
|
||||
exists: false,
|
||||
}
|
||||
}
|
||||
} catch (error) {
|
||||
const result = {
|
||||
executionId: message.executionId,
|
||||
ok: false,
|
||||
error: error instanceof Error ? error.message : 'File operation failed.',
|
||||
}
|
||||
switch (message.type) {
|
||||
case 'file.download':
|
||||
return { ...result, type: 'file.download.result' }
|
||||
case 'file.upload':
|
||||
return { ...result, type: 'file.upload.result' }
|
||||
case 'file.stat':
|
||||
return { ...result, type: 'file.stat.result', exists: false }
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private async upload(
|
||||
message: RunnerFileUploadMessage,
|
||||
filename: string,
|
||||
signal: AbortSignal,
|
||||
): Promise<RunnerToServerMessage> {
|
||||
const file = await open(
|
||||
filename,
|
||||
constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK,
|
||||
)
|
||||
try {
|
||||
const info = await file.stat()
|
||||
if (!info.isFile() || info.size > MAX_FILE_BYTES)
|
||||
throw new Error('Upload must be a regular file no larger than 256 MiB.')
|
||||
// Node and Bun declare different DOM stream types for the same fetch-compatible stream.
|
||||
const body = info.size
|
||||
? (Readable.toWeb(
|
||||
file.createReadStream({ autoClose: false, end: info.size - 1 }),
|
||||
) as unknown as ReadableStream<Uint8Array>)
|
||||
: new Uint8Array()
|
||||
const response = await fetch(transferUrl(message.url), {
|
||||
method: 'PUT',
|
||||
body,
|
||||
...{ duplex: 'half' },
|
||||
headers: {
|
||||
'content-type': message.contentType ?? 'application/octet-stream',
|
||||
'content-length': String(info.size),
|
||||
},
|
||||
signal,
|
||||
redirect: 'error',
|
||||
})
|
||||
await response.body?.cancel()
|
||||
if (!response.ok) throw new Error(`Upload failed (HTTP ${response.status}).`)
|
||||
return {
|
||||
type: 'file.upload.result',
|
||||
executionId: message.executionId,
|
||||
ok: true,
|
||||
size: info.size,
|
||||
name: path.basename(filename),
|
||||
}
|
||||
} finally {
|
||||
await file.close()
|
||||
}
|
||||
}
|
||||
|
||||
private async download(message: RunnerFileDownloadMessage, signal: AbortSignal) {
|
||||
const destination = await this.resolve(message.destPath, true)
|
||||
const temporary = await mkdtemp(path.join(path.dirname(destination), '.shumai-'))
|
||||
let preserveBackup = false
|
||||
try {
|
||||
const response = await fetch(transferUrl(message.url), { signal, redirect: 'error' })
|
||||
if (!response.ok || !response.body) {
|
||||
await response.body?.cancel()
|
||||
throw new Error(`Download failed (HTTP ${response.status}).`)
|
||||
}
|
||||
const hash = createHash('sha256')
|
||||
let size = 0
|
||||
const archive = path.join(temporary, 'download')
|
||||
await pipeline(
|
||||
response.body,
|
||||
new Transform({
|
||||
transform(chunk: Buffer, _encoding, callback) {
|
||||
size += chunk.length
|
||||
if (size > MAX_FILE_BYTES) {
|
||||
callback(new Error('Download exceeds 256 MiB.'))
|
||||
return
|
||||
}
|
||||
hash.update(chunk)
|
||||
callback(null, chunk)
|
||||
},
|
||||
}),
|
||||
createWriteStream(archive, { flags: 'wx', mode: 0o600 }),
|
||||
{ signal },
|
||||
)
|
||||
if (message.expectedHash && hash.digest('hex') !== message.expectedHash)
|
||||
throw new Error('Downloaded file hash does not match.')
|
||||
let source = archive
|
||||
if (message.extractZip) {
|
||||
source = path.join(temporary, 'extracted')
|
||||
await mkdir(source, { mode: 0o700 })
|
||||
await this.extract(archive, source, signal)
|
||||
}
|
||||
signal.throwIfAborted()
|
||||
await this.resolve(message.destPath)
|
||||
if (message.extractZip) {
|
||||
const backup = path.join(temporary, 'previous')
|
||||
let backedUp = false
|
||||
try {
|
||||
await rename(destination, backup)
|
||||
backedUp = true
|
||||
} catch (error) {
|
||||
if (!isMissing(error)) throw error
|
||||
}
|
||||
try {
|
||||
await rename(source, destination)
|
||||
} catch (error) {
|
||||
if (backedUp) {
|
||||
preserveBackup = true
|
||||
await rename(backup, destination)
|
||||
preserveBackup = false
|
||||
}
|
||||
throw error
|
||||
}
|
||||
} else await rename(source, destination)
|
||||
return { size, cached: false }
|
||||
} finally {
|
||||
if (!preserveBackup) await rm(temporary, { recursive: true, force: true })
|
||||
}
|
||||
}
|
||||
|
||||
private async extract(archive: string, directory: string, signal: AbortSignal) {
|
||||
const zip = await yauzl.openPromise(archive, {
|
||||
lazyEntries: true,
|
||||
strictFileNames: true,
|
||||
autoClose: false,
|
||||
})
|
||||
let size = 0
|
||||
let count = 0
|
||||
try {
|
||||
signal.throwIfAborted()
|
||||
// Let each metadata read finish before cancellation can close the ZIP descriptor.
|
||||
for await (const entry of zip.eachEntry()) {
|
||||
signal.throwIfAborted()
|
||||
if (++count > MAX_ZIP_ENTRIES) throw new Error('ZIP contains too many entries.')
|
||||
const parts = pathParts(entry.fileName.replace(/\/$/, ''))
|
||||
const mode = entry.externalFileAttributes >>> 16
|
||||
const kind = mode & 0o170000
|
||||
if (kind && kind !== 0o100000 && kind !== 0o040000)
|
||||
throw new Error('ZIP links and special files are forbidden.')
|
||||
size += entry.uncompressedSize
|
||||
if (size > MAX_FILE_BYTES) throw new Error('Extracted ZIP exceeds 256 MiB.')
|
||||
const destination = path.join(directory, ...parts)
|
||||
if (entry.fileName.endsWith('/')) await mkdir(destination, { recursive: true, mode: 0o700 })
|
||||
else {
|
||||
await mkdir(path.dirname(destination), { recursive: true, mode: 0o700 })
|
||||
const input = await zip.openReadStreamPromise(entry)
|
||||
await pipeline(
|
||||
input,
|
||||
createWriteStream(destination, { flags: 'wx', mode: 0o600 | (mode & 0o155) }),
|
||||
{ signal },
|
||||
)
|
||||
}
|
||||
}
|
||||
} finally {
|
||||
zip.close()
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,44 @@
|
||||
import { describe, expect, it } from 'vitest'
|
||||
import {
|
||||
createRunnerLogger,
|
||||
formatBytes,
|
||||
formatDuration,
|
||||
formatLogString,
|
||||
formatTimestamp,
|
||||
shortId,
|
||||
} from './log'
|
||||
|
||||
describe('runner log helpers', () => {
|
||||
it('formats timestamps and aligned log levels', () => {
|
||||
const fixed = new Date(2026, 0, 1, 9, 4, 5)
|
||||
expect(formatTimestamp(fixed)).toBe('09:04:05')
|
||||
const lines: string[] = []
|
||||
const logger = createRunnerLogger(
|
||||
(line) => lines.push(line),
|
||||
false,
|
||||
() => fixed,
|
||||
)
|
||||
logger.info('Bash started [a8f2]')
|
||||
logger.warn('Runner disconnected; reconnecting…')
|
||||
logger.error('Fatal error')
|
||||
expect(lines).toEqual([
|
||||
'09:04:05 INFO Bash started [a8f2]',
|
||||
'09:04:05 WARN Runner disconnected; reconnecting…',
|
||||
'09:04:05 ERROR Fatal error',
|
||||
])
|
||||
})
|
||||
|
||||
it('formats short IDs, durations, byte counts, and single-line quoted strings', () => {
|
||||
expect(shortId('01JABCDEF1234567890A8F2')).toBe('a8f2')
|
||||
expect(shortId('one')).toBe('one')
|
||||
expect(formatDuration(1840)).toBe('1.8s')
|
||||
expect(formatDuration(-10)).toBe('0.0s')
|
||||
expect(formatBytes(0)).toBe('0')
|
||||
expect(formatBytes(512)).toBe('512B')
|
||||
expect(formatBytes(1536)).toBe('1.5KB')
|
||||
expect(formatBytes(12 * 1024)).toBe('12KB')
|
||||
expect(formatBytes(Math.round(2.4 * 1024 * 1024))).toBe('2.4MB')
|
||||
expect(formatLogString('echo "hi"\nls')).toBe('"echo \\"hi\\"\\nls"')
|
||||
expect(formatLogString('x'.repeat(210))).toBe(`"${'x'.repeat(200)}…"`)
|
||||
})
|
||||
})
|
||||
@@ -0,0 +1,59 @@
|
||||
export type RunnerLogLevel = 'INFO' | 'WARN' | 'ERROR'
|
||||
|
||||
export interface RunnerLogger {
|
||||
readonly verbose: boolean
|
||||
info(message: string): void
|
||||
warn(message: string): void
|
||||
error(message: string): void
|
||||
}
|
||||
|
||||
/** Formats a local wall-clock timestamp as HH:MM:SS for runner stderr logs. */
|
||||
export function formatTimestamp(date = new Date()): string {
|
||||
const pad = (value: number) => String(value).padStart(2, '0')
|
||||
return `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`
|
||||
}
|
||||
|
||||
/** Builds a prefixed runner logger writing uniform timestamped lines to stderr. */
|
||||
export function createRunnerLogger(
|
||||
write: (message: string) => void = console.error,
|
||||
verbose = false,
|
||||
now: () => Date = () => new Date(),
|
||||
): RunnerLogger {
|
||||
const emit = (level: RunnerLogLevel, message: string) => {
|
||||
write(`${formatTimestamp(now())} ${level.padEnd(5)} ${message}`)
|
||||
}
|
||||
return {
|
||||
verbose,
|
||||
info: (message) => emit('INFO', message),
|
||||
warn: (message) => emit('WARN', message),
|
||||
error: (message) => emit('ERROR', message),
|
||||
}
|
||||
}
|
||||
|
||||
/** Extracts the trailing 4-character tail of an execution ID for compact log labels. */
|
||||
export function shortId(executionId: string): string {
|
||||
return executionId.slice(-4).toLowerCase()
|
||||
}
|
||||
|
||||
/** Formats a millisecond duration as seconds with one decimal place (e.g. `1.8s`). */
|
||||
export function formatDuration(ms: number): string {
|
||||
return `${(Math.max(0, ms) / 1000).toFixed(1)}s`
|
||||
}
|
||||
|
||||
/** Formats a byte count concisely for runner logs (`0`, `128B`, `12KB`, `2.4MB`). */
|
||||
export function formatBytes(bytes: number): string {
|
||||
if (bytes <= 0) return '0'
|
||||
if (bytes < 1024) return `${bytes}B`
|
||||
if (bytes < 1024 * 1024) {
|
||||
const kb = bytes / 1024
|
||||
return kb < 10 ? `${kb.toFixed(1).replace(/\.0$/, '')}KB` : `${Math.round(kb)}KB`
|
||||
}
|
||||
const mb = bytes / (1024 * 1024)
|
||||
return `${mb.toFixed(1).replace(/\.0$/, '')}MB`
|
||||
}
|
||||
|
||||
/** Formats an arbitrary string (command, path, error) as a bounded single-line JSON string. */
|
||||
export function formatLogString(value: string, maxLength = 200): string {
|
||||
const text = value.length > maxLength ? `${value.slice(0, maxLength)}…` : value
|
||||
return JSON.stringify(text)
|
||||
}
|
||||
@@ -0,0 +1,106 @@
|
||||
import { spawnSync, type SpawnSyncReturns } from 'node:child_process'
|
||||
import { accessSync, constants } from 'node:fs'
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
|
||||
import { resolveRunnerShell } from './shell-config'
|
||||
|
||||
vi.mock('node:child_process', () => ({ spawnSync: vi.fn() }))
|
||||
vi.mock('node:fs', { spy: true })
|
||||
|
||||
const access = vi.mocked(accessSync)
|
||||
const where = vi.mocked(spawnSync)
|
||||
const gitBash = 'D:\\Program Files\\Git\\bin\\bash.exe'
|
||||
const gitBashX86 = 'D:\\Program Files (x86)\\Git\\bin\\bash.exe'
|
||||
|
||||
function whereResult(stdout = '', status = 0): SpawnSyncReturns<string> {
|
||||
return { stdout, stderr: '', status, output: [null, stdout, ''], pid: 1, signal: null }
|
||||
}
|
||||
|
||||
function available(...paths: string[]) {
|
||||
access.mockImplementation((executable) => {
|
||||
if (!paths.some((path) => executable === path)) throw new Error('File not found')
|
||||
})
|
||||
}
|
||||
|
||||
beforeEach(() => {
|
||||
vi.stubEnv('ProgramFiles', 'D:\\Program Files')
|
||||
vi.stubEnv('ProgramFiles(x86)', 'D:\\Program Files (x86)')
|
||||
vi.stubEnv('SystemRoot', 'E:\\WinNT')
|
||||
available()
|
||||
where.mockReturnValue(whereResult('', 1))
|
||||
})
|
||||
|
||||
afterEach(() => {
|
||||
vi.resetAllMocks()
|
||||
vi.unstubAllEnvs()
|
||||
})
|
||||
|
||||
describe('runner shell selection', () => {
|
||||
it.each(['linux', 'darwin'] as const)('uses /bin/sh on %s', (platform) => {
|
||||
expect(resolveRunnerShell(platform)).toEqual({
|
||||
executable: '/bin/sh',
|
||||
commandTransport: 'shell',
|
||||
})
|
||||
expect(where).not.toHaveBeenCalled()
|
||||
})
|
||||
|
||||
it.each([
|
||||
[gitBash, [gitBash, gitBashX86]],
|
||||
[gitBashX86, [gitBashX86]],
|
||||
] as const)('prefers installed Git Bash at %s before PATH', (executable, paths) => {
|
||||
available(...paths)
|
||||
expect(resolveRunnerShell('win32')).toEqual({ executable, commandTransport: 'argv' })
|
||||
expect(where).not.toHaveBeenCalled()
|
||||
})
|
||||
|
||||
// Adapted from Pi's shell-path-exists.test.ts. See apps/cli/THIRD-PARTY-NOTICES.txt.
|
||||
it('accepts a Windows Store Bash alias found on PATH via access(F_OK)', () => {
|
||||
const alias = 'D:\\Users\\runner\\AppData\\Local\\Microsoft\\WindowsApps\\bash.exe'
|
||||
available(alias)
|
||||
where.mockReturnValue(whereResult(alias + '\r\n'))
|
||||
expect(resolveRunnerShell('win32')).toEqual({ executable: alias, commandTransport: 'argv' })
|
||||
expect(access).toHaveBeenCalledWith(alias, constants.F_OK)
|
||||
expect(where).toHaveBeenCalledWith('E:\\WinNT\\System32\\where.exe', ['$PATH:bash.exe'], {
|
||||
encoding: 'utf8',
|
||||
timeout: 5000,
|
||||
windowsHide: true,
|
||||
})
|
||||
})
|
||||
|
||||
it('skips relative and inaccessible PATH results', () => {
|
||||
const executable = 'D:\\MSYS2\\usr\\bin\\bash.exe'
|
||||
available(executable)
|
||||
where.mockReturnValue(
|
||||
whereResult(['bash.exe', 'D:\\missing\\bash.exe', executable].join('\r\n')),
|
||||
)
|
||||
expect(resolveRunnerShell('win32')).toEqual({ executable, commandTransport: 'argv' })
|
||||
})
|
||||
|
||||
it.each([
|
||||
['E:\\WinNT', 'E:\\WinNT\\System32\\cmd.exe'],
|
||||
[undefined, 'C:\\Windows\\System32\\cmd.exe'],
|
||||
] as const)(
|
||||
'falls back to cmd.exe when no Bash is available (SystemRoot %s)',
|
||||
(root, executable) => {
|
||||
vi.stubEnv('SystemRoot', root)
|
||||
expect(resolveRunnerShell('win32')).toEqual({ executable, commandTransport: 'shell' })
|
||||
},
|
||||
)
|
||||
|
||||
// Adapted from Pi's windows-shell-config.test.ts.
|
||||
it.each([
|
||||
['D:\\WinNT\\', 'd:/WINNT/System32/BASH.EXE', 'stdin'],
|
||||
['D:\\WinNT', 'D:\\WinNT\\Sysnative\\bash.exe', 'stdin'],
|
||||
[undefined, 'E:\\Windows\\System32\\bash.exe', 'stdin'],
|
||||
['D:\\WinNT', 'D:\\Git\\bin\\bash.exe', 'argv'],
|
||||
['D:\\WinNT', 'E:\\Windows\\System32\\bash.exe', 'argv'],
|
||||
['WinNT', 'C:\\Windows\\System32\\bash.exe', 'argv'],
|
||||
] as const)(
|
||||
'uses the correct command transport for SystemRoot %s and %s',
|
||||
(root, executable, commandTransport) => {
|
||||
vi.stubEnv('SystemRoot', root)
|
||||
available(executable)
|
||||
where.mockReturnValue(whereResult(executable + '\r\n'))
|
||||
expect(resolveRunnerShell('win32')).toEqual({ executable, commandTransport })
|
||||
},
|
||||
)
|
||||
})
|
||||
@@ -0,0 +1,64 @@
|
||||
import { spawnSync } from 'node:child_process'
|
||||
import { accessSync, constants } from 'node:fs'
|
||||
import { win32 } from 'node:path'
|
||||
|
||||
export interface RunnerShellConfig {
|
||||
executable: string
|
||||
commandTransport: 'shell' | 'argv' | 'stdin'
|
||||
}
|
||||
|
||||
// Windows Bash discovery and legacy WSL detection adapted from pi-mono.
|
||||
// See apps/cli/THIRD-PARTY-NOTICES.txt.
|
||||
function isLegacyWslBashPath(executable: string, systemRoot: string | undefined): boolean {
|
||||
const normalized = win32.normalize(executable).toLowerCase()
|
||||
if (systemRoot) {
|
||||
if (!/^[a-z]:[\\/]/i.test(systemRoot)) return false
|
||||
return ['System32', 'Sysnative'].some(
|
||||
(directory) => normalized === win32.join(systemRoot, directory, 'bash.exe').toLowerCase(),
|
||||
)
|
||||
}
|
||||
return /^[a-z]:\\windows\\(?:system32|sysnative)\\bash\.exe$/.test(normalized)
|
||||
}
|
||||
|
||||
function shellPathExists(executable: string): boolean {
|
||||
// access(F_OK) accepts runnable Windows Store aliases that fail an extra stat check.
|
||||
try {
|
||||
accessSync(executable, constants.F_OK)
|
||||
return true
|
||||
} catch {
|
||||
return false
|
||||
}
|
||||
}
|
||||
|
||||
function findWindowsBash(system32: string): string | undefined {
|
||||
for (const directory of [process.env.ProgramFiles, process.env['ProgramFiles(x86)']]) {
|
||||
if (!directory || !win32.isAbsolute(directory)) continue
|
||||
const executable = win32.join(directory, 'Git', 'bin', 'bash.exe')
|
||||
if (shellPathExists(executable)) return executable
|
||||
}
|
||||
|
||||
// Use the system tool and limit its search to PATH. The workspace may contain a bash.exe.
|
||||
const found = spawnSync(win32.join(system32, 'where.exe'), ['$PATH:bash.exe'], {
|
||||
encoding: 'utf8',
|
||||
timeout: 5000,
|
||||
windowsHide: true,
|
||||
})
|
||||
if (found.status !== 0 || !found.stdout) return
|
||||
return found.stdout
|
||||
.trim()
|
||||
.split(/\r?\n/)
|
||||
.find((executable) => win32.isAbsolute(executable) && shellPathExists(executable))
|
||||
}
|
||||
|
||||
export function resolveRunnerShell(platform = process.platform): RunnerShellConfig {
|
||||
if (platform !== 'win32') return { executable: '/bin/sh', commandTransport: 'shell' }
|
||||
|
||||
const systemRoot = process.env.SystemRoot
|
||||
const system32 = win32.join(systemRoot ?? 'C:\\Windows', 'System32')
|
||||
const executable = findWindowsBash(system32)
|
||||
if (!executable) return { executable: win32.join(system32, 'cmd.exe'), commandTransport: 'shell' }
|
||||
return {
|
||||
executable,
|
||||
commandTransport: isLegacyWslBashPath(executable, systemRoot) ? 'stdin' : 'argv',
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,352 @@
|
||||
import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
|
||||
import { tmpdir } from 'node:os'
|
||||
import path from 'node:path'
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
|
||||
import { SandboxManager } from '@anthropic-ai/sandbox-runtime'
|
||||
import { RunnerFiles } from './files'
|
||||
import { RunnerShell } from './shell'
|
||||
|
||||
describe('runner bash execution', () => {
|
||||
let cwd: string
|
||||
let shell: RunnerShell
|
||||
beforeEach(async () => {
|
||||
cwd = await mkdtemp(path.join(tmpdir(), 'shumai-shell-test-'))
|
||||
shell = new RunnerShell(new RunnerFiles(cwd))
|
||||
vi.spyOn(SandboxManager, 'initialize').mockResolvedValue()
|
||||
vi.spyOn(SandboxManager, 'reset').mockResolvedValue()
|
||||
vi.spyOn(SandboxManager, 'wrapWithSandboxArgv').mockImplementation(async (command) => ({
|
||||
argv: ['/bin/sh', '-c', command],
|
||||
env: process.env,
|
||||
}))
|
||||
})
|
||||
afterEach(async () => {
|
||||
await shell.close()
|
||||
vi.restoreAllMocks()
|
||||
vi.unstubAllEnvs()
|
||||
await rm(cwd, { recursive: true, force: true })
|
||||
})
|
||||
|
||||
const request = (command: string, executionId = 'test') => ({
|
||||
type: 'exec.start' as const,
|
||||
executionId,
|
||||
command,
|
||||
})
|
||||
|
||||
it('runs with no executables on PATH when SRT is not requested', async () => {
|
||||
vi.stubEnv('PATH', '')
|
||||
await shell.initialize()
|
||||
let output = ''
|
||||
const result = await shell.run(
|
||||
request('printf no-extra-runtime'),
|
||||
new AbortController().signal,
|
||||
(_stream, data) => {
|
||||
output += data
|
||||
},
|
||||
)
|
||||
expect(result).toMatchObject({ exitCode: 0 })
|
||||
expect(output).toBe('no-extra-runtime')
|
||||
})
|
||||
|
||||
// Adapted from Pi's tools.test.ts. See apps/cli/THIRD-PARTY-NOTICES.txt.
|
||||
it('sends the complete command over stdin for the legacy Bash launcher', async () => {
|
||||
shell = new RunnerShell(new RunnerFiles(cwd), undefined, {
|
||||
executable: '/bin/sh',
|
||||
commandTransport: 'stdin',
|
||||
})
|
||||
const command = [
|
||||
'name="Hello, 世界"',
|
||||
'for choice in "one two" \'three "four"\'; do',
|
||||
' printf \'%s / %s\\n\' "$name" "$choice"',
|
||||
'done',
|
||||
].join('\n')
|
||||
let output = ''
|
||||
const result = await shell.run(
|
||||
request(command),
|
||||
new AbortController().signal,
|
||||
(_stream, data) => {
|
||||
output += data
|
||||
},
|
||||
)
|
||||
expect(result).toMatchObject({ exitCode: 0 })
|
||||
expect(output).toBe('Hello, 世界 / one two\nHello, 世界 / three "four"\n')
|
||||
})
|
||||
|
||||
it('passes a command with shell quoting directly to the selected executable', async () => {
|
||||
shell = new RunnerShell(new RunnerFiles(cwd), undefined, {
|
||||
executable: '/bin/sh',
|
||||
commandTransport: 'argv',
|
||||
})
|
||||
const command = "printf '%s' '$literal \"quotes\"'"
|
||||
let output = ''
|
||||
const result = await shell.run(
|
||||
request(command),
|
||||
new AbortController().signal,
|
||||
(_stream, data) => {
|
||||
output += data
|
||||
},
|
||||
)
|
||||
expect(result).toMatchObject({ exitCode: 0 })
|
||||
expect(output).toBe('$literal "quotes"')
|
||||
})
|
||||
|
||||
it('rejects the legacy WSL launcher before starting SRT', async () => {
|
||||
shell = new RunnerShell(new RunnerFiles(cwd), path.join(cwd, 'sandbox.json'), {
|
||||
executable: 'C:\\Windows\\System32\\bash.exe',
|
||||
commandTransport: 'stdin',
|
||||
})
|
||||
await expect(shell.initialize()).rejects.toThrow('SRT cannot run the legacy WSL Bash launcher')
|
||||
expect(SandboxManager.initialize).not.toHaveBeenCalled()
|
||||
})
|
||||
|
||||
it('streams both outputs, returns the exit code, and saves a log in the runner workspace', async () => {
|
||||
const output: string[] = []
|
||||
const result = await shell.run(
|
||||
request('printf "hello 世界"; printf "failure" >&2; exit 7'),
|
||||
new AbortController().signal,
|
||||
(stream, data) => output.push(`${stream}:${data}`),
|
||||
)
|
||||
expect(result).toMatchObject({
|
||||
exitCode: 7,
|
||||
signal: null,
|
||||
timedOut: false,
|
||||
fullOutputPath: '.pi/logs/bash-test.log',
|
||||
})
|
||||
expect(output.join('|')).toContain('stdout:hello 世界')
|
||||
expect(output.join('|')).toContain('stderr:failure')
|
||||
expect(await readFile(path.join(cwd, result.fullOutputPath!), 'utf8')).toContain('hello 世界')
|
||||
})
|
||||
|
||||
it('passes skill env without inheriting runner or unrelated credentials', async () => {
|
||||
vi.stubEnv('SHUMAI_RUNNER_KEY', 'runner-secret')
|
||||
vi.stubEnv('AWS_SECRET_ACCESS_KEY', 'aws-secret')
|
||||
let output = ''
|
||||
await shell.run(
|
||||
{
|
||||
...request(
|
||||
'printf "%s|%s|%s" "$SKILL_TOKEN" "$SHUMAI_RUNNER_KEY" "$AWS_SECRET_ACCESS_KEY"',
|
||||
),
|
||||
env: { SKILL_TOKEN: 'skill-secret' },
|
||||
},
|
||||
new AbortController().signal,
|
||||
(_stream, data) => {
|
||||
output += data
|
||||
},
|
||||
)
|
||||
expect(output).toBe('skill-secret||')
|
||||
})
|
||||
|
||||
it('times out and terminates background children', async () => {
|
||||
const result = await shell.run(
|
||||
{ ...request('sleep 30 & echo $!; wait'), timeoutSec: 0.1 },
|
||||
new AbortController().signal,
|
||||
() => {},
|
||||
)
|
||||
expect(result).toMatchObject({ timedOut: true, signal: 'SIGKILL' })
|
||||
const pid = Number((await readFile(path.join(cwd, '.pi/logs/bash-test.log'), 'utf8')).trim())
|
||||
expect(() => process.kill(pid, 0)).toThrow()
|
||||
})
|
||||
|
||||
it('cancels a running command and never starts an already cancelled one', async () => {
|
||||
const controller = new AbortController()
|
||||
const running = shell.run(request('echo ready; sleep 30'), controller.signal, () =>
|
||||
controller.abort(),
|
||||
)
|
||||
expect(await running).toMatchObject({ aborted: true, signal: 'SIGKILL' })
|
||||
expect(
|
||||
await shell.run(request('touch unwanted', 'cancelled'), controller.signal, () => {}),
|
||||
).toMatchObject({ aborted: true })
|
||||
await expect(readFile(path.join(cwd, 'unwanted'))).rejects.toThrow()
|
||||
})
|
||||
|
||||
it('finishes draining after a timely root exit even if a background process holds the pipes', async () => {
|
||||
const source = `const {spawn} = require('node:child_process'); const child = spawn(process.execPath, ['-e', 'setTimeout(() => {}, 30000)'], {detached: true, stdio: ['ignore', 1, 2]}); console.log(child.pid); child.unref()`
|
||||
const quote = (value: string) => `'${value.replaceAll("'", "'\\''")}'`
|
||||
const result = await shell.run(
|
||||
{ ...request(`${quote(process.execPath)} -e ${quote(source)}`), timeoutSec: 0.5 },
|
||||
new AbortController().signal,
|
||||
() => {},
|
||||
)
|
||||
const pid = Number((await readFile(path.join(cwd, '.pi/logs/bash-test.log'), 'utf8')).trim())
|
||||
try {
|
||||
expect(result).toMatchObject({ exitCode: 0, timedOut: false, aborted: false })
|
||||
expect(result.error).toBeUndefined()
|
||||
} finally {
|
||||
if (pid > 0) process.kill(pid, 'SIGKILL')
|
||||
}
|
||||
})
|
||||
|
||||
it('reports launch failure without including command text or skill secrets', async () => {
|
||||
shell = new RunnerShell(new RunnerFiles(cwd), undefined, {
|
||||
executable: path.join(cwd, 'missing-shell'),
|
||||
commandTransport: 'shell',
|
||||
})
|
||||
const result = await shell.run(
|
||||
request('echo private-command'),
|
||||
new AbortController().signal,
|
||||
() => {},
|
||||
)
|
||||
expect(result).toMatchObject({
|
||||
exitCode: null,
|
||||
signal: null,
|
||||
error: 'Command execution failed (ENOENT).',
|
||||
})
|
||||
expect(result.error).not.toContain('private-command')
|
||||
})
|
||||
|
||||
it('terminates a running process if the output consumer fails', async () => {
|
||||
let pid = 0
|
||||
const result = await shell.run(
|
||||
request('printf "%s\\n" "$$"; sleep 30'),
|
||||
new AbortController().signal,
|
||||
(_stream, data) => {
|
||||
pid = Number(data.trim())
|
||||
throw new Error('Output consumer failed')
|
||||
},
|
||||
)
|
||||
expect(result.error).toBe('Output consumer failed')
|
||||
expect(pid).toBeGreaterThan(0)
|
||||
expect(() => process.kill(pid, 0)).toThrow()
|
||||
})
|
||||
|
||||
it('rejects invalid timeouts and caps runaway output', async () => {
|
||||
expect(
|
||||
await shell.run(
|
||||
{ ...request('sleep 30'), timeoutSec: -1 },
|
||||
new AbortController().signal,
|
||||
() => {},
|
||||
),
|
||||
).toHaveProperty('error')
|
||||
expect(
|
||||
await shell.run(
|
||||
request('head -c 70000000 /dev/zero', 'large'),
|
||||
new AbortController().signal,
|
||||
() => {},
|
||||
),
|
||||
).toMatchObject({ error: 'Command exceeded the 64 MiB output limit.' })
|
||||
})
|
||||
|
||||
it('uses the exact SRT JSON snapshot and validates SRT before connecting', async () => {
|
||||
const settings = path.join(cwd, 'sandbox.json')
|
||||
const config = {
|
||||
network: { allowedDomains: [], deniedDomains: [] },
|
||||
filesystem: { denyRead: [], allowWrite: ['.pi'], denyWrite: [] },
|
||||
}
|
||||
const json = JSON.stringify(config)
|
||||
await writeFile(settings, json)
|
||||
vi.stubEnv('PATH', '')
|
||||
shell = new RunnerShell(new RunnerFiles(cwd), settings)
|
||||
await shell.initialize()
|
||||
await writeFile(settings, '{}')
|
||||
expect(
|
||||
await shell.run(request('echo sandboxed'), new AbortController().signal, () => {}),
|
||||
).toMatchObject({ exitCode: 0 })
|
||||
expect(SandboxManager.initialize).toHaveBeenCalledExactlyOnceWith(
|
||||
expect.objectContaining(config),
|
||||
)
|
||||
expect(SandboxManager.wrapWithSandboxArgv).toHaveBeenCalledWith(
|
||||
expect.stringContaining('echo sandboxed'),
|
||||
'/bin/sh',
|
||||
undefined,
|
||||
expect.any(AbortSignal),
|
||||
cwd,
|
||||
{ commandId: 'test', commandText: 'echo sandboxed' },
|
||||
)
|
||||
expect(SandboxManager.reset).not.toHaveBeenCalled()
|
||||
})
|
||||
|
||||
it('keeps skill PATH and Node startup settings out of the SRT launcher', async () => {
|
||||
const settings = path.join(cwd, 'sandbox.json')
|
||||
const marker = path.join(cwd, 'injected')
|
||||
const evil = path.join(cwd, 'evil.cjs')
|
||||
await writeFile(
|
||||
settings,
|
||||
JSON.stringify({
|
||||
network: { allowedDomains: [], deniedDomains: [] },
|
||||
filesystem: { denyRead: [], allowWrite: ['.pi'], denyWrite: [] },
|
||||
}),
|
||||
)
|
||||
await writeFile(evil, `require('node:fs').writeFileSync('${marker}', 'escaped')`)
|
||||
shell = new RunnerShell(new RunnerFiles(cwd), settings)
|
||||
await shell.initialize()
|
||||
const result = await shell.run(
|
||||
{
|
||||
...request('printf secure'),
|
||||
env: { PATH: '/evil-srt', NODE_OPTIONS: `--require=${evil}` },
|
||||
},
|
||||
new AbortController().signal,
|
||||
() => {},
|
||||
)
|
||||
expect(result).toMatchObject({ exitCode: 0 })
|
||||
await expect(readFile(marker)).rejects.toThrow()
|
||||
})
|
||||
|
||||
it('initializes one sandbox for parallel commands and resets only at shutdown', async () => {
|
||||
const settings = path.join(cwd, 'sandbox.json')
|
||||
await writeFile(
|
||||
settings,
|
||||
JSON.stringify({
|
||||
network: { allowedDomains: [], deniedDomains: [] },
|
||||
filesystem: { denyRead: [], allowWrite: ['.pi'], denyWrite: [] },
|
||||
}),
|
||||
)
|
||||
shell = new RunnerShell(new RunnerFiles(cwd), settings)
|
||||
await shell.initialize()
|
||||
const value = "quoted ' value\n$(echo should-not-expand)"
|
||||
let output = ''
|
||||
const results = await Promise.all(
|
||||
['one', 'two'].map((id) =>
|
||||
shell.run(
|
||||
{ ...request('printf "%s" "$SKILL_TOKEN"', id), env: { SKILL_TOKEN: value } },
|
||||
new AbortController().signal,
|
||||
(_stream, data) => {
|
||||
output += data
|
||||
},
|
||||
),
|
||||
),
|
||||
)
|
||||
expect(results.every((result) => result.exitCode === 0)).toBe(true)
|
||||
expect(output).toBe(value.repeat(2))
|
||||
expect(SandboxManager.initialize).toHaveBeenCalledTimes(1)
|
||||
expect(SandboxManager.reset).not.toHaveBeenCalled()
|
||||
await shell.close()
|
||||
expect(SandboxManager.reset).toHaveBeenCalledTimes(1)
|
||||
})
|
||||
|
||||
it('fails startup and cleans up if sandbox initialization or execution fails', async () => {
|
||||
const settings = path.join(cwd, 'sandbox.json')
|
||||
await writeFile(
|
||||
settings,
|
||||
JSON.stringify({
|
||||
network: { allowedDomains: [], deniedDomains: [] },
|
||||
filesystem: { denyRead: [], allowWrite: ['.pi'], denyWrite: [] },
|
||||
}),
|
||||
)
|
||||
shell = new RunnerShell(new RunnerFiles(cwd), settings)
|
||||
vi.mocked(SandboxManager.initialize).mockRejectedValueOnce(
|
||||
new Error('Run windows-install first'),
|
||||
)
|
||||
await expect(shell.initialize()).rejects.toThrow('windows-install')
|
||||
expect(SandboxManager.reset).toHaveBeenCalledTimes(1)
|
||||
expect(
|
||||
await shell.run(request('echo unsafe'), new AbortController().signal, () => {}),
|
||||
).toHaveProperty('error', 'SRT has not been initialized.')
|
||||
vi.mocked(SandboxManager.wrapWithSandboxArgv).mockRejectedValueOnce(
|
||||
new Error('sandbox unavailable'),
|
||||
)
|
||||
await expect(shell.initialize()).rejects.toThrow('SRT preflight failed: sandbox unavailable')
|
||||
})
|
||||
|
||||
it('fails closed for missing or malformed SRT settings', async () => {
|
||||
const settings = path.join(cwd, 'sandbox.json')
|
||||
await expect(new RunnerShell(new RunnerFiles(cwd), settings).initialize()).rejects.toThrow()
|
||||
await writeFile(settings, 'invalid json')
|
||||
await expect(new RunnerShell(new RunnerFiles(cwd), settings).initialize()).rejects.toThrow()
|
||||
await writeFile(settings, '[]')
|
||||
await expect(new RunnerShell(new RunnerFiles(cwd), settings).initialize()).rejects.toThrow(
|
||||
/object/,
|
||||
)
|
||||
await writeFile(settings, JSON.stringify({ network: { allowedDomains: 42 } }))
|
||||
await expect(new RunnerShell(new RunnerFiles(cwd), settings).initialize()).rejects.toThrow()
|
||||
expect(SandboxManager.initialize).not.toHaveBeenCalled()
|
||||
})
|
||||
})
|
||||
@@ -0,0 +1,232 @@
|
||||
import { randomUUID } from 'node:crypto'
|
||||
import { execa } from 'execa'
|
||||
import { SandboxManager } from '@anthropic-ai/sandbox-runtime'
|
||||
import {
|
||||
runnerEnvironmentSchema,
|
||||
type RunnerEnvironment,
|
||||
type RunnerExecResultMessage,
|
||||
type RunnerExecStartMessage,
|
||||
} from '@shumai/dtos'
|
||||
import { commandEnv } from './config'
|
||||
import { RunnerFiles } from './files'
|
||||
import { resolveRunnerShell } from './shell-config'
|
||||
import { loadSandbox } from './srt'
|
||||
|
||||
const MAX_OUTPUT_BYTES = 64 * 1024 * 1024
|
||||
const MAX_TIMEOUT_SEC = 3600
|
||||
|
||||
export class RunnerShell {
|
||||
readonly environment: RunnerEnvironment
|
||||
private sandbox?: Awaited<ReturnType<typeof loadSandbox>>
|
||||
private initialized = false
|
||||
private active = 0
|
||||
|
||||
constructor(
|
||||
private readonly files: RunnerFiles,
|
||||
private readonly srtPath?: string,
|
||||
private readonly config = resolveRunnerShell(),
|
||||
) {
|
||||
this.environment = runnerEnvironmentSchema.parse({
|
||||
platform: process.platform,
|
||||
shell: config.executable,
|
||||
})
|
||||
}
|
||||
|
||||
async initialize() {
|
||||
if (!this.srtPath) return
|
||||
if (this.config.commandTransport === 'stdin')
|
||||
throw new Error(
|
||||
'SRT cannot run the legacy WSL Bash launcher. Install Git for Windows to use Bash with SRT.',
|
||||
)
|
||||
// Read and validate once; commands cannot weaken the policy by editing the file.
|
||||
this.sandbox = await loadSandbox(this.srtPath)
|
||||
try {
|
||||
await SandboxManager.initialize(this.sandbox.config)
|
||||
this.initialized = true
|
||||
let diagnostic = ''
|
||||
const probe = await this.run(
|
||||
{ type: 'exec.start', executionId: randomUUID(), command: 'exit 0', timeoutSec: 15 },
|
||||
new AbortController().signal,
|
||||
(_stream, data) => {
|
||||
diagnostic = (diagnostic + data).slice(-4096)
|
||||
},
|
||||
)
|
||||
if (probe.exitCode !== 0 || probe.error || probe.timedOut)
|
||||
throw new Error(
|
||||
`SRT preflight failed: ${probe.error || diagnostic.trim() || 'Check settings and local SRT prerequisites.'}`,
|
||||
)
|
||||
} catch (error) {
|
||||
await this.close()
|
||||
throw error
|
||||
}
|
||||
}
|
||||
|
||||
async close() {
|
||||
if (!this.sandbox) return
|
||||
try {
|
||||
await SandboxManager.reset()
|
||||
} finally {
|
||||
await this.sandbox.cleanup()
|
||||
this.sandbox = undefined
|
||||
this.initialized = false
|
||||
}
|
||||
}
|
||||
|
||||
async run(
|
||||
message: RunnerExecStartMessage,
|
||||
signal: AbortSignal,
|
||||
output: (stream: 'stdout' | 'stderr', data: string) => void,
|
||||
): Promise<RunnerExecResultMessage> {
|
||||
const result: RunnerExecResultMessage = {
|
||||
type: 'exec.result',
|
||||
executionId: message.executionId,
|
||||
exitCode: null,
|
||||
signal: null,
|
||||
timedOut: false,
|
||||
aborted: false,
|
||||
}
|
||||
if (this.srtPath) this.active++
|
||||
try {
|
||||
if (signal.aborted) return { ...result, aborted: true }
|
||||
const timeout = message.timeoutSec ?? 120
|
||||
if (!Number.isFinite(timeout) || timeout <= 0 || timeout > MAX_TIMEOUT_SEC)
|
||||
throw new Error(`Command timeout must be between 0 and ${MAX_TIMEOUT_SEC} seconds.`)
|
||||
const logPath = `.pi/logs/bash-${message.executionId}.log`
|
||||
const log = await this.files.createWriter(logPath)
|
||||
try {
|
||||
const windows = process.platform === 'win32'
|
||||
const { commandTransport } = this.config
|
||||
const useShell = commandTransport === 'shell'
|
||||
const sendCommandOnStdin = commandTransport === 'stdin'
|
||||
let executable = useShell ? message.command : this.config.executable
|
||||
let args = useShell ? [] : sendCommandOnStdin ? ['-s'] : ['-c', message.command]
|
||||
let shell: string | false = useShell && this.config.executable
|
||||
let env = commandEnv(message.env)
|
||||
if (this.srtPath) {
|
||||
if (!this.initialized) throw new Error('SRT has not been initialized.')
|
||||
const skillEnv = commandEnv(message.env, false)
|
||||
const command = windows
|
||||
? message.command
|
||||
: [
|
||||
...Object.entries(skillEnv).map(
|
||||
([key, value]) => `export ${key}='${value!.replaceAll("'", "'\\''")}'`,
|
||||
),
|
||||
message.command,
|
||||
].join('\n')
|
||||
const wrapped = await SandboxManager.wrapWithSandboxArgv(
|
||||
command,
|
||||
this.config.executable,
|
||||
undefined,
|
||||
signal,
|
||||
this.files.cwd,
|
||||
{ commandId: message.executionId, commandText: message.command },
|
||||
)
|
||||
;[executable, ...args] = wrapped.argv
|
||||
shell = false
|
||||
if (windows) {
|
||||
// SRT's broker starts a fresh sandbox-user environment. Explicit skill
|
||||
// values belong in its child overlay, never in the broker's startup env.
|
||||
const separator = args.indexOf('--')
|
||||
if (separator < 0) throw new Error('SRT returned an invalid Windows launch command.')
|
||||
args.splice(
|
||||
separator,
|
||||
0,
|
||||
...Object.entries(skillEnv).flatMap(([key, value]) => ['--env', `${key}=${value}`]),
|
||||
)
|
||||
env = wrapped.env
|
||||
} else env = commandEnv()
|
||||
}
|
||||
if (signal.aborted) return { ...result, aborted: true }
|
||||
const deadline = Date.now() + Math.ceil(timeout * 1000)
|
||||
const child = execa(executable, args, {
|
||||
cwd: this.files.cwd,
|
||||
env,
|
||||
extendEnv: false,
|
||||
shell,
|
||||
stdin: sendCommandOnStdin ? [Buffer.from(message.command)] : 'ignore',
|
||||
buffer: false,
|
||||
reject: false,
|
||||
stripFinalNewline: false,
|
||||
verbose: 'none',
|
||||
windowsHide: true,
|
||||
killDescendants: true,
|
||||
killSignal: 'SIGKILL',
|
||||
cancelSignal: signal,
|
||||
timeout: Math.ceil(timeout * 1000),
|
||||
})
|
||||
let bytes = 0
|
||||
let writes = Promise.resolve()
|
||||
let drainTimer: ReturnType<typeof setTimeout> | undefined
|
||||
let drainExpired = false
|
||||
let exitedWithinDeadline = false
|
||||
child.nodeChildProcess.once('exit', (exitCode) => {
|
||||
exitedWithinDeadline = exitCode !== null && Date.now() < deadline
|
||||
// Execa cleans up descendants where the OS still permits it. Bound
|
||||
// draining if a background child keeps inherited output pipes open.
|
||||
child.kill('SIGKILL')
|
||||
drainTimer = setTimeout(() => {
|
||||
drainExpired = true
|
||||
child.stdout.destroy()
|
||||
child.stderr.destroy()
|
||||
}, 1000)
|
||||
})
|
||||
try {
|
||||
const readers = (['stdout', 'stderr'] as const).map(async (stream) => {
|
||||
child[stream].setEncoding('utf8')
|
||||
try {
|
||||
for await (const data of child[stream]) {
|
||||
bytes += Buffer.byteLength(data)
|
||||
if (bytes > MAX_OUTPUT_BYTES)
|
||||
throw new Error('Command exceeded the 64 MiB output limit.')
|
||||
await (writes = writes.then(async () => {
|
||||
await log.write(data)
|
||||
output(stream, data)
|
||||
}))
|
||||
}
|
||||
} catch (error) {
|
||||
if (
|
||||
drainExpired &&
|
||||
error instanceof Error &&
|
||||
'code' in error &&
|
||||
error.code === 'ERR_STREAM_PREMATURE_CLOSE'
|
||||
)
|
||||
return
|
||||
result.error ??= error instanceof Error ? error.message : 'Output streaming failed.'
|
||||
child.kill('SIGKILL')
|
||||
}
|
||||
})
|
||||
const [completed] = await Promise.all([child, Promise.all(readers)])
|
||||
await writes
|
||||
result.exitCode = completed.exitCode ?? null
|
||||
result.signal = completed.signal ?? null
|
||||
// Execa's timeout includes stream draining. Report the command's
|
||||
// runtime, so a timely exit does not become a timeout while draining.
|
||||
result.timedOut = completed.timedOut && !exitedWithinDeadline
|
||||
result.aborted = completed.isCanceled
|
||||
if (
|
||||
completed.failed &&
|
||||
completed.exitCode === undefined &&
|
||||
!result.timedOut &&
|
||||
!result.aborted &&
|
||||
!completed.signal
|
||||
)
|
||||
result.error = `Command execution failed (${completed.code ?? 'unknown error'}).`
|
||||
result.fullOutputPath = logPath
|
||||
} finally {
|
||||
clearTimeout(drainTimer)
|
||||
}
|
||||
} finally {
|
||||
await log.close()
|
||||
}
|
||||
} catch (error) {
|
||||
result.aborted = signal.aborted
|
||||
result.error = error instanceof Error ? error.message : 'Command execution failed.'
|
||||
} finally {
|
||||
// SRT's temporary mount resources are shared: clean up only after every
|
||||
// concurrent command has finished, and keep the proxies until shutdown.
|
||||
if (this.srtPath && --this.active === 0 && this.initialized)
|
||||
SandboxManager.cleanupAfterCommand()
|
||||
}
|
||||
return result
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,2 @@
|
||||
// Release builds embed SRT's native helpers through scripts/srt-bundle.ts.
|
||||
export const bundledSrtVendor: Record<string, string> | undefined = undefined
|
||||
@@ -0,0 +1,59 @@
|
||||
import { mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises'
|
||||
import { tmpdir } from 'node:os'
|
||||
import path from 'node:path'
|
||||
import { afterEach, beforeEach, describe, expect, it } from 'vitest'
|
||||
import { loadSandbox } from './srt'
|
||||
|
||||
describe('runner SRT configuration', () => {
|
||||
let directory: string
|
||||
let settings: string
|
||||
const config = {
|
||||
network: { allowedDomains: [], deniedDomains: [] },
|
||||
filesystem: { denyRead: [], allowWrite: ['.pi'], denyWrite: [] },
|
||||
}
|
||||
beforeEach(async () => {
|
||||
directory = await mkdtemp(path.join(tmpdir(), 'shumai-srt-settings-'))
|
||||
settings = path.join(directory, 'sandbox.json')
|
||||
})
|
||||
afterEach(() => rm(directory, { recursive: true, force: true }))
|
||||
|
||||
it('validates upstream settings, supplies packaged helpers, and removes them on cleanup', async () => {
|
||||
await writeFile(settings, JSON.stringify(config))
|
||||
const sandbox = await loadSandbox(settings)
|
||||
const helper = sandbox.config.javaAgentJarPath!
|
||||
expect(sandbox.config).toMatchObject(config)
|
||||
expect((await readFile(helper)).subarray(0, 2).toString()).toBe('PK')
|
||||
if (process.platform === 'linux')
|
||||
expect(await stat(sandbox.config.seccomp!.applyPath!)).toHaveProperty(
|
||||
'size',
|
||||
expect.any(Number),
|
||||
)
|
||||
if (process.platform === 'win32')
|
||||
expect(await stat(sandbox.config.windows!.srtWin!.path!)).toHaveProperty(
|
||||
'size',
|
||||
expect.any(Number),
|
||||
)
|
||||
await sandbox.cleanup()
|
||||
await expect(stat(helper)).rejects.toThrow()
|
||||
})
|
||||
|
||||
it('preserves explicit upstream helper paths', async () => {
|
||||
await writeFile(
|
||||
settings,
|
||||
JSON.stringify({
|
||||
...config,
|
||||
javaAgentJarPath: '/custom/proxy.jar',
|
||||
seccomp: { applyPath: '/custom/seccomp' },
|
||||
windows: { srtWin: { path: 'C:\\custom\\srt-win.exe' } },
|
||||
}),
|
||||
)
|
||||
const sandbox = await loadSandbox(settings)
|
||||
try {
|
||||
expect(sandbox.config.javaAgentJarPath).toBe('/custom/proxy.jar')
|
||||
expect(sandbox.config.seccomp?.applyPath).toBe('/custom/seccomp')
|
||||
expect(sandbox.config.windows?.srtWin?.path).toBe('C:\\custom\\srt-win.exe')
|
||||
} finally {
|
||||
await sandbox.cleanup()
|
||||
}
|
||||
})
|
||||
})
|
||||
@@ -0,0 +1,59 @@
|
||||
import { createRequire } from 'node:module'
|
||||
import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
|
||||
import { tmpdir } from 'node:os'
|
||||
import path from 'node:path'
|
||||
import {
|
||||
SandboxRuntimeConfigSchema,
|
||||
type SandboxRuntimeConfig,
|
||||
} from '@anthropic-ai/sandbox-runtime'
|
||||
import { bundledSrtVendor } from './srt-vendor'
|
||||
|
||||
/** Load the upstream JSON format and supply the helpers bundled with this CLI. */
|
||||
export async function loadSandbox(configPath: string) {
|
||||
const config = SandboxRuntimeConfigSchema.parse(JSON.parse(await readFile(configPath, 'utf8')))
|
||||
const directory = await mkdtemp(path.join(tmpdir(), 'shumai-srt-'))
|
||||
const cleanup = () => rm(directory, { recursive: true, force: true })
|
||||
const asset = async (name: string) => {
|
||||
const encoded = bundledSrtVendor?.[name]
|
||||
const bytes =
|
||||
encoded !== undefined
|
||||
? Buffer.from(encoded, 'base64')
|
||||
: await readFile(
|
||||
path.join(
|
||||
path.dirname(
|
||||
createRequire(import.meta.url).resolve(
|
||||
'@anthropic-ai/sandbox-runtime/package.json',
|
||||
),
|
||||
),
|
||||
'vendor',
|
||||
name,
|
||||
),
|
||||
)
|
||||
const destination = path.join(directory, path.basename(name))
|
||||
await writeFile(destination, bytes, { mode: 0o500 })
|
||||
return destination
|
||||
}
|
||||
try {
|
||||
if (process.platform === 'linux' && !config.seccomp?.applyPath) {
|
||||
config.seccomp = {
|
||||
...config.seccomp,
|
||||
applyPath: await asset(`seccomp/${process.arch}/apply-seccomp`),
|
||||
}
|
||||
}
|
||||
if (process.platform === 'win32' && !config.windows?.srtWin?.path) {
|
||||
config.windows = {
|
||||
...config.windows,
|
||||
srtWin: {
|
||||
...config.windows?.srtWin,
|
||||
path: await asset(`srt-win/${process.arch}/srt-win.exe`),
|
||||
},
|
||||
}
|
||||
}
|
||||
if (!config.javaAgentJarPath)
|
||||
config.javaAgentJarPath = await asset('java-proxy-agent/srt-proxy-agent.jar')
|
||||
return { config: config satisfies SandboxRuntimeConfig, cleanup }
|
||||
} catch (error) {
|
||||
await cleanup()
|
||||
throw error
|
||||
}
|
||||
}
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@shumai/premiere-uxp",
|
||||
"version": "0.4.8",
|
||||
"version": "0.7.0",
|
||||
"private": true,
|
||||
"type": "commonjs",
|
||||
"scripts": {
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@shumai/transcode-app",
|
||||
"version": "0.4.8",
|
||||
"version": "0.7.0",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"bin": {
|
||||
|
||||
@@ -14,18 +14,85 @@ async function run() {
|
||||
// Initialize workflows and activities
|
||||
initTranscodeWorkflows()
|
||||
|
||||
console.log('🚀 Starting Transcode Worker...')
|
||||
let idleTimeoutMs = process.env.SHUMAI_WORKER_IDLE_TIMEOUT_MS
|
||||
? parseInt(process.env.SHUMAI_WORKER_IDLE_TIMEOUT_MS, 10)
|
||||
: 0
|
||||
|
||||
const options: { workflowBundle?: unknown; workflowsPath?: string } = {}
|
||||
if (process.env.NODE_ENV === 'production') {
|
||||
// @ts-ignore: Bun temporal plugin macro
|
||||
const { default: workflowBundle } = await import('./workflows.ts:::workflow')
|
||||
options.workflowBundle = workflowBundle
|
||||
} else {
|
||||
options.workflowsPath = new URL('./workflows.ts', import.meta.url).pathname
|
||||
const idleTimeoutArg = process.argv.find((arg) => arg.startsWith('--idle-timeout='))
|
||||
if (idleTimeoutArg) {
|
||||
const val = parseInt(idleTimeoutArg.split('=')[1], 10)
|
||||
if (!isNaN(val)) idleTimeoutMs = val
|
||||
}
|
||||
|
||||
await workflowService.startWorkers(TaskQueueTranscode, options)
|
||||
if (idleTimeoutMs > 0) {
|
||||
console.log(
|
||||
`🚀 Starting Transcode Worker with idle timeout (${idleTimeoutMs / 1000}s auto-drain)...`,
|
||||
)
|
||||
} else {
|
||||
console.log('🚀 Starting Transcode Worker (persistent daemon mode)...')
|
||||
}
|
||||
|
||||
await workflowService.startWorkers(TaskQueueTranscode)
|
||||
|
||||
let isShuttingDown = false
|
||||
let idleTimer: Timer | null = null
|
||||
let activeWorkflows = 0
|
||||
|
||||
const shutdown = async () => {
|
||||
if (isShuttingDown) return
|
||||
isShuttingDown = true
|
||||
if (idleTimer) {
|
||||
clearTimeout(idleTimer)
|
||||
idleTimer = null
|
||||
}
|
||||
console.log('Shutting down Transcode Worker gracefully...')
|
||||
try {
|
||||
await workflowService.shutdownWorkers()
|
||||
} catch (err) {
|
||||
console.error('Error during Transcode Worker shutdown:', err)
|
||||
}
|
||||
process.exit(0)
|
||||
}
|
||||
|
||||
if (idleTimeoutMs > 0) {
|
||||
const resetIdleTimer = () => {
|
||||
if (idleTimer) {
|
||||
clearTimeout(idleTimer)
|
||||
idleTimer = null
|
||||
}
|
||||
if (activeWorkflows === 0 && !isShuttingDown) {
|
||||
idleTimer = setTimeout(async () => {
|
||||
console.log(
|
||||
`[Transcode Worker] Inactive for ${idleTimeoutMs / 1000}s with no active workflows, shutting down.`,
|
||||
)
|
||||
await shutdown()
|
||||
}, idleTimeoutMs)
|
||||
}
|
||||
}
|
||||
|
||||
// Start idle timer immediately on startup in case no tasks are enqueued
|
||||
resetIdleTimer()
|
||||
|
||||
workflowService.getExecutor().on('workflowStarted', (task) => {
|
||||
activeWorkflows++
|
||||
console.log(
|
||||
`[Transcode Worker] Claimed task ${task.id} (active: ${activeWorkflows}), cancelling idle timer.`,
|
||||
)
|
||||
if (idleTimer) {
|
||||
clearTimeout(idleTimer)
|
||||
idleTimer = null
|
||||
}
|
||||
})
|
||||
|
||||
workflowService.getExecutor().on('workflowFinished', async ({ taskId }) => {
|
||||
activeWorkflows = Math.max(0, activeWorkflows - 1)
|
||||
console.log(`[Transcode Worker] Completed task ${taskId} (active: ${activeWorkflows}).`)
|
||||
resetIdleTimer()
|
||||
})
|
||||
}
|
||||
|
||||
process.on('SIGINT', shutdown)
|
||||
process.on('SIGTERM', shutdown)
|
||||
}
|
||||
|
||||
handleDaemonCommands('shumai-transcode', run).catch((err) => {
|
||||
|
||||
@@ -1 +0,0 @@
|
||||
export * from '@shumai/transcode/src/workflows/transcode'
|
||||
@@ -66,6 +66,8 @@ apps/web/e2e/
|
||||
| Owner removes a member via the members dialog; the membership is deleted from the DB | `tests/team/remove-member.spec.ts` |
|
||||
| Owner changes a team member role in the members dialog and permissions update | `tests/team/change-member-role.spec.ts` |
|
||||
| Owner manages resource quotas in settings and resets usage from the dashboard | `tests/team/quotas-settings.spec.ts` |
|
||||
| Owner creates an API token that is shown once, listed by hint, and authenticates API calls | `tests/team/api-tokens.spec.ts` |
|
||||
| Session logs stay within the dialog and scroll through long messages and expanded records on desktop and narrow screens | `tests/team/agent-session-logs.spec.ts` |
|
||||
|
||||
### project
|
||||
| Test | File |
|
||||
@@ -89,6 +91,7 @@ apps/web/e2e/
|
||||
| Owner removes version from 2-version stack which dissolves into standalone files | `tests/project/version-stack-manage.spec.ts` |
|
||||
| Dissolving a shared version stack renders the remaining standalone file name on the share page | `tests/project/version-stack-manage.spec.ts` |
|
||||
| Moving a shared file into a shared version stack leaves only 1 stack card on the share page | `tests/project/version-stack-manage.spec.ts` |
|
||||
| Manage versions dialog constrains card width and truncates long file names without dialog overflow | `tests/project/version-stack-manage.spec.ts` |
|
||||
| Owner searches the file list by an English name keyword | `tests/project/search-file-list.spec.ts` |
|
||||
| Owner searches the file list by Chinese, Japanese, and Korean name keywords | `tests/project/search-file-list.spec.ts` |
|
||||
| Owner searches the file list with a keyword and a filter condition | `tests/project/search-file-list.spec.ts` |
|
||||
@@ -96,6 +99,8 @@ apps/web/e2e/
|
||||
| Image share with watermark + download disabled: no download buttons on public list/detail pages, watermarked proxy served, download-url rejected | `tests/project/share-watermark-no-download.spec.ts` |
|
||||
| Video share with watermark + download disabled: no download buttons on public list/detail pages, watermarked proxy served, download-url rejected | `tests/project/share-watermark-no-download.spec.ts` |
|
||||
| Owner views a file and it appears in recents | `tests/project/recents.spec.ts` |
|
||||
| Owner archives a file to archive storage and restores it back to main storage | `tests/project/archive-restore.spec.ts` |
|
||||
| Owner opens Copy submenu in context menu and copies file name | `tests/project/copy-menu.spec.ts` |
|
||||
|
||||
### file
|
||||
| Test | File |
|
||||
|
||||
@@ -10,12 +10,16 @@ export default async function globalTeardown() {
|
||||
if (fs.existsSync(envPath)) {
|
||||
const content = fs.readFileSync(envPath, 'utf8')
|
||||
let bucketName: string | undefined
|
||||
let archiveRoot: string | undefined
|
||||
|
||||
content.split('\n').forEach((line) => {
|
||||
const parts = line.split('=')
|
||||
if (parts.length >= 2 && parts[0].trim() === 'S3_BUCKET') {
|
||||
bucketName = parts.slice(1).join('=').trim()
|
||||
}
|
||||
if (parts.length >= 2 && parts[0].trim() === 'ARCHIVE_LOCAL_ROOT') {
|
||||
archiveRoot = parts.slice(1).join('=').trim()
|
||||
}
|
||||
})
|
||||
|
||||
if (bucketName) {
|
||||
@@ -26,6 +30,11 @@ export default async function globalTeardown() {
|
||||
}
|
||||
}
|
||||
|
||||
if (archiveRoot && fs.existsSync(archiveRoot)) {
|
||||
console.log(`Cleaning up E2E archive storage root: ${archiveRoot}`)
|
||||
fs.rmSync(archiveRoot, { recursive: true, force: true })
|
||||
}
|
||||
|
||||
// Delete the temp .env.e2e file
|
||||
fs.unlinkSync(envPath)
|
||||
}
|
||||
|
||||
+10
-3
@@ -13,17 +13,24 @@ async function start() {
|
||||
// Generate a random S3 bucket name
|
||||
const randomSuffix = randomBytes(4).toString('hex')
|
||||
const bucketName = `shumai-e2e-${randomSuffix}`
|
||||
const archiveRoot = path.resolve('data', `shumai-e2e-archive-${randomSuffix}`)
|
||||
|
||||
process.env.S3_BUCKET = bucketName
|
||||
process.env.ARCHIVE_STORAGE_BACKEND = 'local'
|
||||
process.env.ARCHIVE_LOCAL_ROOT = archiveRoot
|
||||
process.env.SHUMAI_SERVER_PORT = '5200'
|
||||
process.env.BETTER_AUTH_URL = 'http://localhost:5200'
|
||||
process.env.NODE_ENV = 'development'
|
||||
process.env.SHUMAI_E2E = 'true'
|
||||
process.env.ENABLE_EMBEDDING_AGENT = 'false'
|
||||
|
||||
// Write variables to .env.e2e file so the teardown can load them
|
||||
const envContent = [`DATABASE_URL=${process.env.DATABASE_URL}`, `S3_BUCKET=${bucketName}`].join(
|
||||
'\n',
|
||||
)
|
||||
const envContent = [
|
||||
`DATABASE_URL=${process.env.DATABASE_URL}`,
|
||||
`S3_BUCKET=${bucketName}`,
|
||||
`ARCHIVE_STORAGE_BACKEND=local`,
|
||||
`ARCHIVE_LOCAL_ROOT=${archiveRoot}`,
|
||||
].join('\n')
|
||||
|
||||
fs.writeFileSync(path.resolve(currentDir, '.env.e2e'), envContent)
|
||||
console.log(`E2E env file written. Starting Web App...`)
|
||||
|
||||
@@ -0,0 +1,65 @@
|
||||
import { expect, test } from '../../fixtures'
|
||||
import { fileCard } from '../../helpers/files'
|
||||
|
||||
test('owner archives a file to archive storage and restores it back to main storage', async ({
|
||||
file,
|
||||
prisma,
|
||||
}) => {
|
||||
const { page, projectId, fileName, fileId } = file
|
||||
|
||||
await page.goto(`/projects/${projectId}`)
|
||||
const card = fileCard(page, fileName)
|
||||
await expect(card).toBeVisible()
|
||||
|
||||
// 1. Archive via context menu + confirmation dialog
|
||||
await card.click({ button: 'right' })
|
||||
await page.getByTestId('context-menu-archive').click()
|
||||
|
||||
const confirmDialog = page.getByTestId('archive-confirm-dialog')
|
||||
await expect(confirmDialog).toBeVisible()
|
||||
await page.getByTestId('archive-confirm-submit').click()
|
||||
|
||||
// Wait for the DBOS archive workflow to finish and the card badge to settle to Archived
|
||||
await expect(card.getByTestId('file-card-archived-badge')).toBeVisible({ timeout: 15000 })
|
||||
|
||||
const archivedAsset = await prisma.asset.findUniqueOrThrow({
|
||||
where: { id: fileId },
|
||||
include: { storageKey: true },
|
||||
})
|
||||
expect(archivedAsset.status).toBe('archived')
|
||||
expect(archivedAsset.storageKey?.isArchived).toBe(true)
|
||||
|
||||
// 2. Open detail page and verify Archived header badge + disabled original download button
|
||||
await card.dblclick()
|
||||
await expect(page.getByTestId('detail-header-archived-badge')).toBeVisible()
|
||||
await expect(page.getByTestId('default-viewer-download-button')).toBeDisabled()
|
||||
|
||||
// 3. Return to project file list and restore from archive
|
||||
await page.goto(`/projects/${projectId}`)
|
||||
await expect(card.getByTestId('file-card-archived-badge')).toBeVisible()
|
||||
|
||||
await card.click({ button: 'right' })
|
||||
await page.getByTestId('context-menu-restore-archive').click()
|
||||
|
||||
await expect(confirmDialog).toBeVisible()
|
||||
await page.getByTestId('archive-confirm-submit').click()
|
||||
|
||||
// Wait for the DBOS restore workflow to finish and the Archived badge to disappear
|
||||
await expect(card.getByTestId('file-card-archived-badge')).not.toBeVisible({ timeout: 15000 })
|
||||
|
||||
await expect
|
||||
.poll(
|
||||
async () => {
|
||||
const restored = await prisma.asset.findUnique({
|
||||
where: { id: fileId },
|
||||
include: { storageKey: true },
|
||||
})
|
||||
return {
|
||||
status: restored?.status,
|
||||
isArchived: restored?.storageKey?.isArchived,
|
||||
}
|
||||
},
|
||||
{ timeout: 10000 },
|
||||
)
|
||||
.toEqual({ status: 'processed', isArchived: false })
|
||||
})
|
||||
@@ -0,0 +1,43 @@
|
||||
import { expect, test } from '../../fixtures'
|
||||
import { fileCard } from '../../helpers/files'
|
||||
|
||||
test('owner sees Copy submenu in context menu and copies file name', async ({
|
||||
file,
|
||||
browserName,
|
||||
}) => {
|
||||
const { page, projectId, fileName } = file
|
||||
|
||||
if (browserName === 'chromium') {
|
||||
await page.context().grantPermissions(['clipboard-read', 'clipboard-write'])
|
||||
}
|
||||
await page.goto(`/projects/${projectId}`)
|
||||
await expect(fileCard(page, fileName)).toBeVisible()
|
||||
|
||||
// Right-click context menu
|
||||
await fileCard(page, fileName).click({ button: 'right' })
|
||||
const copySubTrigger = page.getByRole('menuitem', { name: /^Copy$|^复制$/i })
|
||||
await expect(copySubTrigger).toBeVisible()
|
||||
await copySubTrigger.click()
|
||||
|
||||
// Verify submenu items are visible
|
||||
await expect(page.getByRole('menuitem', { name: /^Name$|^名称$/i })).toBeVisible()
|
||||
await expect(page.getByRole('menuitem', { name: /^Link$|^链接$/i })).toBeVisible()
|
||||
await expect(page.getByRole('menuitem', { name: /^Download link$|^下载链接$/i })).toBeVisible()
|
||||
await expect(page.getByRole('menuitem', { name: /^ID$/i })).toBeVisible()
|
||||
await expect(
|
||||
page.getByRole('menuitem', { name: /^Markdown link$|^Markdown 链接$/i }),
|
||||
).toBeVisible()
|
||||
await expect(page.getByRole('menuitem', { name: /^Storage path$|^存储路径$/i })).toBeVisible()
|
||||
|
||||
// Click "Name"
|
||||
await page.getByRole('menuitem', { name: /^Name$|^名称$/i }).click()
|
||||
const toast = page.locator('[data-sonner-toast]').filter({
|
||||
hasText: /Copied name to clipboard|已复制名称到剪贴板/i,
|
||||
})
|
||||
await expect(toast).toBeVisible()
|
||||
|
||||
if (browserName === 'chromium') {
|
||||
const clipboardText = await page.evaluate(() => navigator.clipboard.readText())
|
||||
expect(clipboardText).toBe(fileName)
|
||||
}
|
||||
})
|
||||
@@ -231,3 +231,76 @@ test('moving a shared file into a shared version stack leaves only 1 stack card
|
||||
const updatedShareRoot = await prisma.asset.findUnique({ where: { id: share.rootFolderId } })
|
||||
expect(updatedShareRoot?.fileCount).toBe(1)
|
||||
})
|
||||
|
||||
test('manage versions dialog constrains card width and truncates long file names without dialog overflow', async ({
|
||||
project,
|
||||
prisma,
|
||||
}) => {
|
||||
const { page, projectId, rootFolderId } = project
|
||||
|
||||
const longName =
|
||||
'super-extremely-long-asset-name-for-testing-manage-versions-dialog-card-overflow-issue-that-keeps-expanding-without-truncating-properly.mp4'
|
||||
const fileA = await seedFile(prisma, projectId, rootFolderId, longName)
|
||||
const fileB = await seedFile(prisma, projectId, rootFolderId, `short-${Date.now()}.mp4`)
|
||||
|
||||
await page.goto(`/projects/${projectId}`)
|
||||
await expect(fileCard(page, fileA.name)).toBeVisible()
|
||||
await expect(fileCard(page, fileB.name)).toBeVisible()
|
||||
|
||||
// Create version stack: drag B on A
|
||||
await dragCard(page, fileCard(page, fileB.name), fileCard(page, fileA.name))
|
||||
await expect(page.getByText('v2', { exact: true })).toBeVisible()
|
||||
|
||||
const stack = await prisma.asset.findFirstOrThrow({
|
||||
where: { projectId, parentId: rootFolderId, type: 'version_stack' },
|
||||
})
|
||||
|
||||
// Navigate to file viewer for the stack
|
||||
await page.goto(`/projects/${projectId}/files/${stack.id}`)
|
||||
|
||||
// Open breadcrumb menu and click "Manage versions..."
|
||||
await page.getByRole('button', { name: new RegExp(fileB.name) }).click()
|
||||
await page.getByRole('menuitem', { name: 'Versions', exact: true }).hover()
|
||||
await page.getByRole('button', { name: /manage versions$/i }).click()
|
||||
|
||||
const dialog = page.getByRole('dialog')
|
||||
await expect(dialog).toBeVisible()
|
||||
|
||||
const rowA = dialog.locator('div.group', { hasText: longName })
|
||||
await expect(rowA).toBeVisible()
|
||||
|
||||
// Measure the dialog and version row
|
||||
const metrics = await page.evaluate(() => {
|
||||
const dialogEl = document.querySelector('[role="dialog"]') as HTMLElement | null
|
||||
if (!dialogEl) return null
|
||||
const row = dialogEl.querySelector('div.group') as HTMLElement | null
|
||||
return {
|
||||
dialogScrollWidth: dialogEl.scrollWidth,
|
||||
dialogClientWidth: dialogEl.clientWidth,
|
||||
dialogOffsetWidth: dialogEl.offsetWidth,
|
||||
rowScrollWidth: row?.scrollWidth,
|
||||
rowClientWidth: row?.clientWidth,
|
||||
}
|
||||
})
|
||||
|
||||
expect(metrics).not.toBeNull()
|
||||
// Dialog should not horizontally scroll or overflow
|
||||
expect(metrics!.dialogScrollWidth).toBeLessThanOrEqual(metrics!.dialogClientWidth)
|
||||
// Row clientWidth should be bounded within the dialog
|
||||
expect(metrics!.rowClientWidth).toBeLessThanOrEqual(metrics!.dialogClientWidth)
|
||||
expect(metrics!.rowScrollWidth).toBeLessThanOrEqual(metrics!.rowClientWidth!)
|
||||
|
||||
// Hover over the row and verify the more-options button is visible and within bounds
|
||||
await rowA.hover()
|
||||
const moreButton = rowA.getByRole('button', { name: 'More options' })
|
||||
await expect(moreButton).toBeVisible()
|
||||
const moreBtnBox = await moreButton.boundingBox()
|
||||
const dialogBox = await dialog.boundingBox()
|
||||
expect(moreBtnBox).not.toBeNull()
|
||||
expect(dialogBox).not.toBeNull()
|
||||
expect(moreBtnBox!.x + moreBtnBox!.width).toBeLessThanOrEqual(dialogBox!.x + dialogBox!.width)
|
||||
|
||||
// Click more options button and verify menu opens
|
||||
await moreButton.click()
|
||||
await expect(page.getByRole('menuitem', { name: /remove from stack/i })).toBeVisible()
|
||||
})
|
||||
|
||||
@@ -0,0 +1,125 @@
|
||||
import { expect, test } from '../../fixtures'
|
||||
|
||||
test('session logs stay within the dialog and scroll through long messages and expanded records', async ({
|
||||
owner,
|
||||
prisma,
|
||||
}) => {
|
||||
const { page, teamId, email } = owner
|
||||
const user = await prisma.user.findUniqueOrThrow({ where: { email } })
|
||||
const agentUser = await prisma.user.create({
|
||||
data: { name: 'Session Logs Agent', email: 'session-logs@shumai.test', type: 'agent' },
|
||||
})
|
||||
const agent = await prisma.agent.create({
|
||||
data: {
|
||||
id: agentUser.id,
|
||||
teamId,
|
||||
type: 'chat',
|
||||
enabled: false,
|
||||
config: { provider: 'test', model: 'test' },
|
||||
},
|
||||
})
|
||||
const session = await prisma.agentSession.create({
|
||||
data: {
|
||||
agentId: agent.id,
|
||||
userId: user.id,
|
||||
type: 'chat',
|
||||
name: 'Scrollable Session Logs',
|
||||
cwd: '/test',
|
||||
},
|
||||
})
|
||||
await prisma.agentSessionCommit.create({
|
||||
data: {
|
||||
sessionId: session.id,
|
||||
seq: 1n,
|
||||
data: {
|
||||
version: 1,
|
||||
writes: [
|
||||
{ type: 'conversation', value: { id: 1 } },
|
||||
...Array.from({ length: 30 }, (_, index) => ({
|
||||
type: 'entry',
|
||||
value: {
|
||||
id: index + 2,
|
||||
conversationId: 1,
|
||||
kind: 'pi.user',
|
||||
model: [
|
||||
{
|
||||
role: 'user',
|
||||
content: `Log message ${index + 1}\n\n\`\`\`text\n${'unbroken_output_'.repeat(100)}\n\`\`\``,
|
||||
timestamp: Date.now(),
|
||||
},
|
||||
],
|
||||
data: { output: 'raw_output_'.repeat(100) },
|
||||
},
|
||||
})),
|
||||
],
|
||||
},
|
||||
},
|
||||
})
|
||||
|
||||
await page.goto(`/teams/${teamId}/dashboard`)
|
||||
await page.getByRole('button', { name: /^(Sessions|会话)$/ }).click()
|
||||
await page.getByRole('row').filter({ hasText: session.name! }).click()
|
||||
const dialog = page.getByRole('dialog')
|
||||
await expect(dialog.getByText('Log message 1', { exact: true })).toBeVisible()
|
||||
await expect(dialog.getByText(/^(Entry ID|条目 ID):/)).toHaveCount(0)
|
||||
const viewport = dialog.locator('[data-slot="scroll-area-viewport"]')
|
||||
const heading = dialog.getByRole('heading')
|
||||
|
||||
for (const size of [
|
||||
{ width: 1280, height: 800 },
|
||||
{ width: 390, height: 640 },
|
||||
]) {
|
||||
await page.setViewportSize(size)
|
||||
await dialog.evaluate(async (element) => {
|
||||
await Promise.all(element.getAnimations().map((animation) => animation.finished))
|
||||
})
|
||||
await expect
|
||||
.poll(async () => {
|
||||
return dialog.evaluate((element) => {
|
||||
const bounds = element.getBoundingClientRect()
|
||||
return (
|
||||
bounds.top >= 0 &&
|
||||
bounds.bottom <= window.innerHeight &&
|
||||
bounds.left >= 0 &&
|
||||
bounds.right <= window.innerWidth
|
||||
)
|
||||
})
|
||||
})
|
||||
.toBe(true)
|
||||
await expect
|
||||
.poll(() =>
|
||||
viewport.evaluate(
|
||||
(element) =>
|
||||
element.clientHeight > 0 &&
|
||||
element.scrollHeight > element.clientHeight &&
|
||||
element.scrollWidth <= element.clientWidth,
|
||||
),
|
||||
)
|
||||
.toBe(true)
|
||||
const headerTop = (await heading.boundingBox())!.y
|
||||
await viewport.evaluate((element) => {
|
||||
element.scrollTop = 0
|
||||
})
|
||||
await viewport.hover()
|
||||
// Wheel events may be capped; verify movement before jumping to the final record.
|
||||
await page.mouse.wheel(0, 400)
|
||||
await expect.poll(() => viewport.evaluate((element) => element.scrollTop)).toBeGreaterThan(0)
|
||||
const record = dialog.locator('details').last()
|
||||
await viewport.evaluate((element) => {
|
||||
element.scrollTop = element.scrollHeight
|
||||
})
|
||||
await expect(record.locator('summary')).toBeInViewport()
|
||||
expect((await heading.boundingBox())!.y).toBeCloseTo(headerTop, 0)
|
||||
|
||||
await record.locator('summary').click()
|
||||
await viewport.evaluate((element) => {
|
||||
element.scrollTop = element.scrollHeight
|
||||
})
|
||||
await expect(record.locator('pre')).toBeInViewport()
|
||||
await expect(record.locator('pre')).toContainText('"id": 31')
|
||||
expect(await viewport.evaluate((element) => element.scrollWidth <= element.clientWidth)).toBe(
|
||||
true,
|
||||
)
|
||||
await record.locator('summary').click()
|
||||
}
|
||||
})
|
||||
@@ -0,0 +1,61 @@
|
||||
import { createHash } from 'node:crypto'
|
||||
import { expect, test } from '../../fixtures'
|
||||
import { E2E_APP_URL } from '../../helpers/auth'
|
||||
|
||||
test('owner creates an API token that is shown once, listed by hint, and authenticates API calls', async ({
|
||||
owner,
|
||||
prisma,
|
||||
playwright,
|
||||
}) => {
|
||||
const { page, teamId } = owner
|
||||
|
||||
// 1. Open the API Tokens settings tab
|
||||
await page.goto(`/teams/${teamId}/settings`)
|
||||
await page.getByRole('button', { name: /^(API Tokens|API 令牌)$/i }).click()
|
||||
await expect(page.getByText(/No API tokens found|未找到 API 令牌/i)).toBeVisible()
|
||||
|
||||
// 2. Generate a token
|
||||
await page.fill('#tokenName', 'e2e-cli')
|
||||
await page.getByRole('button', { name: /^(Generate|生成)$/i }).click()
|
||||
|
||||
// 3. The plaintext is shown once in a dialog
|
||||
const dialog = page.getByRole('dialog')
|
||||
await expect(dialog.getByText(/Save your API token|保存您的 API 令牌/i)).toBeVisible()
|
||||
const tokenInput = dialog.getByRole('textbox')
|
||||
await expect(tokenInput).toHaveValue(/^shumai_[A-Za-z0-9_-]{43}$/)
|
||||
const token = await tokenInput.inputValue()
|
||||
|
||||
await dialog.getByRole('button', { name: /^(Done|完成)$/i }).click()
|
||||
await expect(dialog).toBeHidden()
|
||||
|
||||
// 4. The list identifies the token by name and hint only
|
||||
const hint = token.slice(-4)
|
||||
const row = page.getByRole('row', { name: /e2e-cli/ })
|
||||
await expect(row).toBeVisible()
|
||||
await expect(row.getByText(`…${hint}`)).toBeVisible()
|
||||
await expect(page.getByText(token)).toHaveCount(0)
|
||||
|
||||
// 5. Only the hash is stored
|
||||
const stored = await prisma.apiToken.findFirstOrThrow({ where: { name: 'e2e-cli' } })
|
||||
expect(stored.tokenHash).toBe(createHash('sha256').update(token, 'utf8').digest('hex'))
|
||||
expect(stored.tokenHint).toBe(hint)
|
||||
|
||||
// 6. The token authenticates a request that carries no session cookie
|
||||
const tokenClient = await playwright.request.newContext({
|
||||
// eslint-disable-next-line @typescript-eslint/naming-convention
|
||||
baseURL: E2E_APP_URL,
|
||||
})
|
||||
try {
|
||||
const ok = await tokenClient.get('/api/projects', {
|
||||
headers: { Authorization: `Bearer ${token}` },
|
||||
})
|
||||
expect(ok.status()).toBe(200)
|
||||
|
||||
const rejected = await tokenClient.get('/api/projects', {
|
||||
headers: { Authorization: `Bearer ${stored.tokenHash}` },
|
||||
})
|
||||
expect(rejected.status()).toBe(401)
|
||||
} finally {
|
||||
await tokenClient.dispose()
|
||||
}
|
||||
})
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@shumai/web-app",
|
||||
"version": "0.4.8",
|
||||
"version": "0.7.0",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"dependencies": {
|
||||
|
||||
+94
-43
@@ -5,17 +5,24 @@ loadEnvConfig(process.cwd(), process.env.NODE_ENV !== 'production')
|
||||
|
||||
import index from '@shumai/webui/index.html'
|
||||
|
||||
import { initAgentWorkflows } from '@shumai/agent'
|
||||
import { app } from '@shumai/api'
|
||||
import { closeAgentSessions, initAgentWorkflows } from '@shumai/agent'
|
||||
import { app, runnerWebsocket } from '@shumai/api'
|
||||
import { agentService } from '@shumai/core/src/agent/agent'
|
||||
import { migrateLegacyAgentAvatars } from '@shumai/core/src/agent/migration'
|
||||
import { assetService } from '@shumai/core/src/asset/asset'
|
||||
import { metadataService } from '@shumai/core/src/metadata/metadata'
|
||||
import { validateArchiveStorageConfig } from '@shumai/core/src/s3/archive-storage'
|
||||
import { initTranscodeWorkflows } from '@shumai/transcode'
|
||||
import { workflowService } from '@shumai/workflow-core'
|
||||
import { migrateLegacyAgentAvatars } from '@shumai/core/src/agent/migration'
|
||||
|
||||
import { handleDaemonCommands } from '@shumai/core/src/utils/daemon'
|
||||
import { runnerService } from '@shumai/core'
|
||||
import { autoArchiveJobService } from '@shumai/core/src/asset/auto-archive-job'
|
||||
import { authService } from '@shumai/core/src/auth/auth'
|
||||
import { sandboxService } from '@shumai/core'
|
||||
import { notificationJobService } from '@shumai/core/src/notification/notification-job'
|
||||
import { embeddingService } from '@shumai/core/src/search/embedding-service'
|
||||
import { handleDaemonCommands } from '@shumai/core/src/utils/daemon'
|
||||
import { createHtmlHandler, createStaticFileHandler } from './static'
|
||||
import { getServerQueues } from './workers'
|
||||
|
||||
if (process.argv.includes('--check')) {
|
||||
console.log('✅ Web app evaluated successfully!')
|
||||
@@ -46,42 +53,69 @@ if (resetCmdIndex !== -1) {
|
||||
}
|
||||
}
|
||||
|
||||
const regenCmdIndex = cliArgs.findIndex((arg) => arg === 'regenerate-embeddings')
|
||||
|
||||
if (regenCmdIndex !== -1) {
|
||||
try {
|
||||
initAgentWorkflows()
|
||||
initTranscodeWorkflows()
|
||||
console.log('🔄 Regenerating embeddings...')
|
||||
const result = await embeddingService.regenerateEmbeddings()
|
||||
await workflowService.waitForPendingSubmissions()
|
||||
console.log(
|
||||
`✅ Successfully queued ${result.tasksCreated} embedding tasks for ${result.totalAssets} assets.`,
|
||||
)
|
||||
if (result.skippedTeams.length > 0) {
|
||||
console.warn(
|
||||
`⚠️ Skipped ${result.skippedTeams.length} team(s) without an active embedding agent.`,
|
||||
)
|
||||
}
|
||||
console.log('The background workers will process the embedding tasks.')
|
||||
process.exit(0)
|
||||
} catch (err: unknown) {
|
||||
const message = err instanceof Error ? err.message : 'Unknown error'
|
||||
console.error(`Error: ${message}`)
|
||||
process.exit(1)
|
||||
}
|
||||
}
|
||||
|
||||
async function run() {
|
||||
validateArchiveStorageConfig()
|
||||
const runnerLease = await runnerService.startServerTopology()
|
||||
runnerLease.addEventListener(
|
||||
'abort',
|
||||
() => {
|
||||
console.error('Lost the runner server lease:', runnerLease.reason)
|
||||
process.exit(1)
|
||||
},
|
||||
{ once: true },
|
||||
)
|
||||
runnerLease.throwIfAborted()
|
||||
// Initialize workflows and activities for local executor mode
|
||||
initAgentWorkflows()
|
||||
initTranscodeWorkflows()
|
||||
await sandboxService.ensureInitialized().catch((err) => {
|
||||
console.error('Failed to eagerly initialize sandbox in web app:', err)
|
||||
})
|
||||
runnerService.startHeartbeatMonitor()
|
||||
|
||||
// Start services
|
||||
await metadataService.syncSystemFields().catch(console.error)
|
||||
await migrateLegacyAgentAvatars().catch(console.error)
|
||||
await agentService.ensureSystemEmbeddingAgents().catch(console.error)
|
||||
assetService.startCleanupJob()
|
||||
workflowService.start()
|
||||
if (process.env.WORKFLOW_EXECUTOR === 'temporal') {
|
||||
const args = process.argv.slice(2)
|
||||
let workersOption = ''
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
if (args[i] === '--workers') {
|
||||
workersOption = args[i + 1] || ''
|
||||
} else if (args[i].startsWith('--workers=')) {
|
||||
workersOption = args[i].split('=')[1]
|
||||
}
|
||||
notificationJobService.start()
|
||||
autoArchiveJobService.start()
|
||||
const args = process.argv.slice(2)
|
||||
let workersOption = process.env.SHUMAI_WORKERS || 'all'
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
if (args[i] === '--workers') {
|
||||
workersOption = args[i + 1] || workersOption
|
||||
} else if (args[i].startsWith('--workers=')) {
|
||||
workersOption = args[i].split('=')[1] || workersOption
|
||||
}
|
||||
|
||||
const queuesToStart: string[] = []
|
||||
if (workersOption === 'agent' || workersOption === 'ai') {
|
||||
queuesToStart.push('agent_queue')
|
||||
} else if (workersOption === 'transcode') {
|
||||
queuesToStart.push('transcode_queue')
|
||||
} else if (workersOption === 'all') {
|
||||
queuesToStart.push('agent_queue', 'transcode_queue')
|
||||
}
|
||||
|
||||
Promise.all(queuesToStart.map((q) => workflowService.startWorkers(q))).catch(console.error)
|
||||
}
|
||||
|
||||
workflowService.start(getServerQueues(workersOption))
|
||||
workflowService.startStaleTaskRecovery()
|
||||
|
||||
const isProd = process.env.NODE_ENV === 'production'
|
||||
|
||||
const port = process.env.SHUMAI_SERVER_PORT ? parseInt(process.env.SHUMAI_SERVER_PORT) : 3000
|
||||
@@ -105,6 +139,9 @@ async function run() {
|
||||
const routes: Record<string, any> = {
|
||||
'/api/*': app.fetch,
|
||||
'/files/*': app.fetch,
|
||||
'/.well-known/*': app.fetch,
|
||||
// Shumai's MCP server; without this entry the SPA catch-all (`/*`) would serve it HTML.
|
||||
'/mcp': app.fetch,
|
||||
}
|
||||
|
||||
if (isProd) {
|
||||
@@ -113,7 +150,8 @@ async function run() {
|
||||
for (const file of bundle.files) {
|
||||
const routePath = file.path.startsWith('.') ? file.path.slice(1) : file.path
|
||||
const filePath = join(import.meta.dir, file.path)
|
||||
routes[routePath] = () => new Response(Bun.file(filePath), { headers: file.headers })
|
||||
const isHtml = file.loader === 'html' || file.path.endsWith('.html')
|
||||
routes[routePath] = createStaticFileHandler(filePath, file.headers, !isHtml)
|
||||
}
|
||||
|
||||
const sampleFile = bundle.files[0]?.path || bundle.index || ''
|
||||
@@ -125,13 +163,14 @@ async function run() {
|
||||
const routePath = '/' + pdfWorkerFile
|
||||
const filePath = join(bundleDir, pdfWorkerFile)
|
||||
const bunFile = Bun.file(filePath)
|
||||
routes[routePath] = () =>
|
||||
new Response(bunFile, {
|
||||
headers: {
|
||||
'content-type': 'text/javascript;charset=utf-8',
|
||||
etag: `"${bunFile.size}-${bunFile.lastModified}"`,
|
||||
},
|
||||
})
|
||||
routes[routePath] = createStaticFileHandler(
|
||||
filePath,
|
||||
{
|
||||
'content-type': 'text/javascript;charset=utf-8',
|
||||
etag: `"${bunFile.size}-${bunFile.lastModified}"`,
|
||||
},
|
||||
true,
|
||||
)
|
||||
}
|
||||
} catch (err) {
|
||||
console.warn('Failed to register pdf.worker route:', err)
|
||||
@@ -147,16 +186,22 @@ async function run() {
|
||||
.replaceAll('href="./', 'href="/')
|
||||
.replaceAll('src="./', 'src="/')
|
||||
.replaceAll('content="./', 'content="/')
|
||||
const serveMainHtml = () => new Response(mainHtmlText, { headers: mainHtmlHeaders })
|
||||
const serveMainHtml = createHtmlHandler(mainHtmlText, mainHtmlHeaders)
|
||||
|
||||
routes['/'] = serveMainHtml
|
||||
routes['/*'] = serveMainHtml
|
||||
} else {
|
||||
const fallbackHtmlPath = join(import.meta.dir, 'shumai-app.html')
|
||||
const serveFallbackHtml = () =>
|
||||
new Response(Bun.file(fallbackHtmlPath), {
|
||||
headers: { 'content-type': 'text/html;charset=utf-8' },
|
||||
})
|
||||
const fallbackHtmlFile = Bun.file(fallbackHtmlPath)
|
||||
if (!(await fallbackHtmlFile.exists())) {
|
||||
throw new Error(
|
||||
`Production HTML bundle is missing: neither bundle.files nor ${fallbackHtmlPath} exists.`,
|
||||
)
|
||||
}
|
||||
const fallbackRaw = await fallbackHtmlFile.text()
|
||||
const serveFallbackHtml = createHtmlHandler(fallbackRaw, {
|
||||
'content-type': 'text/html;charset=utf-8',
|
||||
})
|
||||
routes['/'] = serveFallbackHtml
|
||||
routes['/*'] = serveFallbackHtml
|
||||
}
|
||||
@@ -173,15 +218,21 @@ async function run() {
|
||||
: 1024 * 1024 * 1024 * 20, // Default 20GB
|
||||
development: !isProd,
|
||||
fetch: app.fetch,
|
||||
websocket: runnerWebsocket,
|
||||
routes,
|
||||
})
|
||||
|
||||
console.log(`🚀 Server running at ${server.url}`)
|
||||
|
||||
const shutdown = () => {
|
||||
const shutdown = async () => {
|
||||
console.log('\nShutting down gracefully...')
|
||||
workflowService.stopStaleTaskRecovery()
|
||||
runnerService.stopHeartbeatMonitor()
|
||||
await closeAgentSessions()
|
||||
await workflowService.shutdownWorkers().catch(() => {})
|
||||
assetService.stopCleanupJob()
|
||||
server.stop(true)
|
||||
await runnerService.stopServerTopology().catch(console.error)
|
||||
process.exit(0)
|
||||
}
|
||||
|
||||
|
||||
@@ -0,0 +1,175 @@
|
||||
import { afterAll, beforeAll, describe, expect, it } from 'vitest'
|
||||
import { writeFileSync, unlinkSync } from 'node:fs'
|
||||
import { join } from 'node:path'
|
||||
import { tmpdir } from 'node:os'
|
||||
import { createHtmlHandler, createStaticFileHandler, isEtagMatching, normalizeEtag } from './static'
|
||||
|
||||
describe('Static Asset Serving & Caching', () => {
|
||||
const tempChunkPath = join(tmpdir(), `test-chunk-${Date.now()}.js`)
|
||||
const chunkContent = 'console.log("chunk loaded");'
|
||||
|
||||
beforeAll(() => {
|
||||
writeFileSync(tempChunkPath, chunkContent, 'utf8')
|
||||
})
|
||||
|
||||
afterAll(() => {
|
||||
try {
|
||||
unlinkSync(tempChunkPath)
|
||||
} catch {
|
||||
// Ignore cleanup error if already deleted
|
||||
}
|
||||
})
|
||||
|
||||
describe('normalizeEtag', () => {
|
||||
it('quotes unquoted ETags according to RFC 9110', () => {
|
||||
expect(normalizeEtag('hHRmXFeFVSk')).toBe('"hHRmXFeFVSk"')
|
||||
expect(normalizeEtag('ACJrxcts9Iw')).toBe('"ACJrxcts9Iw"')
|
||||
})
|
||||
|
||||
it('preserves already-quoted strong and weak ETags', () => {
|
||||
expect(normalizeEtag('"hHRmXFeFVSk"')).toBe('"hHRmXFeFVSk"')
|
||||
expect(normalizeEtag('W/"hHRmXFeFVSk"')).toBe('W/"hHRmXFeFVSk"')
|
||||
})
|
||||
|
||||
it('returns undefined for empty or missing ETags', () => {
|
||||
expect(normalizeEtag(undefined)).toBeUndefined()
|
||||
expect(normalizeEtag('')).toBeUndefined()
|
||||
expect(normalizeEtag(' ')).toBeUndefined()
|
||||
})
|
||||
})
|
||||
|
||||
describe('isEtagMatching', () => {
|
||||
it('matches exact etag string', () => {
|
||||
expect(isEtagMatching('"12345"', '"12345"')).toBe(true)
|
||||
})
|
||||
|
||||
it('matches weak etag to strong or weak candidates', () => {
|
||||
expect(isEtagMatching('W/"12345"', '"12345"')).toBe(true)
|
||||
expect(isEtagMatching('"12345"', 'W/"12345"')).toBe(true)
|
||||
expect(isEtagMatching('W/"12345"', 'W/"12345"')).toBe(true)
|
||||
})
|
||||
|
||||
it('matches wildcard *', () => {
|
||||
expect(isEtagMatching('"12345"', '*')).toBe(true)
|
||||
})
|
||||
|
||||
it('matches comma-separated candidate lists', () => {
|
||||
expect(isEtagMatching('"12345"', '"old-etag", "12345", "other"')).toBe(true)
|
||||
expect(isEtagMatching('"12345"', '"old-etag", "mismatch"')).toBe(false)
|
||||
})
|
||||
|
||||
it('returns false when etag or ifNoneMatch is missing or empty', () => {
|
||||
expect(isEtagMatching(undefined, '"12345"')).toBe(false)
|
||||
expect(isEtagMatching('"12345"', null)).toBe(false)
|
||||
expect(isEtagMatching('', '"12345"')).toBe(false)
|
||||
expect(isEtagMatching('"12345"', '')).toBe(false)
|
||||
})
|
||||
})
|
||||
|
||||
describe('createStaticFileHandler', () => {
|
||||
it('sets immutable Cache-Control for immutable content-hashed assets', async () => {
|
||||
const handler = createStaticFileHandler(
|
||||
tempChunkPath,
|
||||
{ 'content-type': 'text/javascript;charset=utf-8', etag: '"chunk-hash-1"' },
|
||||
true,
|
||||
)
|
||||
|
||||
const req = new Request('http://localhost/chunk-123.js')
|
||||
const res = handler(req)
|
||||
|
||||
expect(res.status).toBe(200)
|
||||
expect(res.headers.get('content-type')).toBe('text/javascript;charset=utf-8')
|
||||
expect(res.headers.get('cache-control')).toBe('public, max-age=31536000, immutable')
|
||||
expect(res.headers.get('etag')).toBe('"chunk-hash-1"')
|
||||
expect(await res.text()).toBe(chunkContent)
|
||||
})
|
||||
|
||||
it('returns 304 Not Modified when If-None-Match matches the file etag', async () => {
|
||||
const handler = createStaticFileHandler(
|
||||
tempChunkPath,
|
||||
{ 'content-type': 'text/javascript;charset=utf-8', etag: '"chunk-hash-1"' },
|
||||
true,
|
||||
)
|
||||
|
||||
const req = new Request('http://localhost/chunk-123.js', {
|
||||
headers: { 'if-none-match': '"chunk-hash-1"' },
|
||||
})
|
||||
const res = handler(req)
|
||||
|
||||
expect(res.status).toBe(304)
|
||||
expect(res.headers.get('cache-control')).toBe('public, max-age=31536000, immutable')
|
||||
expect(res.headers.get('etag')).toBe('"chunk-hash-1"')
|
||||
expect(await res.text()).toBe('')
|
||||
})
|
||||
|
||||
it('sets no-cache Cache-Control for non-immutable static assets', async () => {
|
||||
const handler = createStaticFileHandler(
|
||||
tempChunkPath,
|
||||
{ 'content-type': 'text/plain', etag: '"plain-1"' },
|
||||
false,
|
||||
)
|
||||
|
||||
const req = new Request('http://localhost/robots.txt')
|
||||
const res = handler(req)
|
||||
|
||||
expect(res.status).toBe(200)
|
||||
expect(res.headers.get('cache-control')).toBe('no-cache')
|
||||
})
|
||||
|
||||
it('normalizes unquoted manifest ETags to quoted RFC 9110 strings', async () => {
|
||||
const handler = createStaticFileHandler(
|
||||
tempChunkPath,
|
||||
{ 'content-type': 'text/javascript;charset=utf-8', etag: 'hHRmXFeFVSk' },
|
||||
true,
|
||||
)
|
||||
|
||||
const req = new Request('http://localhost/chunk-123.js')
|
||||
const res = handler(req)
|
||||
|
||||
expect(res.status).toBe(200)
|
||||
expect(res.headers.get('etag')).toBe('"hHRmXFeFVSk"')
|
||||
|
||||
const revalidateRes = handler(
|
||||
new Request('http://localhost/chunk-123.js', {
|
||||
headers: { 'if-none-match': '"hHRmXFeFVSk"' },
|
||||
}),
|
||||
)
|
||||
expect(revalidateRes.status).toBe(304)
|
||||
expect(revalidateRes.headers.get('etag')).toBe('"hHRmXFeFVSk"')
|
||||
})
|
||||
})
|
||||
|
||||
describe('createHtmlHandler', () => {
|
||||
const htmlText = '<!DOCTYPE html><html><head><title>Shumai</title></head><body></body></html>'
|
||||
|
||||
it('sets no-cache and generates deterministic ETag for HTML', async () => {
|
||||
const handler = createHtmlHandler(htmlText, { 'content-type': 'text/html;charset=utf-8' })
|
||||
|
||||
const req = new Request('http://localhost/')
|
||||
const res = handler(req)
|
||||
|
||||
expect(res.status).toBe(200)
|
||||
expect(res.headers.get('content-type')).toBe('text/html;charset=utf-8')
|
||||
expect(res.headers.get('cache-control')).toBe('no-cache')
|
||||
const etag = res.headers.get('etag')
|
||||
expect(etag).toBeTruthy()
|
||||
expect(await res.text()).toBe(htmlText)
|
||||
})
|
||||
|
||||
it('returns 304 Not Modified when HTML If-None-Match matches', async () => {
|
||||
const handler = createHtmlHandler(htmlText, { 'content-type': 'text/html;charset=utf-8' })
|
||||
|
||||
const initialRes = handler(new Request('http://localhost/'))
|
||||
const etag = initialRes.headers.get('etag')!
|
||||
|
||||
const revalidateReq = new Request('http://localhost/', {
|
||||
headers: { 'if-none-match': etag },
|
||||
})
|
||||
const revalidateRes = handler(revalidateReq)
|
||||
|
||||
expect(revalidateRes.status).toBe(304)
|
||||
expect(revalidateRes.headers.get('cache-control')).toBe('no-cache')
|
||||
expect(await revalidateRes.text()).toBe('')
|
||||
})
|
||||
})
|
||||
})
|
||||
@@ -0,0 +1,106 @@
|
||||
/**
|
||||
* Helpers for serving static production assets with caching headers and ETag revalidation.
|
||||
*/
|
||||
|
||||
/**
|
||||
* Checks whether an incoming `If-None-Match` header matches the asset's ETag.
|
||||
* Supports weak ETags (`W/"..."`), exact matches, and comma-separated lists.
|
||||
*/
|
||||
export function isEtagMatching(etag: string | undefined, ifNoneMatch: string | null): boolean {
|
||||
if (!etag || !ifNoneMatch) {
|
||||
return false
|
||||
}
|
||||
|
||||
const cleanTarget = etag.trim().replace(/^W\//, '').replace(/^"|"$/g, '')
|
||||
if (!cleanTarget) {
|
||||
return false
|
||||
}
|
||||
|
||||
const candidates = ifNoneMatch
|
||||
.split(',')
|
||||
.map((candidate) => candidate.trim().replace(/^W\//, '').replace(/^"|"$/g, ''))
|
||||
|
||||
return candidates.includes(cleanTarget) || candidates.includes('*')
|
||||
}
|
||||
|
||||
/**
|
||||
* Normalizes an ETag to ensure it is enclosed in quotes according to RFC 9110.
|
||||
* Preserves weak validators (`W/"..."`).
|
||||
*/
|
||||
export function normalizeEtag(etag: string | undefined): string | undefined {
|
||||
if (!etag) {
|
||||
return undefined
|
||||
}
|
||||
const trimmed = etag.trim()
|
||||
if (!trimmed) {
|
||||
return undefined
|
||||
}
|
||||
if (trimmed.startsWith('W/"') && trimmed.endsWith('"')) {
|
||||
return trimmed
|
||||
}
|
||||
if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
|
||||
return trimmed
|
||||
}
|
||||
return `"${trimmed.replace(/^"|"$/g, '')}"`
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates a route handler for a static file on disk.
|
||||
* Content-hashed assets (e.g. `chunk-*.js`, `chunk-*.css`) should be marked `isImmutable: true`
|
||||
* to be aggressively cached locally by browsers across page reloads.
|
||||
*/
|
||||
export function createStaticFileHandler(
|
||||
filePath: string,
|
||||
baseHeaders: Record<string, string>,
|
||||
isImmutable: boolean,
|
||||
): (req: Request) => Response {
|
||||
const bunFile = Bun.file(filePath)
|
||||
const rawEtag = baseHeaders.etag || baseHeaders.ETag
|
||||
const normalizedEtag = normalizeEtag(rawEtag)
|
||||
const headers: Record<string, string> = {
|
||||
...baseHeaders,
|
||||
...(normalizedEtag ? { etag: normalizedEtag } : {}),
|
||||
'cache-control': isImmutable ? 'public, max-age=31536000, immutable' : 'no-cache',
|
||||
}
|
||||
const etag = headers.etag
|
||||
|
||||
return (req: Request): Response => {
|
||||
const ifNoneMatch = req.headers.get('if-none-match')
|
||||
if (etag && isEtagMatching(etag, ifNoneMatch)) {
|
||||
return new Response(null, {
|
||||
status: 304,
|
||||
headers,
|
||||
})
|
||||
}
|
||||
return new Response(bunFile, { headers })
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates a route handler for in-memory transformed HTML entry points.
|
||||
* Sets `cache-control: no-cache` with a deterministic ETag, allowing browsers to cache locally
|
||||
* while always revalidating to ensure new chunk hashes are picked up immediately after deployment.
|
||||
*/
|
||||
export function createHtmlHandler(
|
||||
htmlText: string,
|
||||
baseHeaders: Record<string, string>,
|
||||
): (req: Request) => Response {
|
||||
const rawEtag = baseHeaders.etag || baseHeaders.ETag
|
||||
const etag = normalizeEtag(rawEtag) || `"${Bun.hash(htmlText).toString(16)}"`
|
||||
const headers: Record<string, string> = {
|
||||
...baseHeaders,
|
||||
etag,
|
||||
'cache-control': 'no-cache',
|
||||
}
|
||||
|
||||
return (req: Request): Response => {
|
||||
const ifNoneMatch = req.headers.get('if-none-match')
|
||||
if (isEtagMatching(etag, ifNoneMatch)) {
|
||||
return new Response(null, {
|
||||
status: 304,
|
||||
headers,
|
||||
})
|
||||
}
|
||||
return new Response(htmlText, { headers })
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,15 @@
|
||||
import { describe, expect, it } from 'vitest'
|
||||
import { getServerQueues } from './workers'
|
||||
|
||||
describe('server queues', () => {
|
||||
it.each(['none', 'agent', 'ai', 'archive'])(
|
||||
'keeps agent and archive embedded for %s',
|
||||
(option) => {
|
||||
expect(getServerQueues(option)).toEqual(['agent_queue', 'archive_queue'])
|
||||
},
|
||||
)
|
||||
|
||||
it.each(['all', 'transcode'])('also processes local transcoding for %s', (option) => {
|
||||
expect(getServerQueues(option)).toEqual(['agent_queue', 'archive_queue', 'transcode_queue'])
|
||||
})
|
||||
})
|
||||
@@ -0,0 +1,8 @@
|
||||
import { TaskQueueAgent, TaskQueueArchive, TaskQueueTranscode } from '@shumai/workflow-core'
|
||||
|
||||
/** Agent and archive work always belongs to the server; only transcoding is optional. */
|
||||
export function getServerQueues(option: string): string[] {
|
||||
const queues = [TaskQueueAgent, TaskQueueArchive]
|
||||
if (option === 'all' || option === 'transcode') queues.push(TaskQueueTranscode)
|
||||
return queues
|
||||
}
|
||||
@@ -3,47 +3,57 @@ import { bunPluginPino } from 'bun-plugin-pino'
|
||||
import tailwindPlugin from 'bun-plugin-tailwind'
|
||||
import { existsSync } from 'fs'
|
||||
import { rm } from 'fs/promises'
|
||||
import { temporalWorkflow } from './packages/workflow-core/src/bun-temporal-plugin'
|
||||
|
||||
console.log('\n🚀 Starting build process...\n')
|
||||
|
||||
const outdir = 'dist'
|
||||
const target = process.argv[2] || 'all'
|
||||
|
||||
if (existsSync(outdir)) {
|
||||
if (existsSync(outdir) && target === 'all') {
|
||||
console.log(`🗑️ Cleaning previous build at ${outdir}`)
|
||||
await rm(outdir, { recursive: true, force: true })
|
||||
}
|
||||
|
||||
await Bun.build({
|
||||
entrypoints: ['./apps/web/src/index.ts'],
|
||||
root: '.',
|
||||
target: 'bun',
|
||||
outdir: outdir,
|
||||
minify: true,
|
||||
splitting: true,
|
||||
naming: '[name].[ext]',
|
||||
plugins: [
|
||||
temporalWorkflow({
|
||||
bundleOptions: {},
|
||||
}),
|
||||
tailwindPlugin,
|
||||
bunPluginPino({ transports: ['pino-pretty'] }),
|
||||
],
|
||||
external: [
|
||||
'@temporalio/activity',
|
||||
'@temporalio/client',
|
||||
'@temporalio/worker',
|
||||
'@temporalio/workflow',
|
||||
'pdfkit',
|
||||
],
|
||||
// compile: {
|
||||
// outfile: 'Shumai',
|
||||
// autoloadBunfig: true,
|
||||
// autoloadDotenv: true,
|
||||
// autoloadTsconfig: true,
|
||||
// autoloadPackageJson: true,
|
||||
// },
|
||||
define: {
|
||||
'process.env.NODE_ENV': JSON.stringify('production'),
|
||||
if (target === 'all' || target === 'web') {
|
||||
await Bun.build({
|
||||
entrypoints: ['./apps/web/src/index.ts'],
|
||||
root: '.',
|
||||
target: 'bun',
|
||||
outdir: outdir,
|
||||
minify: true,
|
||||
splitting: true,
|
||||
naming: '[name].[ext]',
|
||||
plugins: [tailwindPlugin, bunPluginPino({ transports: ['pino-pretty'] })],
|
||||
external: ['@dbos-inc/dbos-sdk', 'pg', 'pdfkit'],
|
||||
define: {
|
||||
'process.env.NODE_ENV': JSON.stringify('production'),
|
||||
},
|
||||
})
|
||||
}
|
||||
|
||||
const allWorkers = [
|
||||
{
|
||||
name: 'transcode',
|
||||
entrypoint: './apps/transcode/src/index.ts',
|
||||
naming: 'transcode-worker.[ext]',
|
||||
},
|
||||
})
|
||||
]
|
||||
|
||||
const workersToBuild = target === 'all' ? allWorkers : allWorkers.filter((w) => w.name === target)
|
||||
|
||||
for (const worker of workersToBuild) {
|
||||
await Bun.build({
|
||||
entrypoints: [worker.entrypoint],
|
||||
root: '.',
|
||||
target: 'bun',
|
||||
outdir: outdir,
|
||||
minify: true,
|
||||
splitting: false,
|
||||
naming: worker.naming,
|
||||
plugins: [bunPluginPino({ transports: ['pino-pretty'] })],
|
||||
external: ['@dbos-inc/dbos-sdk', 'pg', 'pdfkit'],
|
||||
define: {
|
||||
'process.env.NODE_ENV': JSON.stringify('production'),
|
||||
},
|
||||
})
|
||||
}
|
||||
|
||||
@@ -0,0 +1,62 @@
|
||||
services:
|
||||
postgres:
|
||||
image: docker.m.daocloud.io/pgvector/pgvector:pg18
|
||||
container_name: shumai_postgres
|
||||
environment:
|
||||
POSTGRES_USER: shumai
|
||||
POSTGRES_PASSWORD: shumai_password
|
||||
POSTGRES_DB: shumai_db
|
||||
volumes:
|
||||
- postgres_data:/var/lib/postgresql/18/docker
|
||||
healthcheck:
|
||||
test: ['CMD-SHELL', 'pg_isready -U shumai -d shumai_db']
|
||||
interval: 5s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
|
||||
embedding-server:
|
||||
image: crpi-000nkafzu6xvpwsc.cn-hongkong.personal.cr.aliyuncs.com/shumai-one/embedding-server:latest
|
||||
container_name: shumai_embedding
|
||||
restart: unless-stopped
|
||||
|
||||
shumai:
|
||||
image: crpi-000nkafzu6xvpwsc.cn-hongkong.personal.cr.aliyuncs.com/shumai-one/shumai:latest
|
||||
container_name: shumai_app
|
||||
ports:
|
||||
- '3000:3000'
|
||||
volumes:
|
||||
- ./data:/app/data
|
||||
# Hardware Acceleration (NVENC / QuickSync / VA-API / RKMPP)
|
||||
# Uncomment the extends section below for hardware acceleration:
|
||||
# extends:
|
||||
# file: hwaccel.transcoding.yaml
|
||||
# service: cpu # set to one of [nvenc, quicksync, rkmpp, vaapi, vaapi-wsl] for accelerated transcoding
|
||||
environment:
|
||||
# Database Configuration
|
||||
DATABASE_URL: postgres://shumai:shumai_password@shumai_postgres:5432/shumai_db?search_path=public&sslmode=disable
|
||||
|
||||
# Server Configuration
|
||||
SHUMAI_SERVER_PORT: 3000
|
||||
|
||||
# S3 Configuration
|
||||
STORAGE_BACKEND: local
|
||||
AWS_ENDPOINT_URL_S3: http://localhost:3000
|
||||
|
||||
# Better Auth
|
||||
BETTER_AUTH_SECRET: qSxs9DxzHDZBbeeTNPEwBuspYwipBqz5Gk5XdBjNhWw=
|
||||
BETTER_AUTH_URL: http://localhost:3000
|
||||
|
||||
# Embedding Configuration
|
||||
EMBEDDING_PROVIDER: gemma-embedding-2-openai
|
||||
GEMMA_EMBEDDING_OPENAI_BASE_URL: http://embedding-server:9379/v1
|
||||
ENABLE_EMBEDDING_AGENT: 'true'
|
||||
CONCURRENCY_AGENT: 1
|
||||
|
||||
depends_on:
|
||||
postgres:
|
||||
condition: service_healthy
|
||||
embedding-server:
|
||||
condition: service_started
|
||||
|
||||
volumes:
|
||||
postgres_data:
|
||||
@@ -0,0 +1,82 @@
|
||||
services:
|
||||
postgres:
|
||||
image: docker.m.daocloud.io/pgvector/pgvector:pg18
|
||||
container_name: shumai_postgres
|
||||
environment:
|
||||
POSTGRES_USER: shumai
|
||||
POSTGRES_PASSWORD: shumai_password
|
||||
POSTGRES_DB: shumai_db
|
||||
volumes:
|
||||
- postgres_data:/var/lib/postgresql/18/docker
|
||||
healthcheck:
|
||||
test: ['CMD-SHELL', 'pg_isready -U shumai -d shumai_db']
|
||||
interval: 5s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
|
||||
embedding-server:
|
||||
image: crpi-000nkafzu6xvpwsc.cn-hongkong.personal.cr.aliyuncs.com/shumai-one/embedding-server:latest
|
||||
container_name: shumai_embedding
|
||||
restart: unless-stopped
|
||||
|
||||
turntable-renderer:
|
||||
image: crpi-000nkafzu6xvpwsc.cn-hongkong.personal.cr.aliyuncs.com/shumai-one/turntable-renderer:latest
|
||||
container_name: shumai_turntable
|
||||
restart: unless-stopped
|
||||
|
||||
gotenberg:
|
||||
image: docker.m.daocloud.io/gotenberg/gotenberg:8
|
||||
container_name: shumai_gotenberg
|
||||
restart: unless-stopped
|
||||
|
||||
shumai:
|
||||
image: crpi-000nkafzu6xvpwsc.cn-hongkong.personal.cr.aliyuncs.com/shumai-one/shumai:latest
|
||||
container_name: shumai_app
|
||||
ports:
|
||||
- '3000:3000'
|
||||
volumes:
|
||||
- ./data:/app/data
|
||||
# Hardware Acceleration (NVENC / QuickSync / VA-API / RKMPP)
|
||||
# Uncomment the extends section below for hardware acceleration:
|
||||
# extends:
|
||||
# file: hwaccel.transcoding.yaml
|
||||
# service: cpu # set to one of [nvenc, quicksync, rkmpp, vaapi, vaapi-wsl] for accelerated transcoding
|
||||
environment:
|
||||
# Database Configuration
|
||||
DATABASE_URL: postgres://shumai:shumai_password@shumai_postgres:5432/shumai_db?search_path=public&sslmode=disable
|
||||
|
||||
# Server Configuration
|
||||
SHUMAI_SERVER_PORT: 3000
|
||||
|
||||
# S3 Configuration
|
||||
STORAGE_BACKEND: local
|
||||
AWS_ENDPOINT_URL_S3: http://localhost:3000
|
||||
|
||||
# Better Auth
|
||||
BETTER_AUTH_SECRET: qSxs9DxzHDZBbeeTNPEwBuspYwipBqz5Gk5XdBjNhWw=
|
||||
BETTER_AUTH_URL: http://localhost:3000
|
||||
|
||||
# Embedding Configuration
|
||||
EMBEDDING_PROVIDER: gemma-embedding-2-openai
|
||||
GEMMA_EMBEDDING_OPENAI_BASE_URL: http://embedding-server:9379/v1
|
||||
ENABLE_EMBEDDING_AGENT: 'true'
|
||||
CONCURRENCY_AGENT: 1
|
||||
|
||||
# 3D Turntable Renderer Configuration
|
||||
TURNTABLE_RENDERER_URL: http://turntable-renderer:3000
|
||||
|
||||
# Gotenberg Document Converter Configuration
|
||||
GOTENBERG_URL: http://gotenberg:3000
|
||||
|
||||
depends_on:
|
||||
postgres:
|
||||
condition: service_healthy
|
||||
embedding-server:
|
||||
condition: service_started
|
||||
turntable-renderer:
|
||||
condition: service_started
|
||||
gotenberg:
|
||||
condition: service_started
|
||||
|
||||
volumes:
|
||||
postgres_data:
|
||||
@@ -16,16 +16,16 @@ services:
|
||||
|
||||
shumai:
|
||||
image: crpi-000nkafzu6xvpwsc.cn-hongkong.personal.cr.aliyuncs.com/shumai-one/shumai:latest
|
||||
cap_add:
|
||||
- SYS_ADMIN
|
||||
security_opt:
|
||||
- apparmor=unconfined
|
||||
- seccomp=unconfined
|
||||
container_name: shumai_app
|
||||
ports:
|
||||
- '3000:3000'
|
||||
volumes:
|
||||
- ./data:/app/data
|
||||
# Hardware Acceleration (NVENC / QuickSync / VA-API / RKMPP)
|
||||
# Uncomment the extends section below for hardware acceleration:
|
||||
# extends:
|
||||
# file: hwaccel.transcoding.yaml
|
||||
# service: cpu # set to one of [nvenc, quicksync, rkmpp, vaapi, vaapi-wsl] for accelerated transcoding
|
||||
environment:
|
||||
# Database Configuration
|
||||
DATABASE_URL: postgres://shumai:shumai_password@shumai_postgres:5432/shumai_db?search_path=public&sslmode=disable
|
||||
@@ -39,9 +39,7 @@ services:
|
||||
|
||||
# Better Auth
|
||||
BETTER_AUTH_SECRET: qSxs9DxzHDZBbeeTNPEwBuspYwipBqz5Gk5XdBjNhWw=
|
||||
|
||||
# Sandbox Configuration
|
||||
ENABLE_WEAKER_NESTED_SANDBOX: 'true'
|
||||
BETTER_AUTH_URL: http://localhost:3000
|
||||
|
||||
depends_on:
|
||||
postgres:
|
||||
|
||||
@@ -0,0 +1,62 @@
|
||||
services:
|
||||
postgres:
|
||||
image: pgvector/pgvector:pg18
|
||||
container_name: shumai_postgres
|
||||
environment:
|
||||
POSTGRES_USER: shumai
|
||||
POSTGRES_PASSWORD: shumai_password
|
||||
POSTGRES_DB: shumai_db
|
||||
volumes:
|
||||
- postgres_data:/var/lib/postgresql/18/docker
|
||||
healthcheck:
|
||||
test: ['CMD-SHELL', 'pg_isready -U shumai -d shumai_db']
|
||||
interval: 5s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
|
||||
embedding-server:
|
||||
image: shumaione/embedding-server:latest
|
||||
container_name: shumai_embedding
|
||||
restart: unless-stopped
|
||||
|
||||
shumai:
|
||||
image: shumaione/shumai:latest
|
||||
container_name: shumai_app
|
||||
ports:
|
||||
- '3000:3000'
|
||||
volumes:
|
||||
- ./data:/app/data
|
||||
# Hardware Acceleration (NVENC / QuickSync / VA-API / RKMPP)
|
||||
# Uncomment the extends section below for hardware acceleration:
|
||||
# extends:
|
||||
# file: hwaccel.transcoding.yaml
|
||||
# service: cpu # set to one of [nvenc, quicksync, rkmpp, vaapi, vaapi-wsl] for accelerated transcoding
|
||||
environment:
|
||||
# Database Configuration
|
||||
DATABASE_URL: postgres://shumai:shumai_password@shumai_postgres:5432/shumai_db?search_path=public&sslmode=disable
|
||||
|
||||
# Server Configuration
|
||||
SHUMAI_SERVER_PORT: 3000
|
||||
|
||||
# S3 Configuration
|
||||
STORAGE_BACKEND: local
|
||||
AWS_ENDPOINT_URL_S3: http://localhost:3000
|
||||
|
||||
# Better Auth
|
||||
BETTER_AUTH_SECRET: qSxs9DxzHDZBbeeTNPEwBuspYwipBqz5Gk5XdBjNhWw=
|
||||
BETTER_AUTH_URL: http://localhost:3000
|
||||
|
||||
# Embedding Configuration
|
||||
EMBEDDING_PROVIDER: gemma-embedding-2-openai
|
||||
GEMMA_EMBEDDING_OPENAI_BASE_URL: http://embedding-server:9379/v1
|
||||
ENABLE_EMBEDDING_AGENT: 'true'
|
||||
CONCURRENCY_AGENT: 1
|
||||
|
||||
depends_on:
|
||||
postgres:
|
||||
condition: service_healthy
|
||||
embedding-server:
|
||||
condition: service_started
|
||||
|
||||
volumes:
|
||||
postgres_data:
|
||||
@@ -0,0 +1,82 @@
|
||||
services:
|
||||
postgres:
|
||||
image: pgvector/pgvector:pg18
|
||||
container_name: shumai_postgres
|
||||
environment:
|
||||
POSTGRES_USER: shumai
|
||||
POSTGRES_PASSWORD: shumai_password
|
||||
POSTGRES_DB: shumai_db
|
||||
volumes:
|
||||
- postgres_data:/var/lib/postgresql/18/docker
|
||||
healthcheck:
|
||||
test: ['CMD-SHELL', 'pg_isready -U shumai -d shumai_db']
|
||||
interval: 5s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
|
||||
embedding-server:
|
||||
image: shumaione/embedding-server:latest
|
||||
container_name: shumai_embedding
|
||||
restart: unless-stopped
|
||||
|
||||
turntable-renderer:
|
||||
image: shumaione/turntable-renderer:latest
|
||||
container_name: shumai_turntable
|
||||
restart: unless-stopped
|
||||
|
||||
gotenberg:
|
||||
image: gotenberg/gotenberg:8
|
||||
container_name: shumai_gotenberg
|
||||
restart: unless-stopped
|
||||
|
||||
shumai:
|
||||
image: shumaione/shumai:latest
|
||||
container_name: shumai_app
|
||||
ports:
|
||||
- '3000:3000'
|
||||
volumes:
|
||||
- ./data:/app/data
|
||||
# Hardware Acceleration (NVENC / QuickSync / VA-API / RKMPP)
|
||||
# Uncomment the extends section below for hardware acceleration:
|
||||
# extends:
|
||||
# file: hwaccel.transcoding.yaml
|
||||
# service: cpu # set to one of [nvenc, quicksync, rkmpp, vaapi, vaapi-wsl] for accelerated transcoding
|
||||
environment:
|
||||
# Database Configuration
|
||||
DATABASE_URL: postgres://shumai:shumai_password@shumai_postgres:5432/shumai_db?search_path=public&sslmode=disable
|
||||
|
||||
# Server Configuration
|
||||
SHUMAI_SERVER_PORT: 3000
|
||||
|
||||
# S3 Configuration
|
||||
STORAGE_BACKEND: local
|
||||
AWS_ENDPOINT_URL_S3: http://localhost:3000
|
||||
|
||||
# Better Auth
|
||||
BETTER_AUTH_SECRET: qSxs9DxzHDZBbeeTNPEwBuspYwipBqz5Gk5XdBjNhWw=
|
||||
BETTER_AUTH_URL: http://localhost:3000
|
||||
|
||||
# Embedding Configuration
|
||||
EMBEDDING_PROVIDER: gemma-embedding-2-openai
|
||||
GEMMA_EMBEDDING_OPENAI_BASE_URL: http://embedding-server:9379/v1
|
||||
ENABLE_EMBEDDING_AGENT: 'true'
|
||||
CONCURRENCY_AGENT: 1
|
||||
|
||||
# 3D Turntable Renderer Configuration
|
||||
TURNTABLE_RENDERER_URL: http://turntable-renderer:3000
|
||||
|
||||
# Gotenberg Document Converter Configuration
|
||||
GOTENBERG_URL: http://gotenberg:3000
|
||||
|
||||
depends_on:
|
||||
postgres:
|
||||
condition: service_healthy
|
||||
embedding-server:
|
||||
condition: service_started
|
||||
turntable-renderer:
|
||||
condition: service_started
|
||||
gotenberg:
|
||||
condition: service_started
|
||||
|
||||
volumes:
|
||||
postgres_data:
|
||||
@@ -16,16 +16,16 @@ services:
|
||||
|
||||
shumai:
|
||||
image: shumaione/shumai:latest
|
||||
cap_add:
|
||||
- SYS_ADMIN
|
||||
security_opt:
|
||||
- apparmor=unconfined
|
||||
- seccomp=unconfined
|
||||
container_name: shumai_app
|
||||
ports:
|
||||
- '3000:3000'
|
||||
volumes:
|
||||
- ./data:/app/data
|
||||
# Hardware Acceleration (NVENC / QuickSync / VA-API / RKMPP)
|
||||
# Uncomment the extends section below for hardware acceleration:
|
||||
# extends:
|
||||
# file: hwaccel.transcoding.yaml
|
||||
# service: cpu # set to one of [nvenc, quicksync, rkmpp, vaapi, vaapi-wsl] for accelerated transcoding
|
||||
environment:
|
||||
# Database Configuration
|
||||
DATABASE_URL: postgres://shumai:shumai_password@shumai_postgres:5432/shumai_db?search_path=public&sslmode=disable
|
||||
@@ -39,9 +39,7 @@ services:
|
||||
|
||||
# Better Auth
|
||||
BETTER_AUTH_SECRET: qSxs9DxzHDZBbeeTNPEwBuspYwipBqz5Gk5XdBjNhWw=
|
||||
|
||||
# Sandbox Configuration
|
||||
ENABLE_WEAKER_NESTED_SANDBOX: 'true'
|
||||
BETTER_AUTH_URL: http://localhost:3000
|
||||
|
||||
depends_on:
|
||||
postgres:
|
||||
|
||||
@@ -0,0 +1,44 @@
|
||||
# Configurations for hardware-accelerated transcoding
|
||||
services:
|
||||
cpu: {}
|
||||
|
||||
nvenc:
|
||||
deploy:
|
||||
resources:
|
||||
reservations:
|
||||
devices:
|
||||
- driver: nvidia
|
||||
count: 1
|
||||
capabilities:
|
||||
- gpu
|
||||
- compute
|
||||
- video
|
||||
|
||||
quicksync:
|
||||
devices:
|
||||
- /dev/dri:/dev/dri
|
||||
|
||||
rkmpp:
|
||||
security_opt: # enables full access to /sys and /proc, still far better than privileged: true
|
||||
- systempaths=unconfined
|
||||
- apparmor=unconfined
|
||||
group_add:
|
||||
- video
|
||||
devices:
|
||||
- /dev/rga:/dev/rga
|
||||
- /dev/dri:/dev/dri
|
||||
- /dev/dma_heap:/dev/dma_heap
|
||||
- /dev/mpp_service:/dev/mpp_service
|
||||
|
||||
vaapi:
|
||||
devices:
|
||||
- /dev/dri:/dev/dri
|
||||
|
||||
vaapi-wsl: # use this for VAAPI if running in WSL2
|
||||
devices:
|
||||
- /dev/dri:/dev/dri
|
||||
- /dev/dxg:/dev/dxg
|
||||
volumes:
|
||||
- /usr/lib/wsl:/usr/lib/wsl
|
||||
environment:
|
||||
- LIBVA_DRIVER_NAME=d3d12
|
||||
@@ -1,84 +0,0 @@
|
||||
services:
|
||||
# --- Shumai Application Services ---
|
||||
postgres:
|
||||
image: pgvector/pgvector:pg18
|
||||
container_name: shumai_postgres
|
||||
environment:
|
||||
POSTGRES_USER: shumai
|
||||
POSTGRES_PASSWORD: shumai_password
|
||||
POSTGRES_DB: shumai_db
|
||||
volumes:
|
||||
- postgres_data:/var/lib/postgresql
|
||||
healthcheck:
|
||||
test: ['CMD-SHELL', 'pg_isready -U shumai -d shumai_db']
|
||||
interval: 5s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
|
||||
shumai:
|
||||
image: shumaione/shumai:latest
|
||||
container_name: shumai_app
|
||||
ports:
|
||||
- '3000:3000'
|
||||
volumes:
|
||||
- shumai_data:/app/data
|
||||
environment:
|
||||
DATABASE_URL: postgres://shumai:shumai_password@postgres:5432/shumai_db?search_path=public&sslmode=disable
|
||||
STORAGE_BACKEND: s3
|
||||
AWS_ENDPOINT_URL_S3: S3_ENDPOINT_URL
|
||||
S3_REGION: S3_REGION
|
||||
S3_BUCKET: BUCKET_NAME
|
||||
S3_ACCESS_KEY_ID: ID
|
||||
S3_SECRET_ACCESS_KEY: KEY
|
||||
BETTER_AUTH_SECRET: qSxs9DxzHDZBbeeTNPEwBuspYwipBqz5Gk5XdBjNhWw=
|
||||
WORKFLOW_EXECUTOR: temporal
|
||||
TEMPORAL_ADDRESS: temporal:7233
|
||||
GEMINI_API_KEY: KEY
|
||||
ENABLE_WEAKER_NESTED_SANDBOX: 'true'
|
||||
depends_on:
|
||||
postgres:
|
||||
condition: service_healthy
|
||||
temporal:
|
||||
condition: service_healthy
|
||||
|
||||
# --- Temporal Services ---
|
||||
temporal:
|
||||
image: temporalio/auto-setup:latest
|
||||
container_name: temporal_server
|
||||
environment:
|
||||
- DB=postgres12
|
||||
- DB_PORT=5432
|
||||
- POSTGRES_USER=shumai
|
||||
- POSTGRES_PWD=shumai_password
|
||||
- POSTGRES_SEEDS=postgres
|
||||
- BIND_ON_IP=0.0.0.0
|
||||
ports:
|
||||
- '7233:7233'
|
||||
healthcheck:
|
||||
test:
|
||||
[
|
||||
'CMD-SHELL',
|
||||
'temporal operator cluster health --address localhost:7233 || temporal operator cluster health --address $$(hostname -i):7233',
|
||||
]
|
||||
interval: 5s
|
||||
timeout: 5s
|
||||
start_period: 30s
|
||||
retries: 10
|
||||
depends_on:
|
||||
postgres:
|
||||
condition: service_healthy
|
||||
|
||||
temporal-ui:
|
||||
image: temporalio/ui:latest
|
||||
container_name: temporal_ui
|
||||
environment:
|
||||
- TEMPORAL_ADDRESS=temporal:7233
|
||||
ports:
|
||||
- '8080:8080'
|
||||
depends_on:
|
||||
temporal:
|
||||
condition: service_healthy
|
||||
|
||||
volumes:
|
||||
postgres_data:
|
||||
shumai_data:
|
||||
@@ -3,6 +3,229 @@ title: "Changelog"
|
||||
description: "Recent updates, new features, and improvements in Shumai"
|
||||
---
|
||||
|
||||
<Update label="v0.7.0" description="November 18, 2026">
|
||||
|
||||
### Added
|
||||
|
||||
- **i18n**: Add Korean as a display language, selectable on the sign-up page and in team settings.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **cli**: Fix release publication failing to find staged standalone downloads.
|
||||
|
||||
### Changed
|
||||
|
||||
- **agent**: ⚠️ **Breaking Change**: Replaced the built-in server-side Bash sandbox with external Runners and removed the team-level sandbox domain allowlist settings. The Bash tool is now disabled by default. If your Agent or Skills require Bash execution, you'll need to set up and connect an external Runner using shumai-cli. The Shumai CLI includes built-in sandbox support, allowing you to configure filesystem access and network domain allowlists for Bash execution directly on the Runner. See [Agent Runners](https://docs.shumai.one/using-shumai/agent-sandbox) for setup instructions and configuration details. The Docker Compose configuration has also been updated to improve security following the removal of the server-side sandbox. We strongly recommend upgrading to the latest Shumai image and updating your Docker Compose file to apply these security improvements.
|
||||
- **cli**: Show copyable commands and shell configuration instructions when the standalone CLI installation directory is missing from PATH.
|
||||
|
||||
</Update>
|
||||
|
||||
<Update label="v0.6.6" description="November 13, 2026">
|
||||
|
||||
### Added
|
||||
|
||||
- **project**: Support creating new projects via the built-in agent, MCP server, and CLI (`shumai-cli project create`).
|
||||
- **cli**: Add standalone downloads and one-line installers for macOS, Linux, and Windows without requiring Node.js or Bun, with verified downloads, version selection, and upgrade support.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **storage**: Remove empty local folders left behind after generating video search embeddings.
|
||||
|
||||
### Changed
|
||||
|
||||
- **agent**: Upgrade the agent runtime and automatically migrate existing conversations, keep thread histories independent, prevent duplicate history during simultaneous mentions, improve session log scrolling and readability, and fix authentication for OpenAI and custom providers. Agents now run with the main server; standalone agent workers are no longer supported.
|
||||
|
||||
</Update>
|
||||
|
||||
<Update label="v0.6.5" description="November 7, 2026">
|
||||
|
||||
### Added
|
||||
|
||||
### Fixed
|
||||
|
||||
### Changed
|
||||
|
||||
- **file-browser**: ⚠️ **Behavior Change**: Align asset selection and click behavior with Frame.io: single-clicking file or folder cards on public share links always opens or enters the asset even when already selected, clicking an already-selected card in workspace file lists preserves multi-selection, checkboxes independently toggle individual items without clearing other selections, and Shift-click range selection is supported on public share links
|
||||
|
||||
</Update>
|
||||
|
||||
<Update label="v0.6.4" description="November 5, 2026">
|
||||
|
||||
### Added
|
||||
|
||||
- **storage**: Add optional archive storage support (`local` folder/NAS or `s3` with configurable storage class and Glacier restore) allowing editors and owners to archive and restore original files while keeping previews, proxy streams, comments, and metadata available in main storage
|
||||
- **storage**: Add team-level automatic asset archival based on age policies (creation time or last modified time) with configurable post-restore grace periods, an hourly background scanning worker, and a dedicated Storage settings page displaying read-only archive backend status and policy configurations
|
||||
|
||||
### Fixed
|
||||
|
||||
- **security**: ⚠️ Several security improvements and access control hardenings. Upgrading to this release is strongly recommended.
|
||||
- **mcp**: Gracefully disable MCP OAuth 2.1 with an error log when deploying on remote HTTP IP addresses without breaking the main server or API token MCP access
|
||||
- **web**: Add immutable cache headers and conditional 304 Not Modified support for production JavaScript and CSS chunks to prevent unnecessary refetches on page reload
|
||||
|
||||
### Changed
|
||||
|
||||
- **file-browser**: Replace the legacy combined "Copy name and download link" action with a context-aware Copy submenu in file browser context menus and card action dropdowns, enabling users to copy image, asset names, in-app links, download links, IDs, Markdown links and storage paths(team-owner only)
|
||||
|
||||
</Update>
|
||||
|
||||
<Update label="v0.6.3" description="November 1, 2026">
|
||||
|
||||
### Added
|
||||
|
||||
- **upload**: Allow users to cancel running upload tasks directly from the upload tasks sidebar with a confirmation dialog, preserving already completed files while discarding incomplete assets
|
||||
- **upload**: Improve upload resilience during network drops, device sleep, and transient gateway errors by adding state-based exponential backoff retries and extending upload link expiration to 12 hours
|
||||
|
||||
### Fixed
|
||||
|
||||
- **upload**: Display a clear diagnostic error toast when remote file uploads fail due to an unconfigured or localhost S3 storage endpoint
|
||||
|
||||
### Changed
|
||||
|
||||
- **upload**: ⚠️ **Important Behavior Change**: Uploading files now appear in their correct sorted position in the file list, following the current sort setting, instead of being pinned to the top and jumping into place after the upload finishes. Cards no longer move when an upload completes. Note that if you sort by name, an uploading file may land outside your current view. Local uploads also show remaining time and transfer speed (e.g. `8m left (390.88 KB/s)`), and other users viewing the folder see `[User] is uploading...`.
|
||||
- **agent**: ⚠️ **Important Behavior Change**: Autofill and Embedding agents will no longer post completion comments when finishing successfully to prevent clutter in asset comment feeds. Comments are now only posted if a task encounters an error.
|
||||
|
||||
</Update>
|
||||
|
||||
<Update label="v0.6.2" description="October 29, 2026">
|
||||
|
||||
### Added
|
||||
|
||||
* **mcp**: Add a built-in MCP server supporting OAuth 2.1 and API tokens, allowing external AI agents (such as Claude Code, Cursor, or Kiro) to browse projects, manage and upload files, inspect media contents (images, video frames, PDF pages, 3D models, and text), search assets, manage review comments, update metadata, and organize version stacks
|
||||
* **cli**: Add `shumai-cli` commands to download files (`download`), view and render media contents (`read`, `render`), search and copy files (`search`, `copy`), manage review comments (`comment`), view and update metadata (`field ls`, `meta set`), organize version stacks (`version`), and view folder instructions (`instructions`)
|
||||
* **agent**: The built-in agent can now list accessible projects, search files by name, meaning, or metadata, read and post review comments, update metadata, copy files, stack and unstack versions, and read folder instructions (`AGENTS.md`), with configurable permissions per agent
|
||||
|
||||
### Fixed
|
||||
|
||||
|
||||
### Changed
|
||||
|
||||
</Update>
|
||||
|
||||
<Update label="v0.6.1" description="October 24, 2026">
|
||||
|
||||
### Added
|
||||
|
||||
* **dashboard**: Add Workflow Tasks section to the Team Dashboard allowing team owners to monitor background workflow jobs, inspect execution payloads and outputs, and stop in-flight tasks
|
||||
|
||||
### Fixed
|
||||
|
||||
* **metadata**: Fix an issue where clicking to edit a metadata field on a card or list row inadvertently selected the file, and prevent expanded text overlays or date pickers from being clipped by container borders
|
||||
|
||||
### Changed
|
||||
|
||||
* **deps**: Upgrade Bun to 1.4.4
|
||||
|
||||
</Update>
|
||||
|
||||
<Update label="v0.6.0" description="October 20, 2026">
|
||||
|
||||
### Added
|
||||
|
||||
* **deploy**: Add dedicated `shumaione/shumai-transcode` Docker image and a complete AWS EKS deployment example (`eks/`) featuring KEDA queue-driven autoscaling, idle-timeout auto-drain worker mode, and Scale-to-Zero On-Demand Graviton5 instances for media processing
|
||||
* **storage**: Support configuring a separate public endpoint (`AWS_PUBLIC_ENDPOINT_URL_S3`) for browser-facing presigned URLs while preserving internal cluster endpoints for backend workers
|
||||
|
||||
### Fixed
|
||||
|
||||
* **transcode**: Fix an issue where PDF, 3D model, and image background transcode workflows could fail with missing temporary file errors if a worker restarted or recovered midway through processing
|
||||
* **webui**: Improve file list and detail loading with matching skeleton layouts, a persistent sidebar carousel to eliminate layout shift, and smoothed video poster previews
|
||||
|
||||
### Changed
|
||||
|
||||
* **workflow**: Migrate the background workflow engine to DBOS, unifying all-in-one and dedicated worker deployments using the existing PostgreSQL database without requiring a separate Temporal cluster
|
||||
|
||||
</Update>
|
||||
|
||||
<Update label="v0.5.3" description="October 16, 2026">
|
||||
|
||||
### Added
|
||||
|
||||
* **cli**: Add administrative `shumai regenerate-embeddings` command to regenerate multimodal vector embeddings for all existing media files across active teams
|
||||
* **docker**: Provide three Docker Compose deployment tiers (Lite, with Embedding Server, and Full) with recommended memory specifications
|
||||
* **agent**: Save video chunk embeddings incrementally to the database as each chunk finishes, preserving completed progress on failure and resuming from where it left off on retry
|
||||
* **agent**: Add support for local LiteRT-LM Gemma Embedding 2 (`gemma-embedding-2-openai`) provider and environment-enforced read-only embedding agents with automatic 768-dimensional vector search indexing
|
||||
|
||||
### Fixed
|
||||
|
||||
### Changed
|
||||
|
||||
* **search**: Display search results in a responsive card grid with interactive hover video sprite scrubbing, semantic match chunk time range previews, and new-tab opening on click
|
||||
* **search**: Significantly improve semantic search response times by generating query text embeddings directly with in-memory caching instead of dispatching background tasks
|
||||
|
||||
</Update>
|
||||
|
||||
<Update label="v0.5.2" description="October 13, 2026">
|
||||
|
||||
### Added
|
||||
|
||||
* **3d asset**: Add support for 3D model files (.glb, .gltf, .obj, .fbx, .stl, .dae, .usd, .usda, .usdc, .usdz) with automated turntable video rendering, hover sprite scrubbing, and an interactive 3D turntable viewer featuring 360° ruler scrubbing and degree-based markup comments
|
||||
* **kanban**: Related assets on a task are now clickable, taking you directly to that file or folder in its project
|
||||
* **settings**: Add an Integrations section to Team Settings with dedicated configuration for Gotenberg Document Converter, supporting connection testing and environment variable override protection
|
||||
|
||||
### Fixed
|
||||
|
||||
* **transcode**: Fix an issue where portrait photos from cameras and phones appeared sideways in thumbnails, previews, watermarked share links and annotated snapshots, and were listed with their width and height swapped
|
||||
|
||||
### Changed
|
||||
|
||||
</Update>
|
||||
|
||||
<Update label="v0.5.1" description="October 6, 2026">
|
||||
|
||||
### Added
|
||||
|
||||
* **notification**: Notification cards are now clickable, taking you directly to the relevant file
|
||||
* **transcode**: Add hardware decoding and GPU scaling support for NVIDIA NVENC, Intel QuickSync Video (QSV), Rockchip (RKMPP), and VA-API (Intel and AMD GPUs), significantly speeding up video proxy and HLS rendition generation across supported platforms. Set `SHUMAI_HW_DECODE=false` to turn hardware decoding off
|
||||
* **transcode**: Add `dcraw_emu` fallback to generate WebP previews for camera RAW files without embedded JPEG previews
|
||||
|
||||
### Fixed
|
||||
|
||||
### Changed
|
||||
|
||||
</Update>
|
||||
|
||||
<Update label="v0.5.0" description="October 2, 2026">
|
||||
|
||||
### Added
|
||||
|
||||
* **transcode**: Add configurable target resolution ladders (480p, 720p, 1080p, 1440p, 2160p) for MP4 Multi Resolutions transcoding in team settings, with unified resolution matching and lowest-resolution fallback for both MP4 and HLS
|
||||
* **transcode**: Add HLS live streaming with fMP4/CMAF adaptive bitrate ladders (480p, 720p, 1080p, 1440p, 2160p), configurable in Transcode Settings, with automatic quality switching, manual resolution selection in the video viewer, seamless rendition switching, and full watermarking support for shared links
|
||||
* **transcode**: Add basic camera RAW image support for popular camera formats (including Sony ARW, Canon CR2/CR3, Nikon NEF, Adobe DNG, Fujifilm RAF, and Panasonic RW2), extracting high-quality embedded JPEG previews and automatically applying camera orientation for fast thumbnail and proxy generation
|
||||
|
||||
### Fixed
|
||||
|
||||
- **asset**: Fix an issue where media files remained stuck in a perpetual "Preparing..." state when transcoding failed, by displaying a clear failed status and error details in the file list and file viewer
|
||||
|
||||
* **transcode**: Fix an issue where videos or audio-only files containing attached cover art or picture streams could cause transcoding to fail during poster generation or select a single static image instead of the video
|
||||
|
||||
* **webui**: Fix inconsistent video resolution labels across download menus, mobile file headers, and the video player by correctly deriving resolutions from the video's short side, including portrait videos and 480p videos
|
||||
|
||||
* **trash**: Fix an issue where the "Empty Trash" confirmation dialog would close immediately instead of showing a loading state while files were being permanently deleted
|
||||
|
||||
### Changed
|
||||
|
||||
* **settings**: Redesign team Video Transcoding settings with dedicated cards for Transcode Policy, Hardware Acceleration, and FFmpeg Threads, clearly explaining MP4 and HLS playback vs download behavior and storage implications
|
||||
* **settings**: Rename AI Settings group to Team AI Settings in settings navigation
|
||||
|
||||
</Update>
|
||||
|
||||
<Update label="v0.4.9" description="September 28, 2026">
|
||||
|
||||
### Added
|
||||
|
||||
- **notification**: You can now receive notifications via email, with batched digest emails and configurable team-level SMTP settings
|
||||
- **transcode**: Add VA-API hardware acceleration support for Linux hosts and Docker environments with Intel and AMD GPUs, featuring automatic DRI render node discovery, variable bitrate control, and structured transcoding observability logs
|
||||
- **transcode**: Add automatic fallback to software transcoding (libx264) when hardware-accelerated video encoding encounters GPU resolution constraints or runtime driver errors
|
||||
- **docker**: Add modular hardware-accelerated transcoding presets matching Immich's compose configuration via `hwaccel.transcoding.yaml` with support for NVENC, QuickSync, RKMPP, and VA-API
|
||||
|
||||
### Fixed
|
||||
|
||||
### Changed
|
||||
|
||||
- **transcode**: Improve video poster selection using intelligent scene detection and color variance filtering to automatically skip black frames, fade-ins, and blank intros in favor of representative video content
|
||||
- **transcode**: Optimize video sprite generation for large and long videos using a concurrent fast-seek pool and image compositing, avoiding full-video decoding while preserving instant single-pass generation for short clips
|
||||
|
||||
</Update>
|
||||
|
||||
<Update label="v0.4.8" description="September 24, 2026">
|
||||
|
||||
### Added
|
||||
|
||||
@@ -0,0 +1,250 @@
|
||||
---
|
||||
title: Archive Storage
|
||||
description: Configure secondary cold storage to offload raw media files while preserving in-browser proxy playback and previews.
|
||||
---
|
||||
|
||||
High-resolution camera footage, RAW image sequences, master audio stems, and large 3D assets quickly consume primary storage. Shumai's **Archive Storage** feature enables creative teams to offload heavy master original files to cost-effective cold storage (such as a local NAS, AWS S3 Glacier, or Google Cloud Storage Coldline) while keeping all proxy media, preview images, waveform files, and metadata in primary storage.
|
||||
|
||||
Team members can continue to browse, search, scrub, and review archived assets in the web browser without interruption. When the original raw file is needed for mastering or color grading, it can be restored back to primary storage with a single click.
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
1. **Original-Only Archiving**: Only the original raw file is moved to archive storage. Previews, thumbnails, and transcoded proxies (e.g., 180p scrubbing proxies, 1080p streamable MP4s, WebP posters) remain in primary storage.
|
||||
2. **Durable Asynchronous Workflows**: Moving and restoring files is handled by background worker tasks on a dedicated queue (`archive_queue`) managed by DBOS. Tasks automatically survive network interruptions, slow S3 transfers, and server restarts.
|
||||
3. **Transparent Asset Lifecycle**:
|
||||
- When an asset is being archived, its status transitions to `archiving` and settles at `archived`.
|
||||
- When an asset is being restored, its status transitions to `restoring` and returns to `processed` once the original file is back in primary storage.
|
||||
- Trashed assets that are permanently purged automatically delete their original file from archive storage as well.
|
||||
4. **Folder & Version Stack Support**: Archiving a folder or version stack recursively archives all contained file assets. Restoring a folder or version stack restores all archived files inside it.
|
||||
|
||||
---
|
||||
|
||||
## Storage Topologies
|
||||
|
||||
Shumai supports flexible storage configurations where primary storage and archive storage can use different backends or storage providers:
|
||||
|
||||
| Topology | Main Storage | Archive Storage | Description |
|
||||
| :------------------------------------ | :----------- | :-------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Local NAS / Directory** | Local or S3 | `local` | Offload files to a mounted network folder (NFS / SMB) or a secondary cold disk array. |
|
||||
| **Separate S3 Bucket / Provider** | S3 or Local | `s3` | Stream files to a dedicated archive bucket on AWS S3, Wasabi, Backblaze B2, or Google Cloud Storage. |
|
||||
| **Same S3 Bucket (In-Place Tiering)** | AWS S3 | `s3` | Re-tier objects in-place on AWS S3 using cold storage classes (`GLACIER`, `GLACIER_IR`, `DEEP_ARCHIVE`) without re-uploading bytes over the network. |
|
||||
|
||||
---
|
||||
|
||||
## Configuration Variables
|
||||
|
||||
Configure archive storage by adding the following environment variables to your `.env` file or Docker Compose configuration.
|
||||
|
||||
### General Configuration
|
||||
|
||||
| Variable | Description | Required | Default |
|
||||
| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | :--------------- |
|
||||
| `ARCHIVE_STORAGE_BACKEND` | Storage backend for archives: `local` or `s3`. When unset, archive functionality is disabled in the WebUI. | No | Unset (Disabled) |
|
||||
| `CONCURRENCY_ARCHIVE` | Maximum concurrent archive and restore tasks executed by background workers. | No | `5` |
|
||||
| `SHUMAI_WORKERS` | Worker queues listened to by the application server: `all` (default), `none`, `agent` (or `ai`), `transcode`, `archive`. Set to `all` or `archive` to process tasks. | No | `all` |
|
||||
| `AUTO_ARCHIVE_INTERVAL_MINUTES` | Frequency (in minutes) of the background auto-archive scanner job. Accepts decimal numbers (e.g. `0.02` for testing). | No | `60` (1 hour) |
|
||||
|
||||
### Local Archive Storage
|
||||
|
||||
Used when `ARCHIVE_STORAGE_BACKEND=local`:
|
||||
|
||||
| Variable | Description | Required | Default |
|
||||
| :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | :--------------- |
|
||||
| `ARCHIVE_LOCAL_ROOT` | Host filesystem directory path where archived files are stored. Must not overlap with main local storage directory (`./data` or `./data/<S3_BUCKET>`). | Yes | Unset (Required) |
|
||||
|
||||
### S3 Archive Storage
|
||||
|
||||
Used when `ARCHIVE_STORAGE_BACKEND=s3`. Note that archive storage maintains its own configuration and **never falls back** to the primary `S3_*` environment variables:
|
||||
|
||||
| Variable | Description | Required | Default |
|
||||
| :--------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | :------------------------------------ |
|
||||
| `ARCHIVE_S3_BUCKET` | Destination S3 bucket for archived files (can be a dedicated bucket or the same bucket as `S3_BUCKET` for in-place tiering). | Yes | Unset (Required) |
|
||||
| `ARCHIVE_S3_ACCESS_KEY_ID` | Access key ID for the archive S3 service. | Yes | Unset (Required) |
|
||||
| `ARCHIVE_S3_SECRET_ACCESS_KEY` | Secret access key for the archive S3 service. | Yes | Unset (Required) |
|
||||
| `ARCHIVE_AWS_ENDPOINT_URL_S3` | S3 endpoint URL for archive storage (e.g. MinIO, Cloudflare R2, Google Cloud Storage). | No | Unset (AWS standard endpoint) |
|
||||
| `ARCHIVE_S3_REGION` | S3 region for the archive bucket. | No | `auto` |
|
||||
| `ARCHIVE_S3_FORCE_PATH_STYLE` | Use path-style S3 URLs (`true` for MinIO/path-style, `false` for virtual-hosted style). | No | `true` |
|
||||
| `ARCHIVE_S3_STORAGE_CLASS` | S3 storage class to apply to archived objects (e.g. `GLACIER`, `GLACIER_IR`, `DEEP_ARCHIVE`, `COLDLINE`). Required and must not be `STANDARD` when archiving to the same S3 bucket. | No | Unset |
|
||||
| `ARCHIVE_S3_USE_RESTORE_OBJECT` | Controls whether S3 `RestoreObject` is called before reading archived objects (`auto`, `true`, or `false`). | No | `auto` |
|
||||
| `ARCHIVE_S3_RESTORE_DAYS` | Number of days a restored temporary copy remains readable in S3 for asynchronous Glacier restores. | No | `1` |
|
||||
| `ARCHIVE_S3_RESTORE_TIER` | S3 Glacier retrieval tier (`Expedited`, `Standard`, or `Bulk`). Omit when using providers that do not require asynchronous retrieval. | No | Unset |
|
||||
| `ARCHIVE_RESTORE_POLL_INTERVAL_MS` | Milliseconds between status checks while waiting for an asynchronous cold storage restore. | No | `60000` (1 min initial, 5 min steady) |
|
||||
|
||||
---
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
### 1. Local NAS / Mounted Path
|
||||
|
||||
Ideal for self-hosted teams with on-premises Network Attached Storage (Synology, QNAP, TrueNAS, or an NFS/SMB share mounted to the host machine):
|
||||
|
||||
```env
|
||||
# Main storage on local disk or S3
|
||||
STORAGE_BACKEND=local
|
||||
LOCAL_STORAGE_PATH=./storage
|
||||
|
||||
# Archive storage pointing to your mounted NAS directory
|
||||
ARCHIVE_STORAGE_BACKEND=local
|
||||
ARCHIVE_LOCAL_ROOT=/mnt/nas/shumai-archive
|
||||
```
|
||||
|
||||
In `docker-compose.yaml`, mount the host NAS volume into the container:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
shumai:
|
||||
volumes:
|
||||
- /mnt/nas/shumai-archive:/mnt/nas/shumai-archive
|
||||
environment:
|
||||
ARCHIVE_STORAGE_BACKEND: local
|
||||
ARCHIVE_LOCAL_ROOT: /mnt/nas/shumai-archive
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. AWS S3 Glacier Instant Retrieval (Archive)
|
||||
|
||||
AWS S3 Glacier Instant Retrieval (`GLACIER_IR`) offers cold storage pricing with **millisecond retrieval latency**. Because objects in `GLACIER_IR` do not require an asynchronous `RestoreObject` request, restoring an asset to main storage is instantaneous.
|
||||
|
||||
#### Same-Bucket In-Place Tiering (Fast Path)
|
||||
|
||||
If your main storage is AWS S3, you can tier files into `GLACIER_IR` within the **same bucket** without re-uploading bytes over the network:
|
||||
|
||||
```env
|
||||
# Main Storage
|
||||
STORAGE_BACKEND=s3
|
||||
S3_BUCKET=my-shumai-production
|
||||
S3_REGION=us-east-1
|
||||
S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
|
||||
S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
|
||||
AWS_ENDPOINT_URL_S3=https://s3.us-east-1.amazonaws.com
|
||||
|
||||
# Archive Storage (same bucket & credentials with cold storage class)
|
||||
ARCHIVE_STORAGE_BACKEND=s3
|
||||
ARCHIVE_S3_BUCKET=my-shumai-production
|
||||
ARCHIVE_S3_REGION=us-east-1
|
||||
ARCHIVE_S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
|
||||
ARCHIVE_S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
|
||||
ARCHIVE_AWS_ENDPOINT_URL_S3=https://s3.us-east-1.amazonaws.com
|
||||
ARCHIVE_S3_STORAGE_CLASS=GLACIER_IR
|
||||
```
|
||||
|
||||
#### Dedicated Archive Bucket
|
||||
|
||||
If you prefer keeping archived media in a separate S3 bucket:
|
||||
|
||||
```env
|
||||
# Archive Storage in a separate bucket
|
||||
ARCHIVE_STORAGE_BACKEND=s3
|
||||
ARCHIVE_S3_BUCKET=my-shumai-archive-glacier-ir
|
||||
ARCHIVE_S3_REGION=us-east-1
|
||||
ARCHIVE_S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
|
||||
ARCHIVE_S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
|
||||
ARCHIVE_AWS_ENDPOINT_URL_S3=https://s3.us-east-1.amazonaws.com
|
||||
ARCHIVE_S3_STORAGE_CLASS=GLACIER_IR
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. AWS S3 Glacier Flexible Archive (Cold Storage)
|
||||
|
||||
For maximum cost savings on rarely accessed footage, AWS S3 Flexible Archive (`GLACIER`) or Deep Archive (`DEEP_ARCHIVE`) stores data at the lowest storage rates.
|
||||
|
||||
When a user restores an asset from Glacier, Shumai initiates a `RestoreObject` request, puts the background workflow into durable DBOS sleep, and periodically checks until AWS completes the retrieval:
|
||||
|
||||
```env
|
||||
ARCHIVE_STORAGE_BACKEND=s3
|
||||
ARCHIVE_S3_BUCKET=my-shumai-cold-archive
|
||||
ARCHIVE_S3_REGION=us-east-1
|
||||
ARCHIVE_S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
|
||||
ARCHIVE_S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
|
||||
ARCHIVE_AWS_ENDPOINT_URL_S3=https://s3.us-east-1.amazonaws.com
|
||||
ARCHIVE_S3_STORAGE_CLASS=GLACIER
|
||||
|
||||
# Keep the restored temporary copy accessible for 7 days
|
||||
ARCHIVE_S3_RESTORE_DAYS=7
|
||||
|
||||
# Glacier retrieval tier: Standard (3-5 hours), Expedited (1-5 min), or Bulk (5-12 hours)
|
||||
ARCHIVE_S3_RESTORE_TIER=Standard
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> During a Glacier restore, DBOS schedules durable sleep timers in PostgreSQL. The worker thread is completely freed and does not consume concurrency slots while waiting for AWS to thaw the file.
|
||||
|
||||
---
|
||||
|
||||
### 4. Google Cloud Storage Coldline (Archive)
|
||||
|
||||
Google Cloud Storage (GCS) provides S3-compatible XML APIs and low-cost storage classes such as `COLDLINE` and `ARCHIVE`. Like Glacier Instant Retrieval, GCS Coldline provides **immediate access** without requiring an asynchronous thaw step:
|
||||
|
||||
```env
|
||||
# Main storage (e.g. Cloudflare R2, MinIO, or standard GCS)
|
||||
STORAGE_BACKEND=s3
|
||||
S3_BUCKET=shumai-main
|
||||
...
|
||||
|
||||
# Archive storage on GCS Coldline
|
||||
ARCHIVE_STORAGE_BACKEND=s3
|
||||
ARCHIVE_S3_BUCKET=shumai-coldline-archive
|
||||
ARCHIVE_S3_ACCESS_KEY_ID=GOOG1EXAMPLETOCKENKEY
|
||||
ARCHIVE_S3_SECRET_ACCESS_KEY=your-gcs-hmac-secret-access-key
|
||||
ARCHIVE_AWS_ENDPOINT_URL_S3=https://storage.googleapis.com
|
||||
ARCHIVE_S3_STORAGE_CLASS=COLDLINE
|
||||
```
|
||||
|
||||
> [!TIP]
|
||||
> Google Cloud Storage objects are readable immediately and do not accept AWS Glacier retrieval parameters. Do not set `ARCHIVE_S3_RESTORE_TIER`. If using GCS's `ARCHIVE` storage class, set `ARCHIVE_S3_USE_RESTORE_OBJECT=false` to bypass S3 `RestoreObject` calls.
|
||||
|
||||
---
|
||||
|
||||
## Automatic Asset Archival
|
||||
|
||||
In addition to manual on-demand archival, Shumai allows teams to automate cold storage tiering based on asset age lifecycle policies. This ensures heavy original master files are automatically offloaded to secondary cold storage without requiring manual housekeeping from creative staff or administrators.
|
||||
|
||||
### WebUI Configuration
|
||||
|
||||
Team owners can configure automatic archival under **Team Settings > Storage**:
|
||||
|
||||
1. **Archive Storage Status Overview**:
|
||||
- Displays the current system archive storage backend (`local` or `s3`), endpoint, bucket, or root directory configured on the server.
|
||||
- If archive storage is not configured in server environment variables, a warning alert is displayed, and auto-archive controls are disabled.
|
||||
- For security, credentials and private server settings are not exposed to client browsers.
|
||||
|
||||
2. **Automatic Asset Archival Policy**:
|
||||
- **Enable Auto Archive**: Toggle automated background archival on or off for the team (disabled by default; requires an active archive storage backend).
|
||||
- **Archive Criteria (`method`)**:
|
||||
- **Not modified for specified days (`not_updated`)**: Evaluates the last modification timestamp (`updatedAt`). Ideal for active production workflows—files stay in fast primary storage as long as team members are actively commenting, annotating, or modifying them. Once no modifications have occurred for the configured duration, the asset is moved to cold storage.
|
||||
- **After creation for specified days (`after_created`)**: Evaluates the initial upload/creation timestamp (`createdAt`). Ideal for strict retention or compliance pipelines where footage is tiered based on its age (e.g., 60 or 90 days after delivery) regardless of recent review comments.
|
||||
- **Age Threshold (`days`)**: The threshold in days (between 1 and 3,650 days) after which eligible assets are queued for archival.
|
||||
- **Post-Restore Grace Period (`postRestoreGraceDays`)**:
|
||||
- When an asset is restored from archive back to primary storage, its modification date is refreshed to the restore time.
|
||||
- When using the **After creation** rule, an asset older than the threshold (e.g. 100 days old) would otherwise be immediately picked up and re-archived by the very next hourly scan.
|
||||
- The post-restore grace period (default: 30 days) guarantees that restored files remain in primary storage for at least the specified number of days before becoming eligible for automated archival again. This value should be set smaller than the Age Threshold. Under this policy, only files that are older than the Age Threshold and have also surpassed the Post-Restore Grace Period since restoration are auto-archived.
|
||||
|
||||
### Sibling Deduplication & Safety
|
||||
|
||||
Shumai uses content-addressable storage keys (`storage_keys`) to deduplicate identical files across projects and folders:
|
||||
|
||||
- **Sibling Protection**: If multiple asset records reference the same underlying storage object (e.g., copied or duplicated files across folders or projects), the auto-archive scanner inspects all sibling assets.
|
||||
- **Strict Consensus**: The underlying storage file is **only** archived if **all active sibling files** satisfy the team's auto-archive criteria and are in a stable `processed` state.
|
||||
- **Starvation-Free Scheduling**: If any sibling copy was modified recently or is currently in an active workflow, the storage key is safely skipped without blocking other eligible assets from being archived.
|
||||
|
||||
### Background Scanner & Execution Semantics
|
||||
|
||||
The auto-archive job runs periodically in the background:
|
||||
|
||||
- **Scan Frequency**: Configured via the `AUTO_ARCHIVE_INTERVAL_MINUTES` environment variable (defaults to `60` minutes; accepts decimal values such as `0.02` for automated testing).
|
||||
- **Distributed Leader Election**: Uses PostgreSQL transaction-scoped advisory locks (`pg_try_advisory_xact_lock`) during the candidate discovery phase. In multi-pod or multi-replica container deployments, only one server instance performs the scan per interval while other replicas cleanly skip.
|
||||
- **Race Condition Prevention**: During archival, candidate assets transition atomically via conditional SQL (`UPDATE assets SET status = 'archiving' WHERE status = 'processed'`) protected by row-level `storage_keys FOR UPDATE` locks. This guarantees zero race conditions with concurrent manual user archival, restoration, or file deletion.
|
||||
|
||||
---
|
||||
|
||||
## WebUI Behavior & Permissions
|
||||
|
||||
- **Permissions**: Only team **Owners** and **Editors** can archive or restore assets.
|
||||
- **Context Menus**: Right-click any file, folder, or version stack in the file browser to select **Archive** or **Restore from Archive**.
|
||||
- **Visual Badges**: Archived items display an `Archived` badge on grid cards and list rows. Inside the file viewer, an archive icon is displayed in front of the file name in the breadcrumb bar.
|
||||
- **Playback & Previews**: Video streaming, scrubbers, waveform audio, PDF rendering, and image viewing remain fully functional using cached proxies.
|
||||
- **Download Restrictions**: The download button for the original raw file is disabled with a tooltip explaining that the raw file is archived. Transcoded proxy downloads (e.g. 1080p MP4) remain available.
|
||||
@@ -0,0 +1,119 @@
|
||||
---
|
||||
title: Deploy with Distributed Workers
|
||||
description: Run media transcoding on dedicated workers while agents run with the main server.
|
||||
---
|
||||
|
||||
Shumai runs agent, embedding, and archive queues with the main web server. Media transcoding can run on dedicated workers through PostgreSQL queues managed by DBOS Transact.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
User[User] --> Server[Shumai Web UI / API + Agents + Archives]
|
||||
Server --> DB[(PostgreSQL / DBOS Queues)]
|
||||
DB --> Transcode[Dedicated Transcode Workers]
|
||||
```
|
||||
|
||||
## Main Server
|
||||
|
||||
Set `SHUMAI_WORKERS=none` (or `--workers=none`) to run agents and archives with the main server and send transcoding jobs to dedicated workers. `all` and `transcode` also run the transcode queue in the server. The older `agent`, `ai`, and `archive` values remain accepted and run agents and archives.
|
||||
|
||||
```env
|
||||
DATABASE_URL=postgresql://shumai:shumai_password@localhost:5432/shumai_db?schema=public
|
||||
STORAGE_BACKEND=s3
|
||||
AWS_ENDPOINT_URL_S3=https://your-s3-endpoint.com
|
||||
S3_BUCKET=shumai
|
||||
S3_REGION=us-east-1
|
||||
S3_ACCESS_KEY_ID=your-access-key-id
|
||||
S3_SECRET_ACCESS_KEY=your-secret-access-key
|
||||
SHUMAI_WORKERS=none
|
||||
BETTER_AUTH_SECRET=your-random-32-character-secret-key
|
||||
```
|
||||
|
||||
Agent tools run on the server, so install its sandbox dependencies (`bubblewrap` on Linux or `sandbox-exec` on macOS). Standalone agent workers are no longer supported.
|
||||
|
||||
## Dedicated Transcode Workers
|
||||
|
||||
Configure workers with the same PostgreSQL database and S3 storage as the server. A shared S3-compatible backend is required when machines do not share a filesystem.
|
||||
|
||||
```bash
|
||||
npm install -g @shumai-one/shumai-transcode
|
||||
shumai-transcode
|
||||
```
|
||||
|
||||
Or use the dedicated image:
|
||||
|
||||
```bash
|
||||
docker run -d --name shumai-transcode-worker --env-file .env shumaione/shumai-transcode:latest
|
||||
```
|
||||
|
||||
Bun users can run `bun run --bun shumai-transcode`.
|
||||
|
||||
## Upgrading Existing Agent Sessions
|
||||
|
||||
Stop and drain old agent workers before upgrading the server. The normal database migration copies existing session context into independent histories automatically. No separate migration command is required. Legacy records remain in the database during this transition.
|
||||
|
||||
Each session uses a local SQLite working copy, restored from PostgreSQL when missing. `AGENT_SESSION_CACHE_DIR` optionally selects the cache directory. Within each server process, history reads and the active agent share the same SQLite database. History can show locally committed entries before PostgreSQL persistence completes; these entries may disappear after recovery if persistence fails. The server mirrors compact session commits to PostgreSQL before acknowledging them. Keep the database in your backup policy; local SQLite copies are disposable. Image and skill placeholders remain compact in both copies and are resolved when the agent needs them.
|
||||
|
||||
---
|
||||
|
||||
## Worker Concurrency & Multi-Instance Deployments
|
||||
|
||||
### Concurrency Tuning
|
||||
|
||||
Workers pull tasks from PostgreSQL queues based on configurable concurrency limits:
|
||||
|
||||
- `CONCURRENCY_TRANSCODE`: Maximum concurrent video transcoding jobs per worker (defaults to `1`).
|
||||
- `CONCURRENCY_AGENT`: Maximum concurrent agent and embedding workflows per main server (defaults to `5`, recommend setting to `1` when paired with a local `embedding-server`).
|
||||
|
||||
### Replica Identity
|
||||
|
||||
When running multiple replicas of the transcode workers or main servers across multiple machines or pods:
|
||||
|
||||
- `DbosExecutor` automatically derives a unique per-instance ID from the machine hostname and process ID to ensure startup recovery only re-enqueues tasks belonging to that specific instance.
|
||||
- **Custom Worker ID**: Set `SHUMAI_WORKERS_ID` (or `SHUMAI_WORKER_ID`) if you wish to assign an explicit identifier.
|
||||
- **Kubernetes**: In Kubernetes Pods, set `POD_NAME` (via Downward API `fieldRef: { fieldPath: metadata.name }`) to provide stable, unique per-pod identity across pod restarts.
|
||||
|
||||
Agent runners require a single main server per database. With runners configured, stop the old main server before starting its replacement. For Kubernetes, use a single main server replica with the Recreate deployment strategy. Transcode workers can still scale independently.
|
||||
|
||||
---
|
||||
|
||||
## Scalable Deployment on Kubernetes & AWS EKS
|
||||
|
||||
For production cloud deployments requiring high-throughput media processing, Shumai can be deployed on Kubernetes or **AWS Elastic Kubernetes Service (AWS EKS)** with automated scale-to-zero queue-driven scaling via **KEDA (Kubernetes Event-driven Autoscaling)**.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
User([User / Web Browser]) -->|Port 80/3000| Server[Pod: shumai-server<br/>SHUMAI_WORKERS=agent]
|
||||
Server -->|Enqueue to transcode_queue| DB[(PostgreSQL: pgvector18<br/>dbos.workflow_status)]
|
||||
Server -->|Direct Uploads / Stream Proxies| Storage[(S3 / Garage Storage)]
|
||||
|
||||
KEDA[KEDA ScaledJob<br/>PostgreSQL Trigger<br/>min: 0, max: 10] -.->|Monitors Queue| DB
|
||||
KEDA -->|Spawns Jobs for queue| Job1[Job: shumai-transcode-1<br/>Auto-drain worker]
|
||||
KEDA -->|Spawns Jobs for queue| JobN[Job: shumai-transcode-N<br/>Auto-drain worker]
|
||||
|
||||
Job1 -->|Fetch Source / Store Proxies| Storage
|
||||
JobN -->|Fetch Source / Store Proxies| Storage
|
||||
Job1 -->|Mark Complete & Exit 0| DB
|
||||
JobN -->|Mark Complete & Exit 0| DB
|
||||
|
||||
CA[Cluster Autoscaler / Karpenter] -.->|Scale-to-Zero On-Demand Nodes<br/>0 to 10 instances| JobN
|
||||
```
|
||||
|
||||
### Key Architectural Highlights
|
||||
|
||||
- **Decoupled Stateless Workers**: The main web and API server, database, and storage run on reliable On-Demand compute (`c9g.large`, `SHUMAI_WORKERS=agent`), delegating media transcoding to background workers orchestrated via DBOS task queues in PostgreSQL.
|
||||
- **Dedicated Graviton5 On-Demand Compute (`c9g.xlarge`)**: Media encoding runs on 4 vCPU / 8 GiB RAM AWS Graviton5 On-Demand instances (~$0.174/hr), utilizing ARM64 vector optimizations and high-speed DDR5 memory without involuntary Spot interruptions.
|
||||
- **Queue-Driven Scale-to-Zero via KEDA**: KEDA monitors `dbos.workflow_status` for enqueued and pending transcode tasks and dynamically provisions Kubernetes `ScaledJob` resources (scaling 0 to 10). When the queue is empty, transcode nodes scale down to zero (`minSize: 0`), incurring **$0/hr** in worker costs.
|
||||
- **Idle-Timeout Auto-Drain**: Worker pods continuously process queued tasks with concurrency `1`. When the queue is fully drained and a pod has been idle for 10 seconds (`SHUMAI_WORKER_IDLE_TIMEOUT_MS=10000`), it exits `0` cleanly so the node can scale down, processing batch uploads without cold-start pod churn.
|
||||
- **Automated Stale Task Recovery**: The core web server runs an integrated recovery sweep that detects stale or orphaned tasks (e.g. from node crash) and resumes them automatically in DBOS, with a 3-attempt cap to safely handle poison-pill media.
|
||||
|
||||
### Complete Deployment Example & Source Code
|
||||
|
||||
For the full, production-ready manifests, declarative `eksctl` cluster configuration, and step-by-step walkthrough, see the **[EKS Deployment Example](https://github.com/shumaiOne/shumai/tree/main/eks)** in the Shumai repository:
|
||||
|
||||
👉 **[View the EKS Deployment Guide & Manifests on GitHub](https://github.com/shumaiOne/shumai/tree/main/eks)**
|
||||
|
||||
The repository includes:
|
||||
|
||||
- [`eks/eks-cluster.yaml`](https://github.com/shumaiOne/shumai/blob/main/eks/eks-cluster.yaml): Complete `eksctl` ClusterConfig with compute tiering.
|
||||
- [`eks/kustomization.yaml`](https://github.com/shumaiOne/shumai/blob/main/eks/kustomization.yaml): Single-command Kustomize deployment for all services.
|
||||
- Detailed instructions for setting up public endpoints, automated Cluster Autoscaler, and zero-downtime graceful shutdown.
|
||||
@@ -24,12 +24,13 @@ Shumai is configured via environment variables. You can define these variables i
|
||||
|
||||
---
|
||||
|
||||
## Authentication Config
|
||||
## Authentication & Application Config
|
||||
|
||||
| Variable | Description | Example / Default |
|
||||
| :------------------- | :--------------------------------------------------------------------- | :--------------------------------------------------------------- |
|
||||
| `BETTER_AUTH_SECRET` | A secure, random 32-byte secret used to sign session cookies and JWTs. | Generate with `openssl rand -base64 32` |
|
||||
| `BETTER_AUTH_URL` | The public URL of your Hono backend API. Used for redirect flows. | `http://localhost:3000` (respects `SHUMAI_SERVER_PORT` fallback) |
|
||||
| Variable | Description | Example / Default |
|
||||
| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------- |
|
||||
| `BETTER_AUTH_SECRET` | A secure, random 32-byte secret used to sign session cookies and JWTs. | Generate with `openssl rand -base64 32` |
|
||||
| `BETTER_AUTH_URL` | The public URL of your Shumai server. Used for MCP OAuth 2.1 discovery, redirect flows, password reset links, and email notifications. | `http://localhost:3000` (respects `SHUMAI_SERVER_PORT` fallback) |
|
||||
| `APP_URL` | The public URL of the web application. Used for notification email deep links (falls back to `BETTER_AUTH_URL`). | `https://shumai.example.com` |
|
||||
|
||||
---
|
||||
|
||||
@@ -37,15 +38,16 @@ Shumai is configured via environment variables. You can define these variables i
|
||||
|
||||
Shumai supports storing files locally or on S3-compatible endpoints.
|
||||
|
||||
| Variable | Description | Example / Default |
|
||||
| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------ |
|
||||
| `STORAGE_BACKEND` | Storage type. Use `local` for local file system storage, or `s3` for S3-compatible cloud storage. | `local` (default) or `s3` |
|
||||
| `AWS_ENDPOINT_URL_S3` | Endpoint for S3 storage or local storage. Used by the browser to build file upload URLs. Must include port if deploying remotely or using custom ports. | `http://localhost:3000` (respects `SHUMAI_SERVER_PORT` fallback if unset) |
|
||||
| `S3_BUCKET` | S3 bucket name. | `shumai` (default) |
|
||||
| `S3_ACCESS_KEY_ID` | Access key credentials for S3. | `minioadmin` (default) |
|
||||
| `S3_SECRET_ACCESS_KEY` | Secret key credentials for S3. | `minioadmin` (default) |
|
||||
| `S3_REGION` | S3 storage region. | `auto` (default) |
|
||||
| `PRESIGNED_URL_EXPIRES_IN` | Number of hours for which generated presigned download/upload links are valid. | `5` (default) |
|
||||
| Variable | Description | Example / Default |
|
||||
| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------ |
|
||||
| `STORAGE_BACKEND` | Storage type. Use `local` for local file system storage, or `s3` for S3-compatible cloud storage. | `local` (default) or `s3` |
|
||||
| `AWS_ENDPOINT_URL_S3` | Endpoint for S3 storage or local storage. Used by the browser to build file upload URLs. Must include port if deploying remotely or using custom ports. | `http://localhost:3000` (respects `SHUMAI_SERVER_PORT` fallback if unset) |
|
||||
| `S3_BUCKET` | S3 bucket name. | `shumai` (default) |
|
||||
| `S3_ACCESS_KEY_ID` | Access key credentials for S3. | `minioadmin` (default) |
|
||||
| `S3_SECRET_ACCESS_KEY` | Secret key credentials for S3. | `minioadmin` (default) |
|
||||
| `S3_REGION` | S3 storage region. | `auto` (default) |
|
||||
| `PRESIGNED_URL_EXPIRES_IN` | Number of hours for which generated presigned download links are valid. | `5` (default) |
|
||||
| `PRESIGNED_UPLOAD_URL_EXPIRES_IN` | Number of hours for which generated presigned upload links are valid. Falls back to `PRESIGNED_URL_EXPIRES_IN` if unset. | `12` (default) |
|
||||
|
||||
### Local Storage Port Configuration
|
||||
|
||||
@@ -59,18 +61,51 @@ For example, if you deploy Shumai on a remote server at `http://123.456.7.8` and
|
||||
- Set `SHUMAI_SERVER_PORT` to `3000`.
|
||||
- Set `AWS_ENDPOINT_URL_S3` to `http://123.456.7.8:12345`.
|
||||
|
||||
### Archive Storage Config
|
||||
|
||||
Shumai supports configuring an optional **Archive Storage** tier (`local` NAS/directory or `s3` bucket/storage class) for moving original raw files while keeping proxies, previews, thumbnails, and metadata in main storage.
|
||||
|
||||
| Variable | Description | Example / Default |
|
||||
| :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------- |
|
||||
| `ARCHIVE_STORAGE_BACKEND` | Archive storage type. Leave unset to disable archive storage, or set to `local` or `s3`. | Unset (disabled), `local`, or `s3` |
|
||||
| `ARCHIVE_LOCAL_ROOT` | Required when `ARCHIVE_STORAGE_BACKEND=local`. Root directory (e.g., a mounted NAS folder) where archived original files are stored directly under `<ARCHIVE_LOCAL_ROOT>/<key>`. | `/mnt/nas/shumai-archive` |
|
||||
| `ARCHIVE_AWS_ENDPOINT_URL_S3` | Optional custom S3 endpoint for archive storage when `ARCHIVE_STORAGE_BACKEND=s3` (independent of `AWS_ENDPOINT_URL_S3`). | `https://s3.us-east-1.amazonaws.com` |
|
||||
| `ARCHIVE_S3_BUCKET` | Required when `ARCHIVE_STORAGE_BACKEND=s3`. Target S3 bucket for archived files (can be a dedicated bucket or the same bucket as `S3_BUCKET` with a cold storage class). | `shumai-archive` |
|
||||
| `ARCHIVE_S3_ACCESS_KEY_ID` | Required when `ARCHIVE_STORAGE_BACKEND=s3`. S3 access key ID for archive storage. | `AKIA...` |
|
||||
| `ARCHIVE_S3_SECRET_ACCESS_KEY` | Required when `ARCHIVE_STORAGE_BACKEND=s3`. S3 secret access key for archive storage. | `...` |
|
||||
| `ARCHIVE_S3_REGION` | S3 region for archive storage when `ARCHIVE_STORAGE_BACKEND=s3`. | `auto` (default) |
|
||||
| `ARCHIVE_S3_STORAGE_CLASS` | Optional S3 `StorageClass` header applied when archiving objects (accepts any standard or provider-specific class string; required and must not be `STANDARD` for same-bucket tiering). | `GLACIER_IR`, `GLACIER`, `DEEP_ARCHIVE`, `STANDARD_IA` |
|
||||
| `ARCHIVE_S3_USE_RESTORE_OBJECT` | Controls whether S3 `RestoreObject` is called before reading archived objects (`auto`, `true`, or `false`). | `auto` (default) |
|
||||
| `ARCHIVE_S3_RESTORE_DAYS` | Number of days a restored copy of a cold S3 object remains readable during restoration. | `1` (default) |
|
||||
| `ARCHIVE_S3_RESTORE_TIER` | Optional S3 Glacier retrieval tier (`Expedited`, `Standard`, `Bulk`). Omitted when unset for S3-compatible providers that reject `GlacierJobParameters`. | Unset (default) |
|
||||
| `AUTO_ARCHIVE_INTERVAL_MINUTES` | Frequency (in minutes) of the background auto-archive scanner job. Accepts decimal values (e.g. `0.02` for testing). | `60` (1 hour default) |
|
||||
|
||||
---
|
||||
|
||||
## Workflow Config
|
||||
|
||||
Configures whether background transcoding and AI agents are executed locally or offloaded to a Temporal cluster.
|
||||
Configures background worker execution, concurrency limits, and worker identity for DBOS Transact queues.
|
||||
|
||||
| Variable | Description | Example / Default |
|
||||
| :------------------------- | :------------------------------------------------------------------------------------------------- | :------------------------------ |
|
||||
| `WORKFLOW_EXECUTOR` | Engine choice. Use `local` for in-process database polling, or `temporal` for distributed workers. | `local` (default) or `temporal` |
|
||||
| `TEMPORAL_ADDRESS` | Host and port of the Temporal cluster gRPC service. | `localhost:7233` (default) |
|
||||
| `EMBEDDING_CHUNK_DURATION` | The duration in seconds for each video chunk when generating video embeddings. | `60.0` (default) |
|
||||
| `EMBEDDING_CHUNK_OVERLAP` | The duration in seconds to overlap video chunks when generating video embeddings. | `5.0` (default) |
|
||||
| Variable | Description | Example / Default |
|
||||
| :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------- | :---------------- |
|
||||
| `SHUMAI_WORKERS` | Queues listened to by the web server. Options: `all` (default), `none` (API/UI only), `agent` (or `ai`), `transcode`, `archive`. | `all` (default) |
|
||||
| `CONCURRENCY_TRANSCODE` | Maximum concurrent media transcoding tasks executed by workers. | `1` (default) |
|
||||
| `CONCURRENCY_ARCHIVE` | Maximum concurrent archive and restore tasks executed by workers. | `5` (default) |
|
||||
| `CONCURRENCY_AGENT` | Maximum concurrent AI tasks executed by workers. Set to `1` when running local `embedding-server`. | `5` (default) |
|
||||
| `SHUMAI_WORKER_ID` | Optional explicit instance ID for worker replicas in multi-node deployments (auto-derived from hostname and process ID if unset). | `worker-1` |
|
||||
| `POD_NAME` | Kubernetes pod name, used to provide stable per-pod worker identity across StatefulSet restarts. | `transcode-pod-0` |
|
||||
|
||||
---
|
||||
|
||||
## Embedding Config
|
||||
|
||||
| Variable | Description | Example / Default |
|
||||
| :-------------------------------- | :------------------------------------------------------------------------------------------------------------ | :-------------------------------- |
|
||||
| `EMBEDDING_PROVIDER` | Multimodal embedding provider. Options: `gemini-embedding-2`, `gemma-embedding-2-openai`. | `gemini-embedding-2` (default) |
|
||||
| `GEMMA_EMBEDDING_OPENAI_BASE_URL` | Base URL of the OpenAI-compatible LiteRT-LM embedding server. | `http://embedding-server:9379/v1` |
|
||||
| `ENABLE_EMBEDDING_AGENT` | When set to `true`, automatically provisions and enables the system embedding agent for all teams on startup. | `false` (default) |
|
||||
| `EMBEDDING_CHUNK_DURATION` | The duration in seconds for each video chunk when generating video embeddings. | `60.0` (default) |
|
||||
| `EMBEDDING_CHUNK_OVERLAP` | The duration in seconds to overlap video chunks when generating video embeddings. | `5.0` (default) |
|
||||
|
||||
## Sandbox Config
|
||||
|
||||
@@ -98,3 +133,29 @@ API keys to AI providers on startup.
|
||||
| `GEMINI_API_KEY` | API key for Google Gemini provider. | `AIzaSy...` |
|
||||
| `OPENAI_API_KEY` | API key for OpenAI provider. | `sk-proj-...` |
|
||||
| `ANTHROPIC_API_KEY` | API key for Anthropic provider. | `sk-ant-...` |
|
||||
|
||||
---
|
||||
|
||||
## External Integrations Config
|
||||
|
||||
Environment variables can configure external microservices globally. When set, these environment variables take precedence over any team-level settings configured in **Team Settings → Integrations**, and lock the corresponding settings fields in the WebUI to read-only.
|
||||
|
||||
### Gotenberg Document Converter
|
||||
|
||||
Used to convert Office documents, HTML, Markdown, and CSV files into high-fidelity PDF proxies for in-browser previewing. See the [Gotenberg Guide](/using-shumai/gotenberg) for setup instructions.
|
||||
|
||||
| Variable | Description | Example / Default |
|
||||
| :------------------------------ | :----------------------------------------------------------------------- | :---------------------- |
|
||||
| `GOTENBERG_URL` | Base URL of the external Gotenberg conversion API. | `http://gotenberg:3000` |
|
||||
| `GOTENBERG_BASIC_AUTH_USERNAME` | Username when Basic Authentication is enabled on the Gotenberg instance. | `admin` |
|
||||
| `GOTENBERG_BASIC_AUTH_PASSWORD` | Password when Basic Authentication is enabled on the Gotenberg instance. | `secret` |
|
||||
|
||||
### 3D Turntable Renderer
|
||||
|
||||
Used to convert 3D model files (GLB, OBJ, FBX, USD, STL, DAE) into interactive 360° turntable video proxies, posters, and hover sprites. See the [3D Asset Support Guide](/using-shumai/3d-asset-support) for setup instructions.
|
||||
|
||||
| Variable | Description | Example / Default |
|
||||
| :--------------------------------------- | :-------------------------------------------------------------------------------------------------------------- | :------------------------------- |
|
||||
| `TURNTABLE_RENDERER_URL` | Base URL of the external turntable-renderer service. | `http://turntable-renderer:3000` |
|
||||
| `TURNTABLE_RENDERER_BASIC_AUTH_USERNAME` | Username when Basic Authentication is enabled on the turntable renderer (alias: `TURNTABLE_RENDERER_USERNAME`). | `admin` |
|
||||
| `TURNTABLE_RENDERER_BASIC_AUTH_PASSWORD` | Password when Basic Authentication is enabled on the turntable renderer (alias: `TURNTABLE_RENDERER_PASSWORD`). | `secret` |
|
||||
|
||||
@@ -0,0 +1,233 @@
|
||||
---
|
||||
title: Hardware Transcoding
|
||||
description: Accelerate video transcoding and reduce CPU load with GPU hardware acceleration.
|
||||
---
|
||||
|
||||
High-resolution camera recordings, phone videos, and animation media files require proxy transcoding to play smoothly in web browsers. Shumai transcodes these assets in the background, generating a universal `180p` proxy for instant scrubbing alongside full-resolution preview streams.
|
||||
|
||||
Hardware-accelerated transcoding allows you to offload video encoding to a dedicated or integrated GPU, dramatically speeding up processing and freeing host CPU cores for other services.
|
||||
|
||||
Shumai includes a built-in usability probe that tests hardware encoders at startup, alongside automatic runtime fallback during video processing. If GPU drivers or device nodes are unavailable, or if a hardware encoder encounters hardware limits (such as resolution or dimension constraints on certain GPUs) or runtime driver errors, Shumai seamlessly falls back to software encoding (`libx264`) without failing user tasks.
|
||||
|
||||
---
|
||||
|
||||
## Supported Backends
|
||||
|
||||
| Backend | Hardware Platform | Container Driver / Devices |
|
||||
| :-------------- | :--------------------------------- | :----------------------------------------------- |
|
||||
| **`nvenc`** | NVIDIA GPUs | NVIDIA Container Toolkit (`gpu, compute, video`) |
|
||||
| **`quicksync`** | Intel Integrated & Arc GPUs | `/dev/dri` render nodes |
|
||||
| **`vaapi`** | AMD & Intel GPUs | `/dev/dri` render nodes |
|
||||
| **`rkmpp`** | Rockchip ARM SoCs (e.g. RK3588) | `/dev/rga`, `/dev/dri`, `/dev/mpp_service` |
|
||||
| **`vaapi-wsl`** | Windows Subsystem for Linux (WSL2) | `/dev/dri`, `/dev/dxg`, `/usr/lib/wsl` |
|
||||
|
||||
---
|
||||
|
||||
## Limitations
|
||||
|
||||
- The instructions on this page focus on **Docker Compose**. Other container orchestrators (such as Kubernetes or Podman) require equivalent device passthrough configurations.
|
||||
- **Docker Desktop on macOS** runs inside a Linux virtual machine and does not support Apple Silicon VideoToolbox passthrough. (VideoToolbox hardware acceleration is supported when running Shumai natively via NPM or from source).
|
||||
- Hardware transcoding produces slightly different bitrate characteristics compared to software encoding. Shumai uses adaptive variable bitrate (VBR) rate control tailored to web streaming to maintain visual fidelity.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### NVENC (NVIDIA)
|
||||
|
||||
1. Ensure the official NVIDIA graphics driver is installed on the host:
|
||||
```bash
|
||||
nvidia-smi
|
||||
```
|
||||
2. Install the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) on the host and restart Docker:
|
||||
```bash
|
||||
sudo apt-get install -y nvidia-container-toolkit
|
||||
sudo nvidia-ctk runtime configure --runtime=docker
|
||||
sudo systemctl restart docker
|
||||
```
|
||||
|
||||
### QuickSync & VA-API (Intel / AMD)
|
||||
|
||||
1. Verify that the Linux kernel has initialized the Direct Rendering Infrastructure (DRI) render node:
|
||||
```bash
|
||||
ls -la /dev/dri
|
||||
```
|
||||
You should see `card0` and `renderD128` (or similar).
|
||||
2. Shumai's Docker image automatically adjusts group permissions on container startup so the non-root application user can access host `/dev/dri` devices without permission errors.
|
||||
|
||||
#### GPU decoding
|
||||
|
||||
With VA-API, Shumai decodes and resizes video on the GPU as well as encoding it, so frames never leave GPU memory. This is much faster than decoding on the CPU, especially for 4K sources on integrated graphics. (Other backends currently decode on the CPU and encode on the GPU.)
|
||||
|
||||
Some videos automatically use CPU decoding with GPU encoding instead:
|
||||
|
||||
- Codecs your GPU cannot decode, such as HEVC or 10-bit video on older Intel chips. Shumai tries the GPU first and retries on the CPU within a second.
|
||||
- Rotated videos, such as portrait phone recordings, so they keep the correct orientation.
|
||||
- Watermarked share links and HDR sources.
|
||||
|
||||
If a GPU-decode attempt stops making progress for 2 minutes (some driver bugs make ffmpeg hang instead of failing), Shumai stops it and retries on the CPU. Change the limit with `SHUMAI_HW_DECODE_STALL_TIMEOUT` (in seconds).
|
||||
|
||||
To always decode on the CPU, set `SHUMAI_HW_DECODE=false` on the `shumai` service.
|
||||
|
||||
### WSL2 (Windows)
|
||||
|
||||
- Ensure you are running Windows 11 with WSL2 and have installed the appropriate GPU drivers on the Windows host.
|
||||
- Use the `vaapi-wsl` preset which maps `/dev/dxg` and `/usr/lib/wsl` into the container.
|
||||
|
||||
---
|
||||
|
||||
## Setup with Docker Compose
|
||||
|
||||
Shumai uses a modular `hwaccel.transcoding.yaml` companion file to configure hardware devices.
|
||||
|
||||
### Step 1: Download Configuration Files
|
||||
|
||||
In your Shumai deployment directory, download the companion `hwaccel.transcoding.yaml` alongside `docker-compose.yaml`:
|
||||
|
||||
```bash
|
||||
# Global / Official
|
||||
curl -o hwaccel.transcoding.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/hwaccel.transcoding.yaml
|
||||
|
||||
# Accelerated Mirror (Mainland China)
|
||||
curl -o hwaccel.transcoding.yaml https://gh-proxy.com/https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/hwaccel.transcoding.yaml
|
||||
```
|
||||
|
||||
### Step 2: Enable Hardware Acceleration in Docker Compose
|
||||
|
||||
Open `docker-compose.yaml` (or `docker-compose-aliyun.yaml`), find the commented `extends` block under the `shumai` service, and uncomment it:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
shumai:
|
||||
# ...
|
||||
# Hardware Acceleration (NVENC / QuickSync / VA-API / RKMPP)
|
||||
extends:
|
||||
file: hwaccel.transcoding.yaml
|
||||
service: nvenc # set to one of [nvenc, quicksync, rkmpp, vaapi, vaapi-wsl]
|
||||
```
|
||||
|
||||
Replace `nvenc` with your target backend:
|
||||
|
||||
- `nvenc` for NVIDIA GPUs
|
||||
- `quicksync` for Intel Quick Sync
|
||||
- `vaapi` for AMD or Intel VA-API
|
||||
- `rkmpp` for Rockchip SoCs
|
||||
- `vaapi-wsl` for WSL2 on Windows
|
||||
|
||||
### Step 3: Start the Stack
|
||||
|
||||
Restart or recreate the Shumai container:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Single Compose File Setup (Unraid / Portainer)
|
||||
|
||||
If your environment or container manager does not support multi-file `extends`, you can inline the hardware configuration directly into the `shumai` service in `docker-compose.yaml`:
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="NVIDIA NVENC">
|
||||
```yaml
|
||||
services:
|
||||
shumai:
|
||||
# ...
|
||||
deploy:
|
||||
resources:
|
||||
reservations:
|
||||
devices:
|
||||
- driver: nvidia
|
||||
count: 1
|
||||
capabilities:
|
||||
- gpu
|
||||
- compute
|
||||
- video
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Intel QuickSync / AMD VA-API">
|
||||
```yaml services: shumai: # ... devices: - /dev/dri:/dev/dri ```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="WSL2 (Windows)">
|
||||
```yaml services: shumai: # ... devices: - /dev/dri:/dev/dri - /dev/dxg:/dev/dxg volumes: -
|
||||
/usr/lib/wsl:/usr/lib/wsl environment: - LIBVA_DRIVER_NAME=d3d12 ```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Rockchip RKMPP">
|
||||
```yaml
|
||||
services:
|
||||
shumai:
|
||||
# ...
|
||||
security_opt:
|
||||
- systempaths=unconfined
|
||||
- apparmor=unconfined
|
||||
group_add:
|
||||
- video
|
||||
devices:
|
||||
- /dev/rga:/dev/rga
|
||||
- /dev/dri:/dev/dri
|
||||
- /dev/dma_heap:/dev/dma_heap
|
||||
- /dev/mpp_service:/dev/mpp_service
|
||||
```
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
---
|
||||
|
||||
## Web UI Settings
|
||||
|
||||
In the Shumai Web UI, navigate to **Team Settings** > **Transcoding Settings**.
|
||||
|
||||
- **Auto (Recommended)**: Shumai automatically probes candidate hardware encoders in optimal order (`h264_nvenc` → `h264_vaapi` → `h264_qsv` → `h264_amf` → `libx264`). If hardware acceleration is unavailable, it gracefully uses software encoding.
|
||||
- **Explicit Encoder**: You can pin the transcode pipeline to a specific encoder (e.g. `NVENC`, `Quick Sync`, `VA-API`).
|
||||
- **Off**: Forces CPU software encoding (`libx264`) for all video jobs.
|
||||
|
||||
---
|
||||
|
||||
## Verification & Monitoring
|
||||
|
||||
### Check Transcode Logs
|
||||
|
||||
When video transcoding begins on an uploaded asset, Shumai writes a structured log indicating the chosen encoder:
|
||||
|
||||
```bash
|
||||
docker compose logs -f shumai
|
||||
```
|
||||
|
||||
Look for the `Starting video transcoding` log entry:
|
||||
|
||||
```json
|
||||
{
|
||||
"level": 30,
|
||||
"time": 1790414665096,
|
||||
"encoder": "h264_nvenc",
|
||||
"hardwareAcceleration": "auto",
|
||||
"inputFile": "/tmp/transcode-.../video.mp4",
|
||||
"outputFile": "/tmp/transcode-.../video-180p.mp4",
|
||||
"msg": "Starting video transcoding"
|
||||
}
|
||||
```
|
||||
|
||||
If hardware acceleration was successfully initialized, `encoder` will show `h264_nvenc`, `h264_vaapi`, or `h264_qsv`.
|
||||
|
||||
### Monitor GPU Utilization
|
||||
|
||||
While transcoding a video, you can observe hardware utilization on the host:
|
||||
|
||||
- **NVIDIA**:
|
||||
```bash
|
||||
nvidia-smi
|
||||
# or
|
||||
nvtop
|
||||
```
|
||||
- **Intel**:
|
||||
```bash
|
||||
sudo intel_gpu_top
|
||||
```
|
||||
- **AMD**:
|
||||
```bash
|
||||
sudo radeontop
|
||||
```
|
||||
@@ -1,85 +0,0 @@
|
||||
---
|
||||
title: Deploy with Temporal
|
||||
description: Configure a high-scale production deployment using Temporal and S3-compatible storage.
|
||||
---
|
||||
|
||||
For production environments or workloads with high-volume video processing and heavy AI agent usage, running background tasks on a single server can cause bottlenecks. Shumai resolves this by offloading task queue management, retries, and background executions to **Temporal**.
|
||||
|
||||
This allows you to decouple workloads and run specialized worker nodes on separate, dedicated machines.
|
||||
|
||||
---
|
||||
|
||||
## How it Works
|
||||
|
||||
When configured for Temporal, the core Shumai web application does not process background jobs itself. Instead, it publishes tasks to a Temporal Cluster queue.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
UserUpload[User Uploads Video] --> WebApp[Shumai Web UI / API]
|
||||
WebApp -->|Register Task| Temporal[Temporal Cluster]
|
||||
Temporal -->|Queue: Transcoding| TranscodeWorker[Transcode Worker Machine]
|
||||
Temporal -->|Queue: AI Agents| AgentWorker[Agent Worker Machine]
|
||||
```
|
||||
|
||||
- **Transcoding Workers**: Can be run on GPU-accelerated or high-CPU compute instances.
|
||||
- **AI Agent Workers**: Can be run on isolated, sandboxed hosts to safely execute automation scripts.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Storage Requirement**: Because the core application and the background workers run on separate machines in a distributed setup, **you must configure an S3-compatible storage backend** (such as AWS S3, Cloudflare R2, or MinIO). Local storage (`STORAGE_BACKEND=local`) is not supported in this mode because the workers and the web application do not share a common filesystem.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Deploy the Core Stack
|
||||
|
||||
On your primary host machine, spin up the database, Temporal cluster services, and the main Shumai web application:
|
||||
|
||||
1. **Download the Temporal Stack Configuration**:
|
||||
```bash
|
||||
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/temporal/docker-compose.yaml
|
||||
```
|
||||
2. **Configure S3 Settings**:
|
||||
Open the `docker-compose.yaml` file and set your S3 credentials and endpoint environment variables under the `shumai` service.
|
||||
3. **Start the Services**:
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
This exposes the web application on port `3000`, the database on `5432`, the Temporal gRPC service on `7233`, and the Temporal management dashboard on `8080`.
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Configure & Run Workers
|
||||
|
||||
On your specialized worker machines, you will run the dedicated background worker services. Each worker requires a `.env` file referencing the database, S3 storage, and the Temporal cluster:
|
||||
|
||||
```env
|
||||
DATABASE_URL=postgresql://shumai:shumai_password@<primary-host-ip>:5432/shumai_db?schema=public
|
||||
WORKFLOW_EXECUTOR=temporal
|
||||
TEMPORAL_ADDRESS=<primary-host-ip>:7233
|
||||
STORAGE_BACKEND=s3
|
||||
AWS_ENDPOINT_URL_S3=https://your-s3-endpoint.com
|
||||
S3_BUCKET=shumai
|
||||
S3_REGION=us-east-1
|
||||
S3_ACCESS_KEY_ID=your-access-key-id
|
||||
S3_SECRET_ACCESS_KEY=your-secret-access-key
|
||||
```
|
||||
|
||||
### Media Transcoding Worker
|
||||
|
||||
Run this on your media processing nodes (requires system installations of `ffmpeg` and `ffprobe`):
|
||||
|
||||
```bash
|
||||
npm install -g @shumai-one/shumai-transcode
|
||||
shumai-transcode
|
||||
```
|
||||
|
||||
### AI Agent Worker
|
||||
|
||||
Run this on your sandboxed agent execution nodes (requires sandbox dependencies like `bubblewrap` or `sandbox-exec`):
|
||||
|
||||
```bash
|
||||
npm install -g @shumai-one/shumai-agent
|
||||
shumai-agent
|
||||
```
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **For Bun Users:** Since the worker package binaries contain a `#!/usr/bin/env node` shebang, running `shumai-transcode` or `shumai-agent` directly will run under Node.js. If you wish to run them using Bun, prefix the commands with `bun run --bun` (e.g., `bun run --bun shumai-transcode` or `bun run --bun shumai-agent`).
|
||||
@@ -0,0 +1,222 @@
|
||||
---
|
||||
title: Shumai MCP Server
|
||||
description: Let external AI agents such as Claude Code, Cursor, or Kiro work with your Shumai projects.
|
||||
---
|
||||
|
||||
Shumai includes a built-in [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server. Any MCP-compatible agent can connect to it and browse projects, look at images, videos, and documents, create folders, and organize assets on your behalf, using the same tools as Shumai's built-in agent.
|
||||
|
||||
<Note>
|
||||
This page is about connecting **external agents to Shumai**. To connect Shumai's own agents to
|
||||
other tools, see [MCP Servers](/using-shumai/mcp-servers).
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Connecting a Client
|
||||
|
||||
The MCP server uses the Streamable HTTP transport at:
|
||||
|
||||
```
|
||||
https://<your-shumai-host>/mcp
|
||||
```
|
||||
|
||||
Shumai supports **OAuth 2.1** (recommended for seamless browser-based authentication) and **API tokens** (for headless environments or clients that do not support OAuth).
|
||||
|
||||
Pick your client below to get started:
|
||||
|
||||
### Claude Code
|
||||
|
||||
[Claude Code](https://docs.anthropic.com/en/docs/claude-code) natively supports remote MCP servers with OAuth authentication. Add Shumai to your Claude Code configuration by running:
|
||||
|
||||
```bash
|
||||
claude mcp add shumai --transport http https://<your-shumai-host>/mcp
|
||||
```
|
||||
|
||||
When you start a new conversation, Claude Code will open a browser window for you to sign in and authorize access to your Shumai account. No manual API token is required.
|
||||
|
||||
Alternatively, you can manually configure `.claude/settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"shumai": {
|
||||
"type": "http",
|
||||
"url": "https://<your-shumai-host>/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Or connect stdio via `mcp-remote`:
|
||||
|
||||
```bash
|
||||
claude mcp add shumai -- npx -y mcp-remote https://<your-shumai-host>/mcp
|
||||
```
|
||||
|
||||
### Cursor
|
||||
|
||||
Add Shumai to your Cursor MCP configuration (`~/.cursor/mcp.json` or project `.cursor/mcp.json`):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"shumai": {
|
||||
"url": "https://<your-shumai-host>/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
When Cursor connects to the server, it will prompt you in the browser to complete the OAuth sign-in and authorize access.
|
||||
|
||||
To authenticate with an API token instead, pass the `Authorization` header:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"shumai": {
|
||||
"url": "https://<your-shumai-host>/mcp",
|
||||
"headers": {
|
||||
"Authorization": "Bearer <your-api-token>"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Codex
|
||||
|
||||
```bash
|
||||
codex mcp add shumai --url https://<your-shumai-host>/mcp
|
||||
codex mcp login shumai
|
||||
```
|
||||
|
||||
### VS Code
|
||||
|
||||
```bash
|
||||
code --add-mcp '{"name":"shumai","type":"http","url":"https://<your-shumai-host>/mcp"}'
|
||||
```
|
||||
|
||||
Start the server from your **MCP Servers** list in VS Code and sign in to Shumai when prompted.
|
||||
|
||||
### Other Clients
|
||||
|
||||
**Remote (HTTP)**
|
||||
|
||||
If your client natively supports remote HTTP MCP servers:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"shumai": {
|
||||
"url": "https://<your-shumai-host>/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Local Bridge (`mcp-remote` / stdio)**
|
||||
|
||||
For clients that only support local (stdio) MCP servers, use `mcp-remote` to connect to Shumai's remote HTTP endpoint:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"shumai": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "mcp-remote", "https://<your-shumai-host>/mcp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Authentication
|
||||
|
||||
Shumai's MCP server supports two authentication methods:
|
||||
|
||||
### OAuth 2.1 (Recommended)
|
||||
|
||||
Shumai implements OAuth 2.1 with Dynamic Client Registration ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) and OAuth Protected Resource Metadata ([RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) / [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)).
|
||||
|
||||
- **Seamless Sign-in**: Supported MCP clients automatically discover authorization endpoints and complete the OAuth handshake in your browser.
|
||||
- **Access Control**: External agents act with your permissions in Shumai. Actions are attributed to your user account and logged in the team audit log with `via: mcp`.
|
||||
- **Clearing OAuth Cache**: If you need to re-authenticate or clear stored credentials in CLI tools such as `mcp-remote` or Claude Code, remove the local authentication cache:
|
||||
|
||||
```bash
|
||||
rm -rf ~/.mcp-auth
|
||||
```
|
||||
|
||||
### API Tokens
|
||||
|
||||
API tokens are ideal for automated CI/CD pipelines, headless environments, or clients that do not support interactive OAuth.
|
||||
|
||||
1. In Shumai, open **Team Settings** → **API Tokens**.
|
||||
2. Enter a name (for example, `ci-agent` or `cursor-token`) and click **Generate**.
|
||||
3. Copy the token from the dialog. It is only shown once.
|
||||
4. Pass the token in the `Authorization: Bearer <your-api-token>` header (or `x-api-key` header).
|
||||
|
||||
<Warning>
|
||||
An API token acts as you: the agent can do anything your account can do in Shumai. Store it like a
|
||||
password, use a separate token per client, and revoke tokens you no longer use from **Team
|
||||
Settings** → **API Tokens**.
|
||||
</Warning>
|
||||
|
||||
---
|
||||
|
||||
## Available Tools
|
||||
|
||||
| Tool | What it does |
|
||||
| ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
|
||||
| `list_projects` | Lists the projects you can access, with each project's root folder. |
|
||||
| `list_assets` | Lists files and folders in a folder, page by page. |
|
||||
| `search_assets` | Searches a folder and its subfolders by name, by meaning (when AI search is enabled), or by metadata. |
|
||||
| `create_folder` | Creates a folder. |
|
||||
| `rename_asset` | Renames a file or folder. |
|
||||
| `move_assets` | Moves files or folders into another folder. |
|
||||
| `copy_assets` | Copies files or folders into another folder of the same team. |
|
||||
| `delete_asset` | Moves a file or folder to the project trash. Marked as destructive so clients can ask you to confirm. |
|
||||
| `read_asset` | Looks at a file: an image, video frames, PDF pages, a 3D model view, or the text of a text file. |
|
||||
| `get_asset_render` | Gets the result of a `read_asset` call that was still rendering. |
|
||||
| `download_asset` | Gets download links for up to 50 files: the web preview version by default, or the original with `proxy: false`. |
|
||||
| `get_folder_instructions` | Reads a folder's instructions for AI agents (its AGENTS.md). |
|
||||
| `create_file` | Starts uploading a new file into a folder (see [Uploading Files](#uploading-files)). |
|
||||
| `create_version` | Starts uploading a new version of a file. |
|
||||
| `complete_upload` | Finishes an upload started with `create_file` or `create_version`. |
|
||||
| `list_comments` | Lists the review comments on a file, with their replies. |
|
||||
| `create_comment` | Comments on a file (optionally at a timecode) or replies to a comment. |
|
||||
| `resolve_comment` | Marks a comment as resolved, or unresolved again. |
|
||||
| `list_metadata_fields` | Lists a project's metadata fields, such as status, rating, and custom fields, with their choices. |
|
||||
| `update_asset_metadata` | Sets metadata values on a file. |
|
||||
| `create_version_stack` | Stacks files in the same folder as versions of one asset. |
|
||||
| `list_versions` | Lists the versions in a version stack, latest first. |
|
||||
| `remove_version` | Takes a version out of its stack. The file is kept. |
|
||||
|
||||
### Reading Files
|
||||
|
||||
`read_asset` attaches the images to the result so the AI model can see them: up to 8 images per call, each up to 2 MB. Any other images are listed as links only. Every result also includes a link to each image, valid for about an hour. Pass `inlineImages: false` to get links only, for example when your client can't show images.
|
||||
|
||||
Rendering video frames or PDF pages can take a while. If it takes longer than about 20 seconds, `read_asset` returns `status: "pending"` with a `taskId`, and the model calls `get_asset_render` with that `taskId` to get the result. Only the user who started the read can get its result.
|
||||
|
||||
### Uploading Files
|
||||
|
||||
Uploading takes three steps, so large files never pass through the AI model:
|
||||
|
||||
1. `create_file` (or `create_version`) returns an `uploadUrl` and an `uploadId`.
|
||||
2. The agent uploads the file's bytes to `uploadUrl` with an HTTP `PUT`, for example `curl -T video.mp4 "<uploadUrl>"`.
|
||||
3. `complete_upload` with the `uploadId` creates the file and starts processing it (previews, transcoding).
|
||||
|
||||
The upload URL and ID are valid for about an hour, and only you can complete your upload. If the project has **Creation Context** metadata fields (for example, the prompt or model used to make a file), pass their values as `metadata` to `create_file` or `create_version`; `list_metadata_fields` shows which fields they are.
|
||||
|
||||
The agent must be able to reach the upload URL. With Shumai's local storage, it points to your Shumai server; with S3 storage, to your S3 endpoint.
|
||||
|
||||
Every call runs with your permissions: for example, a **Reviewer** can list assets but cannot create or rename them. Actions are recorded in the team audit log and attributed to you, marked as coming from MCP.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **OAuth Authorization Expired or Invalid**: Clear your client's local OAuth session cache (`rm -rf ~/.mcp-auth`) and restart your MCP client to re-authenticate.
|
||||
- **401 Unauthorized**: The API token or OAuth access token is missing, expired, mistyped, or revoked. For API tokens, generate a new token under **Team Settings** → **API Tokens** and update your client configuration.
|
||||
- **Permission errors on a tool call**: Your role in that team or project does not allow the action.
|
||||
+168
-53
@@ -14,6 +14,10 @@
|
||||
},
|
||||
"navbar": {
|
||||
"links": [
|
||||
{
|
||||
"label": "Forum",
|
||||
"href": "https://shumai.discourse.group/"
|
||||
},
|
||||
{
|
||||
"label": "Changelog",
|
||||
"href": "/changelog"
|
||||
@@ -21,64 +25,175 @@
|
||||
]
|
||||
},
|
||||
"navigation": {
|
||||
"groups": [
|
||||
"languages": [
|
||||
{
|
||||
"group": "Getting Started",
|
||||
"pages": [
|
||||
"getting-started/overview",
|
||||
"getting-started/quickstart",
|
||||
"getting-started/s3-storage"
|
||||
"language": "en",
|
||||
"default": true,
|
||||
"navbar": {
|
||||
"links": [
|
||||
{
|
||||
"label": "Forum",
|
||||
"href": "https://shumai.discourse.group/"
|
||||
},
|
||||
{
|
||||
"label": "Changelog",
|
||||
"href": "/changelog"
|
||||
}
|
||||
]
|
||||
},
|
||||
"groups": [
|
||||
{
|
||||
"group": "Getting Started",
|
||||
"pages": [
|
||||
"getting-started/overview",
|
||||
"getting-started/quickstart",
|
||||
"getting-started/s3-storage"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Using Shumai",
|
||||
"pages": [
|
||||
"using-shumai/asset-management",
|
||||
"using-shumai/comments",
|
||||
"using-shumai/version-stack",
|
||||
"using-shumai/sort-and-search",
|
||||
"using-shumai/semantic-search",
|
||||
"using-shumai/team-project-management",
|
||||
"using-shumai/notifications",
|
||||
"using-shumai/metadata",
|
||||
"using-shumai/collections",
|
||||
"using-shumai/share-links",
|
||||
"using-shumai/nle-and-premiere",
|
||||
"using-shumai/3d-asset-support",
|
||||
"using-shumai/gotenberg",
|
||||
"using-shumai/embedding-server"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Shumai Agent Settings",
|
||||
"pages": [
|
||||
"using-shumai/agent-providers",
|
||||
"using-shumai/image-video-generation",
|
||||
"using-shumai/agents",
|
||||
"using-shumai/agents-md",
|
||||
"using-shumai/agent-skills",
|
||||
"using-shumai/agent-tools",
|
||||
"using-shumai/mcp-servers",
|
||||
"using-shumai/agent-sandbox"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Team Settings",
|
||||
"pages": [
|
||||
"using-shumai/transcode-settings",
|
||||
"using-shumai/quotas-settings",
|
||||
"using-shumai/email-notifications",
|
||||
"using-shumai/password-reset"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Developer",
|
||||
"pages": ["developer/mcp-server"]
|
||||
},
|
||||
{
|
||||
"group": "Configuration",
|
||||
"pages": [
|
||||
"configuration/env-variables",
|
||||
"configuration/hardware-transcoding",
|
||||
"configuration/archive-storage"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Distributed Deployment",
|
||||
"pages": ["configuration/distributed"]
|
||||
},
|
||||
{
|
||||
"group": "Releases",
|
||||
"pages": ["changelog"]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Using Shumai",
|
||||
"pages": [
|
||||
"using-shumai/asset-management",
|
||||
"using-shumai/comments",
|
||||
"using-shumai/version-stack",
|
||||
"using-shumai/sort-and-search",
|
||||
"using-shumai/semantic-search",
|
||||
"using-shumai/team-project-management",
|
||||
"using-shumai/notifications",
|
||||
"using-shumai/metadata",
|
||||
"using-shumai/collections",
|
||||
"using-shumai/share-links",
|
||||
"using-shumai/nle-and-premiere",
|
||||
"using-shumai/gotenberg"
|
||||
"language": "zh",
|
||||
"navbar": {
|
||||
"links": [
|
||||
{
|
||||
"label": "论坛",
|
||||
"href": "https://shumai.discourse.group/"
|
||||
},
|
||||
{
|
||||
"label": "Changelog",
|
||||
"href": "/changelog"
|
||||
}
|
||||
]
|
||||
},
|
||||
"groups": [
|
||||
{
|
||||
"group": "快速入门",
|
||||
"pages": [
|
||||
"zh/getting-started/overview",
|
||||
"zh/getting-started/quickstart",
|
||||
"zh/getting-started/s3-storage"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "使用指南",
|
||||
"pages": [
|
||||
"zh/using-shumai/asset-management",
|
||||
"zh/using-shumai/comments",
|
||||
"zh/using-shumai/version-stack",
|
||||
"zh/using-shumai/sort-and-search",
|
||||
"zh/using-shumai/semantic-search",
|
||||
"zh/using-shumai/team-project-management",
|
||||
"zh/using-shumai/notifications",
|
||||
"zh/using-shumai/metadata",
|
||||
"zh/using-shumai/collections",
|
||||
"zh/using-shumai/share-links",
|
||||
"zh/using-shumai/nle-and-premiere",
|
||||
"zh/using-shumai/3d-asset-support",
|
||||
"zh/using-shumai/gotenberg",
|
||||
"zh/using-shumai/embedding-server"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Agent 智能体配置",
|
||||
"pages": [
|
||||
"zh/using-shumai/agent-providers",
|
||||
"zh/using-shumai/image-video-generation",
|
||||
"zh/using-shumai/agents",
|
||||
"zh/using-shumai/agents-md",
|
||||
"zh/using-shumai/agent-skills",
|
||||
"zh/using-shumai/agent-tools",
|
||||
"zh/using-shumai/mcp-servers",
|
||||
"zh/using-shumai/agent-sandbox"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "团队设置",
|
||||
"pages": [
|
||||
"zh/using-shumai/transcode-settings",
|
||||
"zh/using-shumai/quotas-settings",
|
||||
"zh/using-shumai/email-notifications",
|
||||
"zh/using-shumai/password-reset"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "开发者指南",
|
||||
"pages": ["zh/developer/mcp-server"]
|
||||
},
|
||||
{
|
||||
"group": "系统配置",
|
||||
"pages": [
|
||||
"zh/configuration/env-variables",
|
||||
"zh/configuration/hardware-transcoding",
|
||||
"zh/configuration/archive-storage"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "分布式部署",
|
||||
"pages": ["zh/configuration/distributed"]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Shumai Agent Settings",
|
||||
"pages": [
|
||||
"using-shumai/agent-providers",
|
||||
"using-shumai/image-video-generation",
|
||||
"using-shumai/agents",
|
||||
"using-shumai/agents-md",
|
||||
"using-shumai/agent-skills",
|
||||
"using-shumai/agent-tools",
|
||||
"using-shumai/mcp-servers",
|
||||
"using-shumai/agent-sandbox"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Team Settings",
|
||||
"pages": [
|
||||
"using-shumai/transcode-settings",
|
||||
"using-shumai/quotas-settings",
|
||||
"using-shumai/password-reset"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Configuration",
|
||||
"pages": ["configuration/env-variables"]
|
||||
},
|
||||
{
|
||||
"group": "Temporal Deployment",
|
||||
"pages": ["configuration/temporal"]
|
||||
},
|
||||
{
|
||||
"group": "Releases",
|
||||
"pages": ["changelog"]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -32,6 +32,6 @@ Ideal for small teams, local development, or low-volume workflows. In this setup
|
||||
|
||||
### 2. High-Scale Distributed Deployment
|
||||
|
||||
Recommended for production environments with high-volume video uploads. In this setup, background tasks are managed via a centralized queue (Temporal). This allows you to offload heavy workloads to specialized worker machines (for example, putting video transcoding tasks on high-CPU/GPU machines and AI agents on separate sandboxed environments).
|
||||
Recommended for production environments with high-volume video uploads. In this setup, background tasks are managed via durable queues (orchestrated by DBOS directly in PostgreSQL). This allows you to offload heavy workloads to specialized worker machines (for example, putting video transcoding tasks on high-CPU/GPU machines and AI agents on separate sandboxed environments).
|
||||
|
||||
_Note: S3-compatible cloud storage is required for distributed deployments so that all workers can access the uploaded files._
|
||||
|
||||
@@ -9,22 +9,97 @@ We support three installation options. For most administrators, **Docker Compose
|
||||
|
||||
## Option 1: Docker Compose (Recommended)
|
||||
|
||||
Docker Compose automatically configures and spins up all required services (the web application, a database, and local storage).
|
||||
Docker Compose is the fastest way to get Shumai running. You do not need to clone the repository or install packages manually. Ensure you have [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) installed, then follow these steps:
|
||||
|
||||
1. **Create Directory**:
|
||||
Create and navigate to a new directory for your configuration and data volumes:
|
||||
|
||||
1. **Download the Configuration**:
|
||||
```bash
|
||||
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.yaml
|
||||
mkdir shumai && cd shumai
|
||||
```
|
||||
2. **Start the Services**:
|
||||
|
||||
2. **Download the Configuration**:
|
||||
Download your preferred `docker-compose.yaml` configuration based on your needs and available RAM:
|
||||
|
||||
- **Lite (Suggested RAM: 2 GB+)**: Minimal deployment containing Shumai and PostgreSQL database.
|
||||
|
||||
```bash
|
||||
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.yaml
|
||||
```
|
||||
|
||||
- **With Embedding Server (Suggested RAM: 4 GB+)**: Adds local multimodal semantic search powered by `shumaiOne/embedding-server` (`EmbeddingGemma 2 740M`).
|
||||
|
||||
```bash
|
||||
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.embedding.yaml
|
||||
```
|
||||
|
||||
- **Full (Suggested RAM: 8 GB+)**: All-in-one setup including `embedding-server`, `turntable-renderer` (3D previews), and `Gotenberg` (document PDF proxying).
|
||||
```bash
|
||||
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.full.yaml
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> By default, the Docker Compose setups use CPU software transcoding. If your server has a GPU (NVIDIA NVENC, Intel QuickSync, AMD/Intel VA-API, or Rockchip RKMPP) and you want to enable GPU hardware acceleration, check the [Hardware Transcoding Guide](/configuration/hardware-transcoding).
|
||||
|
||||
3. **Configure Environment Variables**:
|
||||
Open `docker-compose.yaml` to adjust environment variables for your deployment:
|
||||
|
||||
- `BETTER_AUTH_URL`: The public base URL of your Shumai server (e.g., `https://shumai.example.com` or `http://12.34.56.78:3000`). It is used for:
|
||||
- **Password reset links**: Generates CLI and user password reset URLs (`{BETTER_AUTH_URL}/reset-password?token=...`).
|
||||
- **Email notification deep links**: Default base URL for notification emails (if `APP_URL` is unset).
|
||||
- **Session cookie security**: Determines whether to issue session cookies with `Secure` flags and `__Secure-` prefixes for HTTPS deployments.
|
||||
- **MCP OAuth 2.1 & discovery**: Sets the OAuth resource identifier (`{BETTER_AUTH_URL}/mcp`), discovery endpoints (`/.well-known/...`), and default redirect URI for outbound MCP OAuth.
|
||||
|
||||
> [!NOTE]
|
||||
> **Email/password Web UI login** works over plain HTTP/IP even if `BETTER_AUTH_URL` is omitted. However, setting it is strongly recommended for production, custom domains, or HTTPS deployments. Note that remote deployments must use HTTPS for MCP OAuth 2.1 (RFC 9728); if an HTTP IP address or domain is used, MCP OAuth 2.1 is gracefully disabled while the Web UI and MCP API tokens remain functional.
|
||||
|
||||
- `BETTER_AUTH_SECRET`: A random secret key used to sign session cookies, JWTs, and presigned file upload/download URLs (in local storage mode). A default placeholder is included in the template for instant local trials, but **you must generate a unique secret for production or public deployments** (e.g., run `openssl rand -base64 32`).
|
||||
- `AWS_ENDPOINT_URL_S3`: By default, `AWS_ENDPOINT_URL_S3` is set to `http://localhost:{SHUMAI_SERVER_PORT}`. When you use local storage (the default storage backend with `STORAGE_BACKEND: local`) and expose Shumai on a remote server, custom domain, or custom host/port combination, set `AWS_ENDPOINT_URL_S3` to the external URL that client browsers will use to upload and download files.
|
||||
|
||||
For example, if you change the port mapping in `docker-compose.yaml` from `3000:3000` to `12345:3000` and deploy on a server with IP address `12.34.56.78`, set:
|
||||
|
||||
```yaml
|
||||
AWS_ENDPOINT_URL_S3: http://12.34.56.78:12345
|
||||
```
|
||||
|
||||
This value must be reachable from client browsers and should include the externally exposed port.
|
||||
|
||||
- `SHUMAI_SERVER_PORT`: Controls the port the Shumai server listens on. The default is `3000`.
|
||||
- **External S3 Storage**: By default, Shumai uses the bundled local storage service in this Docker Compose setup. To use an external S3-compatible storage instead, configure the environment variables for your S3 provider. Here are examples for AWS S3 and Cloudflare R2:
|
||||
|
||||
**AWS S3 Example:**
|
||||
|
||||
```yaml
|
||||
STORAGE_BACKEND: s3
|
||||
S3_BUCKET: your-bucket-name
|
||||
S3_ACCESS_KEY_ID: your-access-key-id
|
||||
S3_SECRET_ACCESS_KEY: your-secret-access-key
|
||||
AWS_ENDPOINT_URL_S3: https://s3.us-east-1.amazonaws.com
|
||||
```
|
||||
|
||||
**Cloudflare R2 Example:**
|
||||
|
||||
```yaml
|
||||
STORAGE_BACKEND: s3
|
||||
S3_BUCKET: your-bucket-name
|
||||
S3_REGION: auto
|
||||
S3_ACCESS_KEY_ID: your-access-key-id
|
||||
S3_SECRET_ACCESS_KEY: your-secret-access-key
|
||||
AWS_ENDPOINT_URL_S3: https://<account-id>.r2.cloudflarestorage.com
|
||||
```
|
||||
|
||||
4. **Start the Services**:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
3. **Access the Dashboard**:
|
||||
Open your browser and navigate to **`http://localhost:3000`** to access the Shumai Web UI.
|
||||
|
||||
### Production Deployments (Temporal)
|
||||
5. **Access the Dashboard**:
|
||||
Open your browser and navigate to **`http://localhost:3000`** (or `http://<your-server-ip>:3000` for remote deployments) to access the Shumai Web UI.
|
||||
|
||||
If you are deploying Shumai for a production team with high-volume video uploads, we recommend setting up a distributed deployment using **Temporal** and an S3-compatible storage backend. This offloads resource-heavy video transcoding and AI agents to separate, dedicated worker nodes to keep your main dashboard fast and responsive. For setup instructions, see the [Deploy with Temporal](/configuration/temporal) guide.
|
||||
### Production Deployments (Distributed Workers)
|
||||
|
||||
If you are deploying Shumai for a production team with high-volume video uploads, we recommend setting up a distributed deployment using dedicated workers and an S3-compatible storage backend. This offloads resource-heavy video transcoding to dedicated worker nodes to keep your main dashboard fast and responsive. For setup instructions, see the [Deploy with Distributed Workers](/configuration/distributed) guide.
|
||||
|
||||
---
|
||||
|
||||
@@ -39,6 +114,9 @@ To handle media processing and security isolation, the host machine must have th
|
||||
- **FFmpeg & FFprobe**: Required for video transcoding and metadata extraction.
|
||||
- _macOS_: `brew install ffmpeg`
|
||||
- _Linux (Ubuntu/Debian)_: `sudo apt-get install ffmpeg`
|
||||
- **dcraw_emu (LibRaw)**: Required for camera RAW image decoding and preview generation.
|
||||
- _macOS_: `brew install libraw`
|
||||
- _Linux (Ubuntu/Debian)_: `sudo apt-get install libraw-bin`
|
||||
- **Agent Sandbox Utilities**: Used to run custom automation scripts securely.
|
||||
- _macOS_: `brew install ripgrep`
|
||||
- _Linux (Ubuntu/Debian)_: `sudo apt-get install bubblewrap socat ripgrep`
|
||||
@@ -71,12 +149,13 @@ To handle media processing and security isolation, the host machine must have th
|
||||
```env
|
||||
DATABASE_URL=postgresql://shumai:shumai_password@localhost:5432/shumai_db?schema=public
|
||||
BETTER_AUTH_SECRET=your-random-32-character-secret-key
|
||||
BETTER_AUTH_URL=http://localhost:3000
|
||||
STORAGE_BACKEND=local
|
||||
AWS_ENDPOINT_URL_S3=http://localhost:3000
|
||||
```
|
||||
|
||||
> [!TIP]
|
||||
> `AWS_ENDPOINT_URL_S3` must include the scheme and port (e.g. `http://localhost:3000`) where Shumai is publicly accessible. This URL is used directly by client browsers for file uploads.
|
||||
> `BETTER_AUTH_URL` should be set to your public server address for remote or production deployments. `AWS_ENDPOINT_URL_S3` must include the scheme and port (e.g. `http://localhost:3000` or `http://12.34.56.78:3000`) where Shumai is publicly accessible, as client browsers use this URL directly for file uploads.
|
||||
|
||||
4. **Start Shumai**:
|
||||
|
||||
@@ -93,26 +172,67 @@ To handle media processing and security isolation, the host machine must have th
|
||||
|
||||
## Option 3: Run from Source (For Developers)
|
||||
|
||||
If you wish to run Shumai locally to customize the platform or contribute:
|
||||
To set up Shumai locally for development:
|
||||
|
||||
1. **Clone the Repository**:
|
||||
1. **Clone the Repository and Install Dependencies**:
|
||||
```bash
|
||||
git clone https://github.com/shumaiOne/shumai.git
|
||||
cd shumai
|
||||
```
|
||||
2. **Install Dependencies**:
|
||||
```bash
|
||||
bun install
|
||||
```
|
||||
3. **Start a Database**:
|
||||
Launch a local database container (as described in the NPM section above).
|
||||
4. **Run Migrations**:
|
||||
Set up your `.env` file at the root, then apply database migrations:
|
||||
2. **Start a Database**:
|
||||
Launch a local database container (as described in the NPM section above):
|
||||
```bash
|
||||
docker run --name shumai_postgres \
|
||||
-e POSTGRES_USER=shumai \
|
||||
-e POSTGRES_PASSWORD=shumai_password \
|
||||
-e POSTGRES_DB=shumai_db \
|
||||
-p 5432:5432 \
|
||||
-d pgvector/pgvector:pg18
|
||||
```
|
||||
3. **Create Environment File**:
|
||||
Create a `.env` file at the root of the workspace:
|
||||
```env
|
||||
DATABASE_URL=postgresql://shumai:shumai_password@localhost:5432/shumai_db?schema=public
|
||||
BETTER_AUTH_SECRET=ySxs7DxzHDZBbeeHNPEwBuspYwipBqz5Gk5XdBjNhWw=
|
||||
BETTER_AUTH_URL=http://localhost:3000
|
||||
STORAGE_BACKEND=local
|
||||
SHUMAI_SERVER_PORT=3000
|
||||
AWS_ENDPOINT_URL_S3=http://localhost:3000
|
||||
```
|
||||
4. **Generate i18n Translations**:
|
||||
```bash
|
||||
bun run i18n:compile
|
||||
```
|
||||
> [!TIP]
|
||||
> During frontend development, you can run `bun run i18n:watch` in a separate terminal to automatically recompile translation files whenever you edit strings in `packages/webui/messages/`.
|
||||
5. **Run Migrations**:
|
||||
Apply database schema migrations:
|
||||
```bash
|
||||
bun run db:migrate
|
||||
```
|
||||
5. **Start the Dev Server**:
|
||||
6. **Start the Dev Server**:
|
||||
```bash
|
||||
bun run dev
|
||||
```
|
||||
This spins up the web server on port `3000` with hot-reloading active.
|
||||
|
||||
---
|
||||
|
||||
## Install the command-line client
|
||||
|
||||
To connect to a running Shumai server, install the standalone CLI without Node.js or Bun:
|
||||
|
||||
```sh
|
||||
curl -fsSL https://github.com/shumaiOne/shumai/releases/latest/download/install.sh | sh
|
||||
```
|
||||
|
||||
On Windows:
|
||||
|
||||
```powershell
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://github.com/shumaiOne/shumai/releases/latest/download/install.ps1 | iex"
|
||||
```
|
||||
|
||||
Native releases support macOS, Linux with glibc, and Windows on ARM64 and x64. The scripts verify SHA-256 checksums and install into your user directory. Re-run the installer to upgrade, and check the installed version with `shumai-cli --version`. The npm alternative, `npm install -g @shumai-one/shumai-cli`, requires Node.js 22.12+.
|
||||
|
||||
Set `SHUMAI_API_SERVER` to your server URL and `SHUMAI_API_KEY` to a personal API token from Settings → API Tokens, then run `shumai-cli project ls`. See the [CLI guide](https://github.com/shumaiOne/shumai/blob/main/apps/cli/README.md) for supported OS versions, PATH setup, pinned versions, rollback, and uninstall instructions.
|
||||
|
||||
@@ -13,15 +13,16 @@ Using external S3 storage is highly recommended for production teams. It allows
|
||||
|
||||
To enable S3-compatible storage, update the following environment variables in your `.env` file or Docker Compose configuration:
|
||||
|
||||
| Variable | Description | Required | Default / Example |
|
||||
| :------------------------- | :------------------------------------------------------------------------ | :------- | :----------------------------------- |
|
||||
| `STORAGE_BACKEND` | Set to `s3` to enable S3 compatible storage. | Yes | `s3` |
|
||||
| `S3_BUCKET` | The name of the S3 bucket where files will be stored. | Yes | `shumai-bucket` |
|
||||
| `S3_REGION` | The region of your S3 bucket. | No | `auto` |
|
||||
| `S3_ACCESS_KEY_ID` | The access key ID for your storage service. | Yes | `your-access-key-id` |
|
||||
| `S3_SECRET_ACCESS_KEY` | The secret access key for your storage service. | Yes | `your-secret-access-key` |
|
||||
| `AWS_ENDPOINT_URL_S3` | The endpoint URL of your S3 compatible storage provider. | Yes | `https://s3.us-east-1.amazonaws.com` |
|
||||
| `PRESIGNED_URL_EXPIRES_IN` | Duration in hours before generated presigned download/upload URLs expire. | No | `5` |
|
||||
| Variable | Description | Required | Default / Example |
|
||||
| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------ | :------- | :----------------------------------- |
|
||||
| `STORAGE_BACKEND` | Set to `s3` to enable S3 compatible storage. | Yes | `s3` |
|
||||
| `S3_BUCKET` | The name of the S3 bucket where files will be stored. | Yes | `shumai-bucket` |
|
||||
| `S3_REGION` | The region of your S3 bucket. | No | `auto` |
|
||||
| `S3_ACCESS_KEY_ID` | The access key ID for your storage service. | Yes | `your-access-key-id` |
|
||||
| `S3_SECRET_ACCESS_KEY` | The secret access key for your storage service. | Yes | `your-secret-access-key` |
|
||||
| `AWS_ENDPOINT_URL_S3` | The endpoint URL of your S3 compatible storage provider. | Yes | `https://s3.us-east-1.amazonaws.com` |
|
||||
| `PRESIGNED_URL_EXPIRES_IN` | Duration in hours before generated presigned download URLs expire. | No | `5` |
|
||||
| `PRESIGNED_UPLOAD_URL_EXPIRES_IN` | Duration in hours before generated presigned upload URLs expire. Falls back to `PRESIGNED_URL_EXPIRES_IN` if unset. | No | `12` |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,153 @@
|
||||
---
|
||||
title: 3D Asset Support with Turntable Renderer
|
||||
description: Render interactive 3D model turntable previews, sprite scrubbing, and video proxies using turntable-renderer.
|
||||
---
|
||||
|
||||
3D models and mesh assets cannot always be rendered consistently or inspected reliably across diverse client web browsers and mobile devices. Shumai integrates with [turntable-renderer](https://github.com/shumaiOne/turntable-renderer) — a standalone service that executes isolated, headless Blender 5.2 LTS subprocesses — to convert 3D model uploads into standardized, high-fidelity turntable previews.
|
||||
|
||||
Turntable Renderer automatically produces:
|
||||
|
||||
- **1080×1080 Turntable Video (`turntable.mp4`)**: A 4-second, 24-frame, 6 fps video rotating the model 360° (15° per frame) clockwise under dark studio lighting with a pure black background.
|
||||
- **Poster Image (`poster.webp`)**: A crisp still poster for grid cards and immediate file display.
|
||||
- **Hover Sprite Sheet (`sprite.webp`)**: A fast scrubbing sheet allowing users to rotate and inspect the model directly from the file browser on hover.
|
||||
- **Interactive 3D Viewer**: A specialized web viewer featuring 360° ruler scrubbing, rotation angle control (0° to 345°), playback controls, and angle-specific review comments and visual markups.
|
||||
|
||||
---
|
||||
|
||||
## Supported File Types
|
||||
|
||||
When turntable-renderer is configured, Shumai automatically generates 3D turntable proxies for the following formats:
|
||||
|
||||
| Format / Standard | Extensions |
|
||||
| --------------------------- | --------------------------------- |
|
||||
| Binary glTF | `.glb` |
|
||||
| Universal Scene Description | `.usd`, `.usda`, `.usdc`, `.usdz` |
|
||||
| Autodesk FBX | `.fbx` |
|
||||
| Wavefront OBJ | `.obj` |
|
||||
| Stereolithography (STL) | `.stl` |
|
||||
| COLLADA | `.dae` |
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
Shumai supports configuring the turntable renderer either through the **WebUI** or via **Environment Variables**.
|
||||
|
||||
### 1. WebUI (Team Settings → Integrations)
|
||||
|
||||
Team owners can configure the turntable renderer directly from the web interface:
|
||||
|
||||
1. Navigate to **Team Settings** from the sidebar.
|
||||
2. Select the **Integrations** tab.
|
||||
3. Under **3D Turntable Renderer**, enter the **Server URL** (e.g. `http://turntable-renderer:3000` or `http://localhost:3003`).
|
||||
4. Enter the **Username** and **Password** if Basic Authentication is enabled on the service.
|
||||
5. Click **Test Connection** to verify that Shumai can communicate with the renderer and check the detected Blender version.
|
||||
6. Click **Save Changes**.
|
||||
|
||||
### 2. Environment Variables
|
||||
|
||||
You can also configure turntable-renderer globally across the system using environment variables on the machine running Shumai or the transcode workers:
|
||||
|
||||
| Variable | Required | Description |
|
||||
| ---------------------------------------- | --------------- | ------------------------------------------------------------------------------------- |
|
||||
| `TURNTABLE_RENDERER_URL` | Yes (to enable) | Base URL of the turntable renderer service, e.g. `http://turntable-renderer:3000`. |
|
||||
| `TURNTABLE_RENDERER_BASIC_AUTH_USERNAME` | No | Username when Basic Authentication is enabled (alias: `TURNTABLE_RENDERER_USERNAME`). |
|
||||
| `TURNTABLE_RENDERER_BASIC_AUTH_PASSWORD` | No | Password when Basic Authentication is enabled (alias: `TURNTABLE_RENDERER_PASSWORD`). |
|
||||
|
||||
### Configuration Priority & Read-Only Mode
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Environment variables take highest priority.** If `TURNTABLE_RENDERER_URL` is set in your environment, Shumai will always use the environment variable configuration.
|
||||
>
|
||||
> When configured via environment variables, the settings in **Team Settings → Integrations** will display a **Configured via environment variables (Read-only)** badge, and the input fields will be locked to prevent accidental changes or configuration drift.
|
||||
|
||||
---
|
||||
|
||||
## Deploying Turntable Renderer
|
||||
|
||||
### Docker Quickstart
|
||||
|
||||
The easiest way to run `turntable-renderer` is using the prebuilt Docker image:
|
||||
|
||||
```bash
|
||||
docker run -d --rm \
|
||||
--name turntable-renderer \
|
||||
-p 3003:3000 \
|
||||
-e TURNTABLE_RENDERER_API_BASIC_AUTH_USERNAME=admin \
|
||||
-e TURNTABLE_RENDERER_API_BASIC_AUTH_PASSWORD=your_password \
|
||||
shumaione/turntable-renderer:latest
|
||||
```
|
||||
|
||||
> **Note**: Host port `3003` maps to internal container port `3000`.
|
||||
|
||||
### Docker Compose Setup
|
||||
|
||||
Add a `turntable-renderer` service to your `docker-compose.yaml`:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
turntable-renderer:
|
||||
image: shumaione/turntable-renderer:latest
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- '3003:3000'
|
||||
environment:
|
||||
TURNTABLE_RENDERER_API_BASIC_AUTH_USERNAME: admin
|
||||
TURNTABLE_RENDERER_API_BASIC_AUTH_PASSWORD: your_password
|
||||
```
|
||||
|
||||
Then point Shumai at it:
|
||||
|
||||
```bash
|
||||
TURNTABLE_RENDERER_URL=http://localhost:3003
|
||||
TURNTABLE_RENDERER_BASIC_AUTH_USERNAME=admin
|
||||
TURNTABLE_RENDERER_BASIC_AUTH_PASSWORD=your_password
|
||||
```
|
||||
|
||||
_(If both Shumai and turntable-renderer run within the same Docker Compose network, use `http://turntable-renderer:3000` as the URL)._
|
||||
|
||||
### GPU Acceleration
|
||||
|
||||
A dedicated GPU is optional — turntable-renderer's CPU rendering pipeline is fast enough for modest hardware. When a GPU is passed into the container, it is automatically detected and leveraged.
|
||||
|
||||
#### Intel / AMD (Open Source Drivers)
|
||||
|
||||
Pass the DRI render node:
|
||||
|
||||
```bash
|
||||
docker run -d --rm \
|
||||
--name turntable-renderer \
|
||||
--shm-size=1gb \
|
||||
-p 3003:3000 \
|
||||
--device /dev/dri \
|
||||
-e TURNTABLE_RENDERER_API_BASIC_AUTH_USERNAME=admin \
|
||||
-e TURNTABLE_RENDERER_API_BASIC_AUTH_PASSWORD=your_password \
|
||||
shumaione/turntable-renderer:latest
|
||||
```
|
||||
|
||||
#### NVIDIA (Proprietary Drivers)
|
||||
|
||||
Requires host driver 580+ and the NVIDIA Container Toolkit (`--runtime nvidia`):
|
||||
|
||||
```bash
|
||||
docker run -d --rm \
|
||||
--name turntable-renderer \
|
||||
--shm-size=1gb \
|
||||
-p 3003:3000 \
|
||||
--runtime nvidia \
|
||||
--gpus all \
|
||||
--device /dev/nvidia-modeset \
|
||||
-e TURNTABLE_RENDERER_API_BASIC_AUTH_USERNAME=admin \
|
||||
-e TURNTABLE_RENDERER_API_BASIC_AUTH_PASSWORD=your_password \
|
||||
shumaione/turntable-renderer:latest
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Behavior Without Turntable Renderer
|
||||
|
||||
If turntable-renderer is not configured or unreachable:
|
||||
|
||||
- The 3D model upload completes successfully with status `processed`.
|
||||
- No turntable video proxy, sprite, or poster is generated.
|
||||
- The original raw 3D file is safely preserved and can be downloaded by team members.
|
||||
@@ -1,45 +1,101 @@
|
||||
---
|
||||
title: Agent Sandbox
|
||||
description: Secure execution environment and network domain restrictions for AI agent scripts.
|
||||
title: Agent Runners
|
||||
description: Connect an optional command runner and configure sandboxing on its machine.
|
||||
---
|
||||
|
||||
Running automated scripts poses security risks. Shumai resolves this by executing all agent skills inside a secure, isolated **Sandbox** environment.
|
||||
Agents use Shumai's built-in tools without a runner. To execute shell commands or download assets into a shell workspace, connect a **runner** on a machine you control. The runner opens an authenticated outbound WebSocket connection; no inbound port is needed.
|
||||
|
||||
---
|
||||
Agent runners require one main Shumai server per database. Multiple main servers can share a database while it has no configured runners. Stop the other main servers before creating a runner. Transcode workers can run separately.
|
||||
|
||||
## Sandbox Security
|
||||
## Connect a runner
|
||||
|
||||
The sandbox restricts the execution process from accessing the host filesystem, system processes, and internal networks:
|
||||
1. In **Settings → Agent Runners**, create a runner and copy its one-time key. Only team owners can manage runners and rotate their keys.
|
||||
2. Install [Shumai CLI](https://github.com/shumaiOne/shumai/tree/main/apps/cli#installation) on macOS, Linux, or Windows.
|
||||
3. Start it in a dedicated, existing workspace:
|
||||
|
||||
- **Isolation**: Scripts run in a virtualized workspace container that prevents them from modifying critical system files or reading other project data.
|
||||
- **Network Bridging**: External network calls from inside the sandbox are strictly monitored.
|
||||
```bash
|
||||
export SHUMAI_API_SERVER="https://shumai.example.com"
|
||||
export SHUMAI_RUNNER_KEY="your-runner-key"
|
||||
shumai-cli runner start --cwd /path/to/workspace
|
||||
```
|
||||
|
||||
### File System Restrictions
|
||||
On Windows, set the variables in PowerShell:
|
||||
|
||||
To protect your workspace environments and sensitive data, the sandbox enforces strict file-level access controls:
|
||||
```powershell
|
||||
$env:SHUMAI_API_SERVER = "https://shumai.example.com"
|
||||
$env:SHUMAI_RUNNER_KEY = "your-runner-key"
|
||||
shumai-cli runner start --cwd C:\workspace
|
||||
```
|
||||
|
||||
- **Read Access**: The sandbox is allowed to read files within the workspace, with a strict exception for sensitive environment and certificate files. It cannot read: `['.env', '.env.*', '*.pem', '*.key']`.
|
||||
- **Write Access**: The sandbox is heavily restricted and may only write to the `.pi` folder located in the current working directory (cwd). Even within this allowed directory, the sandbox is explicitly blocked from writing or creating sensitive files matching: `['.env', '.env.*', '*.pem', '*.key']`.
|
||||
Use a runner key, not a personal API token. Prefer the environment variable over `--key` to keep the key out of shell history. The runner stays in the foreground; Ctrl+C stops it and its active commands. Temporary connection losses trigger reconnection. Revoked or replaced connections stop instead of reconnecting.
|
||||
|
||||
---
|
||||
The first runner becomes the team default. Each agent can use that default or a dedicated runner selected in its settings. Without a configured runner, `bash` and `download_asset` are hidden. With one configured, authorized editors and reviewers can run commands immediately without reading a skill first. Disabled-tool policies still apply. An offline runner produces an execution error.
|
||||
|
||||
## Domain Whitelisting
|
||||
The `bash` tool uses `/bin/sh` on macOS and Linux. On Windows, the runner looks for Git Bash in the standard installation directories, then for `bash.exe` on PATH, and falls back to `cmd.exe`. The runner prints its selected shell at startup and reports it to the agent so it can use compatible syntax. For Bash with SRT on Windows, use Git Bash in place of the legacy WSL Bash launcher.
|
||||
|
||||
By default, Network Sandbox is **disabled** (allowing all outbound network requests). Team Owners can toggle Network Sandbox **ON** in Sandbox Settings to enforce strict domain whitelisting:
|
||||
Commands start in the workspace directory. Skills, downloaded assets, generated files, and output logs live under `.pi`. Commands inherit baseline OS settings and explicit skill variables, rather than the runner's full environment, including its runner key and personal API token.
|
||||
|
||||
### Allowed Domains
|
||||
Everyone with shell access to the same runner can read files left in its workspace, including assets and logs from other projects. Shumai project permissions apply when assets are downloaded. Share a runner only among users who may read all files in that workspace. For separate trust groups, use separate runner accounts or virtual machines and restrict access to the agents bound to each runner.
|
||||
|
||||
A list of domains that sandboxed scripts are permitted to access.
|
||||
## Optional SRT sandbox
|
||||
|
||||
- Default whitelisted domains include standard package registries (like npm or python package hosts) and repository hosts (like `github.com`).
|
||||
- If a script needs to call an external API (e.g. `api.slack.com`), the administrator must add it to the allowed list.
|
||||
Without `--srt`, commands have the runner operating-system user's permissions. Connect only to a trusted Shumai server; use a dedicated container, VM, or account when appropriate.
|
||||
|
||||
### Pending Domains
|
||||
[Anthropic Sandbox Runtime](https://github.com/anthropics/sandbox-runtime) is bundled as a library in Shumai CLI. Install its platform prerequisites on the runner machine (Linux: bubblewrap, socat, and ripgrep; macOS: ripgrep), then start with its JSON settings:
|
||||
|
||||
When an agent script attempts to reach a domain that is not currently authorized:
|
||||
```bash
|
||||
shumai-cli runner start --cwd /path/to/workspace --srt sandbox.json
|
||||
```
|
||||
|
||||
1. The network connection is blocked immediately.
|
||||
2. The target domain is logged and added to the **Pending Domains** list.
|
||||
3. Admins can review this list and click **Approve** to authorize the domain, or **Reject** to keep it blocked.
|
||||
Windows uses SRT's alpha Windows support. Run the one-time setup before starting a sandboxed runner; it requests administrator permission:
|
||||
|
||||

|
||||
```powershell
|
||||
npx @anthropic-ai/sandbox-runtime windows-install
|
||||
```
|
||||
|
||||
SRT verifies the setup at startup and reports an error if it is missing. A runner without `--srt` does not need this setup.
|
||||
|
||||
The JSON uses upstream SRT settings directly. For example:
|
||||
|
||||
```json
|
||||
{
|
||||
"filesystem": {
|
||||
"denyRead": ["~/.ssh", "~/.aws", ".env", ".env.*"],
|
||||
"allowWrite": [".pi"],
|
||||
"denyWrite": []
|
||||
},
|
||||
"network": {
|
||||
"allowedDomains": [],
|
||||
"deniedDomains": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This example allows writes only in `.pi`, denies reads of the listed credential locations, and blocks command network access. Review read permissions and network rules for your environment using SRT's documentation. Relative filesystem paths use the runner workspace. Settings are snapshotted at startup; restart after changing them. Missing or invalid settings, missing SRT prerequisites, and sandbox initialization failures stop startup. Commands never fall back to unrestricted execution.
|
||||
|
||||
SRT wraps shell commands and their child processes. One shared SRT runtime handles concurrent commands and is reset when the runner stops. The runner's WebSocket and server-directed file transfers operate outside SRT. **The Shumai server address is not automatically added to allowed domains.** If a script itself needs network access, explicitly allow its destination in the JSON.
|
||||
|
||||
Shumai has no server-side sandbox or domain settings. SRT is initialized only on runners that opt into it. SRT in Docker may require namespace permissions on that dedicated runner container; these permissions are not needed by the Shumai server.
|
||||
|
||||
## Runner in Docker
|
||||
|
||||
An ordinary runner can run in its own container without extra capabilities or an exposed port:
|
||||
|
||||
```bash
|
||||
docker run --rm --init --name shumai-runner \
|
||||
--cap-drop ALL --security-opt no-new-privileges \
|
||||
-e SHUMAI_API_SERVER -e SHUMAI_RUNNER_KEY \
|
||||
-v shumai-runner-workspace:/workspace -w /workspace \
|
||||
node:22-bookworm sh -c \
|
||||
'npm install -g @shumai-one/shumai-cli && exec shumai-cli runner start'
|
||||
```
|
||||
|
||||
For development, HTTP is accepted for `localhost`, `127.0.0.1`, `[::1]`, and Docker's `host.docker.internal`. Remote servers require HTTPS. Avoid mounting sensitive host directories or the Docker socket into the runner workspace.
|
||||
|
||||
## Limits and lifecycle
|
||||
|
||||
Commands default to 120 seconds and accept a maximum timeout of one hour. Timeout and cancellation attempt to terminate the command and its process tree. Each command saves up to 64 MiB of output in `.pi/logs`; manage retained logs as part of workspace maintenance. Transfers and extracted archives are limited to 256 MiB. Protocol file operations reject paths outside `.pi`, existing symlinks, and unsafe archive entries. V1 assumes commands do not deliberately change workspace paths while transfers are running.
|
||||
|
||||
Temporary reconnects reconcile active and recently completed commands without deliberately executing them again. Restarting the runner process does not resume commands from the previous process.
|
||||
|
||||
Up to eight commands and file transfers can run concurrently in the shared workspace. Additional requests return a busy error. On Windows without SRT, background processes may survive after the command's shell exits; remaining output pipes are closed after one second. Use foreground commands for predictable timeout and cancellation. SRT manages the sandboxed Windows process tree.
|
||||
|
||||
@@ -34,59 +34,125 @@ The following tools can be individually toggled in the agent configuration dialo
|
||||
|
||||
- **Description:** Allows the agent to inspect images, extract still frames from video files, render PDF document pages, and read text/markdown documents.
|
||||
- **Why it matters:** Enables multimodal agents to view visual media assets uploaded to Shumai, extract frame-by-frame video screenshots, inspect document layouts, and answer questions about uploaded creative assets.
|
||||
- **Limits:** Up to 20 video frames or PDF pages per call. If rendering takes longer than about a minute, the tool tells the agent the render is still in progress instead of failing.
|
||||
|
||||
### 4. Browse Shumai (`list_assets`)
|
||||
### 4. Get Asset Render (`get_asset_render`)
|
||||
|
||||
- **Description:** Allows the agent to list folders and browse files in Shumai.
|
||||
- **Description:** Allows the agent to pick up video frames or document pages that were still rendering when `read_asset` returned.
|
||||
- **Why it matters:** Long videos and large documents can take a while to render. With this tool the agent can come back for the result instead of starting over. It only returns renders that `read_asset` started for the same user.
|
||||
|
||||
### 5. Browse Shumai (`list_assets`)
|
||||
|
||||
- **Description:** Allows the agent to list folders and browse files in Shumai. Large folders are returned page by page.
|
||||
- **Why it matters:** Gives the agent visual mapping of the project structure so it can search for other files or locate related assets.
|
||||
|
||||
### 5. Create Folder (`create_folder`)
|
||||
### 6. List Projects (`list_projects`)
|
||||
|
||||
- **Description:** Allows the agent to list the projects you have access to across your teams, including each project's root folder.
|
||||
- **Why it matters:** Lets the agent find the right project and its root folder on its own before browsing or creating files.
|
||||
|
||||
### 7. Create Folder (`create_folder`)
|
||||
|
||||
- **Description:** Allows the agent to create new folders in Shumai.
|
||||
- **Why it matters:** Needed if the agent organizes outputs or places files in custom subdirectory folders.
|
||||
|
||||
### 6. Create File (`create_file`)
|
||||
### 8. Create File (`create_file`)
|
||||
|
||||
- **Description:** Allows the agent to create and upload new files to Shumai.
|
||||
- **Why it matters:** Allows the agent to generate new assets (e.g. text logs, transcoded clips, reports) and save them directly back into your project.
|
||||
|
||||
### 7. Create Version (`create_version`)
|
||||
### 9. Create Version (`create_version`)
|
||||
|
||||
- **Description:** Allows the agent to upload and stack a new version of an existing file in Shumai.
|
||||
- **Why it matters:** Allows the agent to update files in a clean, non-destructive way by stacking revisions rather than creating duplicate files.
|
||||
|
||||
### 8. Generate Image (`generate_image`)
|
||||
### 10. Generate Image (`generate_image`)
|
||||
|
||||
- **Description:** Allows the agent to generate still images from text prompts and reference images using configured AI image models.
|
||||
- **Why it matters:** Enables agents to create concept art, mockups, textures, and illustrations directly inside Shumai.
|
||||
- **Prerequisite:** This tool requires at least one image model to be configured and enabled in [Image / Video Generation](/using-shumai/image-video-generation). If no image models are enabled under a configured provider, this tool is omitted from the agent session even if enabled in the agent settings dialog.
|
||||
|
||||
### 9. Generate Video (`generate_video`)
|
||||
### 11. Generate Video (`generate_video`)
|
||||
|
||||
- **Description:** Allows the agent to generate video clips from text prompts, image animation, or transition keyframes using configured AI video models.
|
||||
- **Why it matters:** Enables agents to produce short animated clips, camera motion shots, and video transitions.
|
||||
- **Prerequisite:** This tool requires at least one video model to be configured and enabled in [Image / Video Generation](/using-shumai/image-video-generation). If no video models are enabled under a configured provider, this tool is omitted from the agent session even if enabled in the agent settings dialog.
|
||||
|
||||
### 10. Download Asset (`download_asset`)
|
||||
### 12. Download Asset (`download_asset`)
|
||||
|
||||
- **Description:** Allows the agent to download a workspace asset or specific storage S3 key to the local `.pi` directory for processing with local scripts or bash commands.
|
||||
- **Description:** Allows the agent to download up to 50 workspace files, or a specific storage S3 key (such as a frame from `read_asset`), to the local `.pi` directory for processing with local scripts or bash commands. By default it downloads the web preview version when there is one (for example the transcoded video or the web image); the agent can ask for the original uploaded file instead. Folders are not supported.
|
||||
- **Why it matters:** Enables agents executing custom skill scripts to fetch files or intermediate transcode artifacts to local disk.
|
||||
|
||||
### 11. Rename Asset (`rename_asset`)
|
||||
### 13. Rename Asset (`rename_asset`)
|
||||
|
||||
- **Description:** Allows the agent to rename an existing file or folder in Shumai.
|
||||
- **Why it matters:** Enables agents to keep project files neatly named and organized according to workspace naming conventions. Enabled by default.
|
||||
|
||||
### 12. Move Assets (`move_assets`)
|
||||
### 14. Move Assets (`move_assets`)
|
||||
|
||||
- **Description:** Allows the agent to move one or more assets to a destination parent folder.
|
||||
- **Why it matters:** Enables agents to reorganize workspace structures, relocate generated outputs, or tidy up project folders. Enabled by default.
|
||||
|
||||
### 13. Delete Asset (`delete_asset`)
|
||||
### 15. Delete Asset (`delete_asset`)
|
||||
|
||||
- **Description:** Allows the agent to delete a single file or folder by moving it to the Trash bin.
|
||||
- **Why it matters:** Provides agents with the ability to clean up outdated or redundant assets. To prevent accidental data loss, this tool is **disabled by default** and strictly limited to deleting one asset at a time. Team Owners must explicitly enable this tool for an agent.
|
||||
|
||||
### 16. Search Assets (`search_assets`)
|
||||
|
||||
- **Description:** Allows the agent to search a folder and its subfolders by name, by meaning (when AI search is enabled for the team), or by metadata such as status.
|
||||
- **Why it matters:** Lets the agent find the files a request is about without browsing folder by folder.
|
||||
|
||||
### 17. Copy Assets (`copy_assets`)
|
||||
|
||||
- **Description:** Allows the agent to copy files or folders, with everything inside them, into another folder of the same team.
|
||||
- **Why it matters:** Lets the agent reuse assets across projects or set up working copies while keeping the originals unchanged.
|
||||
|
||||
### 18. Read Folder Instructions (`get_folder_instructions`)
|
||||
|
||||
- **Description:** Allows the agent to read a folder's instructions for AI agents (its AGENTS.md).
|
||||
- **Why it matters:** Lets the agent follow the team's conventions, such as naming rules or deliverable specs, before adding files to a folder.
|
||||
|
||||
### 19. Read Comments (`list_comments`)
|
||||
|
||||
- **Description:** Allows the agent to read the review comments and replies on a file, including their timecodes.
|
||||
- **Why it matters:** Lets the agent act on review feedback, for example to summarize open notes or address them in a new version.
|
||||
|
||||
### 20. Post Comment (`create_comment`)
|
||||
|
||||
- **Description:** Allows the agent to comment on a file, optionally at a timecode, or reply to a comment. Comments are posted as the user the agent works for; the audit log records that the agent wrote them.
|
||||
- **Why it matters:** Lets the agent take part in reviews like a teammate. Mentions in the agent's comments don't start other agents.
|
||||
|
||||
### 21. Resolve Comment (`resolve_comment`)
|
||||
|
||||
- **Description:** Allows the agent to mark comments as resolved, or reopen them.
|
||||
- **Why it matters:** Lets the agent close the feedback it has addressed.
|
||||
|
||||
### 22. List Metadata Fields (`list_metadata_fields`)
|
||||
|
||||
- **Description:** Allows the agent to see a project's metadata fields, such as status, rating, and custom fields, with their choices.
|
||||
- **Why it matters:** Tells the agent which values it can search by or set.
|
||||
|
||||
### 23. Update Metadata (`update_asset_metadata`)
|
||||
|
||||
- **Description:** Allows the agent to set metadata values on a file, such as its status or tags. Read-only fields can't be changed.
|
||||
- **Why it matters:** Lets the agent keep a file's review status and other fields up to date.
|
||||
|
||||
### 24. Create Version Stack (`create_version_stack`)
|
||||
|
||||
- **Description:** Allows the agent to stack existing files in the same folder as versions of one asset.
|
||||
- **Why it matters:** Lets the agent tidy up loose revisions (for example `cut_v1.mp4` and `cut_v2.mp4`) into one versioned asset.
|
||||
|
||||
### 25. List Versions (`list_versions`)
|
||||
|
||||
- **Description:** Allows the agent to list the versions in a version stack, latest first.
|
||||
- **Why it matters:** Lets the agent compare a file with earlier versions.
|
||||
|
||||
### 26. Remove Version (`remove_version`)
|
||||
|
||||
- **Description:** Allows the agent to take a version out of its stack. The file isn't deleted; it goes back into the folder as a separate file.
|
||||
- **Why it matters:** Lets the agent fix a version that was stacked by mistake.
|
||||
|
||||
---
|
||||
|
||||
## Restricting Tools
|
||||
|
||||
@@ -0,0 +1,127 @@
|
||||
---
|
||||
title: Email Notifications
|
||||
description: Configure team SMTP settings, deliver batched activity digest emails, and send test emails.
|
||||
---
|
||||
|
||||
Shumai includes a built-in email notification system that delivers updates on team activities—such as comments, mentions, new asset uploads, status changes, and Kanban tasks—directly to team members' inboxes.
|
||||
|
||||
To prevent inbox clutter and notification fatigue, Shumai does not send emails for every single action individually. Instead, a background delivery service aggregates pending notifications and sends periodic, batched digest emails with inline thumbnails and deep links.
|
||||
|
||||
---
|
||||
|
||||
## Configuring SMTP Settings
|
||||
|
||||
Email notification settings are managed at the team level by **Team Owners**.
|
||||
|
||||
To configure outgoing mail:
|
||||
|
||||
1. Click on **Team Settings** in the sidebar.
|
||||
2. Select the **Email Notifications** tab.
|
||||
3. Turn on the **Enable Email Notifications** switch.
|
||||
4. Fill in your SMTP server credentials and sender information.
|
||||
5. Click **Save** or **Save and Send Test Email**.
|
||||
|
||||
### SMTP Server Settings
|
||||
|
||||
| Field | Description | Example / Default |
|
||||
| :---------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------- |
|
||||
| **SMTP Host** | The hostname or IP address of your outgoing SMTP server. | `smtp.example.com` or `smtp.sendgrid.net` |
|
||||
| **SMTP Port** | The port used to connect to your SMTP server. | `587` (default, STARTTLS), `465` (SSL/TLS), or `25` |
|
||||
| **Username** | The username or API key required to authenticate with the SMTP server. | `user@example.com` or `apikey` |
|
||||
| **Password** | The authentication password or API secret. | `••••••••` |
|
||||
| **SSL / TLS (SMTPS)** | Connect directly using SSL/TLS encryption. Typically required when connecting over port `465`. | `Disabled` (default) |
|
||||
| **Ignore Certificate Errors** | Allows connections with self-signed, invalid, or unverified TLS certificates. Useful for local testing (e.g. Mailpit, MailHog) or private corporate relays. | `Disabled` (default) |
|
||||
|
||||
> [!TIP]
|
||||
> **Password Retention**: When updating existing email settings, you can leave the password input blank to keep the currently stored password. For security, stored passwords are never returned in cleartext to the client.
|
||||
|
||||
### Sender Information
|
||||
|
||||
| Field | Description | Example / Default |
|
||||
| :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------- |
|
||||
| **From** | The sender name and email address that will appear in the `From` header. Ensure your SMTP provider is authorized to send on behalf of this address. | `Shumai <noreply@example.com>` |
|
||||
| **Reply-To** | _(Optional)_ An email address to receive replies if members respond directly to a notification email. | `support@example.com` |
|
||||
|
||||
---
|
||||
|
||||
## Testing SMTP Delivery
|
||||
|
||||
Before relying on email delivery, you can verify your configuration and credentials directly from the settings page:
|
||||
|
||||
1. Click **Save and Send Test Email**.
|
||||
2. In the **Send Test Email** modal, verify or adjust the sender `From` address.
|
||||
3. Click **Send Test Email**.
|
||||
|
||||
Shumai will perform an active handshake verification (`transport.verify()`) against your SMTP server and dispatch a styled test message to the email address of the currently logged-in administrator.
|
||||
|
||||
If the handshake or delivery fails (for example, due to an invalid password, blocked outbound port, or rejected sender address), an error toast is displayed with the exact message returned by the SMTP server.
|
||||
|
||||
---
|
||||
|
||||
## Delivery Architecture & Digest Batching
|
||||
|
||||
Shumai uses an asynchronous, batched architecture for email delivery:
|
||||
|
||||
```
|
||||
[ Team Activity ]
|
||||
(Comments, Uploads, Mentions, Kanban)
|
||||
│
|
||||
▼
|
||||
[ Database Queue ] (status: pending)
|
||||
│
|
||||
▼ (Every 3 minutes)
|
||||
[ Notification Background Job ]
|
||||
│
|
||||
├─ Filter recipients (check user preferences & project scope)
|
||||
├─ Exclude self-actions and AI agents
|
||||
├─ Group & collapse items (clusters > 3 summarized)
|
||||
├─ Fetch avatars & thumbnails as inline CID attachments
|
||||
│
|
||||
▼
|
||||
[ Nodemailer Transport ] ──> SMTP Server ──> [ Member Inboxes ]
|
||||
```
|
||||
|
||||
### 1. Periodic Background Delivery
|
||||
|
||||
Notifications are queued in PostgreSQL with a `pending` status. A background job runs periodically every **3 minutes**, acquiring pending notifications using atomic queue locking (`FOR UPDATE SKIP LOCKED`). This ensures safe delivery without duplicate emails even when multiple server instances run concurrently.
|
||||
|
||||
### 2. Digest Bundling
|
||||
|
||||
Rather than sending an email immediately for each action, all notifications collected for a recipient during the 3-minute window are combined into a single digest email. This keeps team communication organized and eliminates inbox spam during heavy collaboration sessions.
|
||||
|
||||
### 3. Smart Activity Collapsing
|
||||
|
||||
When an event cluster contains a high volume of items (for example, when an editor uploads dozens of video clips at once), Shumai automatically groups and collapses the items:
|
||||
|
||||
- If **3 or fewer** items are in a group, each item is displayed with its individual thumbnail and details.
|
||||
- If **more than 3** items are uploaded together, Shumai summarizes them into a single concise notification (e.g., _"Alice uploaded 12 new files to Project Alpha"_) with a preview of the first three file names.
|
||||
|
||||
### 4. Inline CID Attachments
|
||||
|
||||
Avatars and video/image asset thumbnails are retrieved from storage and embedded directly into the email as inline MIME attachments (`cid:...`).
|
||||
|
||||
Unlike external image links, inline CID attachments:
|
||||
|
||||
- Display immediately in desktop and mobile email clients (such as Apple Mail, Gmail, and Outlook) without being blocked by "show remote content" security warnings.
|
||||
- Do not require publicly accessible S3 URLs or reverse-proxy authentication to render.
|
||||
|
||||
### 5. Deep Linking
|
||||
|
||||
Every notification card in the email includes deep-linking action buttons (such as **View Asset**, **View Project**, or **View Task**) that navigate members straight to the corresponding resource in Shumai.
|
||||
|
||||
To ensure links point to your public domain instead of `localhost`, configure the `APP_URL` or `BETTER_AUTH_URL` environment variable on your Shumai server:
|
||||
|
||||
```bash
|
||||
APP_URL=https://shumai.example.com
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Member Preferences & Filtering
|
||||
|
||||
Email delivery respects team permissions and member choices:
|
||||
|
||||
- **Personal Preferences**: Team members can independently choose which types of activities they receive by opening **Team Settings > Notifications**. If a user disables notifications for a category (e.g. general comments or status updates), Shumai will not include those items in their email digests.
|
||||
- **Self-Action Suppression**: Members never receive notification emails for their own comments, uploads, or task updates (unless they explicitly enable the **Your Uploads** preference to be notified when their own media transcoding completes).
|
||||
- **Project Scope**: Members whose access is restricted to specific projects only receive email digests for activities within those assigned projects, unless they are explicitly `@mentioned`.
|
||||
- **AI Agents**: Automated AI agent accounts are automatically excluded from receiving email notifications.
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user