Compare commits

...
192 Commits
Author SHA1 Message Date
yiling d8c20d6a11 Release v0.7.0 2026-11-18 21:10:30 +08:00
yiling 8697481d43 update changelog 2026-11-18 20:21:57 +08:00
Yiling-J 4ac274cdd4 feat(runner): replace server-side bash sandbox with remote runner (#530)
* feat(runner): replace server-side bash sandbox with remote runner

* fix(runner): address review findings for output bounds, key rotation, defaults, and generated uploads

* chore(docker): remove sandbox privileges and env vars from remaining compose files

* feat(cli): add runner start with bundled SRT sandboxing (#535)

* refactor(agent): expose runner bash without skill gating

* feat(cli): add runner start with optional SRT sandboxing

* refactor(cli): remove runner Python dependency

* feat(cli): bundle SRT and use platform-native runner shells

* refactor(cli): delegate runner processes to Execa

* chore(cli): upgrade @anthropic-ai/sandbox-runtime to 0.0.83

* feat(cli): discover Bash for Windows runners

Use Pi-style Bash discovery and launch behavior, exercise the packaged CLI shell, and wait for pending ZIP metadata reads before closing cancelled downloads.

* fix(runner): enforce ownership and safe reconnects

Gate dispatch on reconciliation, retain cancellations across disconnects, and stop replaced clients. Guard the single-server runner topology with a database lease. Restage missing generated inputs, report signal exits, and bound generated-file cleanup.

* feat(webui): add Korean translations for agent runners

* feat(cli): add runner event logging and --verbose flag (#536)

* feat(cli): add runner event logging and --verbose flag

* fix(cli): log runner capacity rejections accurately and use monotonic duration
2026-11-18 15:58:57 +08:00
Yiling-J eea844320d fix(signup): separate login prompt from language selector (#534) 2026-11-17 10:17:10 +08:00
d255e76806 feat(i18n): add Korean locale (#531)
Add a Korean message catalog covering every key in the English catalog,
with placeholders matching English for each message. Register ko in the
inlang project, accept it as a sign-up and saved user locale, and offer it
in the sign-up language switch and the team settings language select.

Co-authored-by: phj1081 <5908832+phj1081@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>
2026-11-16 18:48:01 +08:00
yiling 2be1093b91 fix(cli): explain how to configure the installer PATH 2026-11-13 21:11:18 +08:00
yiling 83e902862c fix(cli): discover draft releases before publishing 2026-11-13 20:37:50 +08:00
yiling 0a66776067 Release v0.6.6 2026-11-13 20:01:51 +08:00
Yiling-J c55804a548 feat(operations): add create_project operation across agent, mcp, and cli (#529)
* feat(operations): add create_project operation across agent, mcp, and cli

* fix(api): remove legacy team creation endpoint

* fix(api): preserve ProjectInfo response on POST /teams/:teamId/projects
2026-11-13 11:43:08 +08:00
Yiling-J 97c2939b5e feat(cli): add standalone downloads and installers (#528)
* feat(cli): add standalone downloads and installers

* fix(cli): silence PowerShell download progress

* fix(cli): use framework APIs for Windows verification

* fix(cli): preserve null backup path during Windows updates

* docs(cli): translate native installation quickstart into Chinese
2026-11-12 19:37:33 +08:00
Yiling-J 0325435125 fix(storage): remove empty local embedding directories (#527) 2026-11-12 09:22:48 +08:00
Yiling-J 00fa5fed75 refactor(agent): share the SQLite session cache (#526) 2026-11-11 17:05:34 +08:00
Yiling-J 35a0e82284 refactor(agent)!: migrate to Pi Durable and embed the agent queue (#525)
* refactor(agent)!: migrate sessions to Pi Durable

Replace patched AgentHarness storage with per-session SQLite and PostgreSQL commit mirroring. Migrate legacy history automatically and run agent queues with the main server.

BREAKING CHANGE: Remove standalone agent workers and return native Pi entry records from chat history APIs.

* fix(agent): constrain session log dialog scrolling

Keep the header visible and wrap long output while log entries and expanded records scroll within the dialog. Cover desktop and narrow viewports through the dashboard Sessions flow.

* fix(agent): hide entry IDs from session log card headers

Retain internal entry IDs in expanded raw records for debugging. Verify that card headers omit the IDs while raw JSON preserves them.

* test(e2e): handle browser wheel limits in session log checks

Verify that a normal wheel event moves the viewport before explicitly scrolling to the final record. Keep the dialog bounds, fixed header, wrapping, and expanded-record assertions.

* fix(agent): select model providers without inheriting unrelated auth

* fix(webui): prevent resize feedback when toggling agent panel

* test(agent): reproduce concurrent comment session races

* fix(agent): serialize comment sessions and deduplicate history

* docs(changelog): consolidate Pi Durable changes into one entry
2026-11-11 16:05:18 +08:00
yiling 843a56304c docs: replace discord links with discourse forum 2026-11-09 10:56:30 +08:00
yiling 1050024fff Release v0.6.5 2026-11-07 19:55:05 +08:00
Yiling-J 403e209359 fix(webui): prevent duplicate name in sort/filter selectors and add toolbar quick actions (#523) 2026-11-07 18:35:49 +08:00
Yiling-J 0359733637 fix(share,file-browser): improve public share opening and multi-selection interactions (#522)
* fix(share,file-browser): improve public share opening and multi-selection interactions

* docs(changelog): merge release notes into single entry with Frame.io behavior change details

* fix(file-browser,share): prevent duplicate double-click navigation and fix stale range anchor
2026-11-07 11:18:47 +08:00
Yiling-J 2d2ea51668 docs(i18n): add Chinese documentation (#520) 2026-11-06 11:46:53 +08:00
yiling a71723d455 docs: add BETTER_AUTH_SECRET to docker-compose environment variables 2026-11-06 10:50:18 +08:00
yiling ab250a9f0a docs: clarify BETTER_AUTH_URL usage and scope 2026-11-06 10:36:22 +08:00
yiling 0c0b887b8d Release v0.6.4 2026-11-05 22:45:25 +08:00
Yiling-J f304caea00 fix(auth,web): gracefully degrade MCP on remote HTTP and cache production static assets (#519)
* fix: gracefully handle remote HTTP URLs for MCP and cache production static assets

* test(mcp): add remote http mcp integration test and fix static etag normalization and fallback error
2026-11-05 22:21:11 +08:00
Yiling-J 65e2ac1383 fix(security): improve access control and storage security (#518)
* fix(security): improve access control and storage security

* fix(security): set NODE_ENV in dockerfiles and sign local storage get urls with lru cache
2026-11-05 20:49:38 +08:00
Yiling-J 0dc0bbeb03 feat(file-browser): add context-aware copy submenu (#517)
* feat(file-browser): add context-aware copy submenu

* refactor(file-browser): address code review feedback for copy submenu

* fix(webui): align submenu trigger text and widen file context menu

* test(e2e): guard clipboard permissions in copy-menu spec for cross-browser support
2026-11-05 09:57:34 +08:00
Yiling-J 2ecbd49d18 feat(storage): add team auto-archive assets policy and background job (#516)
* feat(storage): add team auto-archive assets policy and background job

* fix(storage): address code review feedback on lock safety, starvation, and permissions

* docs: update readme and expand archive storage documentation with auto-archive details

* feat(storage): log info message on auto-archive job start and finish with archived count

* style(storage): stack age threshold and grace period vertically with updated grace period description

* fix(storage): only log auto-archive info messages when candidate assets are found to process
2026-11-04 14:40:44 +08:00
Yiling-J ba3c6dbfee feat(storage): add archive storage support for assets (#514)
* feat(storage): add archive storage support for assets

* fix(webui): show archive icon in front of file name in breadcrumb bar

* fix(webui): display archive icon in breadcrumbs when restoring

* refactor(transcode): simplify restore asset workflow to single while loop

* docs(configuration): add archive storage documentation and readme entries

* fix(webui): show archive icon in front of version names and prevent version card overflow

* fix(webui): fix overflow in manage versions dialog scroll area

* fix(webui): prevent manage versions dialog overflow on long file names

* docs(configuration): fix archive storage environment variables and defaults

* fix(storage): address code review findings for archive storage
2026-11-03 20:31:56 +08:00
yiling 49a2d7c380 Release v0.6.3 2026-11-01 19:52:23 +08:00
Yiling-J 6292f3c792 Revise changelog for upload and agent behavior changes
Updated changelog to reflect important behavior changes in file uploads and agent comments.
2026-11-01 17:19:08 +08:00
Yiling-J 20ad0abeba feat(upload): simplify upload file list display and add live speed & ETA (#513)
* feat(upload): simplify upload file list display and add live speed and ETA

* fix(upload): retain authoritative server search results and handle local failed upload state gracefully
2026-11-01 13:29:52 +08:00
Yiling-J fbff404b9b feat(file): optimize upload and transcoding status polling with batch api (#512)
* feat(file): optimize upload and transcoding status polling with batch api

* fix(webui): throttle search invalidation during upload and fix stuck 100% progress ring

* fix(webui): deduplicate upload search invalidation and stabilize batch polling
2026-10-31 20:11:31 +08:00
Yiling-J c2348b0e68 feat(upload): allow canceling in-progress upload tasks from sidebar (#511)
* feat(upload): allow canceling in-progress upload tasks from sidebar

* fix(upload): resolve concurrent confirmation race and store counter issues on cancellation

* fix(webui): immediately remove cancelled upload files from file list view
2026-10-31 16:39:54 +08:00
Yiling-J ff3d71ed3d feat(agent)!: suppress success comments for autofill and embedding agents (#510)
* feat(agent)!: suppress success comments for autofill and embedding agents

* fix(agent): ensure createCommentActivity runs on workflow cancellation
2026-10-31 12:02:30 +08:00
Yiling-J 77bd1422d8 feat(upload): state-based retry tracking and resilient gateway error handling (#509)
* feat(upload): state-based retry tracking and resilient gateway error handling

* fix(upload): check non-retryable statuses before offline state in isNetworkIssue
2026-10-31 10:37:35 +08:00
Yiling-J 9529c63c0a feat(upload): add 12-hour upload expiration and continuous backoff retry (#508)
* feat(upload): add 12-hour upload expiration and continuous backoff retry

* fix(upload): clamp jittered backoff delay to maxDelayMs and update presign JSDoc
2026-10-30 16:06:34 +08:00
Yiling-J 3b00a42a89 fix(webui): show clear toast when upload fails due to localhost s3 endpoint (#507)
* fix(webui): show clear toast when upload fails due to localhost s3 endpoint

* fix(webui): center empty state in file browser list area
2026-10-30 14:16:34 +08:00
yiling f0bdccf713 Release v0.6.2 2026-10-29 20:29:50 +08:00
yiling 5b7fc04b02 docs: document MCP OAuth support and simplify unreleased changelog 2026-10-29 17:52:45 +08:00
Yiling-J 687b5a79d8 fix(core): strip trailing slashes when normalizing auth and MCP resource URLs (#506)
* fix(core): strip trailing slashes when normalizing auth and MCP resource URLs

* docs: document BETTER_AUTH_URL in README and quickstart guides

* docs: prioritize AWS_ENDPOINT_URL_S3 and clarify applicability to local storage

* docs: refine AWS_ENDPOINT_URL_S3 guidance for local storage deployments
2026-10-29 17:24:31 +08:00
Yiling-J baf30730af feat(mcp): add OAuth 2.1 support (#505)
* feat(mcp): add OAuth 2.1 support with dynamic client registration

* feat(api): alias bare oauth-authorization-server discovery endpoint

* fix(auth): preserve user session on OAuth sign-in redirect to consent
2026-10-29 15:39:37 +08:00
yiling 96539207d0 update readme 2026-10-28 11:41:28 +08:00
yiling 43f95a2fa2 update cn compose 2026-10-28 11:38:07 +08:00
yiling 0f92a5377f update readme 2026-10-28 10:30:13 +08:00
Yiling-J 4e3e17a547 docs: simplify AGENTS.md developer guide (#501) 2026-10-27 15:26:42 +08:00
Yiling-J b3cae4f2b0 feat: move MCP to /mcp and add teammate operations (#500)
* feat(operations): move MCP to /mcp and add search, comment, metadata, version, and upload operations

- Serve the MCP server at /mcp instead of /api/mcp
- Add search_assets, copy_assets, get_folder_instructions, list_comments,
  create_comment, resolve_comment, list_metadata_fields,
  update_asset_metadata, create_version_stack, list_versions, and
  remove_version on the agent, MCP, and CLI
- Add create_file and create_version (agent, MCP) with Creation Context
  metadata, and complete_upload (MCP) for presigned two-step uploads
- Replace the native agent create_file/create_version tools with
  Operation-backed ones
- Route the comment-complete, metadata, copy, version stack, and
  AGENTS.md read REST endpoints through their Operations

* docs(readme): add built-in MCP server and CLI to features list
2026-10-27 14:37:26 +08:00
Yiling-J 50fbd97953 feat: expose read_asset and download_asset on MCP and the CLI (#499)
* feat(asset-read): expose read_asset on MCP and the CLI

Enable the mcp and cli surfaces for read_asset and get_asset_render.

- MCP: add per-Operation tool extensions. The read presenter attaches up
  to 8 images (2 MB each) inline, lists image links, supports
  inlineImages: false, and tells the model to call get_asset_render when
  a render is pending. Storage keys are stripped from the result.
- CLI: generated commands can flatten object inputs into prefixed flags
  (cli.flatten) and omit fields (cli.omit); add per-command extensions.
  New `read` and `render` commands print image links, download them with
  --out, and support --no-wait with a printed `render <taskId>` hint.
- Round frame timestamps in labels to 3 decimals.

* fix(mcp): make tool input schemas portable to single-type dialects

Nullable inputs were emitted as `type: ["number", "null"]` (or a `null`
anyOf branch), which clients that map tool schemas onto an OpenAPI-style
subset (e.g. Gemini function declarations) may reject.

- Make read_asset's startPage, endPage, and degree optional instead of
  nullable.
- Move null handling into a shared dropNullOptionals helper in
  @shumai/operations that also strips nulls inside nested config
  objects. The agent uses it, and the MCP server applies it before the
  SDK validates arguments, so models that send null keep working.
- Test that no Operation input schema (and no listed MCP tool) uses a
  nullable type.

* feat(asset-download): share download_asset across agent, MCP and CLI

Turn the agent-only download_asset tool into an Operation on all three
surfaces.

- download_asset takes up to 50 file or version stack IDs and returns
  presigned links. proxy (default true) picks the web preview when there
  is one, as the agent always did; proxy: false returns the original.
  Folders are rejected. Read is checked on every ID before anything runs.
- Agent: an extension saves the files into the .pi sandbox and keeps the
  agent-only storage key mode (e.g. frames from read_asset). Agent tool
  extensions gain description, parameterOverrides and intercept.
- CLI: `shumai-cli download <assetId...> [--out <dir>] [--original]`
  streams files to disk without overwriting existing names.
- read_asset's unsupported-type error now names the right way to
  download on each surface (download_asset, or `shumai-cli download`).
- Add the Download Asset toggle to agent settings.
2026-10-27 08:09:11 +08:00
Yiling-J 155fb95a0e feat(asset-read): rewrite read_asset as a reader registry and Operations (#498)
Replace the monolithic agent read_asset tool with a reader registry in
@shumai/core/src/asset-read (model3d, image, video, document) behind a
shared pipeline that handles access checks, version stacks, annotations,
render tasks, and waiting.

- Add read_asset and get_asset_render Operations (agent surface only).
  Renders that outlast the caller's wait budget return "pending" with the
  workflow task ID; the read request is stored on the task payload so
  get_asset_render works across restarts and instances (requester only).
- Add workflowService.waitFor and presign expiry support.
- Keep agent output compatible via an agent tool extension (s3KeyOnly,
  image blocks, session image details); autofill keeps its team-scoped tool.
- Cap video frames at 20 per call; add the get_asset_render agent toggle.
2026-10-27 08:09:10 +08:00
Yiling-J e44938cb8f feat(cli): generate shumai-cli commands from Operations with commander (#496)
Rebuild the CLI on commander. Commands for every cli-surface Operation
(project ls, ls, mkdir, rename, move/mv, delete/rm) are generated from
@shumai/operations: positionals, options, choices, numeric parsing and
help text come from the Zod input schema. They call POST /api/ops/:name
with x-shumai-client: cli.

Existing invocations keep working. Adds --json, ls --type/--first/
--after, typo suggestions, and generated help. upload and create-version
stay hand-written. Drops the unused @shumai/core dependency.
2026-10-27 08:09:10 +08:00
Yiling-J 4d61786799 feat(mcp): serve Operations over MCP and a generic /api/ops endpoint (#495)
Add a stateless Streamable HTTP MCP server at /api/mcp that exposes every
mcp-surface Operation with its input/output schemas and annotations, and
POST /api/ops/:name for the CLI. Both require an API token (session
cookies are rejected), run Operations as the token's user, honor demo
read-only mode, and record via mcp/cli/api in audit logs.

Also make list_projects toggleable in agent settings and document MCP
client setup.
2026-10-27 08:09:09 +08:00
Yiling-J 76057ccd21 feat(operations): add shared Operation layer for agent capabilities (#494)
Introduce @shumai/operations (pure definitions: Zod schemas, metadata,
CLI hints) and @shumai/core/src/operations (implementOperation and the
runOperation pipeline: validate, authorize, prepare, execute, validate
output, audit).

Migrate list_assets, create_folder, rename_asset, move_assets and
delete_asset to Operations, and add list_projects. The agent now builds
these tools from the registry, and the folder create/rename, file
rename and reparent routes call the same Operations.

Audit logs gain a nullable via column recording the surface. A lint
rule keeps the Prisma client out of Operation implementations.
2026-10-27 08:09:09 +08:00
Yiling-J 47ee794ae4 fix(agent): enforce access checks in read_thread and before file uploads (#493)
read_thread returned any comment thread by ID. It now requires Read on
the thread's asset for the acting user, and confines system agents
without a user to their own team.

create_file and create_version uploaded to storage before checking Edit
permission, leaving orphaned objects on denied calls. The permission
check now runs first.
2026-10-26 11:14:37 +08:00
Yiling-J 22486b893b feat(api-token): store API tokens as SHA-256 hashes (#492)
New tokens are 32 random bytes with a shumai_ prefix and are returned
only once at creation. The list endpoint returns a 4-character hint
instead of the plaintext. A migration hashes existing tokens in place so
they keep authenticating.
2026-10-26 11:08:46 +08:00
yiling c2af7494ec Release v0.6.1 2026-10-24 13:21:50 +08:00
yiling b7d2748b00 docs(changelog): add bun 1.4.4 upgrade to unreleased changes 2026-10-24 12:02:22 +08:00
Yiling-J 3467c0d92b chore(docker): update Aliyun compose images and document transcode worker scaling in README_CN (#491) 2026-10-24 11:51:37 +08:00
Yiling-J 22fede0290 fix(webui): prevent clipping of long text overlay and date picker in cards (#490)
* fix(webui): prevent clipping of long text overlay and date picker in cards

* docs: update DeepWiki badge url in README and README_CN

* fix(webui): preserve expanded overlay height and textarea style in LongTextField

* fix(webui): add bottom padding to file list to prevent screen clipping of expanded fields

* fix(webui): expand directly into edit mode on single click for LongTextField

* fix(webui): prevent file selection when interacting with metadata fields in cards and list rows
2026-10-24 11:40:47 +08:00
Yiling-J d87fe43b0f feat(dashboard): add workflow tasks monitoring and stopping to team dashboard (#489)
* feat(dashboard): add workflow tasks monitoring and stopping to team dashboard

* fix(asset): retain workflow tasks on asset purge and mark active tasks as failed

* style(webui): add edge padding to audit logs and workflow tasks tables

* fix(workflow): atomically update asset status to failed when task is stopped

* fix(workflow): propagate cancellation errors, guard concurrent task stop, and localize UI

* docs(changelog): keep only added log for workflow tasks dashboard

* test(provider): mock upstream catalog api calls using saved fixtures

* feat(dashboard): show file name, size, and project name in workflow tasks list
2026-10-23 16:44:52 +08:00
Yiling-J 7a0ffca629 Add feedback invitation to README
Added a feedback section to encourage user engagement.
2026-10-22 20:39:56 +08:00
Yiling-J 5cf6d31794 chore(deps): upgrade bun to 1.4.4 and migrate to bun fmt (#488)
- Upgrade Bun to 1.4.4 across Dockerfiles, CI workflows, and release configurations.
- Update @types/bun and bun-types.
- Remove eslint-plugin-prettier and update format script to use native bun fmt.
- Configure .prettierignore to exclude packages/webui/public and minified files.
2026-10-22 20:25:54 +08:00
Yiling-J 0d5fe48a3a docs(docker): add guide for scaling transcoding workers horizontally (#486) 2026-10-21 12:45:09 +08:00
Yiling-J 19eed521ae fix(webui): prevent unwanted redirects to login on reset-password page (#487)
* fix(webui): allow reset-password route with token when stale auth exists

* fix(webui): prevent 401 redirect to login on reset-password page
2026-10-21 12:12:25 +08:00
yiling e05a23bcc2 Release v0.6.0 2026-10-20 20:02:34 +08:00
Yiling-J d957ab2339 fix(webui): fix loading skeleton layout mismatches and keep left carousel visible (#485)
* fix(webui): fix loading skeleton layout mismatches and keep left carousel visible

* fix(webui): update mobile file list skeleton to match card layout

* fix(webui): blur video poster before playback with instant cut on play

* docs: consolidate webui changelog entries into single line
2026-10-20 17:39:40 +08:00
Yiling-J 1fcd7245ea fix(transcode): ensure durable file exchange and crash recovery across workflow steps (#484)
* fix(transcode): ensure durable file exchange and crash recovery across workflow steps

* fix(transcode): recognize AWS SDK NoSuchKey by name and add workflow E2E recovery test
2026-10-20 11:29:22 +08:00
Yiling-J 176b7f0eab feat(workflow): migrate workflow engine from temporal to dbos (#481)
* feat(workflow): migrate workflow engine from temporal to dbos

Replace Temporal and LocalExecutor with DBOS Transact (@dbos-inc/dbos-sdk) as the unified workflow engine. Background tasks, media transcoding, and AI agent workflows now execute with durable steps and task queues directly against PostgreSQL, eliminating the need for an external Temporal cluster and separate polling executors.

* fix(workflow): submit tasks via DBOSClient to allow enqueueing from steps

Enqueuing workflows using DBOS.enqueueWorkflowWithOptions threw a
DBOSInvalidWorkflowTransitionError when triggered from within a running
step or activity (e.g. creating embedding or autofill tasks during
video transcoding).

Use DBOSClient to submit and cancel workflow tasks directly against the
system database, detaching execution from the ambient workflow/step
context.

* feat(web): support SHUMAI_WORKERS environment variable

* fix(workflow): ensure CLI tasks are enqueued to DBOS and run DBOS migrations in global setup

- Initialize workflows and wait for pending DBOS submissions in shumai regenerate-embeddings CLI
- Remove no-op submit bypass and enqueue tasks via DBOSClient in producer and CLI contexts
- Add DBOS migration runner in test global setup to avoid concurrent migration deadlocks across test forks
- Update changelog and add regression tests

* fix(workflow): ensure unique per-instance executor identity for worker replicas

- Derive unique per-instance DBOS executor IDs across worker replicas

- Support SHUMAI_WORKER_ID, DBOS__VMID, and POD_NAME (Kubernetes Downward API)

- Disambiguate multi-replica bare metal/container deployments with host, PID, and instance suffix

- Prevent startup recovery from re-enqueueing workflows actively executed by other live workers

- Add multi-instance startup recovery tests and update deployment documentation

* fix(workflow): only register listened queues and update concurrency on change

- Only register queues that the executor instance actively listens to

- Use always_update conflict resolution so environment variable changes take effect on restart

- Prevent dedicated workers from overwriting unmanaged queue concurrency configurations

- Add tests verifying concurrency updates and queue isolation across worker roles

* refactor(workflow): simplify activities to use defineStep and direct calls (#482)

* refactor(workflow): simplify activities to use defineStep and direct calls

- Wrap activities using defineStep from @shumai/workflow-core
- Remove obsolete getActivities, registerActivities, dynamic activity proxies, and workerQueue arguments
- Remove executor.ts and registry.ts, consolidating workflow registration into workflow.ts
- Call activities directly across transcode and agent workflows
- Update all corresponding workflow tests and developer guide documentation

* fix(workflow): properly detect DBOSWorkflowCancelledError in runOnCancel fallback

- DBOSWorkflowCancelledError in DBOS SDK does not set name, inheriting 'Error'
- Implement isDbosWorkflowCancelledError checking instanceof, constructor.name, and dbosErrorCode
- Update unit tests to verify real DBOS SDK cancellation error instances

* docs(workflow): update documentation and readme for dbos migration

- Rename docs/configuration/temporal.mdx to docs/configuration/distributed.mdx
- Document DBOS-based distributed worker architecture and task queues
- Remove obsolete docker-compose/temporal/
- Update environment variables documentation in docs/configuration/env-variables.mdx
- Update references in README.md, README_CN.md, docs/docs.json, and related guides

* feat(deploy): implement KEDA ScaledJob and scale-to-zero On-Demand transcoding (#483)

* feat(deploy): add shumai-transcode docker image and k8s autoscaling example with garage s3

* docs(k8s): document port-forwarding and in-cluster s3 domain mapping

* feat(storage): support public s3 endpoint for browser uploads and update k8s example

* fix(k8s): configure s3 bucket cors rules in garage initialization

* fix(k8s): increase transcode worker memory limit to 4Gi for 4K video encoding

* feat(deploy): add AWS EKS deployment with Graviton3 Spot nodegroups and autoscaling

* docs(deploy): redesign EKS documentation, rename k8s to eks, and add scalable deployment feature

* docs: rephrase DBOS feature bullet to Durable Workflows via DBOS

* docs(eks): upgrade default instances to Graviton5 c9g.large and c9g.xlarge

* feat(eks): use On-Demand for general nodegroup and add spot capacity diversification

* docs(eks): fix Architecture diagram to locate all transcode worker pods in Transcode Compute Pool

* feat(deploy): implement KEDA ScaledJob and scale-to-zero On-Demand transcoding

* feat(transcode): support idle-timeout auto-drain for KEDA scaled jobs

* fix(deploy): fix EKS deployment manifests and documentation based on cluster verification
2026-10-19 15:35:08 +08:00
yiling f7ed3bafdf Release v0.5.3 2026-10-16 22:50:47 +08:00
Yiling-J 9f76e61e23 Add documentation for LiteRT-LM Embedding Server setup
Updated documentation for LiteRT-LM Embedding Server setup and other features.
2026-10-16 22:42:07 +08:00
Yiling-J 7c297895e5 feat(embedding): add compose tiers, docs, and regenerate-embeddings CLI (#480)
* feat(embedding): update compose tiers, docs, and add regenerate-embeddings CLI

- Add Lite, Embedding, and Full Docker Compose configurations (and Aliyun mirrors)
- Set CONCURRENCY_AGENT to 1 for compose files containing embedding-server
- Update README and README_CN with compose options, recommended RAM, and semantic search links
- Add LiteRT-LM Embedding Server setup guide in docs/using-shumai/embedding-server.mdx
- Add shumai regenerate-embeddings CLI command and EmbeddingService to regenerate embeddings across teams
- Add comprehensive test coverage for EmbeddingService

* fix(docker): remove basic auth for turntable-renderer in full compose

* fix(agent): lock and disable embedding agent when ENABLE_EMBEDDING_AGENT is false

Ensure that when ENABLE_EMBEDDING_AGENT is set to 'false', existing embedding agents are automatically disabled on startup, marked as read-only, and blocked from manual API modifications or creations. Additionally guard background task creation and semantic search when the environment variable disables embedding agents.

* test(upload): remove flaky status assertion on workflow tasks
2026-10-16 21:20:25 +08:00
Yiling-J 0f318b4050 feat(search): render results in responsive card grid with sprite preview and new-tab navigation (#479)
* feat(search): render results in responsive card grid with sprite preview and new-tab navigation

* fix(search): align semantic matched duration badge style with standard duration badge

* fix(webui): use pointer cursor instead of crosshair cursor for sprite scrubber on hover
2026-10-16 10:42:32 +08:00
Yiling-J 1a46f63160 fix(agent): adaptively set video embedding frame count based on aspect ratio (#477)
* fix(agent): adaptively set video embedding frame count based on aspect ratio

Adjust sampled video frame counts between 15 and 14 based on the video's aspect ratio. Standard aspect ratios (1:1, 4:3, 3:4, 16:9, 9:16, 21:9) stay within the 2048 token signature bucket when using 15 frames, while non-standard or custom aspect ratios use 14 frames to guarantee that sequence length never exceeds 2048 tokens, preventing out-of-memory errors on the embedding server.

* feat(agent): persist video chunk embeddings incrementally and resume on retry (#478)
2026-10-16 08:36:51 +08:00
Yiling-J 6cc90bf973 feat(search): generate query embeddings directly for semantic search (#476)
* feat(search): generate query embeddings directly for semantic search

* fix(search): resolve embedding provider from env, redact query logs, and preserve case in cache
2026-10-15 20:49:45 +08:00
Yiling-J b7271777e0 feat(agent): support gemma-embedding-2-openai provider (#475)
* feat(agent): support gemma-embedding-2-openai provider

Add support for local LiteRT-LM Gemma Embedding 2 provider with 768-dimensional vector embeddings, environment-configured read-only embedding agents, 16-frame uniform sampling for video chunks, and automatic WebP-to-JPEG conversion.

* refactor(agent): remove unused legacy generateEmbeddingActivity

* chore(agent): align sharp version to 0.35.4

* refactor(agent): rename embedding server env to GEMMA_EMBEDDING_OPENAI_BASE_URL

* refactor(agent,transcode): use native Bun.Archive for video chunk frames

* fix(transcode,agent): populate buffer entries in Bun.Archive and validate frame sizes
2026-10-15 15:49:24 +08:00
yiling c302c162a0 Release v0.5.2 2026-10-13 21:03:51 +08:00
Yiling-J 432be04a96 Update CHANGELOG to remove fixed and changed entries
Removed fixed and changed entries related to 3D visual markup and settings adjustments.
2026-10-13 20:18:03 +08:00
yiling 6c95d14fb3 fix(webui): reverse 3D sprite scrubbing and remove container volumes from turntable doc 2026-10-13 16:49:42 +08:00
Yiling-J 3263580e89 fix(webui): clear markup annotations when rotating 3d model (#474) 2026-10-13 15:21:12 +08:00
yiling f3da916905 fix(asset): remove unbundled GLTF format from supported 3D models 2026-10-13 11:38:25 +08:00
Yiling-J fe8d404a44 feat(agent): support 3D degree comments, markup annotations, and config3d in read_asset (#473)
* feat(agent): support AI embedding, autofill, and read_asset for 3D assets

* feat(agent): support 3D degree comments, markup annotations, and config3d in read_asset

* fix(agent): resolve 3D session annotations to turntable degree frame time
2026-10-13 00:03:21 +08:00
Yiling-J 0f9d213b1d docs: update 3D asset and Gotenberg integration guides (#472) 2026-10-12 16:55:20 +08:00
Yiling-J f952318b34 feat(team): add integrations settings with turntable and gotenberg (#471)
* feat(team): add integrations settings with turntable and gotenberg

* fix(upload): pass teamId to gotenberg availability check during upload preflight
2026-10-12 15:38:15 +08:00
Yiling-J 43a2eced75 feat(transcode): add 3D asset support and turntable viewer (#454)
* feat(transcode): add 3D asset support and turntable viewer

* perf(turntable): stream file via Bun.file and increase upload timeout

* feat(turntable): increase upload timeout to 15m to support 5GB uploads

* fix(webui): align 3D model viewer layout and full-width control bar with video viewer

* feat(webui): unify 3D viewer bottom bar and redesign cyclic ruler slider

- Place RulerSlider in single row with playback and zoom controls, centered with max 320px width
- Flank RulerSlider with minus and plus buttons to step angle by 15°
- Redesign RulerSlider with fixed center indicator and moving cyclic track with continuous 360° wrapping
- Render major ticks longer at 60° intervals without numeric text labels on track
- Display floating degree tooltip above center indicator only during dragging

* fix(webui): prevent RulerSlider from collapsing to 0px width in control bar

- Use flex layout with flex-1 on left and right clusters to preserve center cluster width
- Enforce min-w-[140px] and w-full on RulerSlider
- Fix tooltip positioning and remove outer overflow-hidden

* feat(webui): snap RulerSlider track directly to discrete 15° ticks during drag

* fix(webui): prevent ruler snap-back caused by floating point second truncation

- Use Math.round instead of Math.floor in secondToDegree to avoid 0.999996 dropping to previous frame
- Ensure final dragDegree is committed on pointer up

* fix(webui): fix arrow key frame rounding and duplicate event bubbling

- Use Math.round instead of Math.floor for keyboard arrow frame navigation in ModelViewer
- Add e.stopPropagation() to RulerSlider keyboard events to prevent duplicate bubbling to window listener

* feat(webui): redesign RulerSlider with encapsulated step buttons and capsule pill track

* feat(webui): make RulerSlider responsive on mobile and remove bottom bar reset button

* fix(webui): load 3d video directly without poster and invert drag rotation to counterclockwise

* fix(webui): fix 3d asset viewer frame seeking and drag jitter

* feat(transcode): show 3D asset poster preview immediately after render start

* fix(viewer): synchronize 3D turntable playback via frame callback to prevent skipped degrees

* fix(viewer): handle touchpad zoom gestures and prevent page zoom in 3D viewer

* fix(viewer): eliminate 3D model rotation jitter at 345 degrees

* fix(share): watermark 3D asset turntable video on share links

* fix(share): preserve video transcode resolution on watermarked share links

* fix(viewer): download original 3D model file instead of rendered turntable MP4
2026-10-11 21:32:28 +08:00
Christopher BuzickyandBristopher e894457275 fix(transcode): apply EXIF orientation to non-RAW image transcodes and reported size (#461)
* fix(transcode): apply EXIF orientation to image transcodes and reported size

Cameras and phones store portrait shots as landscape pixels plus an EXIF
orientation tag. sharp ignores the tag and the webp output drops it, so
thumbnails, previews, watermarked share-link images and annotated snapshots
came out sideways, and getImageInfo reported width and height swapped
(a 5152x7728 portrait recorded as 7728x5152).

RAW previews keep their existing handling: transcodeImage still rotates them
from the RAW container orientation and only auto-orients inputs without one,
so RAW and non-RAW images are never rotated twice.

- transcodeImage: autoOrient non-RAW input and size previews from the
  oriented dimensions.
- getImageInfo: report metadata.autoOrient dimensions for non-RAW images.
- compositeOverlayToWebpFile and overlayAnnotationsOnBuffer: autoOrient
  the original, and draw annotations in the displayed coordinate space.
- Tests: service tests that reproduce the bug and guard against double
  rotation of RAW, and a workflow e2e case with a real 600x400 JPEG tagged
  orientation 6 that must come out 400x600.

* refactor(transcode): share orientation helper and test all 8 EXIF orientations

Move the autoOrient decision and the displayed-size lookup into orientedSharpOptions and displayedDimensions so getImageInfo, transcodeImage, compositeOverlayToWebpFile and overlayAnnotationsOnBuffer share one rule: auto-orient unless a RAW container orientation was already applied. Behavior is unchanged.

Add transcode.orientation.test.ts, which runs real sharp over a quadrant-colored JPEG tagged with each of the 8 EXIF orientations and checks the reported and transcoded size plus the top-left and bottom-right corner colors.

* fix(transcode): never auto-orient dcraw output

The dcraw_emu fallback reports orientation undefined because LibRaw already rotates upright, so transcodeImage applied autoOrient to the TIFF and could rotate twice if it kept an Orientation tag. extractAndValidateRawPreview now flags the fallback result as orientationApplied and transcodeImage treats it as already oriented (autoOrient false). Tests cover both the dcraw path and an embedded preview with no container orientation.

---------

Co-authored-by: Bristopher <Bristopher@users.noreply.github.com>
2026-10-10 15:41:49 +08:00
4b1b64fe2b feat(kanban): link related assets to their file or folder (#453)
Related assets in the task edit dialog were plain rows with no way to
open them. Add an opt-in `linkable` prop to TaskRelatedAssets that turns
each row's thumbnail and name into a router Link to the asset in its
project (files -> /projects/$projectId/files/$fileId, folders ->
/projects/$projectId/folders/$folderId), falling back to the task's
project when the asset has none. The edit dialog opts in; the create
dialog does not, so a click cannot discard an unsaved draft.

Co-authored-by: Frederic De Decker <hello@trinity.video>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 20:14:36 +08:00
yiling f8beb195dd Release v0.5.1 2026-10-06 22:29:50 +08:00
yiling a97996cb59 docs(changelog): note clickable notification cards 2026-10-06 22:18:18 +08:00
jorgeandYiling-J f870ca9b49 feat(asset): link to assets on notification cards. (#451)
* feat(asset): link to assets on notification cards.

* Update packages/webui/components/notification-card.tsx

Co-authored-by: Yiling-J <njjyl723@gmail.com>

---------

Co-authored-by: Yiling-J <njjyl723@gmail.com>
2026-10-06 22:14:11 +08:00
Yiling-J 2e5ff281a8 feat(transcode): add hardware decoding support for nvenc, qsv, and rkmpp (#452)
* feat(transcode): add hardware decoding support for nvenc, qsv, and rkmpp

* refactor(transcode): eliminate redundant hardware decode gating and dead condition
2026-10-06 17:35:14 +08:00
yiling de8decf113 fix(ci): prevent tagging main on PR workflow_dispatch docker builds 2026-10-06 11:49:49 +08:00
Cameron HarrisandClaude Opus 5.5 dd57fb9ed2 feat(transcode): decode and scale on the GPU for hardware transcodes (VA-API) (#449)
* feat(transcode): decode and scale on the GPU for VA-API transcodes

When the selected encoder is h264_vaapi, decode with -hwaccel vaapi and
scale with scale_vaapi so frames stay in GPU memory, instead of decoding
and scaling on the CPU and hwupload-ing before the encoder. On a Haswell
iGPU this makes 4K proxy/HLS renditions 3-5x faster.

Fallback order: GPU decode + VA-API encode -> software decode + VA-API
encode (previous behavior) -> libx264. Watermark overlays, HDR sources
and rotated sources skip GPU decode: ffmpeg cannot auto-insert its
rotation filter on hardware frames, so rotated input would otherwise come
out sideways instead of failing. SHUMAI_VAAPI_HW_DECODE=false disables it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(transcode): document VA-API GPU decoding and SHUMAI_VAAPI_HW_DECODE

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor(transcode): generic hardware decode config, stall watchdog, reuse probed rotation

Follow-ups from comparing with Immich and Jellyfin:

- Replace the VA-API-specific helpers with a per-encoder HW_DECODE_CONFIGS
  table (input args, output args, GPU scale filter) and build the MP4 and
  HLS input/filter graph in one shared method so the paths cannot drift.
  Only h264_vaapi has an entry; other backends can be added once tested on
  real hardware. The opt-out is now SHUMAI_HW_DECODE=false.
- Kill a GPU-decode attempt with SIGKILL when its output stops growing for
  SHUMAI_HW_DECODE_STALL_TIMEOUT (default 120s) and fall back, since some
  VA-API driver failures hang ffmpeg instead of exiting (immich#31933).
- Add -noautoscale on the GPU-decode path so a mid-stream decoder reinit
  (e.g. 1080 -> 1088) cannot auto-insert a software scaler into the GPU
  graph (jellyfin#17133).
- Pass the rotation already probed into MediaMetadata through the workflow
  and activities as sourceRotation; ffprobe only runs when it is missing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-05 12:00:01 +08:00
Yiling-J 9a640632aa ci(release): allow manual Docker image build from external PR (#450) 2026-10-05 09:48:48 +08:00
yiling e61641d7ec fix(workflow): increase activity startToCloseTimeout to 120 minutes 2026-10-04 10:22:31 +08:00
Yiling-J 7ca8ba8b2a fix(transcode): resolve RAW transcoding hang in Docker deployments (#447) 2026-10-03 12:45:12 +08:00
Yiling-J 8805d5799a feat(transcode): add dcraw_emu fallback for RAW image preview generation (#446) 2026-10-03 11:03:31 +08:00
yiling 013c4a8156 Release v0.5.0 2026-10-02 20:28:37 +08:00
Yiling-J 20b5ebeefd fix(asset): mark asset as failed and display failure state in webui when transcoding fails (#445)
* fix(asset): mark asset as failed and display failure state in webui when transcoding fails

* fix(transcode): do not mark asset as failed if media processing already succeeded

* test(workflow): add e2e test for video transcode failure status transition

* fix(webui): update failed file card badge to top-right Transcoding Failed label with error tooltip
2026-10-02 20:09:32 +08:00
Yiling-J daa20aed20 fix(webui): add video loading state and poster placeholder (#444)
* fix(webui): add video loading state and poster placeholder

* fix(webui): prevent buffer progress events from canceling stall indicator
2026-10-02 16:19:49 +08:00
Yiling-J 3564d4d164 fix(transcode): avoid selecting attached picture streams for video transcoding (#443)
* fix(transcode): avoid selecting attached picture streams for video transcoding

Filter out attached picture streams (disposition.attached_pic) during video probing and stream selection, matching Immich's default and bitrate selection strategy. Forward explicit primary video and audio stream indices to FFmpeg pipelines to prevent picking embedded cover art or thumbnail streams.

* fix(transcode): skip poster and sprite generation for audio-only assets and add multi-stream e2e tests

* test(workflow): scope pixel format to h264 stream and use yuvj420p for mjpeg cover art
2026-10-02 13:51:17 +08:00
Yiling-J 206763e966 feat(auth): add demo user login button and update demo description (#442)
* feat(auth): add demo user login button and update description

* feat(auth): move demo hint below button and add discord link
2026-10-01 22:04:15 +08:00
Yiling-J 4e4da595a6 feat(settings): redesign video transcoding settings into dedicated cards and rename team AI settings (#441)
* feat(settings): redesign video transcoding settings into dedicated cards and rename team AI settings

* feat(settings): rename Video Strategy to MP4 Transcoding with sub-description
2026-10-01 21:19:25 +08:00
Yiling-J a21a0c9655 fix(settings): prevent deselecting last ladder and coalesce rapid toggles (#440) 2026-10-01 16:35:47 +08:00
Yiling-J fc7282581f fix(share): prevent unwatermarked HLS playback on public shares before transcode completion (#439) 2026-10-01 15:41:45 +08:00
Yiling-J e007054f47 feat(transcode): add multi-resolution strategy with configurable ladders and fallback (#438)
* feat(transcode): add multi-resolution strategy with configurable ladders and fallback

* feat(settings): show toast on settings update and add manual verification plan to PR template

* fix(webui): preserve video resolution and fix 480p label in download dropdowns

* fix(webui): display standard short-side resolution for vertical videos in seekbar

* fix(webui): fix portrait transcode resolution labeling and serialize settings toggles
2026-10-01 13:27:50 +08:00
Yiling-J a84da8678e feat(webui): switch from video.js to hls.js and native video player (#437)
* feat(webui): switch from video.js to hls.js and native video player

* fix(webui): prevent stale seek hijacking and guard native HLS compare mode
2026-09-30 20:23:44 +08:00
Yiling-J 123a8cb5f4 feat(transcode): add HLS live streaming support (#436)
* feat(transcode): add HLS live streaming support

* fix(hls): resolve version stacks for public HLS and add workflow E2E test
2026-09-30 16:31:40 +08:00
Yiling-J 5fe22ac52c feat(transcode): add initial camera RAW image support (#435)
- Add centralized RAW file extension set and detection helper for 23 common camera RAW formats
- Update getProxyType and EXTENSION_MIME_TYPES to route RAW formats into the image pipeline
- Add exiftool-vendored runtime dependency and mark as external in build-npm script
- Implement embedded JPEG extraction to temporary file with priority JpgFromRaw2 -> JpgFromRaw -> PreviewImage
- Read and apply EXIF orientation from RAW container to prevent rotation/mirroring issues
- Integrate into TranscodeService.getImageInfo and transcodeImage with proper temporary file cleanup
- Add hasUsablePreview guard in transcodeImageWorkflow to gracefully handle RAW files without embedded previews
- Add unit, service, workflow, and E2E tests for RAW processing
2026-09-29 21:09:27 +08:00
Yiling-J 11d21444cf fix(trash): prevent empty trash dialog from closing before API call completes (#434)
AlertDialogAction from Radix UI auto-closes the dialog on click.
Added e.preventDefault() so the dialog stays open and shows the
'Deleting...' loading state until the operation finishes.

Fixes both desktop and mobile file browsers.
2026-09-29 10:40:13 +08:00
yiling f2b0415580 Release v0.4.9 2026-09-28 20:17:50 +08:00
Yiling-J c9d0b476cd feat(transcode): fallback to software encoding when hardware transcode fails (#433) 2026-09-28 16:45:28 +08:00
yiling bf5ac566b6 refactor(notification): simplify email wording and remove redundant team references 2026-09-28 13:37:16 +08:00
Yiling-J af8f24aa95 docs(settings): add email notifications documentation to team settings (#432)
* docs(settings): add email notification documentation to team settings

* fix(notification): use correct webui route URLs for project and asset links in emails
2026-09-28 11:27:59 +08:00
Yiling-J d98f486c9d feat(notification): add email notification infrastructure, smtp configuration, and periodic background delivery job (#431)
* feat(notification): add email notification support and dedicated workflow

* feat(webui): add team email notification settings and test email dialog

* refactor(webui): remove redundant card header from email notification settings

* fix(notification): prevent sending notification emails to AI agents

* feat(notification): display project, avatar, upload time and resolve mention names in notification emails

* refactor(notification): remove uploadDebounceSeconds and naive workflow sleep

* refactor(notification): remove temporal notification workflow and keep email infrastructure

* fix(team): prevent leaking email notification settings and credentials in team settings

* feat(notification): add periodic background job for batched email notification delivery

* fix(notification): embed avatars and thumbnails as inline cid attachments
2026-09-28 09:58:59 +08:00
Yiling-J 94ea4c917a feat(transcode): add VA-API hardware acceleration support (#430)
* feat(transcode): add VA-API hardware acceleration support

* fix(docker): switch to jellyfin-ffmpeg 8.1.2-5 for VA-API support

* fix(transcode): probe hardware encoder usability to skip uninitialized drivers

* ci(release): add workflow_dispatch trigger with custom tag input

* fix(transcode): use 256x256 frame dimension for encoder usability probe

* feat(docker): add hwaccel transcoding compose presets matching immich

* docs: add hardware transcoding documentation and quickstart references

* feat(transcode): prioritize h264_vaapi before h264_qsv on Linux

* fix(docker): extend device permission loop to rkmpp and wsl accelerator nodes
2026-09-26 20:55:57 +08:00
Yiling-J 941bf0fd1b feat(transcode): smart poster frame selection and decoupled generation (#428)
* feat(transcode): smart poster frame selection and decoupled generation

* fix(transcode): detect MPEG-TS extension from URL pathname for signed remote sources
2026-09-25 16:37:16 +08:00
Yiling-J 59742dde78 feat(transcode): optimize video sprite generation with seek pool and compositing (#427)
* feat(transcode): optimize video sprite generation with seek pool and compositing

* fix(transcode): handle abort signal during and after sharp compositing
2026-09-25 15:06:15 +08:00
yiling 29cd5d807c test(scripts): find release by version in changelog integration test 2026-09-24 20:34:53 +08:00
yiling f6e27095a5 Release v0.4.8 2026-09-24 20:26:23 +08:00
Yiling-J 55637bc9a8 feat(transcode): optimize video proxy quality and fix videotoolbox first-frame blocking (#426)
- Fix first-frame macroblocking on VideoToolbox hardware acceleration by avoiding -maxrate/-bufsize which triggers Apple's DataRateLimits initial rate controller starvation, applying target -b:v instead.
- Optimize software encoding (libx264) quality by adjusting CRF from 26 to 23.
- Disable B-frames (-bf 0) for libx264 proxies to ensure zero-latency frame stepping (JKL) and scrubbing, matching Frame.io review proxy standards.
- Update unit tests to verify the new encoder configurations and bitrate calculation logic.
2026-09-24 17:16:02 +08:00
Yiling-J 0d6671c3e1 fix(webui): show play button and darken tint only before initial playback (#425)
* fix(webui): remove paused play button overlay and darken cover from video players

* fix(webui): show play button and darken tint only before initial playback
2026-09-24 15:19:46 +08:00
Yiling-J c3375ee935 feat(transcode): add HDR video proxy support and playback (#424)
* feat(transcode): add HDR output proxy support

* fix(transcode): auto-detect MoltenVK Vulkan ICD on macOS for libplacebo filters

* fix(transcode): split filter in generateSprite to ensure poster uses tone-mapped stream

* docs(changelog): update docs/changelog.mdx and ignore in prettier

* fix(transcode): respect video rotation metadata to preserve display aspect ratio

* fix(webui): render native video with hardware EDR acceleration instead of 2D canvas

* fix(webui): show HDR label on mobile video control bar

* fix(share): preserve hdr flag on watermarked video transcodes

* fix(webui): differentiate HDR download options in video player

* fix(transcode): handle Dolby Vision Profile 5 via standard HDR pipeline without libplacebo

* fix(transcode): prepend setparams filter to prevent zscale colorspace path error for DV P5

* refactor(transcode): simplify HDR proxies to always produce HDR without SDR setting
2026-09-24 14:32:47 +08:00
Yiling-J f579947770 feat(docs): add changelog section to mintlify documentation (#422) 2026-09-22 21:02:27 +08:00
Yiling-J 53c9485f10 fix(core): only manage PID files in daemon mode (#421) 2026-09-22 20:31:38 +08:00
Yiling-J 75bf9b3b88 fix(docker): stop publishing postgres port in compose files (#420)
The bundled PostgreSQL service published port 5432 on the host, which caused
docker compose up to fail when that port was already in use. A failed start
leaves the container without a network endpoint, so subsequent runs reuse the
broken container and the app cannot reach the database (Prisma P1001).

The app only needs the database inside the compose network, so the host port
mapping is unnecessary. Remove it from all local and temporal compose files.
2026-09-20 11:46:13 +08:00
yiling 657cd761bc Release v0.4.7 2026-09-19 16:01:20 +08:00
Yiling-J de634a5dc5 feat(asset): show poster and hover preview while video is transcoding (#419)
* feat(asset): show poster and hover preview while video is transcoding

Generate and persist the sprite (and its poster) before the proxy
transcodes run, so the poster/sprite are available in the file list
while the asset is still processing.

Render the preview in the file card behind a translucent processing
overlay instead of a blank skeleton, and replace hardcoded status text
with existing i18n keys.

* feat(asset): pulse the cover and show Preparing/Uploading labels while processing

Drop the processing text overlay on the file card preview in favour of a
subtle pulsing opacity on the cover, and show "Uploading..."/"Preparing..."
in the creator row so the real author and date only appear once the asset
is ready.

* feat(asset): use a hollow ring for the preparing placeholder

Match the geometry of the upload progress ring (empty inside, no
percentage) and hide the duration badge while processing, so the
upload-to-processing transition reads as one continuous animation.

* style(asset): shrink-only preparing ring in muted grey at fixed opacity

Animate only the ring size (1 -> 0.8 -> 1) and hold a constant 0.6
opacity, using a muted grey stroke instead of primary.
2026-09-19 15:25:41 +08:00
Yiling-J 09b65a1eb6 feat(asset): Recently Deleted previews, retention countdown, and version stack delete/restore (#418)
* feat(asset): improve Recently Deleted previews and retention indicators

- Include soft-deleted children when building folder previews for the
  Recently Deleted view, and resolve deleted version stacks to their
  latest version so a trashed folder shows what was inside it.
- Add a "days left" badge (clock + Nd) to file and folder cards in the
  Recently Deleted view, placed to the left of the comments badge.
- Fix an issue where deleting or restoring a version stack from the file
  list did nothing because the WebUI dropped version_stack items before
  calling the API.
- Share the 30-day trash retention window through TRASH_RETENTION_DAYS.

* test(asset): use typed MediaInfo in recently-deleted preview tests

Replace the explicit any cast with a fully typed MediaInfo object so the new tests comply with the no-explicit-any policy.
2026-09-19 11:36:14 +08:00
Yiling-J b52b2ce7d8 fix(transcode): preserve trashed status during background jobs and handle permanent purge (#416)
* fix(transcode): preserve trashed status during background jobs and handle permanent purge

* fix(workflow): clear heartbeat and add info logs on task cancellation

* fix(transcode): terminate media processes and guard task activities on cancellation

- Pass AbortSignal to ffmpeg and pdftoppm child processes in transcodeService to terminate processes on task cancellation
- Add local task AbortController context and cancellation guards in executeActivity to prevent subsequent workflow activities
- Forward taskId and cancellation signals in transcode, screenshot, and PDF activities
- Use updateMany instead of update in task activities to eliminate Prisma P2025 errors on purged task records

* fix(workflow): allow cleanup activities in finally blocks during task cancellation

Remove blanket cancellation check in executeActivity so that workflows can execute cleanup and failure handling activities in catch and finally blocks upon cancellation, while relying on AbortSignal in active activities to abort execution.

* docs(changelog): improve user friendliness of changelog entries and formatting example

* docs(agents): update changelog guidelines to emphasize end-user friendly descriptions

* fix(transcode): handle queued cancellation and delete races in media workflow
2026-09-19 10:40:49 +08:00
Yiling-J 145aa6bfb4 fix(webui,core): center breadcrumb menu on chevron and fix proxy download filename (#417) 2026-09-18 23:14:54 +08:00
Yiling-J a91d8c4521 feat(settings): add FFmpeg threads setting for media processing (#415)
* feat(settings): add FFmpeg threads setting for media processing

* style(settings): add bottom padding to media processing page
2026-09-18 13:30:33 +08:00
Yiling-J 3a509537fd feat(changelog): add CHANGELOG.md, release extraction script, and developer guidelines (#414)
* feat(changelog): add CHANGELOG.md, release extraction script, and developer guidelines

* docs(agents): simplify changelog guidelines for brevity
2026-09-18 11:57:25 +08:00
yiling 76ffb51bb2 Release v0.4.6 2026-09-17 21:58:10 +08:00
Yiling-J ca94e51424 fix(api): enforce SHUMAI_DEMO_MODE for API token and CLI requests (#413) 2026-09-17 21:47:07 +08:00
Yiling-J d8621a53b6 docs: add NLE export and Premiere Pro UXP plugin documentation (#412)
* docs: add NLE export and Premiere Pro UXP plugin documentation

* docs: mark Premiere Pro UXP plugin as experimental
2026-09-17 21:32:41 +08:00
Yiling-J e2f741eda6 feat(settings): add team appearance setting to hide agent features (#411)
* feat(settings): add team appearance setting to hide agent features

Add an Appearance subpage under Team Settings allowing team owners to toggle appearance.hideAgent for the team. Return appearance.hideAgent in the user-metadata API, and conditionally hide the AGENTS.md button, agent chatbot sidebar, and chatbot trigger button in the WebUI.

* refactor(settings): add strongly typed TeamSettingsResponse to remove explicit any

Introduce TeamSettingsResponse and TeamAppearanceSettings in @shumai/dtos, type TeamService.getSettings and updateSettings, and eliminate the explicit any cast in AppearanceSettings.tsx.
2026-09-17 18:31:43 +08:00
Yiling-J 7af3647913 fix(premiere-uxp): scope sequence links by server endpoint and surface sync errors (#409)
* fix(premiere-uxp): scope sequence links by server endpoint and surface sync errors

- Add optional endpoint property to LinkedSequenceAsset to record originating server
- Implement normalizeEndpoint and isSameEndpoint helpers in utils/url
- Skip polling foreign sequence links in autoSyncService when connected to a different server
- Display informative Server: <host> badge and disable manual sync with tooltip for foreign links in SequencesView
- Guard comment fallback in removeSequenceLink and link matching in FileListView by endpoint
- Throw on non-200 responses in fetchAssetComments and display error toast on failed manual sync
- Add comprehensive unit tests covering endpoint normalization, foreign link skipping, and error toast handling
- Rebuild and package shumai-premiere.ccx

* fix(premiere-uxp): filter out foreign endpoint sequence links from sequences tab

- Filter all sequence links in SequencesView to only display links matching the current server endpoint
- Filter existing sequence links in LinkSequenceDialog by endpoint so foreign sequences appear as ready to link on the current server
- Ensure onLinkCountChange in FileListView and SequencesView only counts sequences linked to the active server
- Add 'Browse Assets to Link' action button to the SequencesView unified empty state
- Update SequencesView tests to verify foreign links are completely hidden and link counts are scoped
- Rebuild and package shumai-premiere.ccx

* fix(premiere-uxp): show file creation time on cards and remove sequence icon in link dialog

* fix(premiere-uxp): remove browse button in sequences empty state
2026-09-17 16:37:11 +08:00
Yiling-J 12f99797d2 fix(premiere-uxp): preserve remote cloud storage presigned URLs in asset resolution (#408)
- Stop rewriting absolute URLs in resolveAssetUrl to prevent overwriting cloud storage hosts (e.g. Cloudflare R2, S3) with the plugin endpoint
- Prepend endpoint to relative paths only (e.g. /files/..., /api/...)
- Resolve download URLs through resolveAssetUrl before fetch in importAssetIntoPremiere
- Update unit tests to ensure absolute URLs remain intact and relative download paths resolve correctly
- Rebuild and package shumai-premiere.ccx
2026-09-17 16:37:11 +08:00
Yiling-J 1796de8eda feat(premiere-uxp): introduce Adobe Premiere Pro UXP plugin for Shumai (#407)
* feat(premiere-uxp): use native Bun bundler and build script instead of Vite

* feat(premiere-uxp): switch FileListView to use Search API consistent with WebUI

* feat(premiere-uxp): add on-demand jpeg preview conversion for uxp compatibility

* feat(premiere-uxp): integrate spectrum web components (swc)

* fix(premiere-uxp): align swc packages with 0.37.0 and fix auth layout

* feat(premiere-uxp): use horizontal 2-column card view for projects and files

* style(premiere-uxp): enlarge file preview by 20% and add row padding

* fix(premiere-uxp): prevent card squishing and overflow with large item counts

* fix(premiere-uxp): change host in manifest to single object

* docs(premiere-uxp): add AGENTS.md with SWC preferences and UXP layout rules

* feat(premiere-uxp): integrate spectrum web components across plugin views

* fix(premiere-uxp): remove breadcrumb icons and use slash separator

* feat(premiere-uxp): add collapsible folder and file sections with infinite scroll

* feat(premiere-uxp): update file card layout with right column info and clean preview

* fix(premiere-uxp): use raw text for file card details and fix black icons

* style(premiere-uxp): use contain object-fit and black background for file card preview

* fix(premiere-uxp): refine header logo, sticky title bars, circular badges, and controls

* fix(premiere-uxp): replace stroke icons with spectrum workflow icons

* fix(premiere-uxp): switch icon buttons to swc sp-button with icon-only and slot=icon

* fix(premiere-uxp): vertically center endpoint text in header

* feat(premiere-uxp): add asset and proxy import support into Premiere Pro

- Implement context menu on file cards with left-click, right-click, and more action button triggers
- Support raw file import for non-video assets and video assets
- Support video proxy submenu listing ready transcode resolutions
- Add UXP native file picker save dialog and binary download orchestration
- Call Premiere Pro project.importFiles API to import downloaded assets into active project
- Add non-blocking toast notification banner for progress and status reporting
- Add unit tests for premiere host service and import orchestration

* fix(premiere-uxp): anchor import menu directly to file card using sp-action-menu

- Replace custom fixed-position ContextMenu with native SWC sp-action-menu
- Anchor menu directly to the triggered file card rather than the top-left window corner
- Support programmatic opening on file card click/contextmenu via imperative handle
- Support video submenu with Original and ready proxy options inside sp-action-menu
- Lazy load video proxies on menu open or hover
- Clean up obsolete fixed-position styles and unused backdrop overlays

* fix(premiere-uxp): align SWC packages to 0.37.0 and guard custom element registry

- Downgrade action-menu and menu SWC packages to 0.37.0 to match the rest of the workspace
- Eliminate duplicate icons-ui and sp-icon-chevron100 customElements.define calls
- Add polyfill guard to customElements.define to prevent duplicate registration errors during UXP reload

* fix(premiere-uxp): polyfill window.matchMedia for Adobe UXP

- Add window.matchMedia polyfill in polyfills.ts
- Satisfies SWC MatchMediaController used by ActionMenu and PickerBase in UXP
- Prevents TypeError when opening files page

* feat(premiere-uxp): replace context menu with card download action and video import dialog

* fix(premiere-uxp): resolve download url before save, pass null targetBin, and center download icon

* fix(premiere-uxp): resolve raw download url via download-url endpoint with fallback

* feat(premiere-uxp): use native folder picker and auto-increment conflict suffixes

* feat(premiere-uxp): add sequence linking, comment-marker sync, and navigation tabs

- Add sequence-to-asset linking with persistent project metadata storage

- Support one-way comment-to-marker timeline synchronization

- Add two-tab navigation (Sequences and Browse) using Spectrum buttons

- Add LinkSequenceDialog, SequencesView, and autoSyncService background engine

- Enforce Spectrum Workflow Icons and UXP layout rules

* feat(premiere-uxp): refine UI layouts, card interactions, and search box activation

* fix(premiere-uxp): set compact fixed width for file list search box

* fix(premiere-uxp): ensure search box click activation across full width in UXP

* fix(premiere-uxp): revert search box hacks and restore simple default sp-search layout

* feat(premiere-uxp): sync non-timestamped comments as markers at time 0

* feat(premiere-uxp): change link icon to unlink when asset is linked in file card

* fix(premiere-uxp): sync linked sequences between host project and browse view

* feat(premiere-uxp): remove synced markers on sequence unlink matching Frame.io

* fix(premiere-uxp): ensure reliable marker GUID capture, normalization, and fallback on unlink

* fix(premiere-uxp): use official Shumai logo for plugin manifest icons

* fix(premiere-uxp): use official PNG icons for manifest and plugin entrypoints

* refactor(premiere-uxp): use single 114x114 icon for plugin and panel

* feat(premiere-uxp): show file version in file list page file card

* build(premiere-uxp): check in built ccx package and update packaging configuration

* fix(premiere-uxp): address code review findings for media conversion, marker sync, and link scoping

- Reset hasJpegCover on project cover update and hasJpegPreview on asset media transcode
- Only advance synced comment metadata after confirmed marker transaction
- Normalize GUID keys and lookups in AutoSyncService map
- Restrict cached sequence link lookups to project-specific keys and prevent cross-project leakage on empty sequences
- Update built CCX distribution package
2026-09-17 11:51:03 +08:00
Yiling-J a6b7ac4383 Update project description in README.md 2026-09-16 10:22:13 +08:00
Yiling-J ca575803cb Update README with AI features and agent system details 2026-09-15 12:01:43 +08:00
Yiling-J def42cd000 feat(comment): add emoji reaction support for comments (#405)
* feat(comment): add emoji reaction support for comments

* fix(webui): adjust emoji picker trigger icon size to match mark-done icon

* fix(webui): prevent search icon and placeholder overlap in emoji picker

* fix(webui): use normal text color for reaction count

* feat(db): limit comment reaction code column to VarChar(32)
2026-09-14 15:01:36 +08:00
yiling ede52e5009 Release v0.4.5 2026-09-13 21:50:44 +08:00
Yiling-J ddbf897b27 feat(agent): use deterministic storage keys for preset avatars (#404) 2026-09-13 21:40:34 +08:00
Yiling-J 7d56b5bf90 feat(webui): show comments count badge in file card preview area (#403)
* feat(webui): show comments count badge in file card preview area

* perf(db): add index on asset_comments asset_id
2026-09-13 21:12:21 +08:00
Yiling-J 87e88396d1 feat(webui): add space key quick preview for files and folders (#402)
* feat(webui): add space key quick preview for files and folders

Allow users in file list views to press the Space key to quick preview the most recently selected item.

- Add FilePreviewDialog supporting both folder previews (icon, name, count) and real file previews (reusing FileViewer with viewer area and control bar).
- Constrain dialog to max 1920x1080 or 70vw/70vh.
- Support dismissing via close button, clicking outside, or pressing Space again (intercepted in capture phase).
- Enable across project file lists, share links, and public share views.

* feat(webui): auto play video in quick preview dialog

- Pass autoPlay prop from FilePreviewDialog through FileViewer to VideoViewer
- Configure videojs with autoplay: 'any' and handle policy rejection with muted autoplay fallback
- Add test coverage for autoPlay prop forwarding in FilePreviewDialog

* fix(webui): resolve video quick preview initialization and autoplay pause bugs

* fix(webui): support folder symlinks and password-protected shares in quick preview
2026-09-13 18:51:06 +08:00
Yiling-J c5b57ca862 feat(webui): add NLE comments export and migrate export API to POST (#401) 2026-09-13 16:29:58 +08:00
Yiling-J 3420d848cb feat(core): export comments to FCP, Premiere, Media Composer, and Resolve (#400)
* feat(core): export comments to FCP, Premiere, Media Composer, and Resolve

Add backend support to export video comments matching Frame.io export capabilities:
- DaVinci Resolve (.edl): CMX 3600 EDL with ResolveColorPurple markers and reply threading
- Avid Media Composer (.xml): OMFI StreamItems XML with TC1 / V1 track allocation and sequential frame positioning
- Adobe Premiere Pro (.xml): FCP7 XML sequence with dual marker placement on sequence and generatoritem
- Final Cut Pro 10.4.0+ (.fiojson): Flattened JSON schema with frame, timestamp, and annotation serialization

Includes DTO schema validation, AssetService export method, API route (GET /files/:fileId/comments/export), SMPTE drop-frame timecode calculations, unit tests, golden master tests, service integration tests, and API endpoint tests.

* test(core): move comments export test fixtures to test directory

* fix(core): escape asset name in Premiere XML, align Resolve FCM, and support CJK

- Escape XML special characters in <name> tag for Premiere Pro XML sequence
- Harmonize Resolve EDL FCM header and emitted timecodes using getEffectiveDropFrame
- Use RFC 5987 / RFC 6266 buildContentDisposition for CJK filenames in download headers
- Add test coverage for CJK filenames, comments, and author names across all 4 NLE formats

* fix(core): implement timezone-aware comment exports and sanitize resolve edl
2026-09-13 14:48:41 +08:00
yiling 70b81355c2 Release v0.4.4 2026-09-09 22:07:40 +08:00
yiling 1d552e4ae4 fix(sandbox): change initialization and hotreload log level to debug 2026-09-09 11:17:20 +08:00
Yiling-J b37b2172e7 fix(transcode): co-locate screenshots and derived artifacts in asset storage directory (#399)
* fix(transcode): co-locate screenshots and derived artifacts in asset storage directory

* refactor(transcode): centralize derived artifact directory resolution and strengthen upload assertions
2026-09-09 11:03:48 +08:00
Yiling-J 941000d277 feat(sandbox): abstract SandboxService and hot-reload allowed domains (#398)
* feat(sandbox): abstract SandboxService and hot-reload allowed domains

Introduce SandboxService with pluggable SandboxProvider in @shumai/core. Eliminate disruptive per-session sandbox resets by hot-reloading allowed domains via updateConfig, isolate violations per commandId, and eagerly initialize sandbox at worker/server boot.

* fix(sandbox): isolate command violations and serialize concurrent domain sync

Strictly isolate getBlockedHost per commandId to prevent false-positive blocked reporting on concurrent allowed commands. Serialize syncAllowedDomains to ensure concurrent requests during initialization or updates are never silently dropped. Add comprehensive unit tests for LocalSandboxProvider and concurrent bash commands.

* fix(agent): do not synchronize sandbox when allowedDomains is omitted

Make allowedDomains optional in CreateAgentSessionParams and only invoke sandboxService.syncAllowedDomains when allowedDomains is defined. Omit allowedDomains in generateSessionNameActivity so background chat title generation never overwrites the live sandbox allowlist.
2026-09-08 20:21:29 +08:00
Yiling-J 4a61e87a27 fix(agent): restrict pageCount and duration recommendations to matching media types (#397) 2026-09-08 14:52:37 +08:00
Yiling-J 04fd571bd9 feat(agent): enable read_asset tool for autofill agent (#396)
* feat(agent): enable read_asset tool for autofill agent

* fix(transcode): trigger autofill task for pdf assets

* fix(transcode): allow autofill task creation on all file assets

* fix(agent): require targetAssetId and teamId for autofill read_asset authorization

* feat(agent): instruct autofill agent to report failure directly if read_asset fails
2026-09-08 14:19:03 +08:00
Yiling-J 3a05332cd6 fix(agent): pass agent thinkingLevel to session name generation (#395) 2026-09-08 11:15:26 +08:00
yiling 51f63fc9e4 fix(agent): add error logging for failed session name generation 2026-09-08 10:47:36 +08:00
Yiling-J b35c824a27 feat(transcode): optimize video operations using ffmpeg http range requests (#393)
* feat(transcode): optimize video operations using ffmpeg http range requests

* fix(transcode): preserve non-retryable errors and ensure mapConcurrent settles on rejection
2026-09-08 10:17:15 +08:00
Yiling-J f62df9555a fix(s3): stream downloadToFile and putObject to prevent OOM on large files (#392)
* fix(s3): stream downloadToFile and putObject to prevent OOM on large files

* fix(agent): preserve file MIME detection on download_asset and align local download directory creation
2026-09-07 19:33:13 +08:00
Yiling-J 67b767f1e8 feat(upload): S3 multipart upload with offline resume and wake lock (#391)
* feat(upload): implement S3 multipart upload with offline resume and wake lock

* fix(upload): harden S3 sign and abort authorization, await confirmation, and clean up failed multipart uploads

* fix(webui): resume multipart upload on network recovery and log online event

* fix(webui): remove offline and online toast notifications
2026-09-07 16:49:00 +08:00
yiling 62e86b703e Release v0.4.3 2026-09-06 22:22:14 +08:00
Yiling-J 6c87db0581 fix(webui): clamp file card creation info to 2 lines and show tooltip on hover (#390) 2026-09-06 22:06:03 +08:00
Yiling-J bc85dc4541 docs(agents): add image and video generation settings documentation (#389) 2026-09-06 21:21:16 +08:00
Yiling-J 659a0af2c5 feat(cli): control asset deletion via SHUMAI_ALLOW_DELETE env var (#388) 2026-09-06 19:42:10 +08:00
yiling 54d2c407b5 docs(readme): add target blank to DeepWiki badge 2026-09-06 18:28:43 +08:00
yiling 8e31d05f8a docs(readme): add Ask DeepWiki badge 2026-09-06 17:32:57 +08:00
Yiling-J 8c1e59d131 feat(agent): add asset management tools and CLI commands (#387)
* feat(agent): add asset management tools and CLI commands

* fix(core): resolve code review findings for reparenting cycles, agent deniedTools update, and CLI folder delete
2026-09-06 17:15:58 +08:00
Yiling-J b087bf73ae chore(i18n): update paraglide-js to 2.25.0 and stop checking in generated code (#386)
- Upgrade @inlang/paraglide-js to 2.25.0 in root devDependencies
- Untrack 2,700+ generated paraglide files from git index
- Ignore packages/webui/paraglide in .gitignore and .dockerignore
- Remove --no-emit-git-ignore flag from i18n:compile and i18n:watch
- Chain bun run i18n:compile into build and build-npm scripts
- Add i18n compile step in Dockerfile builder stage
- Add i18n compile step in CI workflows (.github/workflows/ci.yaml, release-npm.yaml)
- Update README.md and README_CN.md with local setup instructions for i18n compilation
2026-09-06 15:48:39 +08:00
Yiling-J a49722d5c7 feat(settings): redesign image/video settings to provider dialog with model toggles (#385) 2026-09-06 15:13:01 +08:00
Yiling-J 576d8ebe64 chore(deps): upgrade bun to 1.4.2 and update packages (#384)
* chore(deps): upgrade bun to 1.4.2 and update packages

- Upgrade Bun to 1.4.2 in Dockerfile, CI workflows, and release workflows.
- Update dependencies across workspace with Bun 1.4.2.
- Preserve @earendil-works/pi-agent-core at 0.82.1.
- Retain stable compatible versions for database adapters and pdfjs-dist.
- Add explicit Buffer type annotation in transcode service.

* chore(deps): upgrade prisma to 7.10.0, pg to 8.23.0, and pdfjs-dist to 6.3.289

* chore(deps): revert dotenv-expand to 13.0.0
2026-09-06 11:31:05 +08:00
Yiling-J ffc1889cdc feat(media-generation): add gemini-omni-1.1-flash video model and redesign settings UI (#383)
* feat(settings): redesign image and video generation settings with tabs, card switch, and 2-box model selector

* fix(settings): remove model type checkmark, remove search inputs, and fix select box scrolling in add model dialog

* refactor(settings): remove display name input from add model dialog

* feat(media-generation): add gemini-omni-1.1-flash as default video model via google interactions api

* feat(media-generation): forward video parameters to gemini-omni-1.1-flash via system instructions and prompt
2026-09-06 09:42:21 +08:00
Yiling-J 6285ff8618 feat(agent): add built-in image and video generation tools and settings (#382)
* feat(agent): add built-in image and video generation tools and settings

* fix(settings): refine media generation layout and expose media tools in agent and quota forms

* feat(media-generation): add alibaba, bytedance, minimax, prodia, and azure providers

* feat(agent): support s3 key references for media generation and s3KeyOnly in read_asset
2026-09-06 09:28:53 +08:00
Yiling-J 1e60933cdb feat(agent): store preset avatars as real files in s3 storage (#381)
* feat(agent): store preset avatars as real files in s3 storage

* fix(agent): use inline base64 previews in dialog and remove static avatar files

* feat(agent): add 4 avatar presets and track avatarPreset in agent config

* refactor(agent): consolidate preset avatar base64 data in dtos
2026-09-04 16:39:19 +08:00
Yiling-J dd0ea05a88 feat(asset): record and display agent provenance on assets and audit logs (#380)
* feat(asset): record and display agent provenance on assets and audit logs

* style(webui): apply 30% translucent frosted glass background to bot badges

* style(webui): match bot icon badge style to thumbnail media overlay (bg-black/60 text-white)

* style(webui): use "AI" text badge with pdf overlay style instead of bot icon
2026-09-04 11:27:52 +08:00
yiling 52330869a2 Release v0.4.2 2026-09-03 21:49:37 +08:00
Yiling-J 0c561e9b39 refactor(webui): use semantic system colors in notification settings (#379) 2026-09-03 21:36:28 +08:00
Yiling-J a236cd3a97 feat(provider): add provider and model sync feature with vendored generator (#378)
* feat(provider): vendor and adapt pi model generator

- Vendor generate-models.ts, model-data.ts, and models-dev-reasoning-options.ts from @earendil-works/pi tag v0.82.1
- Adapt imports to use @earendil-works/pi-ai and expose generateModels programmatic function
- Add compare.test.ts to verify vendored generator against original built-in catalog
- Add packages/core/src/provider/generator to eslint ignores

* feat(provider): add provider and model sync api and ui

* feat(webui): add checkbox for existing providers and clean dialog description

* feat(webui): add expand all and collapse all to sync providers dialog

* refactor(provider): remove compare.test.ts and cli overhead from generate-models

* fix(provider): add 30s timeout and strict error handling to sync catalog fetching

* fix(e2e): eliminate drag-and-drop race condition on webkit

Allow requestAnimationFrame collision updates to settle in dragCard helper before releasing pointer, and scope fileCard locator via data-testid to avoid matching sidebar tree items.
2026-09-03 21:01:14 +08:00
Yiling-J c3ef769f51 feat(provider): optimize provider and model configuration management (#377)
* feat(provider): optimize provider and model configuration management

* style(provider): use default tabs variant in provider settings dialog

* style(provider): make tabs list full width

* feat(provider): make model card row clickable and remove pencil edit icon

* feat(settings): persist active settings tab in url hash

* feat(agent): add search box and alphabetical sorting for provider and model selectors

* refactor(providers): remove frontend pagination and display all models in scrollable list

* fix(providers): address code review findings for model editing, i18n, and api protocol propagation
2026-09-03 15:16:16 +08:00
Yiling-J e58dfaa71a feat(agent): consolidate media tools into read_asset and add S3 key support to download_asset (#376)
* feat(agent): consolidate media tools into read_asset and add S3 key support to download_asset

* fix(agent): refine parameter descriptions and remove download URL from read_asset text content

* fix(agent): resolve owning asset and enforce RBAC permissions when downloading by S3 key
2026-09-02 21:51:07 +08:00
Yiling-J 35b57cc0ab feat(agent): support dynamic annotationId resolution across chat and comments (#375)
* feat(agent): improve timestamp precision and proxy selection for video screenshots

* feat(agent): support dynamic annotationId resolution across chat and comments

* fix(agent): scope annotation resolution to asset and format has_markup consistently
2026-09-02 15:17:56 +08:00
Yiling-J 5a754bcb94 feat(agent): improve timestamp precision and proxy selection for video screenshots (#374) 2026-09-01 21:15:28 +08:00
Yiling-J 64b68e7d63 feat(agent): move thread metadata to structured context XML (#373)
* feat(agent): move thread metadata to structured context XML

* feat(core): dynamically inject thread metadata in getSessionEntries
2026-09-01 17:42:56 +08:00
Yiling-J c2f477a391 fix(agent): hide main comment sessions in dashboard sessions list (#372)
* fix(agent): hide main comment sessions in dashboard sessions list

* feat(webui): auto mention comment creator when replying
2026-09-01 16:20:58 +08:00
Yiling-J 9263971653 更新 README_CN.md 以包含 Docker Compose 部署指南
添加了使用 Docker Compose 部署 Shumai 的详细说明和提示词。
2026-09-01 10:25:57 +08:00
Yiling-J 79a479c87c fix(webui): strip styles and preserve multiline text on paste in chat input (#371)
* fix(webui): strip styles and preserve multiline text on paste in chat input

* fix(db): remove custom log wait strategy in test global setup to prevent postgres startup race condition
2026-08-31 21:29:00 +08:00
Yiling-J 134eb8b7fa fix(agent): set empty details in asset tool results to avoid data duplication (#370) 2026-08-31 20:43:05 +08:00
Yiling-J e06478df88 feat(chat): support markups, attachments, and timestamps in agent 1-to-1 chat (#368)
* feat(chat): support markups, attachments, and timestamps in agent 1-to-1 chat

* feat(chat): improve message card layout with inline badges and integrated assets

* fix(chat): enable image attachment thumbnails in 1-to-1 chat cards

* fix(chat): address code review feedback on input state, mentions, i18n, and session deletion

* fix(chat): replace ring with border color on selected message card
2026-08-31 20:11:27 +08:00
yiling 6e9cf8dfb6 Release v0.4.1 2026-08-30 20:26:57 +08:00
Yiling-J d2620f6911 fix(webui): prevent empty folder flash during initial loading (#367) 2026-08-30 18:43:23 +08:00
Yiling-J 4537baa6a2 feat(webui): redesign comment attachment display into compact rows (#366)
* feat(webui): redesign comment attachment display into compact rows

* feat(webui): support pure frontend image extension matching and self-contained preview dialog

* fix(webui): size image preview dialog to min(image size, 80% screen size)

* fix(webui): prevent horizontal overflow of comment attachment rows in scroll areas

* fix(webui): centralize attachment image preview ownership and localize download title
2026-08-30 17:16:20 +08:00
yiling 810e0c4cf5 fix(agent): only include duration_seconds for time-based media (video/audio) 2026-08-30 15:51:23 +08:00
yiling 07cb648183 fix(agent): use total_frames for video and total_pages for pdf in asset context 2026-08-30 15:44:59 +08:00
yiling c6602c9f1c docs(readme): add docker pulls, release, and license badges 2026-08-30 15:32:27 +08:00
Yiling-J 86032539ed feat(agent): refactor message context into unified shumai_message (#365)
* feat(agent): refactor message context into unified shumai_message

* fix(agent): persist custom_message entry type in DatabaseSessionStorage and handle message mapping defensively

* fix(agent): pass clean prompt to harness and replace optimistic messages on shumai_message stream

* fix(agent): align asset context DTO contract, sync comment attachments, and fix session stats
2026-08-30 15:25:13 +08:00
Yiling-J b2ec012e10 feat(webui): add manage versions option to file card context menu (#364) 2026-08-29 19:19:49 +08:00
Yiling-J 7fd8623684 fix(asset,webui): disallow dropping version stacks onto files and version stacks (#363)
* fix(asset,webui): disallow dropping version stacks onto files and version stacks

* fix(webui): derive isSingleFile from total drag selection and remove unused hasVersionStacks
2026-08-29 16:09:36 +08:00
Yiling-J 083753a96d refactor(agent): remove executeAgentToolWorkflow and invoke core services directly (#362)
* refactor(agent): remove executeAgentToolWorkflow and invoke core services directly

* fix(core): ensure creation atomicity, strict assetType filtering, and id-desc listing
2026-08-29 15:19:08 +08:00
3468 changed files with 184681 additions and 103329 deletions
+2 -1
View File
@@ -14,4 +14,5 @@ helm-charts
.env
.editorconfig
.idea
coverage*
coverage*
packages/webui/paraglide
+13 -7
View File
@@ -24,7 +24,7 @@ jobs:
- name: Setup Bun
uses: oven-sh/setup-bun@v2
with:
bun-version: 1.3.14
bun-version: 1.4.4
- name: Install dependencies
run: bun install
@@ -34,6 +34,9 @@ jobs:
sudo apt-get update
sudo apt-get install -y ripgrep bubblewrap socat ffmpeg poppler-utils imagemagick
- name: Compile i18n
run: bun run i18n:compile
- name: Lint
run: bun run lint
@@ -50,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
@@ -78,11 +78,14 @@ jobs:
- name: Setup Bun
uses: oven-sh/setup-bun@v2
with:
bun-version: 1.3.14
bun-version: 1.4.4
- name: Install dependencies
run: bun install
- name: Compile i18n
run: bun run i18n:compile
- name: Install Playwright browser (${{ matrix.project }})
run: bunx playwright install --with-deps ${{ matrix.project }}
@@ -120,7 +123,7 @@ jobs:
- name: Setup Bun
uses: oven-sh/setup-bun@v2
with:
bun-version: 1.3.14
bun-version: 1.4.4
- name: Install dependencies
run: bun install
@@ -130,6 +133,9 @@ jobs:
sudo apt-get update
sudo apt-get install -y ripgrep bubblewrap socat ffmpeg poppler-utils imagemagick
- name: Compile i18n
run: bun run i18n:compile
- name: Install Playwright browser (${{ matrix.project }})
run: bunx playwright install --with-deps ${{ matrix.project }}
@@ -154,7 +160,7 @@ jobs:
- name: Setup Bun
uses: oven-sh/setup-bun@v2
with:
bun-version: 1.3.14
bun-version: 1.4.4
- name: Install dependencies
run: bun install
+49
View File
@@ -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
+68 -11
View File
@@ -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.3.14
bun-version: 1.4.4
- name: Setup Node.js
uses: actions/setup-node@v6
@@ -53,9 +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
@@ -65,24 +92,54 @@ jobs:
- name: Build NPM packages
run: bun run build-npm
- name: Create GitHub Release
- 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: |
if gh release view "${{ env.RELEASE_TAG }}" >/dev/null 2>&1; then
gh release edit "${{ env.RELEASE_TAG }}" \
--title "${{ env.RELEASE_TAG }}" \
--generate-notes
else
gh release create "${{ env.RELEASE_TAG }}" \
--title "${{ env.RELEASE_TAG }}" \
--generate-notes
fi
CHANGELOG_NOTES=$(bun run scripts/extract-changelog.ts "${{ env.RELEASE_TAG }}" 2>/dev/null || true)
PR_NOTES=$(gh api "repos/${{ github.repository }}/releases/generate-notes" -f tag_name="${{ env.RELEASE_TAG }}" --jq .body 2>/dev/null || true)
{
if [ -n "$CHANGELOG_NOTES" ]; then
echo "$CHANGELOG_NOTES"
echo ""
echo "---"
echo ""
fi
if [ -n "$PR_NOTES" ]; then
echo "$PR_NOTES"
fi
} > /tmp/release-notes.md
- name: Stage draft GitHub Release and CLI assets
if: ${{ !inputs.validate_only }}
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
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
+46 -1
View File
@@ -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 }}
+8
View File
@@ -2,6 +2,8 @@ node_modules
.bun
dist
out
*.ccx
!apps/premiere-uxp/shumai-premiere.ccx
.DS_Store
*.log
.env
@@ -19,3 +21,9 @@ code_quality.md
/test-results/
/blob-report/
/playwright/.cache/
# Paraglide JS
packages/webui/paraglide
runner-package.json
+5 -1
View File
@@ -7,4 +7,8 @@ packages/core/src/generated
src/ui/components/ui
packages/webui/paraglide
*.md
**/*.md
**/*.md
docs/changelog.mdx
packages/webui/public
**/*.min.*
+79 -402
View File
@@ -10,13 +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. Stage and commit your changes.
2. Push the branch to `origin`.
3. Open a pull request using the GitHub CLI.
1. Update `CHANGELOG.md` under `## [Unreleased]` for user-facing changes (see [Changelog Guidelines](#changelog-guidelines)).
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 .
@@ -25,41 +23,14 @@ git push origin <branch-name>
gh pr create --title "<pull-request-title>" --body "<pull-request-body>"
```
---
## Changelog Guidelines
## Commit Messages
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:
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
---
- **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 appends them automatically.
- **Internal Changes**: Routine refactors, test additions, or internal chores without external behavior changes may omit changelog updates.
## Pull Request Template
@@ -78,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.
@@ -85,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`
@@ -93,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`.
+932
View File
@@ -0,0 +1,932 @@
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
## [Unreleased]
### Added
### Fixed
### 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
- **transcode**: Add HDR video proxy support: HDR videos automatically generate HDR video proxies and preview videos preserving HDR color characteristics, tone-mapped SDR thumbnails and posters, and automatic HDR player playback on supported displays with hardware EDR acceleration
- **docs**: Add a Changelog section to the documentation site so users can explore release notes and updates directly in Mintlify
### Fixed
- **webui**: Only show the center play button and darkened tint on initial video open before playback starts; once played, pausing or scrubbing back to start keeps the video canvas clean and unobstructed for review
- **transcode**: Fix an issue where videos with orientation or rotation metadata (such as smartphone vertical videos) were incorrectly displayed with stretched aspect ratios in the video player
- **cli**: Only manage and check PID files in daemon mode, preventing stale PID files, crash-loop conflicts, or spurious process checks during normal foreground and Docker execution
### Changed
- **transcode**: Improve video proxy visual quality and disable B-frames for smoother frame-by-frame seeking and scrubbing
## [0.4.7] - 2026-09-19
### Added
- **changelog**: Introduce Keep a Changelog support, historical release summaries, and automated release notes extraction
- **release**: Automatically populate GitHub release bodies from CHANGELOG.md and promote unreleased notes during version bumps
- **settings**: Add FFmpeg threads slider to team media processing settings
- **asset**: Show previews of a folder's contents and a "days left" countdown for each item in Recently Deleted
- **asset**: Show the poster and hover preview for a video in the file list while it is still transcoding, with a gently pulsing cover (or an animated waiting circle before the poster is ready), "Uploading..."/"Preparing..." labels, and the duration hidden until it is ready
### Fixed
- **asset**: Fix an issue where moving a video to trash while it was still transcoding could cause it to lose its trashed status
- **transcode**: Immediately stop background video processing and transcoding when a file is permanently deleted from the trash
- **asset**: Fix proxy download filename using original file extension instead of proxy extension
- **asset**: Fix an issue where deleting or restoring a version stack from the file list did nothing
- **webui**: Center breadcrumb file action popup menu on the chevron icon
## [0.4.6] - 2026-09-17
### Added
- **comment**: Add emoji reaction support for comments ([#405](https://github.com/shumaiOne/shumai/pull/405))
- **premiere-uxp**: Introduce Adobe Premiere Pro UXP plugin for Shumai ([#407](https://github.com/shumaiOne/shumai/pull/407))
- **settings**: Add team appearance setting to hide agent features ([#411](https://github.com/shumaiOne/shumai/pull/411))
### Fixed
- **premiere-uxp**: Preserve remote cloud storage presigned URLs in asset resolution ([#408](https://github.com/shumaiOne/shumai/pull/408))
- **premiere-uxp**: Scope sequence links by server endpoint and surface sync errors ([#409](https://github.com/shumaiOne/shumai/pull/409))
- **api**: Enforce SHUMAI_DEMO_MODE for API token and CLI requests ([#413](https://github.com/shumaiOne/shumai/pull/413))
### Documentation
- Add NLE export and Premiere Pro UXP plugin documentation ([#412](https://github.com/shumaiOne/shumai/pull/412))
## [0.4.5] - 2026-09-13
### Added
- **core**: Export comments to FCP, Premiere, Media Composer, and Resolve ([#400](https://github.com/shumaiOne/shumai/pull/400))
- **webui**: Add NLE comments export and migrate export API to POST ([#401](https://github.com/shumaiOne/shumai/pull/401))
- **webui**: Add space key quick preview for files and folders ([#402](https://github.com/shumaiOne/shumai/pull/402))
- **webui**: Show comments count badge in file card preview area ([#403](https://github.com/shumaiOne/shumai/pull/403))
- **agent**: Use deterministic storage keys for preset avatars ([#404](https://github.com/shumaiOne/shumai/pull/404))
## [0.4.4] - 2026-09-09
### Added
- **upload**: S3 multipart upload with offline resume and wake lock ([#391](https://github.com/shumaiOne/shumai/pull/391))
- **transcode**: Optimize video operations using ffmpeg http range requests ([#393](https://github.com/shumaiOne/shumai/pull/393))
- **agent**: Enable read_asset tool for autofill agent ([#396](https://github.com/shumaiOne/shumai/pull/396))
- **sandbox**: Abstract SandboxService and hot-reload allowed domains ([#398](https://github.com/shumaiOne/shumai/pull/398))
### Fixed
- **s3**: Stream downloadToFile and putObject to prevent OOM on large files ([#392](https://github.com/shumaiOne/shumai/pull/392))
- **agent**: Pass agent thinkingLevel to session name generation ([#395](https://github.com/shumaiOne/shumai/pull/395))
- **agent**: Restrict pageCount and duration recommendations to matching media types ([#397](https://github.com/shumaiOne/shumai/pull/397))
- **transcode**: Co-locate screenshots and derived artifacts in asset storage directory ([#399](https://github.com/shumaiOne/shumai/pull/399))
## [0.4.3] - 2026-09-06
### Added
- **asset**: Record and display agent provenance on assets and audit logs ([#380](https://github.com/shumaiOne/shumai/pull/380))
- **agent**: Store preset avatars as real files in s3 storage ([#381](https://github.com/shumaiOne/shumai/pull/381))
- **agent**: Add built-in image and video generation tools and settings ([#382](https://github.com/shumaiOne/shumai/pull/382))
- **media-generation**: Add gemini-omni-1.1-flash video model and redesign settings UI ([#383](https://github.com/shumaiOne/shumai/pull/383))
- **settings**: Redesign image/video settings to provider dialog with model toggles ([#385](https://github.com/shumaiOne/shumai/pull/385))
- **agent**: Add asset management tools and CLI commands ([#387](https://github.com/shumaiOne/shumai/pull/387))
- **cli**: Control asset deletion via SHUMAI_ALLOW_DELETE env var ([#388](https://github.com/shumaiOne/shumai/pull/388))
### Fixed
- **webui**: Clamp file card creation info to 2 lines and show tooltip on hover ([#390](https://github.com/shumaiOne/shumai/pull/390))
### Documentation
- **agents**: Add documentation for image and video generation settings ([#389](https://github.com/shumaiOne/shumai/pull/389))
### Maintenance
- **deps**: Upgrade bun to 1.4.2 and update packages ([#384](https://github.com/shumaiOne/shumai/pull/384))
- **i18n**: Update paraglide-js to 2.25.0 and stop checking in generated code ([#386](https://github.com/shumaiOne/shumai/pull/386))
## [0.4.2] - 2026-09-03
### Added
- **chat**: Support markups, attachments, and timestamps in agent 1-to-1 chat ([#368](https://github.com/shumaiOne/shumai/pull/368))
- **agent**: Move thread metadata to structured context XML ([#373](https://github.com/shumaiOne/shumai/pull/373))
- **agent**: Improve timestamp precision and proxy selection for video screenshots ([#374](https://github.com/shumaiOne/shumai/pull/374))
- **agent**: Support dynamic annotationId resolution across chat and comments ([#375](https://github.com/shumaiOne/shumai/pull/375))
- **agent**: Consolidate media tools into read_asset and add S3 key support to download_asset ([#376](https://github.com/shumaiOne/shumai/pull/376))
- **provider**: Optimize provider and model configuration management ([#377](https://github.com/shumaiOne/shumai/pull/377))
- **provider**: Add provider and model sync feature with vendored generator ([#378](https://github.com/shumaiOne/shumai/pull/378))
### Fixed
- **agent**: Set empty details in asset tool results to avoid data duplication ([#370](https://github.com/shumaiOne/shumai/pull/370))
- **webui**: Strip styles and preserve multiline text on paste in chat input ([#371](https://github.com/shumaiOne/shumai/pull/371))
- **agent**: Hide main comment sessions in dashboard sessions list ([#372](https://github.com/shumaiOne/shumai/pull/372))
### Changed
- **webui**: Use semantic system colors in notification settings ([#379](https://github.com/shumaiOne/shumai/pull/379))
## [0.4.1] - 2026-08-30
### Added
- **webui**: Add manage versions option to file card context menu ([#364](https://github.com/shumaiOne/shumai/pull/364))
- **agent**: Refactor message context into unified shumai_message ([#365](https://github.com/shumaiOne/shumai/pull/365))
- **webui**: Redesign comment attachment display into compact rows ([#366](https://github.com/shumaiOne/shumai/pull/366))
### Fixed
- **asset,webui**: Disallow dropping version stacks onto files and version stacks ([#363](https://github.com/shumaiOne/shumai/pull/363))
- **webui**: Prevent empty folder flash during initial loading ([#367](https://github.com/shumaiOne/shumai/pull/367))
### Changed
- **agent**: Remove executeAgentToolWorkflow and invoke core services directly ([#362](https://github.com/shumaiOne/shumai/pull/362))
## [0.4.0] - 2026-08-28
### Added
- **transcode**: Add hardware-accelerated video transcoding support ([#352](https://github.com/shumaiOne/shumai/pull/352))
- **webui**: Truncate long file names with 100ms hover tooltip ([#355](https://github.com/shumaiOne/shumai/pull/355))
- **webui**: Add simplified mobile-friendly layout for file and share lists ([#356](https://github.com/shumaiOne/shumai/pull/356))
- **webui**: Add mobile friendly file detail and public share view ([#359](https://github.com/shumaiOne/shumai/pull/359))
### Fixed
- **transcode**: Apply team hardware acceleration and source bitrate capping to watermark transcoding ([#353](https://github.com/shumaiOne/shumai/pull/353))
- **share**: Hide and soft-delete symlinks when target assets are trashed ([#354](https://github.com/shumaiOne/shumai/pull/354))
- **webui**: Fix breadcrumb file dropdown trigger stretching and alignment ([#360](https://github.com/shumaiOne/shumai/pull/360))
- **webui**: Align mobile comment cards and thread vertical indicator ([#361](https://github.com/shumaiOne/shumai/pull/361))
### Documentation
- Add SECURITY.md with a private disclosure path ([#357](https://github.com/shumaiOne/shumai/pull/357))
## [0.3.11] - 2026-08-25
### Added
- **auth**: Add admin password reset CLI command and reset password web UI ([#347](https://github.com/shumaiOne/shumai/pull/347))
- **project**: Add recent viewed files section to project folder tree ([#348](https://github.com/shumaiOne/shumai/pull/348))
### Fixed
- **webui**: Prevent left carousel remounting and scroll jump on file selection ([#351](https://github.com/shumaiOne/shumai/pull/351))
## [0.3.10] - 2026-08-23
### Added
- **agentic kanban**: Phase 1 not-agentic kanban board ([#330](https://github.com/shumaiOne/shumai/pull/330))
- **kanban**: Resolve latest version for linked version stack assets and update demo login text ([#342](https://github.com/shumaiOne/shumai/pull/342))
- **kanban**: Update task status permissions, reporter defaults, and participant access ([#345](https://github.com/shumaiOne/shumai/pull/345))
### Fixed
- **kanban**: Use true thumbnail and poster for task asset previews ([#343](https://github.com/shumaiOne/shumai/pull/343))
- **webui**: Sidebar selection styling, kanban active state, pointer cursors, and owner dashboard ([#344](https://github.com/shumaiOne/shumai/pull/344))
- **kanban**: Improve drag-drop to column bottom, remove empty drop line, and fix timeline alignment ([#346](https://github.com/shumaiOne/shumai/pull/346))
## [0.3.9] - 2026-08-18
### Added
- **agent**: Add permission controls for chat agents ([#313](https://github.com/shumaiOne/shumai/pull/313))
- **authz**: Enforce project-aware roles for agent/skill/mcp permissions ([#314](https://github.com/shumaiOne/shumai/pull/314))
- **webui**: Use project members for asset comment mentions ([#315](https://github.com/shumaiOne/shumai/pull/315))
- **quota**: Add 2-level database-backed resource quota system ([#318](https://github.com/shumaiOne/shumai/pull/318))
- **settings**: Reorganize settings into personal, team, and AI sections ([#324](https://github.com/shumaiOne/shumai/pull/324))
- **quota**: Move usage monitoring to team dashboard ([#327](https://github.com/shumaiOne/shumai/pull/327))
### Fixed
- **webui**: Preserve selected chatbot agent preference on reload ([#323](https://github.com/shumaiOne/shumai/pull/323))
- **quota**: Exclude agents from quota rules and usage records ([#325](https://github.com/shumaiOne/shumai/pull/325))
### Documentation
- **team-settings**: Add resource quotas documentation and update readme features ([#326](https://github.com/shumaiOne/shumai/pull/326))
## [0.3.8] - 2026-08-15
### Added
- **webui**: Replace legacy markdown editor with new lexical wysiwyg editor ([#308](https://github.com/shumaiOne/shumai/pull/308))
- **agent**: Add nested agents.md support across backend and webui ([#309](https://github.com/shumaiOne/shumai/pull/309))
- **webui**: Improve AGENTS.md editor placeholder and read-only notice ([#310](https://github.com/shumaiOne/shumai/pull/310))
- **version-stack**: Add manage versions dialog and version removal ([#311](https://github.com/shumaiOne/shumai/pull/311))
### Fixed
- **core**: Rename latest version child record on version stack rename ([#312](https://github.com/shumaiOne/shumai/pull/312))
## [0.3.7] - 2026-08-14
### Added
- **metadata**: Replace aiAutofill boolean with autofillSource enum ([#302](https://github.com/shumaiOne/shumai/pull/302))
- **agent**: Type-safe CREATION_CONTEXT metadata on create_file/create_version ([#303](https://github.com/shumaiOne/shumai/pull/303))
- **sandbox**: Default Network Sandbox to off and add settings toggle switch ([#304](https://github.com/shumaiOne/shumai/pull/304))
- **webui**: Redesign select metadata fields and improve long text field widget ([#305](https://github.com/shumaiOne/shumai/pull/305))
- **agent**: Support dynamic newOption in select and selectMulti metadata fields ([#306](https://github.com/shumaiOne/shumai/pull/306))
### Fixed
- **webui**: Fix select field height and multi-select overflow/interaction issues ([#307](https://github.com/shumaiOne/shumai/pull/307))
## [0.3.6] - 2026-08-12
### Added
- **mcp**: Add MCP server support with proxy tool and OAuth flow ([#289](https://github.com/shumaiOne/shumai/pull/289))
- **mcp**: Support tool-level directTools array and 3-state UI configuration ([#297](https://github.com/shumaiOne/shumai/pull/297))
- **webui**: Direct canvas PDF rendering with selectable text ([#299](https://github.com/shumaiOne/shumai/pull/299))
### Fixed
- **agent**: Prevent agents from accessing disabled skills ([#292](https://github.com/shumaiOne/shumai/pull/292))
- **agent**: Resolve version stack name and size in list_assets ([#296](https://github.com/shumaiOne/shumai/pull/296))
- **webui**: Content-only pinch-zoom and two-finger pan in media viewers ([#298](https://github.com/shumaiOne/shumai/pull/298))
- **i18n**: Update Chinese translation for dashboard to 仪表板 ([#301](https://github.com/shumaiOne/shumai/pull/301))
### Documentation
- **mcp**: Add MCP support documentation to README and docs ([#300](https://github.com/shumaiOne/shumai/pull/300))
## [0.3.5] - 2026-08-09
### Added
- **transcode**: Add Gotenberg support for Office, HTML, CSV, and Markdown PDF proxies ([#283](https://github.com/shumaiOne/shumai/pull/283))
### Fixed
- **webui**: Resolve upload card freeze for unsupported files ([#284](https://github.com/shumaiOne/shumai/pull/284))
- **webui**: Exclude file extension when selecting file name during inline rename ([#285](https://github.com/shumaiOne/shumai/pull/285))
- Use renamed asset name in download Content-Disposition ([#286](https://github.com/shumaiOne/shumai/pull/286))
- **webui**: Batch download no longer flashes a tab per file ([#287](https://github.com/shumaiOne/shumai/pull/287))
- **webui**: Enable rename and delete actions in file detail top bar breadcrumb ([#288](https://github.com/shumaiOne/shumai/pull/288))
## [0.3.4] - 2026-08-08
### Added
- **sharelink**: Add sharelink watermark support ([#270](https://github.com/shumaiOne/shumai/pull/270))
- **webui**: Remove original-file display fallbacks, use proxies only ([#273](https://github.com/shumaiOne/shumai/pull/273))
- **share**: Add allow download config to share links ([#275](https://github.com/shumaiOne/shumai/pull/275))
- **transcode**: Update preview thumbnail resolution to 300p with max length constraint ([#281](https://github.com/shumaiOne/shumai/pull/281))
### Fixed
- **share**: Resolve symlink asset downloads in public share pages ([#274](https://github.com/shumaiOne/shumai/pull/274))
- **webui**: Persist project sorting and prevent full page flash ([#276](https://github.com/shumaiOne/shumai/pull/276))
### Documentation
- **share-links**: Document allow download and lazy watermark settings ([#278](https://github.com/shumaiOne/shumai/pull/278))
- **agent**: Clarify create_file/create_version context param guidance ([#282](https://github.com/shumaiOne/shumai/pull/282))
### Maintenance
- **e2e**: Watermarked download-disabled share link coverage (image + video) ([#277](https://github.com/shumaiOne/shumai/pull/277))
- **e2e**: Stabilize watermark share spec on Firefox ([#279](https://github.com/shumaiOne/shumai/pull/279))
- Split e2e scripts into app and webui targets ([#280](https://github.com/shumaiOne/shumai/pull/280))
## [0.3.3] - 2026-08-05
### Added
- **agent**: Enable LLM API call retries in AgentHarness ([#250](https://github.com/shumaiOne/shumai/pull/250))
- **audit**: Add audit log support for APIs and WebUI dashboard ([#251](https://github.com/shumaiOne/shumai/pull/251))
- **webui**: Persist agent preference in localStorage ([#254](https://github.com/shumaiOne/shumai/pull/254))
- **e2e**: Add file domain comment and draw tests ([#260](https://github.com/shumaiOne/shumai/pull/260))
- **agent**: Restrict bash access for non-owner users ([#262](https://github.com/shumaiOne/shumai/pull/262))
- **agent**: Allow create_file tool to create files directly from content ([#263](https://github.com/shumaiOne/shumai/pull/263))
- **agent**: Propagate autofill context from chat to autofill workflow ([#264](https://github.com/shumaiOne/shumai/pull/264))
- **webui**: Render select options in field creation mode and pick random option color ([#265](https://github.com/shumaiOne/shumai/pull/265))
- **project**: Include team-scoped members in project member list and add 3-section dialog layout ([#267](https://github.com/shumaiOne/shumai/pull/267))
- **webui**: Disable role dropdown for project-scoped members in team view ([#269](https://github.com/shumaiOne/shumai/pull/269))
### Fixed
- **webui**: Mention popup avatars, keyboard auto-scroll, and non-sticky section headers ([#256](https://github.com/shumaiOne/shumai/pull/256))
- **webui**: Persist field order on drag and drop ([#266](https://github.com/shumaiOne/shumai/pull/266))
### Changed
- **agent**: Load models directly from database without pi fallback ([#253](https://github.com/shumaiOne/shumai/pull/253))
- **core**: Replace generated provider files with pi-ai dynamic methods ([#255](https://github.com/shumaiOne/shumai/pull/255))
### Maintenance
- **core**: Add missing tests for methods introduced in 97069042 ([#252](https://github.com/shumaiOne/shumai/pull/252))
- **e2e**: Add domain-based auth and project web app e2e tests ([#257](https://github.com/shumaiOne/shumai/pull/257))
- **e2e**: Add file, share, and collection web app e2e tests ([#258](https://github.com/shumaiOne/shumai/pull/258))
- **e2e**: Add project-level invite and file-move e2e tests ([#259](https://github.com/shumaiOne/shumai/pull/259))
- **e2e**: Add search in file list and save-search-as-collection cases ([#261](https://github.com/shumaiOne/shumai/pull/261))
- **e2e**: Add member permission change tests ([#268](https://github.com/shumaiOne/shumai/pull/268))
## [0.3.2] - 2026-07-30
### Added
- **agent**: Add output truncation and streaming limits to sandboxed bash tool ([#248](https://github.com/shumaiOne/shumai/pull/248))
### Fixed
- **agent**: Download original document asset instead of pdf proxy ([#247](https://github.com/shumaiOne/shumai/pull/247))
- **webui**: Persist chatbot sidebar input text across route navigation ([#249](https://github.com/shumaiOne/shumai/pull/249))
## [0.3.1] - 2026-07-30
### Added
- **transcode**: Trigger ai metadata autofill post transcode ([#234](https://github.com/shumaiOne/shumai/pull/234))
- **dashboard**: Add agent sessions view for team owners ([#237](https://github.com/shumaiOne/shumai/pull/237))
- **db**: Preserve agent sessions on asset deletion by setting onDelete to SetNull ([#240](https://github.com/shumaiOne/shumai/pull/240))
- **agent**: Add download_asset tool and prompt instructions ([#242](https://github.com/shumaiOne/shumai/pull/242))
- **db**: Update Asset.sizeByte and AiUsage token fields to BigInt ([#244](https://github.com/shumaiOne/shumai/pull/244))
### Fixed
- **agent**: Include select option labels and field name in autofill schema ([#235](https://github.com/shumaiOne/shumai/pull/235))
- **agent**: Scope agent comment sessions to thread sessions anchored at root comments ([#239](https://github.com/shumaiOne/shumai/pull/239))
- **agent**: Disable tools for session naming and make naming non-blocking ([#241](https://github.com/shumaiOne/shumai/pull/241))
- **webui**: Update file size formatting to SI decimal standard ([#245](https://github.com/shumaiOne/shumai/pull/245))
- **s3**: Enforce property syntax in S3Service interface and fix ReadableStream handling in S3StorageService ([#246](https://github.com/shumaiOne/shumai/pull/246))
## [0.3.0] - 2026-07-28
### Added
- **file-browser**: Add copy name and path option to context menu ([#225](https://github.com/shumaiOne/shumai/pull/225))
- **agent**: Inject user name and role into chat context ([#226](https://github.com/shumaiOne/shumai/pull/226))
- **agent**: Refactor database session storage to normalized DAG entries and lazy thread sync ([#229](https://github.com/shumaiOne/shumai/pull/229))
- **agent**: Support ENABLE_WEAKER_NESTED_SANDBOX environment variable ([#233](https://github.com/shumaiOne/shumai/pull/233))
### Fixed
- **agent**: Ensure atomic appendEntry and persist leaf entries in DatabaseSessionStorage ([#224](https://github.com/shumaiOne/shumai/pull/224))
- Sharp version mismatch bug ([#230](https://github.com/shumaiOne/shumai/pull/230))
- **agent**: Resolve S3 MIME type detection and prompt parameter in image analysis ([#232](https://github.com/shumaiOne/shumai/pull/232))
### Changed
- **agent**: Remove implicit agent mention trigger in comment threads ([#227](https://github.com/shumaiOne/shumai/pull/227))
### Maintenance
- **workflow**: Add docker compose deployment verification job ([#231](https://github.com/shumaiOne/shumai/pull/231))
## [0.2.3] - 2026-07-25
### Fixed
- **webui**: Show right sidebar by default on file detail page ([#219](https://github.com/shumaiOne/shumai/pull/219))
- **webui**: Refresh file list and detail when agent executes asset creation tools ([#220](https://github.com/shumaiOne/shumai/pull/220))
- **webui**: Fix space key drag overlay and shift range selection for version stacks ([#221](https://github.com/shumaiOne/shumai/pull/221))
- **transcode**: Handle timestamp rounding tolerance for screenshot annotations ([#223](https://github.com/shumaiOne/shumai/pull/223))
### Changed
- **e2e**: Split transcode workflow E2E tests into per-workflow test files ([#222](https://github.com/shumaiOne/shumai/pull/222))
## [0.2.2] - 2026-07-23
### Added
- **webui**: Integrate AI usage API into dashboard page ([#216](https://github.com/shumaiOne/shumai/pull/216))
- **ai-usage**: Add team and member token usage tracking and APIs ([#215](https://github.com/shumaiOne/shumai/pull/215))
- **transcode**: Add PSD support via ImageMagick and enforce sRGB conversion ([#217](https://github.com/shumaiOne/shumai/pull/217))
### Fixed
- **search**: Fix buildSqlCondition date range, numeric metadata, and string parsing bugs ([#213](https://github.com/shumaiOne/shumai/pull/213))
- **webui**: Prevent horizontal overflow in search dialog result rows ([#214](https://github.com/shumaiOne/shumai/pull/214))
- **webui**: Invalidate upload tasks query when upload task starts and completes ([#218](https://github.com/shumaiOne/shumai/pull/218))
## [0.2.1] - 2026-07-22
### Added
- **skill**: Add team owner skill permission control ([#209](https://github.com/shumaiOne/shumai/pull/209))
### Fixed
- **agent**: Handle non-builtin models in getModelFromDb and upgrade pi-ai ([#211](https://github.com/shumaiOne/shumai/pull/211))
- **provider**: Preserve model ids on provider update ([#212](https://github.com/shumaiOne/shumai/pull/212))
### Changed
- **core**: Split generated providers into per-provider files ([#210](https://github.com/shumaiOne/shumai/pull/210))
## [0.2.0] - 2026-07-21
### Added
- **transcode**: Add PDF preview, sprite generation, and annotation support ([#193](https://github.com/shumaiOne/shumai/pull/193))
- **web**: Register pdf.worker route in production ([#195](https://github.com/shumaiOne/shumai/pull/195))
- **agent**: Add read_pdf_pages tool and PDF page context support ([#196](https://github.com/shumaiOne/shumai/pull/196))
- **transcode**: Split monolithic transcodeMedia into focused workflows ([#197](https://github.com/shumaiOne/shumai/pull/197))
- **transcode**: Add PDF proxy support for TXT and CSV files ([#199](https://github.com/shumaiOne/shumai/pull/199))
- **asset**: Replace mediaType/mimeType logic with proxyType ([#200](https://github.com/shumaiOne/shumai/pull/200))
- **docker**: Install fonts-noto-cjk in runner stage ([#202](https://github.com/shumaiOne/shumai/pull/202))
- **transcode**: Add markdown file to pdf proxy support ([#203](https://github.com/shumaiOne/shumai/pull/203))
- **chat**: Track context asset changes and update agent context ([#204](https://github.com/shumaiOne/shumai/pull/204))
- **agent**: Refactor media tools to static injection with mandatory assetId and authz ([#208](https://github.com/shumaiOne/shumai/pull/208))
### Fixed
- **transcode**: Mark pdfkit as external and extract for docker runtime ([#201](https://github.com/shumaiOne/shumai/pull/201))
- **agent**: Include skill id in formatSkillsForPrompt ([#205](https://github.com/shumaiOne/shumai/pull/205))
- **asset**: Exclude soft-deleted children from latestChildren preview ([#206](https://github.com/shumaiOne/shumai/pull/206))
- **agent**: Pass latest version asset from version stack to prompt builder ([#207](https://github.com/shumaiOne/shumai/pull/207))
## [0.1.10] - 2026-07-16
### Added
- **workflow-e2e**: Add E2E tests for agentAutofillMedia workflow ([#188](https://github.com/shumaiOne/shumai/pull/188))
- **comments**: Support comment deletion and video player shortcuts ([#191](https://github.com/shumaiOne/shumai/pull/191))
- **agent**: Support disabling specific tools for agents ([#192](https://github.com/shumaiOne/shumai/pull/192))
### Maintenance
- **e2e**: Add E2E workflow tests for remaining agent and transcode services ([#189](https://github.com/shumaiOne/shumai/pull/189))
## [0.1.9] - 2026-07-14
### Added
- **e2e**: Set up fullstack app-level e2e test framework and signup test case ([#184](https://github.com/shumaiOne/shumai/pull/184))
- **chat**: Chatbot UI ([#185](https://github.com/shumaiOne/shumai/pull/185))
- **agent**: Support aborting agent execution ([#186](https://github.com/shumaiOne/shumai/pull/186))
### Changed
- **api/chat**: Remove direct Prisma query from API layer ([#187](https://github.com/shumaiOne/shumai/pull/187))
## [0.1.8] - 2026-07-10
### Added
- **chatbot**: Implement type-safe Chat APIs with compaction support ([#180](https://github.com/shumaiOne/shumai/pull/180))
### Fixed
- **webui**: Enable build splitting and code-split all page routes ([#183](https://github.com/shumaiOne/shumai/pull/183))
### Documentation
- **readme**: Clarify displayed file size represents original file size ([#182](https://github.com/shumaiOne/shumai/pull/182))
## [0.1.7] - 2026-07-06
### Added
- **audio**: Support frame-accurate audio playback, comments, and AI safeguards ([#175](https://github.com/shumaiOne/shumai/pull/175))
- **i18n**: Localize members dialog, notifications, uploads, user menus, dates, and players ([#178](https://github.com/shumaiOne/shumai/pull/178))
- **comments**: Allow marking comments as complete or incomplete ([#179](https://github.com/shumaiOne/shumai/pull/179))
### Fixed
- **upload**: Resolve empty and generic MIME types in confirmFileUpload ([#176](https://github.com/shumaiOne/shumai/pull/176))
### Changed
- **webui**: Modularize file viewer components into registry-driven architecture ([#174](https://github.com/shumaiOne/shumai/pull/174))
### Documentation
- Improve documentation and examples for S3 compatible storage ([#177](https://github.com/shumaiOne/shumai/pull/177))
## [0.1.6] - 2026-07-04
### Added
- **file-browser**: Show video duration on file card preview ([#170](https://github.com/shumaiOne/shumai/pull/170))
- **webui**: Compare versions view for version stacks ([#171](https://github.com/shumaiOne/shumai/pull/171))
### Fixed
- **webui**: Resolve conditional hooks and setState-in-render errors ([#167](https://github.com/shumaiOne/shumai/pull/167))
- **webui**: Resolve video player total frames mismatch ([#172](https://github.com/shumaiOne/shumai/pull/172))
- **version-stack**: Resolve correct latest version ID of version stack ([#173](https://github.com/shumaiOne/shumai/pull/173))
### Maintenance
- **webui**: Video player e2e framework + Safari playhead fix ([#166](https://github.com/shumaiOne/shumai/pull/166))
- **webui**: Add frame-accurate comment seek roundtrip e2e ([#168](https://github.com/shumaiOne/shumai/pull/168))
- **webui**: Verify video player restarts playback after end ([#169](https://github.com/shumaiOne/shumai/pull/169))
## [0.1.5] - 2026-07-02
### Changed
- **storage**: Use original filenames for stored files ([#165](https://github.com/shumaiOne/shumai/pull/165))
### Maintenance
- **release**: Add Aliyun ACR push to release workflow ([#164](https://github.com/shumaiOne/shumai/pull/164))
## [0.1.4] - 2026-07-01
### Added
- **transcode**: Change video poster resolution to 480p ([#161](https://github.com/shumaiOne/shumai/pull/161))
- **auth**: Allow setting user locale on signup ([#163](https://github.com/shumaiOne/shumai/pull/163))
### Fixed
- **webui**: Preserve video ended state by skipping playhead snap on ended ([#162](https://github.com/shumaiOne/shumai/pull/162))
## [0.1.3] - 2026-06-30
### Added
- **webui**: Add i18n support using paraglide-js ([#156](https://github.com/shumaiOne/shumai/pull/156))
- **video**: Add frame-accurate video player, SMPTE timecodes, and format switcher ([#157](https://github.com/shumaiOne/shumai/pull/157))
### Fixed
- **webui**: Align video timeline duration and formatting with frameio ([#158](https://github.com/shumaiOne/shumai/pull/158))
- **webui**: Fix missing left sidebar for nested folders ([#159](https://github.com/shumaiOne/shumai/pull/159))
- **api**: Fix update team settings and make request schema type-safe ([#160](https://github.com/shumaiOne/shumai/pull/160))
## [0.1.2] - 2026-06-25
### Changed
- **s3**: Remove automatic port appending to AWS_ENDPOINT_URL_S3 ([#155](https://github.com/shumaiOne/shumai/pull/155))
## [0.1.1] - 2026-06-23
### Added
- **docker**: Add root entrypoint with privilege dropping for data volumes ([#151](https://github.com/shumaiOne/shumai/pull/151))
## [0.1.0] - 2026-06-22
### Added
- **share**: Secure share info API and fix wrong password feedback ([#150](https://github.com/shumaiOne/shumai/pull/150))
### Fixed
- **webui**: Truncate long folder, collection, and share link names in sidebar ([#149](https://github.com/shumaiOne/shumai/pull/149))
## [0.0.11] - 2026-06-22
### Added
- **cli**: Add shumai-cli and token authentication ([#144](https://github.com/shumaiOne/shumai/pull/144))
- **settings**: Use singular headers and remove collapse/counters for single agent types ([#145](https://github.com/shumaiOne/shumai/pull/145))
- **folders**: Auto expand folder tree in left sidebar on navigation ([#146](https://github.com/shumaiOne/shumai/pull/146))
- **metadata**: Add single user and multiple user custom fields ([#147](https://github.com/shumaiOne/shumai/pull/147))
### Maintenance
- **cli**: Rename npm package to @shumai-one/shumai-cli ([#148](https://github.com/shumaiOne/shumai/pull/148))
## [0.0.10] - 2026-06-21
### Changed
- **web**: Dynamically register production HTML bundle routes ([#142](https://github.com/shumaiOne/shumai/pull/142))
### Documentation
- **readme**: Polish structure, correct grammar, and add dependencies table ([#143](https://github.com/shumaiOne/shumai/pull/143))
## [0.0.9] - 2026-06-20
### Added
- **webui**: Show app version in avatar menu ([#139](https://github.com/shumaiOne/shumai/pull/139))
- **cli**: Add background daemonization and subcommands ([#141](https://github.com/shumaiOne/shumai/pull/141))
### Maintenance
- **release**: Add smoke tests to local release stage ([#140](https://github.com/shumaiOne/shumai/pull/140))
## [0.0.8] - 2026-06-19
### Added
- **api**: Implement read-only mode for reviewers ([#122](https://github.com/shumaiOne/shumai/pull/122))
- **server**: Allow customizing server port via SHUMAI_SERVER_PORT ([#124](https://github.com/shumaiOne/shumai/pull/124))
- **embedding**: Defer embedding workflow, use transcoded assets, and execute chunks in separate activities ([#125](https://github.com/shumaiOne/shumai/pull/125))
- **webui**: Add external drag-and-drop file and folder upload support ([#126](https://github.com/shumaiOne/shumai/pull/126))
- **agent**: Implement overlapping video chunks for semantic search ([#127](https://github.com/shumaiOne/shumai/pull/127))
- **webui**: Support jumping to video timestamp from search results ([#128](https://github.com/shumaiOne/shumai/pull/128))
- **auth**: Add demo mode support ([#131](https://github.com/shumaiOne/shumai/pull/131))
- **auth**: Refine demo mode support ([#132](https://github.com/shumaiOne/shumai/pull/132))
- **webui**: Default right sidebar to collapsed for new users ([#133](https://github.com/shumaiOne/shumai/pull/133))
- **webui**: Use Shadcn Switch in toggle field and Rating component in search filter panel ([#137](https://github.com/shumaiOne/shumai/pull/137))
- **upload**: Track byte-level progress with XMLHttpRequest ([#138](https://github.com/shumaiOne/shumai/pull/138))
### Fixed
- **transcode**: Handle high-precision FPS using rational fractions ([#123](https://github.com/shumaiOne/shumai/pull/123))
- **db**: Automatically update project updatedAt on asset modification ([#129](https://github.com/shumaiOne/shumai/pull/129))
- **webui**: Use system colors for fields and improve search filter select options ([#130](https://github.com/shumaiOne/shumai/pull/130))
- **search**: Fix hasAny and hasNone operators on metadata filter ([#134](https://github.com/shumaiOne/shumai/pull/134))
- **webui**: Resolve folder tree sync, search dialog reset, and sidebar actions issues ([#136](https://github.com/shumaiOne/shumai/pull/136))
### Changed
- **webui**: Fix search dialog layout height, scroll areas, and restrict filter toggle click ([#135](https://github.com/shumaiOne/shumai/pull/135))
## [0.0.7] - 2026-06-17
### Added
- **workflow**: Configure transcode and agent concurrency via environment variables ([#116](https://github.com/shumaiOne/shumai/pull/116))
- **webui**: Replace hardcoded colors with system tokens ([#119](https://github.com/shumaiOne/shumai/pull/119))
- **webui**: Replace native overflow with shadcn ScrollArea in settings ([#120](https://github.com/shumaiOne/shumai/pull/120))
- **api**: Use enum for API protocol in provider config ([#121](https://github.com/shumaiOne/shumai/pull/121))
### Fixed
- **webui**: Reload video player and reset state when switching assets ([#114](https://github.com/shumaiOne/shumai/pull/114))
### Changed
- **transcode**: Relocate TranscodeService to core and flatten API package ([#115](https://github.com/shumaiOne/shumai/pull/115))
### Documentation
- Improve and restructure shumai documentation ([#118](https://github.com/shumaiOne/shumai/pull/118))
## [0.0.6] - 2026-06-15
### Added
- **sandbox**: Add pending domains support for network sandbox ([#109](https://github.com/shumaiOne/shumai/pull/109))
- **webui**: Always show right sidebar and implement left vertical carousel ([#111](https://github.com/shumaiOne/shumai/pull/111))
### Fixed
- **build**: Propagate termination signals to active child process in wrappers ([#102](https://github.com/shumaiOne/shumai/pull/102))
- **transcode**: Make deterministic transcode activity failures non-retryable in Temporal ([#104](https://github.com/shumaiOne/shumai/pull/104))
- **player**: Implement seekbar dragging and match hover highlight color ([#108](https://github.com/shumaiOne/shumai/pull/108))
- **webui**: Avoid refetching all pages on file/folder reorder ([#112](https://github.com/shumaiOne/shumai/pull/112))
- **webui**: Force video-player mime type to video/mp4 ([#113](https://github.com/shumaiOne/shumai/pull/113))
### Changed
- **webui**: Use system color design tokens in video player components ([#106](https://github.com/shumaiOne/shumai/pull/106))
- **webui**: Use requestAnimationFrame for smooth video progress bar updates ([#107](https://github.com/shumaiOne/shumai/pull/107))
- **webui**: Fetch agents in mention input list dynamically ([#110](https://github.com/shumaiOne/shumai/pull/110))
### Documentation
- **readme**: Add comprehensive README.md ([#103](https://github.com/shumaiOne/shumai/pull/103))
- **readme**: Improve remote deployment and temporal execution instructions ([#105](https://github.com/shumaiOne/shumai/pull/105))
## [0.0.5] - 2026-06-13
### Added
- **npm**: Auto deploy database migrations on package start ([#101](https://github.com/shumaiOne/shumai/pull/101))
## [0.0.4] - 2026-06-12
### Fixed
- **cli/docker**: Resolve global CLI external dependencies and fix Docker 404 error ([#100](https://github.com/shumaiOne/shumai/pull/100))
## [0.0.3] - 2026-06-12
### Fixed
- **cli**: Resolve platform binary path resolution under nested node_modules ([#99](https://github.com/shumaiOne/shumai/pull/99))
## [0.0.2] - 2026-06-12
### Fixed
- **npm**: Add repository metadata to package.json for provenance verification ([#98](https://github.com/shumaiOne/shumai/pull/98))
### Maintenance
- Add release-npm.yaml workflow ([#97](https://github.com/shumaiOne/shumai/pull/97))
## [0.0.1] - 2026-06-12
### Added
- Initial release of Shumai
+27 -13
View File
@@ -1,6 +1,6 @@
#syntax=docker/dockerfile:1.7-labs
# Stage 1: Builder
FROM oven/bun:1.3.14 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
@@ -18,6 +17,9 @@ RUN ls -la packages/transcode/node_modules
# Copy source code
COPY . .
# Compile i18n
RUN bun run i18n:compile
# Build API and Worker
RUN bun run build.ts
@@ -25,13 +27,11 @@ RUN bun run build.ts
RUN bun run scripts/extract-runtime-deps.ts
# Stage 2: Runner
FROM oven/bun:1.3.14 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 \
@@ -46,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
@@ -80,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"]
+81
View File
@@ -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"]
+140 -200
View File
@@ -5,11 +5,18 @@
<h1 align="center">Shumai</h1>
<p align="center">
<strong>An open-source platform for all your creative work.</strong>
<strong>The best open-source Frame.io alternative for all your creative work.</strong>
</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 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://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://shumai.discourse.group/">Discourse Forum</a> | <a target="_blank" href="README_CN.md">中文</a>
</p>
![Shumai App Screenshot](docs/screenshot.webp)
@@ -19,24 +26,31 @@
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:
> **AI is optional.** You can use Shumai as a traditional Frame.io alternative and completely ignore the AI features if they aren't useful for your team.
* **Agent as a Team Member**: Mention a context-aware AI agent with `@mentions` directly in asset comments, just like a real teammate.
* **Agent as a One-to-One Assistant**: Chat privately with the agent and ask it to help with tasks.
* **Custom Skills & Tools**: Extend the agent by registering custom scripts, tools, and automation skills.
* **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:
@@ -58,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
@@ -72,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
@@ -99,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:
@@ -306,21 +197,70 @@ 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**.
4. Apply the database schema migrations:
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
```
> [!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. Apply the database schema migrations:
```bash
bun run db:migrate
```
5. Start the local development server:
6. Start the local development server:
```bash
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.
+193 -255
View File
@@ -5,39 +5,51 @@
<h1 align="center">Shumai</h1>
<p align="center">
<strong>为创意工作打造的开源协作平台。</strong>
<strong>开源版 阅流 / 分秒帧 - 专为创意与视频团队打造的审片与管理平台。</strong>
</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 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://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="https://shumai.discourse.group/">Discourse 论坛</a> | <a target="_blank" href="README.md">English</a>
</p>
![Shumai 应用截图](docs/screenshot.webp)
## 功能
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 代理文件进行在线预览。
* **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 能做什么:
@@ -57,62 +69,103 @@ 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>
使用 Docker Compose 是运行 Shumai 最快的方式。您无需克隆仓库,也不需要手动安装依赖包。请确保电脑上已安装 [Docker](https://docs.docker.com/get-docker/) 和 [Docker Compose](https://docs.docker.com/compose/install/),然后按照以下步骤操作:
<summary>复制这个提示词,让agent帮你安装</summary>
1. 创建并进入一个新目录,用于存放配置文件和数据卷:
```
请帮我在本机使用 Docker Compose 一键部署 Shumai。
请严格参考官方文档:
https://gh-proxy.com/https://raw.githubusercontent.com/shumaiOne/shumai/main/README_CN.md
要求:
1. 只能使用 Docker Compose local方式部署,不要使用其他部署方式。
2. 部署前请先检查本机是否已安装并可正常使用 Docker 和 Docker Compose。
3. 如果本机未安装 Docker,请立即提醒用户先安装 Docker,并停止后续部署操作。不要自行安装 Docker,也不要采用其他方式部署。
4. 获取 `docker-compose-aliyun.yaml` 文件内容时,必须通过 `https://gh-proxy.com` 加速访问,不要直接访问 GitHub Raw 地址。
```
</details>
使用 Docker Compose 是运行 Shumai 最快的方式。你无需克隆仓库,也不需要手动安装依赖包。请确保电脑上已安装 [Docker](https://docs.docker.com/get-docker/) 和 [Docker Compose](https://docs.docker.com/compose/install/),然后按照以下步骤操作:
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. 在后台启动所有服务:
@@ -122,230 +175,91 @@ Shumai 也将项目管理融入了创意工作流程。 内置的看板可以帮
```
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. 执行数据库结构迁移:
```bash
bun run db:migrate
4. 生成多语言国际化(i18n)代码:
```bash
bun run i18n:compile
```
> [!TIP]
> 在前端开发过程中,可以在单独的终端窗口中运行 `bun run i18n:watch`,在修改 `packages/webui/messages/` 下的翻译文案时自动重新编译。
```
5. 执行数据库结构迁移:
```bash
bun run db:migrate
```
6. 启动本地开发服务器:
```bash
bun run dev
```
5. 启动本地开发服务器:
```bash
bun run dev
```
> [!NOTE]
> 如需通过 NPM 或包管理器全局安装运行 Shumai,请参考[官方 NPM 安装指南](https://docs.shumai.one/getting-started/quickstart)。
@@ -353,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
View File
@@ -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)**
-14
View File
@@ -1,14 +0,0 @@
{
"name": "@shumai/agent-app",
"version": "0.4.0",
"private": true,
"type": "module",
"bin": {
"shumai-agent": "./src/index.ts"
},
"dependencies": {
"@shumai/agent": "workspace:*",
"@shumai/core": "workspace:*",
"@shumai/workflow-core": "workspace:*"
}
}
-35
View File
@@ -1,35 +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 { 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()
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)
})
-5
View File
@@ -1,5 +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/agent-tool-call'
export * from '@shumai/agent/src/workflows/query-embedding-for-search'
+281 -6
View File
@@ -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,16 +76,58 @@ 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)
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:
@@ -35,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.
@@ -45,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>
@@ -55,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
@@ -89,6 +206,147 @@ shumai-cli create-version <localFilePath> -p <parentAssetId>
- **Options:**
- `-p`, `--parent <id>`: The parent asset ID (file or version stack) to version (required).
#### 6. Rename an Asset
Rename an existing file or folder in Shumai.
```bash
shumai-cli rename <assetId> <newName>
```
#### 7. Move Assets
Move one or more assets (files or folders) to a destination parent folder. Note that all assets to be moved must belong to the same current parent folder.
```bash
shumai-cli move <assetId...> -p <parentId>
# or using the short alias:
shumai-cli mv <assetId...> -p <parentId>
```
- **Options:**
- `-p`, `--parent <id>`: The destination parent folder ID (required).
#### 8. Delete an Asset
Delete a single file or folder by moving it to the Trash bin. For safety, this command only deletes one asset at a time and requires the `SHUMAI_ALLOW_DELETE="true"` environment variable to be set in your environment.
```bash
shumai-cli delete <assetId>
# or using the short alias:
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
@@ -98,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.
+24
View File
@@ -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.
+16 -4
View File
@@ -1,17 +1,29 @@
{
"name": "@shumai/cli",
"version": "0.4.0",
"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:*",
"hono": "4.12.23",
"ulid": "^3.0.2"
"commander": "15.0.0",
"execa": "10.2.1",
"hono": "4.13.5",
"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
View File
@@ -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}`,
+20 -70
View File
@@ -1,7 +1,4 @@
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'
@@ -18,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
@@ -34,17 +31,29 @@ describe('CLI Commands', () => {
$get: vi.fn(),
':projectId': {
$get: vi.fn(),
reparent: {
$post: vi.fn(),
},
},
},
folders: {
$post: vi.fn(),
$delete: vi.fn(),
':folderId': {
$get: vi.fn(),
$put: vi.fn(),
children: {
$get: vi.fn(),
},
},
},
files: {
$delete: vi.fn(),
':fileId': {
$get: vi.fn(),
$put: vi.fn(),
},
},
teams: {
':teamId': {
upload: {
@@ -60,6 +69,8 @@ describe('CLI Commands', () => {
},
}
const originalAllowDelete = process.env.SHUMAI_ALLOW_DELETE
beforeEach(() => {
vi.resetAllMocks()
logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
@@ -79,72 +90,11 @@ describe('CLI Commands', () => {
writeSpy.mockRestore()
errorSpy.mockRestore()
exitSpy.mockRestore()
})
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')
})
if (originalAllowDelete !== undefined) {
process.env.SHUMAI_ALLOW_DELETE = originalAllowDelete
} else {
delete process.env.SHUMAI_ALLOW_DELETE
}
})
describe('upload', () => {
-87
View File
@@ -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)
}
}
-32
View File
@@ -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)
}
}
-42
View File
@@ -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)
}
}
+7 -102
View File
@@ -1,104 +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 { 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
Options:
-p, --parent <id> The parent folder/asset ID (required for ls, mkdir, upload, create-version)
-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 {
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',
)
})
})
+55
View File
@@ -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']>
}
+18
View File
@@ -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)}`,
)
}
}
+269
View File
@@ -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)
}
})
}
}
+68
View File
@@ -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)
})
})
+121
View File
@@ -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)
}
+898
View File
@@ -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')
})
})
+76
View File
@@ -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
}
+446
View File
@@ -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\)$/,
)
}
},
)
})
+461
View File
@@ -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()
}
}
+66
View File
@@ -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)
})
})
+84
View File
@@ -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
}
+364
View File
@@ -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)
})
})
+282
View File
@@ -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()
}
}
}
+44
View File
@@ -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)}…"`)
})
})
+59
View File
@@ -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)
}
+106
View File
@@ -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 })
},
)
})
+64
View File
@@ -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',
}
}
+352
View File
@@ -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()
})
})
+232
View File
@@ -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
}
}
+2
View File
@@ -0,0 +1,2 @@
// Release builds embed SRT's native helpers through scripts/srt-bundle.ts.
export const bundledSrtVendor: Record<string, string> | undefined = undefined
+59
View File
@@ -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()
}
})
})
+59
View File
@@ -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
}
}
+41
View File
@@ -0,0 +1,41 @@
# Premiere UXP Plugin Guidelines
## Component Library (Spectrum Web Components / SWC)
- **Always prefer SWC components if possible**: Use Spectrum Web Component React wrappers (`@swc-react/*`) and `@swc-uxp-wrappers/*` for UI elements (Button, ActionButton, Textfield, Card, Divider, ProgressCircle, StatusLight, Badge, Search, FieldLabel, HelpText, IllustratedMessage, ActionGroup, etc.) rather than hand-crafting custom HTML/CSS elements.
- **SWC Support**: `public/manifest.json` has `"featureFlags": { "enableSWCSupport": true }`.
- **Package Versions**: Keep SWC packages aligned at version `0.37.0` (matching Adobe UXP compatibility).
- **Bundler Aliases**: `build.ts` uses `swcAliasPlugin` with `aliases` from `@swc-uxp-wrappers/utils` to resolve internal SWC imports for Bun.
## Icons
- **Always use Spectrum Workflow Icons (`@spectrum-web-components/icons-workflow`)**: Never use external icon libraries like `lucide-react`.
- **Registration**: All workflow icons used must be imported and registered in `src/index.tsx` (e.g. `import '@spectrum-web-components/icons-workflow/icons/sp-icon-movie-camera.js'`). Note: Ensure the icon exists in `@spectrum-web-components/icons-workflow/icons/` (Spectrum 1 compatible) rather than only `icons-s2/` (which falls back to an empty circular DefaultIcon under Spectrum 1).
- **Typing**: Add custom element declarations to `src/declarations.d.ts` under both `declare namespace React.JSX` and `declare global.JSX.IntrinsicElements` with `SpIconCustomElementProps`.
## Adobe UXP Layout Engine Rules (Critical CSS Gotchas)
Adobe UXP's layout engine (Yoga-based) does **not** support several standard modern CSS features:
1. **No CSS Grid**:
- `display: grid` and `grid-template-columns` are **unsupported / invalid**.
- Always use Flexbox (`display: flex; flex-direction: row | column;`).
2. **No `aspect-ratio`**:
- `aspect-ratio` is invalid in UXP and collapses containers to `0px` height.
- Always specify explicit `width` and `height` on preview / thumbnail containers.
3. **No `box-sizing: border-box`**:
- `box-sizing` is not supported (UXP elements are natively border-box). Specifying it logs invalid property warnings.
4. **No `gap` in Flexbox**:
- `gap` is invalid in Premiere UXP flexbox. Items will render with 0px spacing.
- Use `margin-bottom` or `margin-right` on child items for spacing.
5. **Always Set `flex-shrink: 0` on List Items**:
- Flex children default to `flex-shrink: 1`. When rendering lists with many items (>10 items), flexbox squishes the items down to slivers instead of scrolling.
- Always add `flex-shrink: 0` and an explicit `min-height` to list row cards (`.project-row-card`, `.file-row-card`, `.item-row`, etc.).
6. **Scroll Containers**:
- Scrollable flex children (like `.view-content`) must have `min-height: 0` and `overflow-y: auto` to allow children to overflow and scroll vertically.
## Build and Packaging Commands
- **Build**: `bun run --filter @shumai/premiere-uxp build`
- **Watch mode**: `bun run --filter @shumai/premiere-uxp dev`
- **Package CCX**: `bun run --filter @shumai/premiere-uxp package` (outputs `apps/premiere-uxp/shumai-premiere.ccx`)
+109
View File
@@ -0,0 +1,109 @@
#!/usr/bin/env bun
import { cp, rm, mkdir } from 'node:fs/promises'
import { existsSync, watch } from 'node:fs'
import { $ } from 'bun'
import { aliases } from '@swc-uxp-wrappers/utils'
import type { BunPlugin } from 'bun'
const swcAliasPlugin: BunPlugin = {
name: 'swc-uxp-aliases',
setup(build) {
for (const [key, target] of Object.entries(aliases)) {
const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
const filter = new RegExp(`^${escaped}(/.*)?$`)
build.onResolve({ filter }, (args) => {
const subpath = args.path.slice(key.length)
const targetPath = target + subpath
try {
return { path: import.meta.resolveSync(targetPath) }
} catch {
return undefined
}
})
}
},
}
const isWatch = process.argv.includes('--watch')
const isPackage = process.argv.includes('--package')
async function build(): Promise<boolean> {
const start = performance.now()
try {
if (!existsSync('dist')) {
await mkdir('dist', { recursive: true })
}
// 1. Copy public assets (manifest, index.html, styles, icons)
await cp('public', 'dist', { recursive: true })
// 2. Bundle with Bun.build
const result = await Bun.build({
entrypoints: ['./src/index.tsx'],
outdir: './dist',
naming: 'index.js',
target: 'browser',
format: 'cjs',
sourcemap: 'external',
minify: false,
plugins: [swcAliasPlugin],
external: ['os', 'premierepro', 'uxp'],
define: {
'process.env.NODE_ENV': JSON.stringify('production'),
},
})
if (!result.success) {
console.error('❌ Build failed:')
for (const log of result.logs) {
console.error(log)
}
return false
}
const elapsed = (performance.now() - start).toFixed(1)
console.log(`✅ Build completed in ${elapsed}ms`)
// 3. Package .ccx if requested
if (isPackage) {
console.log('📦 Packaging shumai-premiere.ccx...')
if (existsSync('shumai-premiere.ccx')) {
await rm('shumai-premiere.ccx')
}
await $`cd dist && zip -r ../shumai-premiere.ccx . -x '*.map' -x '.DS_Store' -x '__MACOSX*'`
console.log('✅ Package created.')
}
return true
} catch (err) {
console.error('❌ Build error:', err)
return false
}
}
// Clean and run initial build
if (existsSync('dist')) {
await rm('dist', { recursive: true, force: true })
}
const success = await build()
if (!success && !isWatch) {
process.exit(1)
}
// Watch mode
if (isWatch) {
console.log('👀 Watching src/ and public/ for changes...')
let building = false
const triggerRebuild = async (dir: string) => {
if (building) return
building = true
setTimeout(async () => {
console.log(`\n🔄 Change detected in ${dir}, rebuilding...`)
await build()
building = false
}, 50)
}
watch('./src', { recursive: true }, () => triggerRebuild('src'))
watch('./public', { recursive: true }, () => triggerRebuild('public'))
}
+62
View File
@@ -0,0 +1,62 @@
{
"name": "@shumai/premiere-uxp",
"version": "0.7.0",
"private": true,
"type": "commonjs",
"scripts": {
"build": "bun run ./build.ts",
"dev": "bun run ./build.ts --watch",
"package": "bun run ./build.ts --package",
"clean": "rm -rf dist"
},
"dependencies": {
"@shumai/api": "workspace:*",
"@shumai/dtos": "workspace:*",
"@spectrum-web-components/action-menu": "0.37.0",
"@spectrum-web-components/badge": "0.37.0",
"@spectrum-web-components/icon": "1.12.2",
"@spectrum-web-components/icons-workflow": "1.12.2",
"@spectrum-web-components/menu": "0.37.0",
"@spectrum-web-components/progress-circle": "0.37.0",
"@spectrum-web-components/status-light": "0.37.0",
"@spectrum-web-components/theme": "0.37.0",
"@swc-react/action-button": "0.37.0",
"@swc-react/action-group": "0.37.0",
"@swc-react/action-menu": "0.37.0",
"@swc-react/badge": "0.37.0",
"@swc-react/button": "0.37.0",
"@swc-react/card": "0.37.0",
"@swc-react/divider": "0.37.0",
"@swc-react/field-label": "0.37.0",
"@swc-react/help-text": "0.37.0",
"@swc-react/illustrated-message": "0.37.0",
"@swc-react/menu": "0.37.0",
"@swc-react/progress-circle": "0.37.0",
"@swc-react/search": "0.37.0",
"@swc-react/status-light": "0.37.0",
"@swc-react/textfield": "0.37.0",
"@swc-react/theme": "0.37.0",
"@swc-uxp-wrappers/action-button": "2.0.0",
"@swc-uxp-wrappers/action-group": "2.0.0",
"@swc-uxp-wrappers/button": "2.0.0",
"@swc-uxp-wrappers/card": "2.0.0",
"@swc-uxp-wrappers/divider": "2.0.0",
"@swc-uxp-wrappers/field-label": "2.0.0",
"@swc-uxp-wrappers/help-text": "2.0.0",
"@swc-uxp-wrappers/illustrated-message": "2.0.0",
"@swc-uxp-wrappers/menu": "2.0.0",
"@swc-uxp-wrappers/overlay": "2.0.0",
"@swc-uxp-wrappers/popover": "2.0.0",
"@swc-uxp-wrappers/search": "2.0.0",
"@swc-uxp-wrappers/textfield": "2.0.0",
"@swc-uxp-wrappers/utils": "2.0.1",
"hono": "4.13.5",
"react": "19.2.8",
"react-dom": "19.2.8"
},
"devDependencies": {
"@adobe/premierepro": "26.3.0",
"@types/react": "19.2.18",
"@types/react-dom": "19.2.7"
}
}
Binary file not shown.

After

Width:  |  Height:  |  Size: 4.1 KiB

+13
View File
@@ -0,0 +1,13 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Shumai</title>
<link rel="stylesheet" href="./styles.css" />
<script defer src="./index.js"></script>
</head>
<body>
<div id="root"></div>
</body>
</html>
+61
View File
@@ -0,0 +1,61 @@
{
"id": "com.shumai.premiere",
"name": "Shumai",
"shortname": "shumai",
"version": "0.1.0",
"main": "index.html",
"host": {
"app": "premierepro",
"minVersion": "25.1.0"
},
"manifestVersion": 5,
"featureFlags": {
"enableSWCSupport": true
},
"requiredPermissions": {
"network": {
"domains": "all"
},
"localFileSystem": "request",
"clipboard": "readAndWrite"
},
"entrypoints": [
{
"id": "shumaiPanel",
"type": "panel",
"minimumSize": {
"width": 320,
"height": 480
},
"maximumSize": {
"width": 2000,
"height": 2000
},
"preferredDockedSize": {
"width": 400,
"height": 720
},
"preferredFloatingSize": {
"width": 460,
"height": 780
},
"label": {
"default": "Shumai"
},
"icons": [
{
"width": 114,
"height": 114,
"path": "icons/icon.png"
}
]
}
],
"icons": [
{
"width": 114,
"height": 114,
"path": "icons/icon.png"
}
]
}
File diff suppressed because it is too large Load Diff
Binary file not shown.
+123
View File
@@ -0,0 +1,123 @@
import React, { useEffect, useState } from 'react'
import { Header } from './components/Header'
import { NavigationTabs, type MainTab } from './components/NavigationTabs'
import { AuthView } from './views/AuthView'
import { ProjectsView, ProjectSummary } from './views/ProjectsView'
import { FileListView } from './views/FileListView'
import { SequencesView } from './views/SequencesView'
import { getStoredCredentials, clearStoredCredentials } from './services/storage'
import { getAllSequenceLinksFromCache } from './services/linkStorage'
import { resetClient } from './api/client'
import { autoSyncService } from './services/autoSyncService'
import { ProgressCircle } from '@swc-react/progress-circle'
type AppView = 'auth' | 'projects' | 'files'
export const App: React.FC = () => {
const [view, setView] = useState<AppView>('auth')
const [mainTab, setMainTab] = useState<MainTab>('browse')
const [linkedCount, setLinkedCount] = useState<number>(0)
const [endpoint, setEndpoint] = useState<string>('')
const [apiKey, setApiKey] = useState<string>('')
const [selectedProject, setSelectedProject] = useState<ProjectSummary | null>(null)
const [initialLoading, setInitialLoading] = useState(true)
useEffect(() => {
const creds = getStoredCredentials()
if (creds && creds.endpoint && creds.apiKey) {
setEndpoint(creds.endpoint)
setApiKey(creds.apiKey)
setView('projects')
autoSyncService.start(creds.endpoint, creds.apiKey)
const cached = getAllSequenceLinksFromCache()
setLinkedCount(cached.length)
} else {
setView('auth')
}
setInitialLoading(false)
return () => {
autoSyncService.stop()
}
}, [])
const handleConnectSuccess = (newEndpoint: string, newApiKey: string) => {
setEndpoint(newEndpoint)
setApiKey(newApiKey)
setView('projects')
autoSyncService.start(newEndpoint, newApiKey)
}
const handleDisconnect = () => {
autoSyncService.stop()
clearStoredCredentials()
resetClient()
setEndpoint('')
setApiKey('')
setSelectedProject(null)
setView('auth')
setMainTab('browse')
}
const handleSelectProject = (project: ProjectSummary) => {
setSelectedProject(project)
setView('files')
setMainTab('browse')
}
const handleBackToProjects = () => {
setSelectedProject(null)
setView('projects')
setMainTab('browse')
}
if (initialLoading) {
return (
<div className="app-container">
<Header />
<div className="view-content" style={{ justifyContent: 'center', alignItems: 'center' }}>
<ProgressCircle indeterminate size="l" label="Loading Shumai..." />
</div>
</div>
)
}
return (
<div className="app-container">
<Header
endpoint={view !== 'auth' ? endpoint : undefined}
onDisconnect={view !== 'auth' ? handleDisconnect : undefined}
/>
{view !== 'auth' && (
<NavigationTabs activeTab={mainTab} onTabChange={setMainTab} linkedCount={linkedCount} />
)}
{view === 'auth' && (
<AuthView
initialEndpoint={endpoint || 'http://localhost:3000'}
initialApiKey={apiKey}
onConnectSuccess={handleConnectSuccess}
/>
)}
{view !== 'auth' && mainTab === 'sequences' && (
<SequencesView endpoint={endpoint} apiKey={apiKey} onLinkCountChange={setLinkedCount} />
)}
{view !== 'auth' && mainTab === 'browse' && view === 'projects' && (
<ProjectsView endpoint={endpoint} apiKey={apiKey} onSelectProject={handleSelectProject} />
)}
{view !== 'auth' && mainTab === 'browse' && view === 'files' && selectedProject && (
<FileListView
endpoint={endpoint}
apiKey={apiKey}
project={selectedProject}
onBackToProjects={handleBackToProjects}
onLinkCountChange={setLinkedCount}
/>
)}
</div>
)
}
+31
View File
@@ -0,0 +1,31 @@
import { hc } from 'hono/client'
import type { AppType } from '@shumai/api'
export type ShumaiClient = ReturnType<typeof hc<AppType>>
let currentClient: ShumaiClient | null = null
let currentKey = ''
export function getShumaiClient(endpoint: string, apiKey: string): ShumaiClient {
const normalizedEndpoint = endpoint.trim().replace(/\/+$/, '')
const cacheKey = `${normalizedEndpoint}::${apiKey}`
if (currentClient && currentKey === cacheKey) {
return currentClient
}
currentClient = hc<AppType>(normalizedEndpoint, {
headers: {
Authorization: `Bearer ${apiKey}`,
'x-api-key': apiKey,
},
})
currentKey = cacheKey
return currentClient
}
export function resetClient(): void {
currentClient = null
currentKey = ''
}
@@ -0,0 +1,61 @@
import React from 'react'
import { Divider } from '@swc-react/divider'
export interface BreadcrumbCrumb {
id: string
name: string
}
interface BreadcrumbProps {
projectName?: string
crumbs: BreadcrumbCrumb[]
onNavigateToProjects: () => void
onNavigateToCrumb: (index: number) => void
}
export const Breadcrumb: React.FC<BreadcrumbProps> = ({
projectName,
crumbs,
onNavigateToProjects,
onNavigateToCrumb,
}) => {
return (
<>
<nav className="breadcrumb-bar" aria-label="Folder Path">
<span className="breadcrumb-item" onClick={onNavigateToProjects} title="Back to Projects">
Projects
</span>
{projectName && (
<>
<span className="breadcrumb-separator">/</span>
<span
className={`breadcrumb-item ${crumbs.length === 0 ? 'active' : ''}`}
onClick={() => onNavigateToCrumb(-1)}
title={projectName}
>
{projectName}
</span>
</>
)}
{crumbs.map((crumb, idx) => {
const isLast = idx === crumbs.length - 1
return (
<React.Fragment key={crumb.id}>
<span className="breadcrumb-separator">/</span>
<span
className={`breadcrumb-item ${isLast ? 'active' : ''}`}
onClick={() => (!isLast ? onNavigateToCrumb(idx) : undefined)}
title={crumb.name}
>
{crumb.name}
</span>
</React.Fragment>
)
})}
</nav>
<Divider size="s" />
</>
)
}
@@ -0,0 +1,409 @@
// @vitest-environment happy-dom
import React from 'react'
import { describe, it, expect, vi, afterEach } from 'vitest'
import { render, screen, fireEvent, cleanup } from '@testing-library/react'
import {
getFileTypeCategory,
getAssetVersionLabel,
FileItem,
FileCardItem,
type AssetSummary,
} from './FileItem'
// Configure React 19 act environment for happy-dom
;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
describe('getFileTypeCategory', () => {
it('identifies folder type', () => {
const asset: AssetSummary = {
id: 'f1',
name: 'My Folder',
type: 'folder',
}
expect(getFileTypeCategory(asset)).toBe('folder')
})
it('identifies video by mimeType', () => {
const asset: AssetSummary = {
id: 'v1',
name: 'clip.dat',
type: 'file',
mimeType: 'video/mp4',
}
expect(getFileTypeCategory(asset)).toBe('video')
})
it('identifies video by extension', () => {
const extensions = ['mp4', 'mov', 'avi', 'mkv', 'm4v', 'webm']
for (const ext of extensions) {
const asset: AssetSummary = {
id: `v-${ext}`,
name: `sample.${ext}`,
type: 'file',
}
expect(getFileTypeCategory(asset)).toBe('video')
}
})
it('identifies audio by mimeType or extension', () => {
const asset1: AssetSummary = {
id: 'a1',
name: 'audio.raw',
type: 'file',
mimeType: 'audio/wav',
}
const asset2: AssetSummary = {
id: 'a2',
name: 'track.mp3',
type: 'file',
}
expect(getFileTypeCategory(asset1)).toBe('audio')
expect(getFileTypeCategory(asset2)).toBe('audio')
})
it('identifies image by mimeType or extension', () => {
const asset1: AssetSummary = {
id: 'i1',
name: 'photo.bin',
type: 'file',
mimeType: 'image/png',
}
const asset2: AssetSummary = {
id: 'i2',
name: 'art.jpg',
type: 'file',
}
expect(getFileTypeCategory(asset1)).toBe('image')
expect(getFileTypeCategory(asset2)).toBe('image')
})
it('falls back to generic file', () => {
const asset: AssetSummary = {
id: 'doc1',
name: 'notes.pdf',
type: 'file',
mimeType: 'application/pdf',
}
expect(getFileTypeCategory(asset)).toBe('file')
})
})
describe('FileItem and FileCardItem UI Components', () => {
afterEach(() => {
cleanup()
vi.clearAllMocks()
})
const mockOnClick = vi.fn()
const mockOnImportRaw = vi.fn()
const mockOnSelectVideoForImport = vi.fn()
const folderAsset: AssetSummary = {
id: 'folder-1',
name: 'Raw Footage',
type: 'folder',
fileCount: 5,
}
const imageAsset: AssetSummary = {
id: 'img-1',
name: 'logo.png',
type: 'file',
mimeType: 'image/png',
sizeByte: 2048,
}
const videoAsset: AssetSummary = {
id: 'vid-1',
name: 'interview.mp4',
type: 'file',
mimeType: 'video/mp4',
sizeByte: 50 * 1024 * 1024,
}
it('FileItem navigates into folder on click without download button', () => {
render(
<FileItem
asset={folderAsset}
onClick={mockOnClick}
onImportRaw={mockOnImportRaw}
onSelectVideoForImport={mockOnSelectVideoForImport}
/>,
)
expect(screen.getByText('Raw Footage')).toBeTruthy()
expect(screen.queryByTitle('Import into Premiere Pro')).toBeNull()
fireEvent.click(screen.getByText('Raw Footage'))
expect(mockOnClick).toHaveBeenCalled()
expect(mockOnImportRaw).not.toHaveBeenCalled()
})
it('FileCardItem calls onImportRaw when download button is clicked for non-video, but clicking card does not', () => {
render(
<FileCardItem
asset={imageAsset}
onClick={mockOnClick}
onImportRaw={mockOnImportRaw}
onSelectVideoForImport={mockOnSelectVideoForImport}
/>,
)
expect(screen.getByText('logo.png')).toBeTruthy()
// Clicking the file title / card text should NOT trigger import
fireEvent.click(screen.getByText('logo.png'))
expect(mockOnImportRaw).not.toHaveBeenCalled()
const downloadBtn = screen.getByTitle('Import into Premiere Pro')
expect(downloadBtn).toBeTruthy()
fireEvent.click(downloadBtn)
expect(mockOnImportRaw).toHaveBeenCalledWith(imageAsset)
})
it('FileCardItem calls onSelectVideoForImport when download button is clicked for video', () => {
render(
<FileCardItem
asset={videoAsset}
onClick={mockOnClick}
onImportRaw={mockOnImportRaw}
onSelectVideoForImport={mockOnSelectVideoForImport}
/>,
)
expect(screen.getByText('interview.mp4')).toBeTruthy()
const downloadBtn = screen.getByTitle('Import into Premiere Pro')
fireEvent.click(downloadBtn)
expect(mockOnSelectVideoForImport).toHaveBeenCalledWith(videoAsset)
expect(mockOnImportRaw).not.toHaveBeenCalled()
})
it('FileCardItem renders sp-icon-link when isLinked is false, and triggers onLinkSequence on click', () => {
const mockOnLinkSequence = vi.fn()
const { container } = render(
<FileCardItem
asset={videoAsset}
onClick={mockOnClick}
onLinkSequence={mockOnLinkSequence}
isLinked={false}
/>,
)
const linkIcon = container.querySelector('sp-icon-link')
const unlinkIcon = container.querySelector('sp-icon-unlink')
expect(linkIcon).toBeTruthy()
expect(unlinkIcon).toBeNull()
const linkBtn = screen.getByTitle('Link to Sequence')
expect(linkBtn).toBeTruthy()
fireEvent.click(linkBtn)
expect(mockOnLinkSequence).toHaveBeenCalledWith(videoAsset)
})
it('FileCardItem renders sp-icon-unlink when isLinked is true, and triggers onUnlinkSequence on click', () => {
const mockOnLinkSequence = vi.fn()
const mockOnUnlinkSequence = vi.fn()
const { container } = render(
<FileCardItem
asset={videoAsset}
onClick={mockOnClick}
onLinkSequence={mockOnLinkSequence}
onUnlinkSequence={mockOnUnlinkSequence}
isLinked={true}
linkedSequenceName="Cut_v1"
/>,
)
const linkIcon = container.querySelector('sp-icon-link')
const unlinkIcon = container.querySelector('sp-icon-unlink')
expect(linkIcon).toBeNull()
expect(unlinkIcon).toBeTruthy()
const unlinkBtn = screen.getByTitle('Unlink from Cut_v1')
expect(unlinkBtn).toBeTruthy()
fireEvent.click(unlinkBtn)
expect(mockOnUnlinkSequence).toHaveBeenCalledWith(videoAsset)
expect(mockOnLinkSequence).not.toHaveBeenCalled()
})
it('FileItem renders sp-icon-unlink when isLinked is true', () => {
const mockOnLinkSequence = vi.fn()
const mockOnUnlinkSequence = vi.fn()
const { container } = render(
<FileItem
asset={videoAsset}
onClick={mockOnClick}
onLinkSequence={mockOnLinkSequence}
onUnlinkSequence={mockOnUnlinkSequence}
isLinked={true}
linkedSequenceName="Cut_v1"
/>,
)
const linkIcon = container.querySelector('sp-icon-link')
const unlinkIcon = container.querySelector('sp-icon-unlink')
expect(linkIcon).toBeNull()
expect(unlinkIcon).toBeTruthy()
const unlinkBtn = screen.getByTitle('Unlink from Cut_v1')
expect(unlinkBtn).toBeTruthy()
fireEvent.click(unlinkBtn)
expect(mockOnUnlinkSequence).toHaveBeenCalledWith(videoAsset)
})
it('FileCardItem renders version in details when asset has versionStack', () => {
const versionedAsset: AssetSummary = {
id: 'vid-v2',
name: 'interview_cut.mp4',
type: 'file',
mimeType: 'video/mp4',
sizeByte: 20 * 1024 * 1024,
versionStack: {
id: 'stack-1',
versions: [
{ version: 2, current: true, id: 'vid-v2', name: 'interview_cut.mp4' },
{ version: 1, current: false, id: 'vid-v1', name: 'interview_cut_v1.mp4' },
],
},
}
render(<FileCardItem asset={versionedAsset} onClick={mockOnClick} />)
expect(screen.getByText('v2')).toBeTruthy()
})
it('FileCardItem does not render version when asset has no versionStack', () => {
render(<FileCardItem asset={videoAsset} onClick={mockOnClick} />)
expect(screen.queryByText(/^v\d+$/)).toBeNull()
})
it('FileItem renders version in subtext when asset has versionStack', () => {
const versionedAsset: AssetSummary = {
id: 'vid-v2',
name: 'interview_cut.mp4',
type: 'file',
mimeType: 'video/mp4',
sizeByte: 20 * 1024 * 1024,
versionStack: {
id: 'stack-1',
versions: [
{ version: 2, current: true, id: 'vid-v2', name: 'interview_cut.mp4' },
{ version: 1, current: false, id: 'vid-v1', name: 'interview_cut_v1.mp4' },
],
},
}
render(<FileItem asset={versionedAsset} onClick={mockOnClick} />)
expect(screen.getByText(/v2 •/)).toBeTruthy()
})
it('FileCardItem renders createdAt time when provided', () => {
const assetWithDates: AssetSummary = {
id: 'date-1',
name: 'render.mp4',
type: 'file',
createdAt: new Date(Date.now() - 3600 * 1000).toISOString(),
updatedAt: new Date(Date.now() - 60 * 1000).toISOString(),
}
render(<FileCardItem asset={assetWithDates} onClick={mockOnClick} />)
expect(screen.getByText('1h ago')).toBeTruthy()
expect(screen.queryByText('1m ago')).toBeNull()
})
it('FileCardItem falls back to updatedAt if createdAt is absent', () => {
const assetWithUpdatedOnly: AssetSummary = {
id: 'date-2',
name: 'render2.mp4',
type: 'file',
updatedAt: new Date(Date.now() - 60 * 1000).toISOString(),
}
render(<FileCardItem asset={assetWithUpdatedOnly} onClick={mockOnClick} />)
expect(screen.getByText('1m ago')).toBeTruthy()
})
it('FileItem renders createdAt time in subtext when provided', () => {
const assetWithDates: AssetSummary = {
id: 'date-3',
name: 'render3.mp4',
type: 'file',
createdAt: new Date(Date.now() - 3600 * 1000).toISOString(),
updatedAt: new Date(Date.now() - 60 * 1000).toISOString(),
}
render(<FileItem asset={assetWithDates} onClick={mockOnClick} />)
expect(screen.getByText(/1h ago/)).toBeTruthy()
expect(screen.queryByText(/1m ago/)).toBeNull()
})
})
describe('getAssetVersionLabel', () => {
it('returns null for folder asset', () => {
const folder: AssetSummary = {
id: 'f1',
name: 'Footage',
type: 'folder',
}
expect(getAssetVersionLabel(folder)).toBeNull()
})
it('returns null for standalone file without versionStack', () => {
const file: AssetSummary = {
id: 'file1',
name: 'clip.mp4',
type: 'file',
}
expect(getAssetVersionLabel(file)).toBeNull()
})
it('returns null when versionStack has empty versions array', () => {
const file: AssetSummary = {
id: 'file1',
name: 'clip.mp4',
type: 'file',
versionStack: {
id: 'stack-1',
versions: [],
},
}
expect(getAssetVersionLabel(file)).toBeNull()
})
it('returns formatted version matching asset id', () => {
const file: AssetSummary = {
id: 'ver-1',
name: 'cut.mov',
type: 'file',
versionStack: {
id: 'stack-1',
versions: [
{ version: 3, current: false, id: 'ver-3' },
{ version: 2, current: false, id: 'ver-2' },
{ version: 1, current: false, id: 'ver-1' },
],
},
}
expect(getAssetVersionLabel(file)).toBe('v1')
})
it('returns current version when asset id is stack id or does not match', () => {
const file: AssetSummary = {
id: 'stack-1',
name: 'cut.mov',
type: 'version_stack',
versionStack: {
id: 'stack-1',
versions: [
{ version: 3, current: true, id: 'ver-3' },
{ version: 2, current: false, id: 'ver-2' },
{ version: 1, current: false, id: 'ver-1' },
],
},
}
expect(getAssetVersionLabel(file)).toBe('v3')
})
})
@@ -0,0 +1,503 @@
import React, { useState } from 'react'
import { formatDateAgo } from '../utils/date'
import { formatBytes, formatDuration } from '../utils/format'
import { resolveAssetUrl } from '../utils/url'
export { formatBytes, formatDuration }
export interface AssetSummary {
id: string
name: string
type: string
size?: number | null
sizeByte?: number | null
mimeType?: string | null
updatedAt?: string | Date
createdAt?: string | Date
commentsCount?: number
fileCount?: number
creator?: {
id: string
name: string
image?: string | null
} | null
agent?: {
id: string
name: string
} | null
preview?: {
thumbnailUrl?: string
duration?: number
pageCount?: number
proxyType?: string | null
} | null
media?: {
original?: {
key?: string
filesizeInBytes?: number
codec?: string
} | null
metadata?: {
duration?: number
}
videoTranscodes?: Array<{
id: string
url: string
key: string
width: number
height: number
size: number
}>
} | null
versionStack?: {
id: string
versions: Array<{
version: number
current: boolean
id: string
name?: string | null
createdAt?: string | null
previewUrl?: string | null
}>
} | null
}
export interface FileItemProps {
asset: AssetSummary
endpoint?: string
apiKey?: string
onClick: (e: React.MouseEvent) => void
onImportRaw?: (asset: AssetSummary) => void
onSelectVideoForImport?: (asset: AssetSummary) => void
onLinkSequence?: (asset: AssetSummary) => void
onUnlinkSequence?: (asset: AssetSummary) => void
isLinked?: boolean
linkedSequenceName?: string
}
export function getFileTypeCategory(
asset: AssetSummary,
): 'folder' | 'video' | 'audio' | 'image' | 'file' {
if (asset.type === 'folder') return 'folder'
const name = asset.name.toLowerCase()
const mime = asset.mimeType?.toLowerCase() || ''
if (mime.startsWith('video/') || /\.(mp4|mov|avi|mkv|m4v|webm)$/.test(name)) {
return 'video'
}
if (mime.startsWith('audio/') || /\.(mp3|wav|aac|flac|m4a|ogg)$/.test(name)) {
return 'audio'
}
if (mime.startsWith('image/') || /\.(png|jpg|jpeg|gif|webp|svg|bmp)$/.test(name)) {
return 'image'
}
return 'file'
}
export function getAssetVersionLabel(asset: AssetSummary): string | null {
if (asset.versionStack?.versions && asset.versionStack.versions.length > 0) {
const matched = asset.versionStack.versions.find((v) => v.id === asset.id)
if (matched?.version != null) {
return `v${matched.version}`
}
const current = asset.versionStack.versions.find((v) => v.current)
if (current?.version != null) {
return `v${current.version}`
}
const first = asset.versionStack.versions[0]
if (first?.version != null) {
return `v${first.version}`
}
return `v${asset.versionStack.versions.length}`
}
return null
}
/** List View Row Item */
export const FileItem: React.FC<FileItemProps> = ({
asset,
endpoint = '',
onClick,
onImportRaw,
onSelectVideoForImport,
onLinkSequence,
onUnlinkSequence,
isLinked = false,
linkedSequenceName,
}) => {
const [imgError, setImgError] = useState(false)
const category = getFileTypeCategory(asset)
const isFolder = category === 'folder'
const versionLabel = getAssetVersionLabel(asset)
const effectiveSize = asset.sizeByte ?? asset.size
const timeText = formatDateAgo(asset.createdAt || asset.updatedAt)
const thumbUrl = resolveAssetUrl(asset.preview?.thumbnailUrl, endpoint)
const iconFallback = (
<div className={`item-icon ${category}`}>
{category === 'folder' && (
<sp-icon-folder size="s" style={{ color: '#fbbf24' }}></sp-icon-folder>
)}
{category === 'video' && (
<sp-icon-filmstrip size="s" style={{ color: '#60a5fa' }}></sp-icon-filmstrip>
)}
{category === 'audio' && (
<sp-icon-audio size="s" style={{ color: '#a78bfa' }}></sp-icon-audio>
)}
{category === 'image' && (
<sp-icon-image size="s" style={{ color: '#f472b6' }}></sp-icon-image>
)}
{category === 'file' && (
<sp-icon-document size="s" style={{ color: '#999999' }}></sp-icon-document>
)}
</div>
)
const handleImportAction = () => {
if (isFolder) return
if (category === 'video' && onSelectVideoForImport) {
onSelectVideoForImport(asset)
} else if (onImportRaw) {
onImportRaw(asset)
}
}
const handleRowClick = (e: React.MouseEvent) => {
if (isFolder) {
onClick(e)
} else {
e.stopPropagation()
handleImportAction()
}
}
return (
<div
className="item-row"
onClick={handleRowClick}
role="button"
tabIndex={0}
onKeyDown={(e) => {
if (e.key === 'Enter' || e.key === ' ') {
e.preventDefault()
handleRowClick(e as unknown as React.MouseEvent)
}
}}
>
<div className="item-left">
{thumbUrl && !isFolder && !imgError ? (
<div className="item-thumb-wrapper">
<img
src={thumbUrl}
alt={asset.name}
className="item-thumb-img"
onLoad={() => console.log('[UXP Image OK]', thumbUrl)}
onError={() => {
console.error('[UXP Image Failed]', thumbUrl)
setImgError(true)
}}
/>
</div>
) : (
iconFallback
)}
<div className="item-meta">
<span className="item-name" title={asset.name}>
{asset.name}
</span>
<span className="item-subtext">
{versionLabel ? `${versionLabel} • ` : ''}
{isFolder ? 'Folder' : formatBytes(effectiveSize)}
{timeText ? ` • ${timeText}` : ''}
</span>
</div>
</div>
<div className="item-right">
{asset.commentsCount != null && asset.commentsCount > 0 && (
<span className="item-comments-count" title={`${asset.commentsCount} comments`}>
{asset.commentsCount} {asset.commentsCount === 1 ? 'comment' : 'comments'}
</span>
)}
{isFolder ? (
<sp-icon-chevron-right size="xs"></sp-icon-chevron-right>
) : (
<div style={{ display: 'flex', alignItems: 'center' }}>
{(onLinkSequence || onUnlinkSequence) &&
(category === 'video' || category === 'audio') && (
<sp-action-button
quiet
size="xs"
icon-only
label={
isLinked
? onUnlinkSequence
? `Unlink from ${linkedSequenceName || 'Sequence'}`
: `Linked to ${linkedSequenceName || 'Sequence'}`
: 'Link to Sequence'
}
title={
isLinked
? onUnlinkSequence
? `Unlink from ${linkedSequenceName || 'Sequence'}`
: `Linked to ${linkedSequenceName || 'Sequence'}`
: 'Link to Sequence'
}
className="item-row-link-btn"
style={{ marginRight: 4 }}
onClick={(e: React.MouseEvent) => {
e.stopPropagation()
if (isLinked && onUnlinkSequence) {
onUnlinkSequence(asset)
} else if (onLinkSequence) {
onLinkSequence(asset)
}
}}
>
{isLinked ? (
<sp-icon-unlink
size="s"
slot="icon"
style={{ color: '#f87171' }}
></sp-icon-unlink>
) : (
<sp-icon-link size="s" slot="icon"></sp-icon-link>
)}
</sp-action-button>
)}
{(onImportRaw || onSelectVideoForImport) && (
<sp-action-button
quiet
size="xs"
icon-only
label="Import into Premiere Pro"
title="Import into Premiere Pro"
className="item-row-import-btn"
onClick={(e: React.MouseEvent) => {
e.stopPropagation()
handleImportAction()
}}
>
<sp-icon-download size="s" slot="icon"></sp-icon-download>
</sp-action-button>
)}
</div>
)}
</div>
</div>
)
}
/** Card View Row Item (2 Columns: Left Preview, Right Info as Raw Text) */
export const FileCardItem: React.FC<FileItemProps> = ({
asset,
endpoint = '',
onClick,
onImportRaw,
onSelectVideoForImport,
onLinkSequence,
onUnlinkSequence,
isLinked = false,
linkedSequenceName,
}) => {
const [imgError, setImgError] = useState(false)
const category = getFileTypeCategory(asset)
const isFolder = category === 'folder'
const effectiveSize = asset.sizeByte ?? asset.size
const timeText = formatDateAgo(asset.createdAt || asset.updatedAt)
const thumbUrl = resolveAssetUrl(asset.preview?.thumbnailUrl, endpoint)
const duration = asset.preview?.duration ?? asset.media?.metadata?.duration
const durationText = formatDuration(duration)
const creatorName = asset.creator?.name || asset.agent?.name
const cardFallback = (
<div className={`file-row-placeholder ${category}`}>
{category === 'folder' && (
<sp-icon-folder size="l" style={{ color: '#fbbf24' }}></sp-icon-folder>
)}
{category === 'video' && (
<sp-icon-filmstrip size="l" style={{ color: '#60a5fa' }}></sp-icon-filmstrip>
)}
{category === 'audio' && (
<sp-icon-audio size="l" style={{ color: '#a78bfa' }}></sp-icon-audio>
)}
{category === 'image' && (
<sp-icon-image size="l" style={{ color: '#f472b6' }}></sp-icon-image>
)}
{category === 'file' && (
<sp-icon-document size="l" style={{ color: '#999999' }}></sp-icon-document>
)}
</div>
)
const handleImportAction = () => {
if (isFolder) return
if (category === 'video' && onSelectVideoForImport) {
onSelectVideoForImport(asset)
} else if (onImportRaw) {
onImportRaw(asset)
}
}
const handleCardClick = (e: React.MouseEvent) => {
if (isFolder) {
onClick(e)
}
}
// Assemble raw text details for Line 3 (Version • Duration • Size/Type • Comments)
const details: string[] = []
const versionLabel = getAssetVersionLabel(asset)
if (versionLabel) {
details.push(versionLabel)
}
if (durationText) {
details.push(durationText)
}
if (isFolder) {
details.push(asset.fileCount != null ? `${asset.fileCount} items` : 'Folder')
} else if (effectiveSize != null) {
details.push(formatBytes(effectiveSize))
}
if (asset.commentsCount != null && asset.commentsCount > 0) {
details.push(`${asset.commentsCount} ${asset.commentsCount === 1 ? 'comment' : 'comments'}`)
}
if (isLinked) {
details.push(`Linked: ${linkedSequenceName || 'Sequence'}`)
}
return (
<div
className={`file-row-card ${isFolder ? 'is-folder' : 'is-file'}`}
onClick={isFolder ? handleCardClick : undefined}
role={isFolder ? 'button' : undefined}
tabIndex={isFolder ? 0 : undefined}
title={isFolder ? asset.name : undefined}
onKeyDown={
isFolder
? (e) => {
if (e.key === 'Enter' || e.key === ' ') {
e.preventDefault()
handleCardClick(e as unknown as React.MouseEvent)
}
}
: undefined
}
>
{/* Left Column: Preview Only (NO LABELS, NO BADGES) */}
<div className="file-row-preview">
{thumbUrl && !isFolder && !imgError ? (
<img
src={thumbUrl}
alt={asset.name}
className="file-row-img"
onError={() => setImgError(true)}
/>
) : (
cardFallback
)}
</div>
{/* Right Column: Title, Creator & Date, Duration / Size / Comments as Raw Text */}
<div className="file-row-content">
<div className="file-row-header">
<span className="file-row-title" title={isFolder ? asset.name : undefined}>
{asset.name}
</span>
</div>
{(creatorName || timeText) && (
<div className="file-row-meta">
{creatorName && <span className="file-row-creator">{creatorName}</span>}
{creatorName && timeText && <span className="file-row-meta-dot">•</span>}
{timeText && <span className="file-row-time">{timeText}</span>}
</div>
)}
{details.length > 0 && (
<div className="file-row-subtext file-row-details">
{details.map((item, idx) => (
<React.Fragment key={idx}>
{idx > 0 && <span className="file-row-meta-dot">•</span>}
<span
className={`file-row-detail-item${item === versionLabel ? ' file-row-version' : ''}`}
>
{item}
</span>
</React.Fragment>
))}
</div>
)}
</div>
{/* Far Right Action Column (Centered Vertically across the card) */}
<div className="file-row-actions" style={{ display: 'flex', alignItems: 'center' }}>
{isFolder ? (
<sp-icon-chevron-right size="xs" className="file-row-chevron"></sp-icon-chevron-right>
) : (
<>
{(onLinkSequence || onUnlinkSequence) &&
(category === 'video' || category === 'audio') && (
<sp-action-button
quiet
size="xs"
icon-only
label={
isLinked
? onUnlinkSequence
? `Unlink from ${linkedSequenceName || 'Sequence'}`
: `Linked to ${linkedSequenceName || 'Sequence'}`
: 'Link to Sequence'
}
title={
isLinked
? onUnlinkSequence
? `Unlink from ${linkedSequenceName || 'Sequence'}`
: `Linked to ${linkedSequenceName || 'Sequence'}`
: 'Link to Sequence'
}
className="file-row-link-btn"
style={{ marginRight: 4 }}
onClick={(e: React.MouseEvent) => {
e.stopPropagation()
if (isLinked && onUnlinkSequence) {
onUnlinkSequence(asset)
} else if (onLinkSequence) {
onLinkSequence(asset)
}
}}
>
{isLinked ? (
<sp-icon-unlink
size="s"
slot="icon"
style={{ color: '#f87171' }}
></sp-icon-unlink>
) : (
<sp-icon-link size="s" slot="icon"></sp-icon-link>
)}
</sp-action-button>
)}
{(onImportRaw || onSelectVideoForImport) && (
<sp-action-button
quiet
size="xs"
icon-only
label="Import into Premiere Pro"
title="Import into Premiere Pro"
className="file-row-import-btn"
onClick={(e: React.MouseEvent) => {
e.stopPropagation()
handleImportAction()
}}
>
<sp-icon-download size="s" slot="icon"></sp-icon-download>
</sp-action-button>
)}
</>
)}
</div>
</div>
)
}
@@ -0,0 +1,59 @@
import React from 'react'
import { Divider } from '@swc-react/divider'
import { ShumaiLogo } from './icons'
interface HeaderProps {
endpoint?: string
onDisconnect?: () => void
}
export const Header: React.FC<HeaderProps> = ({ endpoint, onDisconnect }) => {
let displayHost = ''
if (endpoint) {
try {
const url = new URL(endpoint)
displayHost = url.host
} catch {
displayHost = endpoint
}
}
return (
<>
<header className="app-header">
<div className="logo-group">
<div className="logo-icon">
<ShumaiLogo width={18} height={18} />
</div>
<span className="app-title">Shumai</span>
</div>
{endpoint && onDisconnect && (
<div className="actions-group">
<div
className="header-status"
title={`Connected to ${endpoint}`}
role="status"
aria-label={`Connected to ${displayHost}`}
>
<span className="status-dot positive" />
<span className="status-text">{displayHost}</span>
</div>
<sp-button
quiet
variant="secondary"
size="s"
label="Disconnect / Change Server"
icon-only
onClick={onDisconnect}
title="Disconnect / Change Server"
>
<sp-icon-log-out slot="icon" size="s"></sp-icon-log-out>
</sp-button>
</div>
)}
</header>
<Divider size="s" />
</>
)
}
@@ -0,0 +1,162 @@
// @vitest-environment happy-dom
import React, { act } from 'react'
import { describe, it, expect, vi, afterEach } from 'vitest'
import { render, screen, fireEvent, cleanup } from '@testing-library/react'
import { ImportVideoDialog } from './ImportVideoDialog'
import type { AssetSummary } from './FileItem'
import * as importService from '../services/import'
// Configure React 19 act environment for happy-dom
;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
describe('ImportVideoDialog Component', () => {
const mockOnClose = vi.fn()
const mockOnImportRaw = vi.fn()
const mockOnImportProxy = vi.fn()
const videoAsset: AssetSummary = {
id: 'asset-vid-1',
name: 'interview_clip.mp4',
type: 'file',
mimeType: 'video/mp4',
sizeByte: 1024 * 1024 * 45,
preview: {
duration: 154,
},
}
afterEach(() => {
cleanup()
vi.clearAllMocks()
})
it('renders nothing when closed or asset is null', () => {
const { container } = render(
<ImportVideoDialog
asset={videoAsset}
endpoint="https://api.shumai.test"
apiKey="test-key"
isOpen={false}
onClose={mockOnClose}
onImportRaw={mockOnImportRaw}
onImportProxy={mockOnImportProxy}
/>,
)
expect(container.firstChild).toBeNull()
const { container: containerNull } = render(
<ImportVideoDialog
asset={null}
endpoint="https://api.shumai.test"
apiKey="test-key"
isOpen={true}
onClose={mockOnClose}
onImportRaw={mockOnImportRaw}
onImportProxy={mockOnImportProxy}
/>,
)
expect(containerNull.firstChild).toBeNull()
})
it('renders video info and selects original file by default', async () => {
vi.spyOn(importService, 'fetchVideoProxies').mockResolvedValue([])
await act(async () => {
render(
<ImportVideoDialog
asset={videoAsset}
endpoint="https://api.shumai.test"
apiKey="test-key"
isOpen={true}
onClose={mockOnClose}
onImportRaw={mockOnImportRaw}
onImportProxy={mockOnImportProxy}
/>,
)
})
expect(screen.getByText('Import Video')).toBeTruthy()
expect(screen.getByText('interview_clip.mp4')).toBeTruthy()
expect(screen.getByText('Original File')).toBeTruthy()
expect(screen.getByText('No proxy transcodes available for this video.')).toBeTruthy()
// Click Import button
const importBtn = screen.getByText('Import')
fireEvent.click(importBtn)
expect(mockOnImportRaw).toHaveBeenCalledWith(videoAsset)
expect(mockOnClose).toHaveBeenCalled()
})
it('fetches and allows selecting a proxy transcode', async () => {
vi.spyOn(importService, 'fetchVideoProxies').mockResolvedValue([
{
id: 'proxy-1',
label: '1080p (MP4)',
resolution: '1080p',
url: 'https://cdn.shumai.test/1080p.mp4',
key: 'proxies/1080p.mp4',
width: 1920,
height: 1080,
size: 1024 * 1024 * 12,
},
])
await act(async () => {
render(
<ImportVideoDialog
asset={videoAsset}
endpoint="https://api.shumai.test"
apiKey="test-key"
isOpen={true}
onClose={mockOnClose}
onImportRaw={mockOnImportRaw}
onImportProxy={mockOnImportProxy}
/>,
)
})
expect(screen.getByText('1080p (MP4)')).toBeTruthy()
// Select the proxy card
const proxyCard = screen.getByText('1080p (MP4)')
fireEvent.click(proxyCard)
// Click Import button
const importBtn = screen.getByText('Import')
fireEvent.click(importBtn)
expect(mockOnImportProxy).toHaveBeenCalledWith(
videoAsset,
expect.objectContaining({ id: 'proxy-1', label: '1080p (MP4)' }),
)
expect(mockOnClose).toHaveBeenCalled()
})
it('closes on Escape key or cancel button', async () => {
vi.spyOn(importService, 'fetchVideoProxies').mockResolvedValue([])
await act(async () => {
render(
<ImportVideoDialog
asset={videoAsset}
endpoint="https://api.shumai.test"
apiKey="test-key"
isOpen={true}
onClose={mockOnClose}
onImportRaw={mockOnImportRaw}
onImportProxy={mockOnImportProxy}
/>,
)
})
const cancelBtn = screen.getByText('Cancel')
fireEvent.click(cancelBtn)
expect(mockOnClose).toHaveBeenCalledTimes(1)
act(() => {
fireEvent.keyDown(document, { key: 'Escape' })
})
expect(mockOnClose).toHaveBeenCalledTimes(2)
})
})
@@ -0,0 +1,245 @@
import React, { useState, useEffect, useCallback } from 'react'
import type { AssetSummary } from './FileItem'
import { fetchVideoProxies, type ProxyOption } from '../services/import'
import { formatBytes, formatDuration } from '../utils/format'
import { resolveAssetUrl } from '../utils/url'
import { ProgressCircle } from '@swc-react/progress-circle'
export interface ImportVideoDialogProps {
asset: AssetSummary | null
endpoint: string
apiKey: string
isOpen: boolean
onClose: () => void
onImportRaw: (asset: AssetSummary) => void
onImportProxy: (asset: AssetSummary, proxy: ProxyOption) => void
}
export const ImportVideoDialog: React.FC<ImportVideoDialogProps> = ({
asset,
endpoint,
apiKey,
isOpen,
onClose,
onImportRaw,
onImportProxy,
}) => {
const [selectedVersion, setSelectedVersion] = useState<'raw' | string>('raw')
const [proxies, setProxies] = useState<ProxyOption[]>([])
const [loadingProxies, setLoadingProxies] = useState(false)
const [thumbError, setThumbError] = useState(false)
// Reset and fetch proxies when a new video asset is opened
useEffect(() => {
if (!isOpen || !asset) {
setProxies([])
setSelectedVersion('raw')
setLoadingProxies(false)
setThumbError(false)
return
}
let isMounted = true
setLoadingProxies(true)
setSelectedVersion('raw')
void fetchVideoProxies(endpoint, apiKey, asset.id)
.then((items) => {
if (isMounted) {
setProxies(items)
}
})
.catch((err) => {
console.warn('Failed to load video proxies:', err)
})
.finally(() => {
if (isMounted) {
setLoadingProxies(false)
}
})
return () => {
isMounted = false
}
}, [isOpen, asset, endpoint, apiKey])
// Handle Escape key to close dialog
useEffect(() => {
if (!isOpen) return
const handleKeyDown = (e: KeyboardEvent) => {
if (e.key === 'Escape') {
onClose()
}
}
document.addEventListener('keydown', handleKeyDown)
return () => {
document.removeEventListener('keydown', handleKeyDown)
}
}, [isOpen, onClose])
const handleConfirm = useCallback(() => {
if (!asset) return
if (selectedVersion === 'raw') {
onClose()
onImportRaw(asset)
} else if (selectedVersion.startsWith('proxy:')) {
const proxyId = selectedVersion.slice('proxy:'.length)
const targetProxy = proxies.find((p) => p.id === proxyId)
if (targetProxy) {
onClose()
onImportProxy(asset, targetProxy)
}
}
}, [asset, selectedVersion, proxies, onClose, onImportRaw, onImportProxy])
if (!isOpen || !asset) return null
const effectiveSize = asset.sizeByte ?? asset.size
const thumbUrl = resolveAssetUrl(asset.preview?.thumbnailUrl, endpoint)
const duration = asset.preview?.duration ?? asset.media?.metadata?.duration
const durationText = formatDuration(duration)
return (
<div
className="shumai-dialog-backdrop"
onClick={(e) => {
if (e.target === e.currentTarget) {
onClose()
}
}}
>
<div className="shumai-dialog" role="dialog" aria-modal="true" aria-labelledby="dialog-title">
{/* Dialog Header */}
<div className="shumai-dialog-header">
<span id="dialog-title" className="shumai-dialog-title">
Import Video
</span>
<button
type="button"
className="shumai-dialog-close"
onClick={onClose}
title="Close dialog"
aria-label="Close dialog"
>
<sp-icon-close size="s"></sp-icon-close>
</button>
</div>
{/* Video Asset Preview Info */}
<div className="shumai-dialog-asset-info">
<div className="shumai-dialog-thumb">
{thumbUrl && !thumbError ? (
<img src={thumbUrl} alt={asset.name} onError={() => setThumbError(true)} />
) : (
<sp-icon-filmstrip size="xxl" style={{ color: '#60a5fa' }}></sp-icon-filmstrip>
)}
</div>
<div className="shumai-dialog-asset-meta">
<span className="shumai-dialog-asset-name" title={asset.name}>
{asset.name}
</span>
<span className="shumai-dialog-asset-details">
{durationText ? `${durationText} • ` : ''}
{effectiveSize ? formatBytes(effectiveSize) : 'Video'}
</span>
</div>
</div>
{/* Options Selection Body */}
<div className="shumai-dialog-body">
<div className="shumai-dialog-section-label">Choose Version to Import</div>
{/* Original Version Card */}
<div
className={`shumai-option-card ${selectedVersion === 'raw' ? 'selected' : ''}`}
onClick={() => setSelectedVersion('raw')}
role="radio"
aria-checked={selectedVersion === 'raw'}
tabIndex={0}
onKeyDown={(e) => {
if (e.key === 'Enter' || e.key === ' ') {
e.preventDefault()
setSelectedVersion('raw')
}
}}
>
<div className="shumai-option-left">
<div className="shumai-option-texts">
<span className="shumai-option-title">Original File</span>
<span className="shumai-option-meta">
Full resolution • {effectiveSize ? formatBytes(effectiveSize) : 'Raw file'}
</span>
</div>
</div>
<div className="shumai-option-radio">
{selectedVersion === 'raw' && <div className="shumai-option-radio-dot" />}
</div>
</div>
<div className="shumai-dialog-divider" />
{/* Proxies Section */}
<div className="shumai-dialog-section-label">Transcode Proxies</div>
{loadingProxies ? (
<div className="shumai-dialog-loading">
<ProgressCircle indeterminate size="s" label="Checking available proxies..." />
<span>Checking available proxies...</span>
</div>
) : proxies.length > 0 ? (
proxies.map((proxy) => {
const isSelected = selectedVersion === `proxy:${proxy.id}`
return (
<div
key={proxy.id}
className={`shumai-option-card ${isSelected ? 'selected' : ''}`}
onClick={() => setSelectedVersion(`proxy:${proxy.id}`)}
role="radio"
aria-checked={isSelected}
tabIndex={0}
onKeyDown={(e) => {
if (e.key === 'Enter' || e.key === ' ') {
e.preventDefault()
setSelectedVersion(`proxy:${proxy.id}`)
}
}}
>
<div className="shumai-option-left">
<div className="shumai-option-texts">
<span className="shumai-option-title">{proxy.label}</span>
<span className="shumai-option-meta">
{proxy.width && proxy.height ? `${proxy.width}x${proxy.height} • ` : ''}
{proxy.size ? `${formatBytes(proxy.size)} • ` : ''}
Fast editing proxy
</span>
</div>
</div>
<div className="shumai-option-radio">
{isSelected && <div className="shumai-option-radio-dot" />}
</div>
</div>
)
})
) : (
<div className="shumai-dialog-empty-proxies">
<span>No proxy transcodes available for this video.</span>
</div>
)}
</div>
{/* Dialog Footer Actions */}
<div className="shumai-dialog-footer">
<sp-button quiet variant="secondary" size="s" onClick={onClose}>
Cancel
</sp-button>
<sp-button variant="accent" size="s" onClick={handleConfirm}>
Import
</sp-button>
</div>
</div>
</div>
)
}
@@ -0,0 +1,194 @@
// @vitest-environment happy-dom
import React, { act } from 'react'
import { describe, it, expect, vi, afterEach, beforeEach } from 'vitest'
import { render, screen, fireEvent, cleanup } from '@testing-library/react'
import { LinkSequenceDialog } from './LinkSequenceDialog'
import type { AssetSummary } from './FileItem'
import * as premiereService from '../services/premiere'
import * as linkStorage from '../services/linkStorage'
import * as markersService from '../services/markers'
import type { Project, Sequence } from '@adobe/premierepro'
import type { CommentInfo } from '@shumai/dtos'
// Configure React 19 act environment for happy-dom
;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
describe('LinkSequenceDialog Component', () => {
const mockOnClose = vi.fn()
const mockOnLinkSuccess = vi.fn()
const videoAsset: AssetSummary = {
id: 'asset-vid-1',
name: 'interview_clip.mp4',
type: 'file',
mimeType: 'video/mp4',
sizeByte: 1024 * 1024 * 45,
preview: {
duration: 154,
},
commentsCount: 3,
}
beforeEach(() => {
vi.restoreAllMocks()
})
afterEach(() => {
cleanup()
})
it('renders nothing when closed or asset is null', () => {
const { container } = render(
<LinkSequenceDialog
asset={videoAsset}
endpoint="https://api.shumai.test"
apiKey="test-key"
isOpen={false}
onClose={mockOnClose}
onLinkSuccess={mockOnLinkSuccess}
/>,
)
expect(container.firstChild).toBeNull()
const { container: containerNull } = render(
<LinkSequenceDialog
asset={null}
endpoint="https://api.shumai.test"
apiKey="test-key"
isOpen={true}
onClose={mockOnClose}
onLinkSuccess={mockOnLinkSuccess}
/>,
)
expect(containerNull.firstChild).toBeNull()
})
it('displays error message when no active project is open', async () => {
vi.spyOn(premiereService, 'getActiveProject').mockResolvedValue(null)
await act(async () => {
render(
<LinkSequenceDialog
asset={videoAsset}
endpoint="https://api.shumai.test"
apiKey="test-key"
isOpen={true}
onClose={mockOnClose}
onLinkSuccess={mockOnLinkSuccess}
/>,
)
})
expect(screen.getByText(/no active premiere pro project found/i)).toBeDefined()
})
it('lists project sequences and highlights active sequence without sequence icon', async () => {
const mockSeq1 = { guid: 'seq-1', name: 'Rough Cut' }
const mockSeq2 = { guid: 'seq-2', name: 'Fine Cut' }
const mockProject = { guid: 'proj-1' }
vi.spyOn(premiereService, 'getActiveProject').mockResolvedValue(
mockProject as unknown as Project,
)
vi.spyOn(premiereService, 'getAllSequences').mockResolvedValue([
mockSeq1,
mockSeq2,
] as unknown as Sequence[])
vi.spyOn(premiereService, 'getActiveSequence').mockResolvedValue(
mockSeq2 as unknown as Sequence,
)
vi.spyOn(linkStorage, 'getAllLinkedSequences').mockResolvedValue([])
let renderedContainer: HTMLElement = null!
await act(async () => {
const { container } = render(
<LinkSequenceDialog
asset={videoAsset}
endpoint="https://api.shumai.test"
apiKey="test-key"
isOpen={true}
onClose={mockOnClose}
onLinkSuccess={mockOnLinkSuccess}
/>,
)
renderedContainer = container
})
expect(screen.getByText('Rough Cut')).toBeDefined()
expect(screen.getByText('Fine Cut')).toBeDefined()
expect(screen.getByText('Active')).toBeDefined()
expect(renderedContainer.querySelectorAll('.shumai-option-card sp-icon-filmstrip').length).toBe(
0,
)
})
it('executes sync and invokes onLinkSuccess on confirmation', async () => {
const mockSeq1 = { guid: 'seq-1', name: 'Rough Cut' }
const mockProject = { guid: 'proj-1' }
vi.spyOn(premiereService, 'getActiveProject').mockResolvedValue(
mockProject as unknown as Project,
)
vi.spyOn(premiereService, 'getAllSequences').mockResolvedValue([
mockSeq1,
] as unknown as Sequence[])
vi.spyOn(premiereService, 'getActiveSequence').mockResolvedValue(
mockSeq1 as unknown as Sequence,
)
vi.spyOn(linkStorage, 'getAllLinkedSequences').mockResolvedValue([])
vi.spyOn(markersService, 'fetchAssetComments').mockResolvedValue([
{ id: 'comm-1', second: 10, message: 'Test marker' } as unknown as CommentInfo,
])
const mockUpdatedLink = {
sequenceGuid: 'seq-1',
sequenceName: 'Rough Cut',
assetId: 'asset-vid-1',
assetName: 'interview_clip.mp4',
syncedCommentIds: ['comm-1'],
lastSyncAt: Date.now(),
totalCommentsSynced: 1,
}
vi.spyOn(markersService, 'syncCommentsToSequence').mockResolvedValue({
updatedLink: mockUpdatedLink,
addedCount: 1,
})
await act(async () => {
render(
<LinkSequenceDialog
asset={videoAsset}
endpoint="https://api.shumai.test"
apiKey="test-key"
isOpen={true}
onClose={mockOnClose}
onLinkSuccess={mockOnLinkSuccess}
/>,
)
})
const linkBtn = screen.getByText('Link Sequence')
await act(async () => {
fireEvent.click(linkBtn)
})
expect(markersService.fetchAssetComments).toHaveBeenCalledWith(
'https://api.shumai.test',
'test-key',
'asset-vid-1',
)
expect(markersService.syncCommentsToSequence).toHaveBeenCalledWith(
mockProject,
mockSeq1,
expect.any(Array),
expect.objectContaining({
endpoint: 'https://api.shumai.test',
sequenceGuid: 'seq-1',
assetId: 'asset-vid-1',
}),
)
expect(mockOnLinkSuccess).toHaveBeenCalledWith(mockUpdatedLink, 1)
expect(mockOnClose).toHaveBeenCalled()
})
})
@@ -0,0 +1,420 @@
import React, { useState, useEffect, useCallback } from 'react'
import type { Sequence, Project } from '@adobe/premierepro'
import type { AssetSummary } from './FileItem'
import type { LinkedSequenceAsset } from '../types/link'
import { getActiveProject, getAllSequences, getActiveSequence } from '../services/premiere'
import { getAllLinkedSequences, normalizeGuid, removeSequenceLink } from '../services/linkStorage'
import { fetchAssetComments, syncCommentsToSequence } from '../services/markers'
import { resolveAssetUrl, isSameEndpoint } from '../utils/url'
import { formatBytes, formatDuration } from '../utils/format'
import { ProgressCircle } from '@swc-react/progress-circle'
export interface LinkSequenceDialogProps {
asset: AssetSummary | null
endpoint: string
apiKey: string
isOpen: boolean
onClose: () => void
onLinkSuccess: (link: LinkedSequenceAsset, addedMarkersCount: number) => void
}
interface SequenceOption {
sequence: Sequence
guid: string
name: string
isActive: boolean
currentLink: LinkedSequenceAsset | null
}
export const LinkSequenceDialog: React.FC<LinkSequenceDialogProps> = ({
asset,
endpoint,
apiKey,
isOpen,
onClose,
onLinkSuccess,
}) => {
const [project, setProject] = useState<Project | null>(null)
const [sequences, setSequences] = useState<SequenceOption[]>([])
const [selectedGuid, setSelectedGuid] = useState<string>('')
const [loadingSequences, setLoadingSequences] = useState(true)
const [linking, setLinking] = useState(false)
const [errorMessage, setErrorMessage] = useState<string | null>(null)
const [thumbError, setThumbError] = useState(false)
// Load project sequences and link states when opened
useEffect(() => {
if (!isOpen || !asset) {
setProject(null)
setSequences([])
setSelectedGuid('')
setErrorMessage(null)
setLinking(false)
setThumbError(false)
return
}
let isMounted = true
setLoadingSequences(true)
setErrorMessage(null)
async function loadProjectData() {
try {
const pr = await getActiveProject()
if (!isMounted) return
if (!pr) {
setProject(null)
setLoadingSequences(false)
setErrorMessage('No active Premiere Pro project found. Please open a project first.')
return
}
setProject(pr)
const [allSeqs, activeSeq, existingLinks] = await Promise.all([
getAllSequences(pr),
getActiveSequence(pr),
getAllLinkedSequences(pr),
])
if (!isMounted) return
if (!allSeqs || allSeqs.length === 0) {
setLoadingSequences(false)
setErrorMessage(
'No sequences found in the current project. Please create a sequence first.',
)
return
}
const activeGuid = normalizeGuid(activeSeq?.guid)
const linksMap = new Map<string, LinkedSequenceAsset>()
for (const link of existingLinks) {
if (!link.endpoint || isSameEndpoint(link.endpoint, endpoint)) {
linksMap.set(normalizeGuid(link.sequenceGuid), link)
}
}
const options: SequenceOption[] = allSeqs.map((seq) => {
const guidStr = normalizeGuid(seq.guid)
return {
sequence: seq,
guid: guidStr,
name: seq.name || 'Untitled Sequence',
isActive: Boolean(activeGuid && guidStr === activeGuid),
currentLink: linksMap.get(guidStr) || null,
}
})
setSequences(options)
// Pre-select active sequence if found, else first sequence
if (activeGuid && options.some((opt) => opt.guid === activeGuid)) {
setSelectedGuid(activeGuid)
} else if (options.length > 0) {
setSelectedGuid(options[0].guid)
}
} catch (err) {
if (!isMounted) return
console.error('[LinkSequenceDialog] Error loading project data:', err)
setErrorMessage('Failed to load project sequences from Premiere Pro.')
} finally {
if (isMounted) {
setLoadingSequences(false)
}
}
}
void loadProjectData()
return () => {
isMounted = false
}
}, [isOpen, asset, endpoint])
// Escape key handler
useEffect(() => {
if (!isOpen) return
const handleKeyDown = (e: KeyboardEvent) => {
if (e.key === 'Escape' && !linking) {
onClose()
}
}
document.addEventListener('keydown', handleKeyDown)
return () => {
document.removeEventListener('keydown', handleKeyDown)
}
}, [isOpen, linking, onClose])
const handleConfirm = useCallback(async () => {
if (!asset || !project || !selectedGuid || linking) return
const targetOption = sequences.find(
(opt) => normalizeGuid(opt.guid) === normalizeGuid(selectedGuid),
)
if (!targetOption) return
setLinking(true)
try {
// If sequence was linked to another asset, remove its previous link and markers first
if (targetOption.currentLink && targetOption.currentLink.assetId !== asset.id) {
await removeSequenceLink(project, targetOption.sequence)
}
// 1. Fetch timecoded comments for this asset
const comments = await fetchAssetComments(endpoint, apiKey, asset.id)
// 2. Prepare initial link metadata
const prGuidStr = project.guid ? normalizeGuid(project.guid) : undefined
const initialLink: LinkedSequenceAsset = {
sequenceGuid: normalizeGuid(targetOption.guid),
sequenceName: targetOption.name,
assetId: asset.id,
assetName: asset.name,
assetThumbnailUrl: asset.preview?.thumbnailUrl,
endpoint: endpoint.trim().replace(/\/+$/, ''),
projectId: prGuidStr,
syncedCommentIds:
targetOption.currentLink?.assetId === asset.id
? targetOption.currentLink.syncedCommentIds
: [],
syncedMarkerGuids:
targetOption.currentLink?.assetId === asset.id
? (targetOption.currentLink.syncedMarkerGuids || []).map(normalizeGuid)
: [],
lastSyncAt: Date.now(),
totalCommentsSynced:
targetOption.currentLink?.assetId === asset.id
? targetOption.currentLink.totalCommentsSynced
: 0,
}
// 3. Translate comments to markers on the sequence
const { updatedLink, addedCount } = await syncCommentsToSequence(
project,
targetOption.sequence,
comments,
initialLink,
)
onLinkSuccess(updatedLink, addedCount)
onClose()
} catch (err) {
console.error('[LinkSequenceDialog] Failed to link sequence:', err)
setErrorMessage('Failed to link sequence and sync markers. Please try again.')
} finally {
setLinking(false)
}
}, [asset, project, selectedGuid, linking, sequences, endpoint, apiKey, onLinkSuccess, onClose])
if (!isOpen || !asset) return null
const selectedOption = sequences.find((opt) => opt.guid === selectedGuid)
const isReplacingOtherAsset =
selectedOption?.currentLink && selectedOption.currentLink.assetId !== asset.id
const effectiveSize = asset.sizeByte ?? asset.size
const thumbUrl = resolveAssetUrl(asset.preview?.thumbnailUrl, endpoint)
const duration = asset.preview?.duration ?? asset.media?.metadata?.duration
const durationText = formatDuration(duration)
return (
<div
className="shumai-dialog-backdrop"
onClick={(e) => {
if (e.target === e.currentTarget && !linking) {
onClose()
}
}}
>
<div
className="shumai-dialog"
role="dialog"
aria-modal="true"
aria-labelledby="link-dialog-title"
>
{/* Header */}
<div className="shumai-dialog-header">
<div style={{ display: 'flex', alignItems: 'center' }}>
<sp-icon-link size="s" style={{ marginRight: 6, color: '#3b82f6' }}></sp-icon-link>
<span id="link-dialog-title" className="shumai-dialog-title">
Link to Sequence
</span>
</div>
<button
type="button"
className="shumai-dialog-close"
onClick={onClose}
disabled={linking}
title="Close dialog"
aria-label="Close dialog"
>
<sp-icon-close size="s"></sp-icon-close>
</button>
</div>
{/* Asset Info Card */}
<div className="shumai-dialog-asset-info">
<div className="shumai-dialog-thumb">
{thumbUrl && !thumbError ? (
<img src={thumbUrl} alt={asset.name} onError={() => setThumbError(true)} />
) : asset.type === 'video' ? (
<sp-icon-filmstrip size="xxl" style={{ color: '#60a5fa' }}></sp-icon-filmstrip>
) : asset.type === 'audio' ? (
<sp-icon-audio size="xxl" style={{ color: '#a78bfa' }}></sp-icon-audio>
) : (
<sp-icon-document size="xxl" style={{ color: '#999999' }}></sp-icon-document>
)}
</div>
<div className="shumai-dialog-asset-meta">
<span className="shumai-dialog-asset-name" title={asset.name}>
{asset.name}
</span>
<span className="shumai-dialog-asset-details">
{durationText ? `${durationText} • ` : ''}
{effectiveSize ? `${formatBytes(effectiveSize)} • ` : ''}
{asset.commentsCount != null && asset.commentsCount > 0
? `${asset.commentsCount} comments`
: 'No comments'}
</span>
</div>
</div>
{/* Dialog Body */}
<div className="shumai-dialog-body">
<div className="shumai-dialog-section-label">Select Sequence in Project</div>
{loadingSequences ? (
<div className="shumai-dialog-loading">
<ProgressCircle indeterminate size="s" label="Checking project sequences..." />
<span>Checking project sequences...</span>
</div>
) : errorMessage ? (
<div className="shumai-dialog-empty-proxies" style={{ color: '#f87171' }}>
<span>{errorMessage}</span>
</div>
) : sequences.length > 0 ? (
sequences.map((opt) => {
const isSelected = selectedGuid === opt.guid
const isLinkedToAnother = opt.currentLink && opt.currentLink.assetId !== asset.id
const isLinkedToThis = opt.currentLink && opt.currentLink.assetId === asset.id
return (
<div
key={opt.guid}
className={`shumai-option-card ${isSelected ? 'selected' : ''}`}
onClick={() => !linking && setSelectedGuid(opt.guid)}
role="radio"
aria-checked={isSelected}
tabIndex={0}
onKeyDown={(e) => {
if (e.key === 'Enter' || e.key === ' ') {
e.preventDefault()
if (!linking) setSelectedGuid(opt.guid)
}
}}
>
<div className="shumai-option-left">
<div className="shumai-option-texts">
<div style={{ display: 'flex', alignItems: 'center' }}>
<span className="shumai-option-title">{opt.name}</span>
{opt.isActive && (
<span
style={{
fontSize: '10px',
marginLeft: 6,
padding: '1px 5px',
borderRadius: '3px',
backgroundColor: 'rgba(59, 130, 246, 0.2)',
color: '#60a5fa',
fontWeight: 500,
}}
>
Active
</span>
)}
</div>
<span className="shumai-option-meta">
{isLinkedToThis ? (
<span style={{ color: '#34d399' }}>Already linked to this asset</span>
) : isLinkedToAnother ? (
<span style={{ color: '#fbbf24' }}>
Linked to &quot;{opt.currentLink?.assetName}&quot; (will replace)
</span>
) : (
'Ready to link'
)}
</span>
</div>
</div>
<div className="shumai-option-radio">
{isSelected && <div className="shumai-option-radio-dot" />}
</div>
</div>
)
})
) : (
<div className="shumai-dialog-empty-proxies">
<span>No sequences available in current project.</span>
</div>
)}
{isReplacingOtherAsset && (
<div
style={{
marginTop: 10,
padding: '8px 10px',
borderRadius: 4,
backgroundColor: 'rgba(245, 158, 11, 0.12)',
border: '1px solid rgba(245, 158, 11, 0.3)',
display: 'flex',
alignItems: 'center',
fontSize: 11,
color: '#fbbf24',
}}
>
<sp-icon-alert-triangle
size="s"
style={{ marginRight: 6, flexShrink: 0 }}
></sp-icon-alert-triangle>
<span>
This sequence is already linked to another asset. Proceeding will replace the link
and sync markers for this asset.
</span>
</div>
)}
<div style={{ marginTop: 12, fontSize: 11, color: 'var(--text-secondary)' }}>
Comments with timestamps will be placed on the sequence timeline as markers. Markers
deleted in Premiere Pro will not be re-synced.
</div>
</div>
{/* Footer */}
<div className="shumai-dialog-footer">
<sp-button quiet variant="secondary" size="s" onClick={onClose} disabled={linking}>
Cancel
</sp-button>
<sp-button
variant="accent"
size="s"
onClick={handleConfirm}
disabled={!selectedGuid || loadingSequences || Boolean(errorMessage) || linking}
>
{linking ? (
<>
<ProgressCircle indeterminate size="s" slot="icon" label="Linking..." />
Linking...
</>
) : isReplacingOtherAsset ? (
'Replace & Link'
) : (
'Link Sequence'
)}
</sp-button>
</div>
</div>
</div>
)
}
@@ -0,0 +1,33 @@
// @vitest-environment happy-dom
import React from 'react'
import { describe, it, expect, vi, afterEach } from 'vitest'
import { render, screen, fireEvent, cleanup } from '@testing-library/react'
import { NavigationTabs } from './NavigationTabs'
describe('NavigationTabs Component', () => {
afterEach(() => {
cleanup()
})
it('renders Sequences and Browse tabs with badge', () => {
const handleTabChange = vi.fn()
render(<NavigationTabs activeTab="sequences" onTabChange={handleTabChange} linkedCount={3} />)
expect(screen.getByText('Sequences')).toBeDefined()
expect(screen.getByText('Browse')).toBeDefined()
expect(screen.getByText('3')).toBeDefined()
})
it('handles tab click events', () => {
const handleTabChange = vi.fn()
render(<NavigationTabs activeTab="sequences" onTabChange={handleTabChange} linkedCount={0} />)
const browseTab = screen.getByText('Browse')
fireEvent.click(browseTab)
expect(handleTabChange).toHaveBeenCalledWith('browse')
const sequencesTab = screen.getByText('Sequences')
fireEvent.click(sequencesTab)
expect(handleTabChange).toHaveBeenCalledWith('sequences')
})
})
@@ -0,0 +1,44 @@
import React from 'react'
export type MainTab = 'sequences' | 'browse'
export interface NavigationTabsProps {
activeTab: MainTab
onTabChange: (tab: MainTab) => void
linkedCount?: number
}
export const NavigationTabs: React.FC<NavigationTabsProps> = ({
activeTab,
onTabChange,
linkedCount = 0,
}) => {
return (
<div className="shumai-nav-tabs-bar" role="tablist">
<sp-button
size="s"
variant={activeTab === 'sequences' ? 'accent' : 'secondary'}
treatment="fill"
onClick={() => onTabChange('sequences')}
className={`shumai-tab-sp-btn ${activeTab === 'sequences' ? 'active' : ''}`}
>
<span className="shumai-tab-label">Sequences</span>
{linkedCount > 0 && (
<span className="shumai-tab-badge" title={`${linkedCount} linked sequence assets`}>
{linkedCount}
</span>
)}
</sp-button>
<sp-button
size="s"
variant={activeTab === 'browse' ? 'accent' : 'secondary'}
treatment="fill"
onClick={() => onTabChange('browse')}
className={`shumai-tab-sp-btn ${activeTab === 'browse' ? 'active' : ''}`}
>
<span className="shumai-tab-label">Browse</span>
</sp-button>
</div>
)
}
@@ -0,0 +1,88 @@
import React, { useState } from 'react'
import { formatDateAgo } from '../utils/date'
import { resolveAssetUrl } from '../utils/url'
import type { ProjectSummary } from '../views/ProjectsView'
interface ProjectCardProps {
project: ProjectSummary
endpoint?: string
onClick: () => void
}
export const ShumaiPolygonCover: React.FC = () => (
<svg
xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 180.95 164.7"
preserveAspectRatio="xMidYMid slice"
style={{ width: '100%', height: '100%', display: 'block' }}
>
<polygon fill="#FC9F8E" points="0 18.5 0 76.0 151.69 164.7 180.95 164.7 180.95 113.6" />
<polygon fill="#FEBAB8" points="0 0 74.58 61.5 90.53 51.6 110.33 63.9 180.95 18.9 180.95 0" />
<polyline
fill="#FAA5A5"
points="0 18.5 74.58 61.5 90.53 51.6 110.33 63.9 180.95 18.9 180.95 0 0 0"
/>
<polygon fill="#EC5B6C" points="0 76.0 0 164.7 151.69 164.7" />
<polygon fill="#E85C71" points="180.95 18.9 110.33 63.9 117.37 68.0 117.26 73.4 180.95 113.6" />
<polygon
fill="#C8405B"
points="117.26 73.4 117.37 99.0 90.53 114.9 174.35 164.7 180.95 164.7 180.95 113.6"
/>
<polygon fill="#FFCCBE" points="90.53 51.6 63.69 68.1 90.53 83.4" />
<path
fill="#FB9991"
d="M 90.53 51.6 L 90.53 61.3 L 100.87 67.4 L 90.53 73.5 L 90.53 83.4 L 117.37 68.0 C 117.15 67.6 90.53 51.6 90.53 51.6 Z"
/>
<path
fill="#FFEACD"
d="M 63.69 68.1 C 63.47 68.5 64.02 99.3 64.02 99.3 C 64.02 99.3 64.46 99.6 64.9 99.9 L 90.53 83.4 L 63.69 68.1 Z"
/>
<polygon fill="#FFCFB5" points="64.02 99.3 90.53 114.9 90.53 83.4" />
<path fill="#F67D73" d="M 90.53 83.4 L 90.53 114.9 L 117.37 99.0 Z" />
<path fill="#F26560" d="M 90.53 83.4 L 117.37 99.0 L 117.37 68.0 Z" />
<polygon fill="#EB5F5B" points="80.08 67.5 90.53 73.5 90.53 61.3" />
<polygon fill="#DB4D50" points="90.53 61.3 90.53 73.5 100.87 67.4" />
</svg>
)
export const ProjectCard: React.FC<ProjectCardProps> = ({ project, endpoint, onClick }) => {
const [imgError, setImgError] = useState(false)
const updatedText = formatDateAgo(project.updatedAt)
const coverUrl = resolveAssetUrl(project.coverImage, endpoint)
return (
<div
className="project-row-card"
onClick={onClick}
role="button"
tabIndex={0}
title={project.name}
onKeyDown={(e) => {
if (e.key === 'Enter' || e.key === ' ') {
e.preventDefault()
onClick()
}
}}
>
<div className="project-row-preview">
{coverUrl && !imgError ? (
<img
src={coverUrl}
alt={project.name}
className="project-row-img"
onError={() => setImgError(true)}
/>
) : (
<ShumaiPolygonCover />
)}
</div>
<div className="project-row-content">
<span className="project-row-title">{project.name}</span>
<span className="project-row-subtext">
{updatedText ? `Updated ${updatedText}` : 'Project'}
</span>
</div>
</div>
)
}
@@ -0,0 +1,41 @@
import React from 'react'
export const ShumaiLogo: React.FC<React.SVGProps<SVGSVGElement>> = (props) => {
return (
<svg viewBox="0 0 100 100" fill="none" xmlns="http://www.w3.org/2000/svg" {...props}>
<defs>
<clipPath id="bg-clip">
<rect x="5" y="5" width="90" height="90" rx="22" />
</clipPath>
</defs>
{/* Background */}
<rect x="5" y="5" width="90" height="90" rx="22" fill="#D95A66" />
{/* Long Shadow */}
<path
d="M 35 75 L 65 75 L 80 60 L 75 30 L 175 130 L 135 175 Z"
fill="#A8384D"
clipPath="url(#bg-clip)"
/>
{/* Left Cream */}
<path d="M 25 30 Q 38 36 50 42 L 35 55 L 35 75 L 20 60 Z" fill="#FDF0D5" />
{/* Right Orange */}
<path d="M 50 42 Q 62 36 75 30 L 80 60 L 65 75 L 65 55 Z" fill="#E77A65" />
{/* Front Peach */}
<path d="M 35 75 L 65 75 L 65 55 L 50 42 L 35 55 Z" fill="#F5B895" />
{/* Top Pink */}
<path d="M 50 42 Q 38 36 25 30 Q 38 26 50 20 Q 62 26 75 30 Q 62 36 50 42 Z" fill="#F4B8B8" />
{/* Hole Left */}
<path d="M 50 25 L 42 30 L 50 35 Z" fill="#E57A5F" />
{/* Hole Right */}
<path d="M 50 25 L 58 30 L 50 35 Z" fill="#C2523C" />
</svg>
)
}
+299
View File
@@ -0,0 +1,299 @@
/* eslint-disable @typescript-eslint/naming-convention -- Custom element tag names in IntrinsicElements require hyphens */
declare module '@swc-uxp-wrappers/utils' {
export const aliases: Record<string, string>
}
type SpIconCustomElementProps = import('react').DetailedHTMLProps<
import('react').HTMLAttributes<HTMLElement>,
HTMLElement
> & {
size?: 'xxs' | 'xs' | 's' | 'm' | 'l' | 'xl' | 'xxl'
slot?: string
name?: string
label?: string
}
type SpButtonCustomElementProps = import('react').DetailedHTMLProps<
import('react').ButtonHTMLAttributes<HTMLButtonElement>,
HTMLButtonElement
> & {
variant?: 'accent' | 'primary' | 'secondary' | 'negative' | 'white' | 'black' | string
treatment?: 'fill' | 'outline' | string
quiet?: boolean
size?: 'xs' | 's' | 'm' | 'l' | 'xl'
label?: string
'icon-only'?: boolean
disabled?: boolean
slot?: string
}
type SpButtonGroupCustomElementProps = import('react').DetailedHTMLProps<
import('react').HTMLAttributes<HTMLElement>,
HTMLElement
> & {
vertical?: boolean
size?: 'xs' | 's' | 'm' | 'l' | 'xl'
}
type SpActionButtonCustomElementProps = import('react').DetailedHTMLProps<
import('react').ButtonHTMLAttributes<HTMLButtonElement>,
HTMLButtonElement
> & {
quiet?: boolean
size?: 'xs' | 's' | 'm' | 'l' | 'xl'
label?: string
disabled?: boolean
selected?: boolean
toggles?: boolean
emphasized?: boolean
slot?: string
}
type SpActionMenuCustomElementProps = import('react').DetailedHTMLProps<
import('react').HTMLAttributes<HTMLElement>,
HTMLElement
> & {
quiet?: boolean
size?: 'xs' | 's' | 'm' | 'l' | 'xl'
label?: string
disabled?: boolean
open?: boolean
placement?:
| 'top'
| 'top-start'
| 'top-end'
| 'right'
| 'right-start'
| 'right-end'
| 'bottom'
| 'bottom-start'
| 'bottom-end'
| 'left'
| 'left-start'
| 'left-end'
'force-popover'?: boolean
selects?: 'single'
value?: string
slot?: string
}
type SpMenuCustomElementProps = import('react').DetailedHTMLProps<
import('react').HTMLAttributes<HTMLElement>,
HTMLElement
> & {
slot?: string
selects?: 'single' | 'multiple' | 'inherit'
label?: string
}
type SpMenuItemCustomElementProps = import('react').DetailedHTMLProps<
import('react').HTMLAttributes<HTMLElement>,
HTMLElement
> & {
disabled?: boolean
selected?: boolean
value?: string
slot?: string
}
type SpMenuDividerCustomElementProps = import('react').DetailedHTMLProps<
import('react').HTMLAttributes<HTMLElement>,
HTMLElement
> & {
size?: 's' | 'm' | 'l'
}
type SpMenuGroupCustomElementProps = import('react').DetailedHTMLProps<
import('react').HTMLAttributes<HTMLElement>,
HTMLElement
> & {
slot?: string
}
type SpStatusLightCustomElementProps = import('react').DetailedHTMLProps<
import('react').HTMLAttributes<HTMLElement>,
HTMLElement
> & {
variant?:
| 'negative'
| 'notice'
| 'positive'
| 'info'
| 'neutral'
| 'yellow'
| 'fuchsia'
| 'indigo'
| 'seafoam'
| 'chartreuse'
| 'magenta'
| 'celery'
| 'purple'
| string
disabled?: boolean
slot?: string
}
type SpProgressCircleCustomElementProps = import('react').DetailedHTMLProps<
import('react').HTMLAttributes<HTMLElement>,
HTMLElement
> & {
size?: 's' | 'm' | 'l'
indeterminate?: boolean
label?: string
slot?: string
'static-color'?: 'white' | string
}
type SpTopNavCustomElementProps = import('react').DetailedHTMLProps<
import('react').HTMLAttributes<HTMLElement>,
HTMLElement
> & {
selected?: string
quiet?: boolean
compact?: boolean
label?: string
}
type SpTopNavItemCustomElementProps = import('react').DetailedHTMLProps<
import('react').HTMLAttributes<HTMLElement>,
HTMLElement
> & {
value?: string
selected?: boolean
href?: string
disabled?: boolean
}
declare namespace React {
namespace JSX {
interface IntrinsicElements {
'sp-icon': SpIconCustomElementProps
'sp-icon-refresh': SpIconCustomElementProps
'sp-icon-chevron-down': SpIconCustomElementProps
'sp-icon-chevron-right': SpIconCustomElementProps
'sp-icon-log-out': SpIconCustomElementProps
'sp-icon-arrow-right': SpIconCustomElementProps
'sp-icon-filmstrip': SpIconCustomElementProps
'sp-icon-folder': SpIconCustomElementProps
'sp-icon-folder-open': SpIconCustomElementProps
'sp-icon-audio': SpIconCustomElementProps
'sp-icon-image': SpIconCustomElementProps
'sp-icon-document': SpIconCustomElementProps
'sp-icon-link': SpIconCustomElementProps
'sp-icon-unlink': SpIconCustomElementProps
'sp-icon-link-out': SpIconCustomElementProps
'sp-icon-download': SpIconCustomElementProps
'sp-icon-briefcase': SpIconCustomElementProps
'sp-icon-alert-circle': SpIconCustomElementProps
'sp-icon-alert-triangle': SpIconCustomElementProps
'sp-icon-checkmark-circle': SpIconCustomElementProps
'sp-icon-close': SpIconCustomElementProps
'sp-icon-movie-camera': SpIconCustomElementProps
'sp-icon-video-filled': SpIconCustomElementProps
'sp-button': SpButtonCustomElementProps
'sp-button-group': SpButtonGroupCustomElementProps
'sp-action-button': SpActionButtonCustomElementProps
'sp-action-menu': SpActionMenuCustomElementProps
'sp-menu': SpMenuCustomElementProps
'sp-menu-item': SpMenuItemCustomElementProps
'sp-menu-divider': SpMenuDividerCustomElementProps
'sp-menu-group': SpMenuGroupCustomElementProps
'sp-status-light': SpStatusLightCustomElementProps
'sp-progress-circle': SpProgressCircleCustomElementProps
'sp-top-nav': SpTopNavCustomElementProps
'sp-top-nav-item': SpTopNavItemCustomElementProps
}
}
}
declare namespace JSX {
interface IntrinsicElements {
'sp-icon': SpIconCustomElementProps
'sp-icon-refresh': SpIconCustomElementProps
'sp-icon-chevron-down': SpIconCustomElementProps
'sp-icon-chevron-right': SpIconCustomElementProps
'sp-icon-log-out': SpIconCustomElementProps
'sp-icon-arrow-right': SpIconCustomElementProps
'sp-icon-filmstrip': SpIconCustomElementProps
'sp-icon-folder': SpIconCustomElementProps
'sp-icon-folder-open': SpIconCustomElementProps
'sp-icon-audio': SpIconCustomElementProps
'sp-icon-image': SpIconCustomElementProps
'sp-icon-document': SpIconCustomElementProps
'sp-icon-link': SpIconCustomElementProps
'sp-icon-unlink': SpIconCustomElementProps
'sp-icon-link-out': SpIconCustomElementProps
'sp-icon-download': SpIconCustomElementProps
'sp-icon-briefcase': SpIconCustomElementProps
'sp-icon-alert-circle': SpIconCustomElementProps
'sp-icon-alert-triangle': SpIconCustomElementProps
'sp-icon-checkmark-circle': SpIconCustomElementProps
'sp-icon-close': SpIconCustomElementProps
'sp-icon-movie-camera': SpIconCustomElementProps
'sp-icon-video-filled': SpIconCustomElementProps
'sp-button': SpButtonCustomElementProps
'sp-button-group': SpButtonGroupCustomElementProps
'sp-action-button': SpActionButtonCustomElementProps
'sp-action-menu': SpActionMenuCustomElementProps
'sp-menu': SpMenuCustomElementProps
'sp-menu-item': SpMenuItemCustomElementProps
'sp-menu-divider': SpMenuDividerCustomElementProps
'sp-menu-group': SpMenuGroupCustomElementProps
'sp-status-light': SpStatusLightCustomElementProps
'sp-progress-circle': SpProgressCircleCustomElementProps
'sp-top-nav': SpTopNavCustomElementProps
'sp-top-nav-item': SpTopNavItemCustomElementProps
}
}
type UxpEntry = UxpFileEntry | UxpFolderEntry
interface UxpFileEntry {
readonly isFile: true
readonly isFolder: false
readonly name: string
readonly nativePath: string
write(data: ArrayBuffer | string, options?: { format?: unknown; append?: boolean }): Promise<void>
}
interface UxpFolderEntry {
readonly isFile: false
readonly isFolder: true
readonly name: string
readonly nativePath: string
createFile(name: string, options?: { overwrite?: boolean }): Promise<UxpFileEntry>
getEntries(): Promise<UxpEntry[]>
getFiles?(): Promise<UxpFileEntry[]>
}
interface UxpLocalFileSystem {
getFileForSaving(
defaultName?: string,
options?: { types?: string[] },
): Promise<UxpFileEntry | null>
getFileForOpening(options?: {
allowMultiple?: boolean
types?: string[]
}): Promise<UxpFileEntry | UxpFileEntry[] | null>
getFolder(): Promise<UxpFolderEntry | null>
getTemporaryFolder(): Promise<UxpFolderEntry>
getDataFolder(): Promise<UxpFolderEntry>
getPluginFolder(): Promise<UxpFolderEntry>
}
interface UxpStorageFormats {
readonly binary: unknown
readonly utf8: unknown
}
interface UxpModule {
storage: {
localFileSystem: UxpLocalFileSystem
formats: UxpStorageFormats
}
}
declare module 'uxp' {
const uxp: UxpModule
export = uxp
}
+52
View File
@@ -0,0 +1,52 @@
import './polyfills'
import React from 'react'
import { createRoot } from 'react-dom/client'
import { Theme } from '@swc-react/theme'
import '@spectrum-web-components/theme/theme-dark.js'
import '@spectrum-web-components/theme/theme-darkest.js'
import '@spectrum-web-components/theme/theme-light.js'
import '@spectrum-web-components/theme/scale-medium.js'
import '@swc-uxp-wrappers/button/sp-button.js'
import '@swc-uxp-wrappers/action-button/sp-action-button.js'
import '@swc-uxp-wrappers/menu/sp-menu.js'
import '@swc-uxp-wrappers/menu/sp-menu-item.js'
import '@swc-uxp-wrappers/menu/sp-menu-divider.js'
import '@swc-uxp-wrappers/menu/sp-menu-group.js'
import '@swc-uxp-wrappers/popover/sp-popover.js'
import '@spectrum-web-components/icons-workflow/icons/sp-icon-refresh.js'
import '@spectrum-web-components/icons-workflow/icons/sp-icon-chevron-down.js'
import '@spectrum-web-components/icons-workflow/icons/sp-icon-chevron-right.js'
import '@spectrum-web-components/icons-workflow/icons/sp-icon-log-out.js'
import '@spectrum-web-components/icons-workflow/icons/sp-icon-arrow-right.js'
import '@spectrum-web-components/icons-workflow/icons/sp-icon-filmstrip.js'
import '@spectrum-web-components/icons-workflow/icons/sp-icon-folder.js'
import '@spectrum-web-components/icons-workflow/icons/sp-icon-folder-open.js'
import '@spectrum-web-components/icons-workflow/icons/sp-icon-audio.js'
import '@spectrum-web-components/icons-workflow/icons/sp-icon-image.js'
import '@spectrum-web-components/icons-workflow/icons/sp-icon-document.js'
import '@spectrum-web-components/icons-workflow/icons/sp-icon-link.js'
import '@spectrum-web-components/icons-workflow/icons/sp-icon-unlink.js'
import '@spectrum-web-components/icons-workflow/icons/sp-icon-link-out.js'
import '@spectrum-web-components/icons-workflow/icons/sp-icon-download.js'
import '@spectrum-web-components/icons-workflow/icons/sp-icon-briefcase.js'
import '@spectrum-web-components/icons-workflow/icons/sp-icon-alert-circle.js'
import '@spectrum-web-components/icons-workflow/icons/sp-icon-alert-triangle.js'
import '@spectrum-web-components/icons-workflow/icons/sp-icon-checkmark-circle.js'
import '@spectrum-web-components/icons-workflow/icons/sp-icon-close.js'
import '@spectrum-web-components/icons-workflow/icons/sp-icon-movie-camera.js'
import '@spectrum-web-components/icons-workflow/icons/sp-icon-video-filled.js'
import { App } from './App'
const container = document.getElementById('root')
if (container) {
const root = createRoot(container)
root.render(
<React.StrictMode>
<Theme theme="spectrum" scale="medium" color="dark">
<App />
</Theme>
</React.StrictMode>,
)
} else {
console.error('Failed to find root container element')
}
+12
View File
@@ -0,0 +1,12 @@
// @vitest-environment happy-dom
import { describe, it, expect } from 'vitest'
import './polyfills'
describe('polyfills', () => {
it('defines window.matchMedia polyfill when missing', () => {
expect(typeof window.matchMedia).toBe('function')
const mql = window.matchMedia('(prefers-color-scheme: dark)')
expect(mql).toBeDefined()
expect(mql.matches).toBe(false)
})
})
+31
View File
@@ -0,0 +1,31 @@
// Guard against duplicate custom element registrations during UXP development and plugin reload
if (typeof window !== 'undefined' && window.customElements) {
const origDefine = window.customElements.define.bind(window.customElements)
window.customElements.define = (
name: string,
constructor: CustomElementConstructor,
options?: ElementDefinitionOptions,
) => {
if (window.customElements.get(name)) {
return
}
origDefine(name, constructor, options)
}
}
// Polyfill window.matchMedia for Adobe UXP environment
if (typeof window !== 'undefined' && typeof window.matchMedia !== 'function') {
window.matchMedia = (query: string): MediaQueryList => {
const mql: MediaQueryList = {
matches: false,
media: query,
onchange: null,
addListener: () => {},
removeListener: () => {},
addEventListener: () => {},
removeEventListener: () => {},
dispatchEvent: () => false,
}
return mql
}
}
@@ -0,0 +1,182 @@
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
import { autoSyncService } from './autoSyncService'
import type { Project, Sequence } from '@adobe/premierepro'
import type { CommentInfo } from '@shumai/dtos'
import * as premiereService from './premiere'
import * as linkStorage from './linkStorage'
import * as markersService from './markers'
describe('autoSyncService', () => {
beforeEach(() => {
vi.useFakeTimers()
vi.restoreAllMocks()
autoSyncService.stop()
})
afterEach(() => {
autoSyncService.stop()
vi.useRealTimers()
})
it('starts and stops background interval without throwing', () => {
autoSyncService.start('https://api.shumai.test', 'test-key')
expect(autoSyncService['timer']).not.toBeNull()
autoSyncService.stop()
expect(autoSyncService['timer']).toBeNull()
})
it('syncs all linked sequences on triggerImmediateSync', async () => {
const mockSeq = { guid: 'seq-1', name: 'Seq 1' }
const mockProject = { guid: 'proj-1' }
const mockLink = {
sequenceGuid: 'seq-1',
sequenceName: 'Seq 1',
assetId: 'asset-1',
assetName: 'video.mp4',
syncedCommentIds: [],
lastSyncAt: 0,
totalCommentsSynced: 0,
}
vi.spyOn(premiereService, 'getActiveProject').mockResolvedValue(
mockProject as unknown as Project,
)
vi.spyOn(premiereService, 'getAllSequences').mockResolvedValue([mockSeq as unknown as Sequence])
vi.spyOn(linkStorage, 'getAllLinkedSequences').mockResolvedValue([mockLink])
vi.spyOn(markersService, 'fetchAssetComments').mockResolvedValue([
{ id: 'comm-1', second: 5, message: 'hello' } as unknown as CommentInfo,
])
vi.spyOn(markersService, 'syncCommentsToSequence').mockResolvedValue({
updatedLink: { ...mockLink, syncedCommentIds: ['comm-1'] },
addedCount: 1,
})
autoSyncService.start('https://api.shumai.test', 'test-key')
await autoSyncService.triggerImmediateSync()
expect(markersService.fetchAssetComments).toHaveBeenCalledWith(
'https://api.shumai.test',
'test-key',
'asset-1',
)
expect(markersService.syncCommentsToSequence).toHaveBeenCalled()
})
it('normalizes sequence GUIDs with braces and uppercase when matching against linked sequences', async () => {
const mockSeq = { guid: '{B991F605-7BD7-4028-B05F-0BC36B66CD0A}', name: 'Seq Braced' }
const mockProject = { guid: 'proj-1' }
const mockLink = {
sequenceGuid: 'b991f605-7bd7-4028-b05f-0bc36b66cd0a',
sequenceName: 'Seq Braced',
assetId: 'asset-99',
assetName: 'video.mp4',
syncedCommentIds: [],
lastSyncAt: 0,
totalCommentsSynced: 0,
}
vi.spyOn(premiereService, 'getActiveProject').mockResolvedValue(
mockProject as unknown as Project,
)
vi.spyOn(premiereService, 'getAllSequences').mockResolvedValue([mockSeq as unknown as Sequence])
vi.spyOn(linkStorage, 'getAllLinkedSequences').mockResolvedValue([mockLink])
vi.spyOn(markersService, 'fetchAssetComments').mockResolvedValue([
{ id: 'comm-1', second: 1, message: 'braced guid comment' } as unknown as CommentInfo,
])
vi.spyOn(markersService, 'syncCommentsToSequence').mockResolvedValue({
updatedLink: { ...mockLink, syncedCommentIds: ['comm-1'] },
addedCount: 1,
})
autoSyncService.start('https://api.shumai.test', 'test-key')
await autoSyncService.triggerImmediateSync()
expect(markersService.fetchAssetComments).toHaveBeenCalledWith(
'https://api.shumai.test',
'test-key',
'asset-99',
)
expect(markersService.syncCommentsToSequence).toHaveBeenCalledWith(
mockProject,
mockSeq,
expect.any(Array),
mockLink,
)
})
it('skips linked sequences configured for a different server endpoint', async () => {
const mockSeq1 = { guid: 'seq-foreign', name: 'Seq Foreign' }
const mockSeq2 = { guid: 'seq-local', name: 'Seq Local' }
const mockProject = { guid: 'proj-1' }
const foreignLink = {
sequenceGuid: 'seq-foreign',
sequenceName: 'Seq Foreign',
assetId: 'asset-foreign',
assetName: 'foreign.mp4',
endpoint: 'http://localhost:3000',
syncedCommentIds: [],
lastSyncAt: 0,
totalCommentsSynced: 0,
}
const sameLink = {
sequenceGuid: 'seq-local',
sequenceName: 'Seq Local',
assetId: 'asset-local',
assetName: 'local.mp4',
endpoint: 'https://staging.shumai.one/', // trailing slash variation
syncedCommentIds: [],
lastSyncAt: 0,
totalCommentsSynced: 0,
}
vi.spyOn(premiereService, 'getActiveProject').mockResolvedValue(
mockProject as unknown as Project,
)
vi.spyOn(premiereService, 'getAllSequences').mockResolvedValue([
mockSeq1 as unknown as Sequence,
mockSeq2 as unknown as Sequence,
])
vi.spyOn(linkStorage, 'getAllLinkedSequences').mockResolvedValue([foreignLink, sameLink])
vi.spyOn(markersService, 'fetchAssetComments').mockResolvedValue([
{ id: 'comm-1', second: 2, message: 'comment' } as unknown as CommentInfo,
])
vi.spyOn(markersService, 'syncCommentsToSequence').mockResolvedValue({
updatedLink: { ...sameLink, syncedCommentIds: ['comm-1'] },
addedCount: 1,
})
autoSyncService.start('https://staging.shumai.one', 'test-key')
await autoSyncService.triggerImmediateSync()
// Foreign link should be skipped
expect(markersService.fetchAssetComments).not.toHaveBeenCalledWith(
expect.anything(),
expect.anything(),
'asset-foreign',
)
// Matching link should be synced
expect(markersService.fetchAssetComments).toHaveBeenCalledWith(
'https://staging.shumai.one',
'test-key',
'asset-local',
)
expect(markersService.syncCommentsToSequence).toHaveBeenCalledWith(
mockProject,
mockSeq2,
expect.any(Array),
sameLink,
)
})
it('aborts syncing when stop() is called and credentials are reset', async () => {
const fetchSpy = vi.spyOn(markersService, 'fetchAssetComments')
autoSyncService.start('https://api.shumai.test', 'test-key')
autoSyncService.stop()
await autoSyncService.triggerImmediateSync()
expect(fetchSpy).not.toHaveBeenCalled()
})
})
@@ -0,0 +1,175 @@
import type { Sequence } from '@adobe/premierepro'
import { getActiveProject, getAllSequences, getPremiereModule } from './premiere'
import { getAllLinkedSequences, normalizeGuid } from './linkStorage'
import { fetchAssetComments, syncCommentsToSequence } from './markers'
import { isSameEndpoint } from '../utils/url'
const SYNC_INTERVAL_MS = 12000 // 12 seconds
class AutoSyncService {
private timer: ReturnType<typeof setInterval> | null = null
private endpoint = ''
private apiKey = ''
private cleanupListeners: (() => void) | null = null
private syncPromise: Promise<void> | null = null
/**
* Starts the background auto-sync loop.
*/
start(endpoint: string, apiKey: string): void {
this.stop()
this.endpoint = endpoint
this.apiKey = apiKey
if (!endpoint || !apiKey) return
// Setup background interval
this.timer = setInterval(() => {
void this.syncAllLinkedSequences()
}, SYNC_INTERVAL_MS)
// Setup host and window event listeners
this.setupListeners()
}
/**
* Stops the background auto-sync loop and tears down listeners.
*/
stop(): void {
if (this.timer) {
clearInterval(this.timer)
this.timer = null
}
if (this.cleanupListeners) {
this.cleanupListeners()
this.cleanupListeners = null
}
this.endpoint = ''
this.apiKey = ''
this.syncPromise = null
}
/**
* Forces an immediate synchronization cycle.
*/
async triggerImmediateSync(): Promise<void> {
if (this.syncPromise) {
await this.syncPromise
}
await this.syncAllLinkedSequences()
}
private setupListeners(): void {
const onFocus = () => {
void this.triggerImmediateSync()
}
const onVisibilityChange = () => {
if (typeof document !== 'undefined' && document.visibilityState === 'visible') {
void this.triggerImmediateSync()
}
}
if (typeof window !== 'undefined') {
window.addEventListener('focus', onFocus)
}
if (typeof document !== 'undefined') {
document.addEventListener('visibilitychange', onVisibilityChange)
}
// Premiere Pro Sequence Activated listener
const ppro = getPremiereModule()
let hasSeqListener = false
const onSequenceActivated = () => {
void this.triggerImmediateSync()
}
if (ppro?.EventManager && ppro.Constants?.SequenceEvent?.ACTIVATED) {
try {
ppro.EventManager.addGlobalEventListener(
ppro.Constants.SequenceEvent.ACTIVATED,
onSequenceActivated,
)
hasSeqListener = true
} catch (err) {
console.warn('[autoSyncService] Could not register SequenceEvent listener:', err)
}
}
this.cleanupListeners = () => {
if (typeof window !== 'undefined') {
window.removeEventListener('focus', onFocus)
}
if (typeof document !== 'undefined') {
document.removeEventListener('visibilitychange', onVisibilityChange)
}
if (hasSeqListener && ppro?.EventManager && ppro.Constants?.SequenceEvent?.ACTIVATED) {
try {
ppro.EventManager.removeGlobalEventListener(
ppro.Constants.SequenceEvent.ACTIVATED,
onSequenceActivated,
)
} catch {
// Ignore error during cleanup
}
}
}
}
private async syncAllLinkedSequences(): Promise<void> {
if (this.syncPromise) {
return this.syncPromise
}
const currentEndpoint = this.endpoint
const currentApiKey = this.apiKey
if (!currentEndpoint || !currentApiKey) return
this.syncPromise = (async () => {
try {
const project = await getActiveProject()
if (!project || this.endpoint !== currentEndpoint || this.apiKey !== currentApiKey) return
const allSeqs = await getAllSequences(project)
if (!allSeqs || allSeqs.length === 0 || this.endpoint !== currentEndpoint) return
const linkedItems = await getAllLinkedSequences(project, allSeqs)
if (!linkedItems || linkedItems.length === 0 || this.endpoint !== currentEndpoint) return
const seqsMap = new Map<string, Sequence>()
for (const s of allSeqs) {
const normGuid = normalizeGuid(s.guid)
if (normGuid) {
seqsMap.set(normGuid, s)
}
}
for (const link of linkedItems) {
if (this.endpoint !== currentEndpoint || this.apiKey !== currentApiKey) break
// Skip links created against a different server endpoint
if (link.endpoint && !isSameEndpoint(link.endpoint, currentEndpoint)) {
continue
}
const targetSeq = seqsMap.get(normalizeGuid(link.sequenceGuid))
if (!targetSeq) continue
try {
const comments = await fetchAssetComments(currentEndpoint, currentApiKey, link.assetId)
if (this.endpoint !== currentEndpoint) break
await syncCommentsToSequence(project, targetSeq, comments, link)
} catch (itemErr) {
console.error(`[autoSyncService] Error syncing sequence ${link.sequenceName}:`, itemErr)
}
}
} catch (err) {
console.error('[autoSyncService] Sync cycle failed:', err)
} finally {
this.syncPromise = null
}
})()
return this.syncPromise
}
}
export const autoSyncService = new AutoSyncService()
@@ -0,0 +1,124 @@
import { describe, it, expect, vi, beforeEach } from 'vitest'
import { fetchAssetComments, formatCommentBody } from './commentUtils'
import * as clientModule from '../api/client'
import type { CommentInfo } from '@shumai/dtos'
describe('commentUtils', () => {
beforeEach(() => {
vi.restoreAllMocks()
})
describe('fetchAssetComments', () => {
it('returns comments array when response is ok', async () => {
const mockComments: Partial<CommentInfo>[] = [
{ id: 'c1', message: 'First comment', second: 12 },
{ id: 'c2', message: 'Second comment', second: 45 },
]
const mockGet = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({ data: mockComments }),
})
vi.spyOn(clientModule, 'getShumaiClient').mockReturnValue({
api: {
files: {
':fileId': {
comments: {
$get: mockGet,
},
},
},
},
// eslint-disable-next-line @typescript-eslint/no-explicit-any
} as any)
const result = await fetchAssetComments('https://api.shumai.test', 'test-key', 'asset-1')
expect(mockGet).toHaveBeenCalledWith({
param: { fileId: 'asset-1' },
query: { first: '100' },
})
expect(result).toEqual(mockComments)
})
it('throws error with message from server response when res.ok is false', async () => {
const mockGet = vi.fn().mockResolvedValue({
ok: false,
status: 404,
json: async () => ({ error: 'Asset not found on this server' }),
})
vi.spyOn(clientModule, 'getShumaiClient').mockReturnValue({
api: {
files: {
':fileId': {
comments: {
$get: mockGet,
},
},
},
},
// eslint-disable-next-line @typescript-eslint/no-explicit-any
} as any)
await expect(
fetchAssetComments('https://api.shumai.test', 'test-key', 'asset-missing'),
).rejects.toThrow('Asset not found on this server')
})
it('throws fallback HTTP status error when res.ok is false and response has no error field', async () => {
const mockGet = vi.fn().mockResolvedValue({
ok: false,
status: 500,
json: async () => {
throw new Error('Invalid JSON')
},
})
vi.spyOn(clientModule, 'getShumaiClient').mockReturnValue({
api: {
files: {
':fileId': {
comments: {
$get: mockGet,
},
},
},
},
// eslint-disable-next-line @typescript-eslint/no-explicit-any
} as any)
await expect(
fetchAssetComments('https://api.shumai.test', 'test-key', 'asset-crash'),
).rejects.toThrow('Failed to fetch comments (HTTP 500)')
})
})
describe('formatCommentBody', () => {
it('formats single comment without replies', () => {
const comment = {
message: 'Review cut at 01:23',
replies: [],
} as unknown as CommentInfo
expect(formatCommentBody(comment)).toBe('Review cut at 01:23')
})
it('formats comment with nested replies and authors', () => {
const comment = {
message: 'Needs color correction',
replies: [
{ creator: { name: 'Alice' }, message: 'Applied LUT' },
{ creator: { name: 'Bob' }, message: 'Looks better' },
],
} as unknown as CommentInfo
const result = formatCommentBody(comment)
expect(result).toContain('Needs color correction')
expect(result).toContain('--- Replies ---')
expect(result).toContain('Alice: Applied LUT')
expect(result).toContain('Bob: Looks better')
})
})
})
@@ -0,0 +1,43 @@
import type { CommentInfo } from '@shumai/dtos'
import { getShumaiClient } from '../api/client'
/**
* Fetches timecoded comments for an asset from Shumai.
*/
export async function fetchAssetComments(
endpoint: string,
apiKey: string,
assetId: string,
): Promise<CommentInfo[]> {
const client = getShumaiClient(endpoint, apiKey)
const res = await client.api.files[':fileId'].comments.$get({
param: { fileId: assetId },
query: { first: '100' },
})
if (!res.ok) {
const errData = (await res.json().catch(() => ({}))) as { error?: string }
throw new Error(errData.error || `Failed to fetch comments (HTTP ${res.status})`)
}
const data = await res.json()
return (data?.data as CommentInfo[]) || []
}
/**
* Formats a Shumai comment into marker text including any threaded replies.
*/
export function formatCommentBody(comment: CommentInfo): string {
let body = comment.message || ''
if (comment.replies && comment.replies.length > 0) {
body += '\n\n--- Replies ---'
for (const reply of comment.replies) {
const author = reply.creator?.name || 'User'
const replyMsg = reply.message || ''
body += `\n${author}: ${replyMsg}`
}
}
return body
}
@@ -0,0 +1,619 @@
import { describe, it, expect, vi, beforeEach } from 'vitest'
import {
formatResolutionLabel,
getResolutionRank,
resolveRawDownloadUrl,
fetchVideoProxies,
getUniqueFileName,
getFolderEntryNames,
createUniqueFileInFolder,
importAssetIntoPremiere,
} from './import'
import * as premiereModule from './premiere'
import * as clientModule from '../api/client'
import type { AssetSummary } from '../components/FileItem'
describe('import service', () => {
beforeEach(() => {
vi.restoreAllMocks()
})
describe('formatResolutionLabel', () => {
it('formats given resolution strings', () => {
expect(formatResolutionLabel(undefined, undefined, '1080p')).toBe('1080p (MP4)')
expect(formatResolutionLabel(undefined, undefined, '720')).toBe('720p (MP4)')
})
it('formats given height numbers', () => {
expect(formatResolutionLabel(1920, 1080)).toBe('1080p (MP4)')
expect(formatResolutionLabel(1280, 720)).toBe('720p (MP4)')
})
it('formats by width if height is missing', () => {
expect(formatResolutionLabel(1920, undefined)).toBe('1080p (MP4)')
expect(formatResolutionLabel(1280, undefined)).toBe('720p (MP4)')
expect(formatResolutionLabel(3840, undefined)).toBe('2160p (MP4)')
})
it('falls back to Proxy (MP4)', () => {
expect(formatResolutionLabel(undefined, undefined)).toBe('Proxy (MP4)')
})
})
describe('getResolutionRank', () => {
it('extracts resolution numeric rank', () => {
expect(getResolutionRank('1080p (MP4)')).toBe(1080)
expect(getResolutionRank('720p (MP4)')).toBe(720)
expect(getResolutionRank('Proxy (MP4)')).toBe(0)
})
})
describe('resolveRawDownloadUrl', () => {
it('resolves directly via download-url when original key is in knownAsset', async () => {
const mockDownloadUrlPost = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({ url: 'https://s3.example.com/direct-raw.mp4' }),
})
vi.spyOn(clientModule, 'getShumaiClient').mockReturnValue({
api: {
files: {
'download-url': {
$post: mockDownloadUrlPost,
},
},
},
// eslint-disable-next-line @typescript-eslint/no-explicit-any
} as any)
const knownAsset: AssetSummary = {
id: 'file-1',
name: 'direct-raw.mp4',
type: 'file',
media: {
original: {
key: 'files/test/direct-raw.mp4',
},
},
}
const result = await resolveRawDownloadUrl('http://test', 'key', 'file-1', knownAsset)
expect(result.url).toBe('https://s3.example.com/direct-raw.mp4')
expect(result.name).toBe('direct-raw.mp4')
expect(mockDownloadUrlPost).toHaveBeenCalledWith({
json: { key: 'files/test/direct-raw.mp4', assetId: 'file-1' },
})
})
it('resolves via GET :fileId and download-url when not in knownAsset', async () => {
const mockGet = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({
id: 'file-1',
name: 'remote-video.mp4',
media: {
original: {
key: 'files/remote/video.mp4',
},
},
}),
})
const mockDownloadUrlPost = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({ url: 'https://s3.example.com/presigned-remote.mp4' }),
})
vi.spyOn(clientModule, 'getShumaiClient').mockReturnValue({
api: {
files: {
':fileId': {
$get: mockGet,
},
'download-url': {
$post: mockDownloadUrlPost,
},
},
},
// eslint-disable-next-line @typescript-eslint/no-explicit-any
} as any)
const result = await resolveRawDownloadUrl('http://test', 'key', 'file-1')
expect(result.url).toBe('https://s3.example.com/presigned-remote.mp4')
expect(result.name).toBe('remote-video.mp4')
expect(mockGet).toHaveBeenCalledWith({ param: { fileId: 'file-1' } })
expect(mockDownloadUrlPost).toHaveBeenCalledWith({
json: { key: 'files/remote/video.mp4', assetId: 'file-1' },
})
})
it('falls back to download-links endpoint when download-url is unavailable', async () => {
const mockPost = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({
files: [{ id: 'file-1', name: 'video.mov', url: 'https://s3.example.com/video.mov' }],
}),
})
vi.spyOn(clientModule, 'getShumaiClient').mockReturnValue({
api: {
files: {
'download-links': {
$post: mockPost,
},
},
},
// Partial mock of Hono client for unit test isolation
// eslint-disable-next-line @typescript-eslint/no-explicit-any
} as any)
const result = await resolveRawDownloadUrl('http://test', 'key', 'file-1')
expect(result.url).toBe('https://s3.example.com/video.mov')
expect(result.name).toBe('video.mov')
expect(mockPost).toHaveBeenCalledWith({ json: { ids: ['file-1'] } })
})
it('throws error when all resolution methods fail', async () => {
vi.spyOn(clientModule, 'getShumaiClient').mockReturnValue({
api: {
files: {
'download-links': {
$post: vi.fn().mockResolvedValue({
ok: false,
status: 500,
json: async () => ({ error: 'Server error' }),
}),
},
},
},
// Partial mock of Hono client for unit test isolation
// eslint-disable-next-line @typescript-eslint/no-explicit-any
} as any)
await expect(resolveRawDownloadUrl('http://test', 'key', 'file-1')).rejects.toThrow(
'Server error',
)
})
})
describe('fetchVideoProxies', () => {
it('returns available proxies sorted descending', async () => {
const mockGet = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({
id: 'file-1',
media: {
videoTranscodes: [
{
id: 't-720',
key: 'files/720.mp4',
url: 'https://s3.example.com/720.mp4',
width: 1280,
height: 720,
},
{
id: 't-1080',
key: 'files/1080.mp4',
url: 'https://s3.example.com/1080.mp4',
width: 1920,
height: 1080,
},
],
},
}),
})
vi.spyOn(clientModule, 'getShumaiClient').mockReturnValue({
api: {
files: {
':fileId': {
$get: mockGet,
},
},
},
// Partial mock of Hono client for unit test isolation
// eslint-disable-next-line @typescript-eslint/no-explicit-any
} as any)
const proxies = await fetchVideoProxies('http://test', 'key', 'file-1')
expect(proxies).toHaveLength(2)
// Highest resolution first
expect(proxies[0].label).toBe('1080p (MP4)')
expect(proxies[1].label).toBe('720p (MP4)')
})
})
describe('getUniqueFileName', () => {
it('returns exact name when no collision exists', () => {
expect(getUniqueFileName([], 'image.png')).toBe('image.png')
expect(getUniqueFileName(['other.png', 'test.mov'], 'image.png')).toBe('image.png')
})
it('appends _1 on first collision', () => {
expect(getUniqueFileName(['image.png'], 'image.png')).toBe('image_1.png')
})
it('appends _2 when original and _1 both exist', () => {
expect(getUniqueFileName(['image.png', 'image_1.png'], 'image.png')).toBe('image_2.png')
})
it('handles case-insensitive collision checks', () => {
expect(getUniqueFileName(['IMAGE.PNG'], 'image.png')).toBe('image_1.png')
expect(getUniqueFileName(['image.png', 'IMAGE_1.PNG'], 'image.png')).toBe('image_2.png')
})
it('handles files without extensions', () => {
expect(getUniqueFileName(['README'], 'README')).toBe('README_1')
expect(getUniqueFileName(['README', 'README_1'], 'README')).toBe('README_2')
})
it('handles files with multiple dots', () => {
expect(getUniqueFileName(['archive.tar.gz'], 'archive.tar.gz')).toBe('archive.tar_1.gz')
expect(getUniqueFileName(['archive.tar.gz', 'archive.tar_1.gz'], 'archive.tar.gz')).toBe(
'archive.tar_2.gz',
)
})
})
describe('getFolderEntryNames', () => {
it('reads entry names from folder.getEntries', async () => {
const mockFolder = {
isFile: false as const,
isFolder: true as const,
name: 'dir',
nativePath: '/path/dir',
createFile: vi.fn(),
getEntries: vi.fn().mockResolvedValue([
{ name: 'file1.mp4', isFile: true, isFolder: false },
{ name: 'subfolder', isFile: false, isFolder: true },
]),
}
const names = await getFolderEntryNames(mockFolder)
expect(names).toEqual(['file1.mp4', 'subfolder'])
})
it('handles folder.getEntries error gracefully', async () => {
const mockFolder = {
isFile: false as const,
isFolder: true as const,
name: 'dir',
nativePath: '/path/dir',
createFile: vi.fn(),
getEntries: vi.fn().mockRejectedValue(new Error('Permission denied')),
}
const names = await getFolderEntryNames(mockFolder)
expect(names).toEqual([])
})
})
describe('createUniqueFileInFolder', () => {
it('creates file with candidate name when no collision', async () => {
const mockCreatedFile = {
isFile: true as const,
isFolder: false as const,
name: 'test.mp4',
nativePath: '/path/test.mp4',
write: vi.fn(),
}
const mockFolder = {
isFile: false as const,
isFolder: true as const,
name: 'dir',
nativePath: '/path/dir',
createFile: vi.fn().mockResolvedValue(mockCreatedFile),
getEntries: vi.fn().mockResolvedValue([]),
}
const res = await createUniqueFileInFolder(mockFolder, 'test.mp4')
expect(res.name).toBe('test.mp4')
expect(res.file).toBe(mockCreatedFile)
expect(mockFolder.createFile).toHaveBeenCalledWith('test.mp4', { overwrite: false })
})
it('auto-increments suffix when candidate creation fails due to collision', async () => {
const mockCreatedFile = {
isFile: true as const,
isFolder: false as const,
name: 'test_1.mp4',
nativePath: '/path/test_1.mp4',
write: vi.fn(),
}
const mockFolder = {
isFile: false as const,
isFolder: true as const,
name: 'dir',
nativePath: '/path/dir',
createFile: vi
.fn()
.mockRejectedValueOnce(new Error('File exists'))
.mockResolvedValueOnce(mockCreatedFile),
getEntries: vi.fn().mockResolvedValue([]),
}
const res = await createUniqueFileInFolder(mockFolder, 'test.mp4')
expect(res.name).toBe('test_1.mp4')
expect(res.file).toBe(mockCreatedFile)
})
})
describe('importAssetIntoPremiere', () => {
const mockAsset: AssetSummary = {
id: 'asset-1',
name: 'Sample.mov',
type: 'file',
}
it('returns error when no active project in Premiere', async () => {
vi.spyOn(premiereModule, 'getActiveProject').mockResolvedValue(null)
const result = await importAssetIntoPremiere({
endpoint: 'http://test',
apiKey: 'key',
asset: mockAsset,
type: 'raw',
})
expect(result.success).toBe(false)
expect(result.message).toContain('Please open or create a project')
})
it('returns cancelled when user cancels folder picker', async () => {
// Mocking incomplete Premiere Project object in unit test
// eslint-disable-next-line @typescript-eslint/no-explicit-any
vi.spyOn(premiereModule, 'getActiveProject').mockResolvedValue({} as any)
vi.spyOn(premiereModule, 'promptSelectFolder').mockResolvedValue(null)
const result = await importAssetIntoPremiere({
endpoint: 'http://test',
apiKey: 'key',
asset: mockAsset,
type: 'raw',
})
expect(result.success).toBe(false)
expect(result.cancelled).toBe(true)
expect(premiereModule.promptSelectFolder).toHaveBeenCalled()
})
it('fails after folder selection if download link resolution fails', async () => {
// Mocking incomplete Premiere Project object in unit test
// eslint-disable-next-line @typescript-eslint/no-explicit-any
vi.spyOn(premiereModule, 'getActiveProject').mockResolvedValue({} as any)
const mockFolder = {
isFile: false as const,
isFolder: true as const,
name: 'dir',
nativePath: '/path/dir',
createFile: vi.fn(),
getEntries: vi.fn().mockResolvedValue([]),
}
vi.spyOn(premiereModule, 'promptSelectFolder').mockResolvedValue(mockFolder)
vi.spyOn(clientModule, 'getShumaiClient').mockReturnValue({
api: {
files: {
'download-links': {
$post: vi.fn().mockResolvedValue({
ok: false,
status: 401,
json: async () => ({ error: 'Unauthorized: Invalid API Key' }),
}),
},
},
},
// Partial mock of Hono client for unit test isolation
// eslint-disable-next-line @typescript-eslint/no-explicit-any
} as any)
await expect(
importAssetIntoPremiere({
endpoint: 'http://test',
apiKey: 'key',
asset: mockAsset,
type: 'raw',
}),
).rejects.toThrow('Unauthorized: Invalid API Key')
})
it('downloads and imports file successfully with original name when no conflict', async () => {
// Mocking incomplete Premiere Project object in unit test
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const mockProject = {} as any
vi.spyOn(premiereModule, 'getActiveProject').mockResolvedValue(mockProject)
const mockSaveFile = {
isFile: true as const,
isFolder: false as const,
name: 'Sample.mov',
nativePath: '/Users/test/Downloads/Sample.mov',
write: vi.fn().mockResolvedValue(undefined),
}
const mockFolder = {
isFile: false as const,
isFolder: true as const,
name: 'Downloads',
nativePath: '/Users/test/Downloads',
createFile: vi.fn().mockResolvedValue(mockSaveFile),
getEntries: vi.fn().mockResolvedValue([]),
}
vi.spyOn(premiereModule, 'promptSelectFolder').mockResolvedValue(mockFolder)
vi.spyOn(premiereModule, 'writeBinaryFile').mockResolvedValue(undefined)
vi.spyOn(premiereModule, 'importFilesIntoProject').mockResolvedValue(true)
vi.spyOn(clientModule, 'getShumaiClient').mockReturnValue({
api: {
files: {
'download-links': {
$post: vi.fn().mockResolvedValue({
ok: true,
json: async () => ({
files: [{ id: 'asset-1', name: 'Sample.mov', url: 'https://s3.example.com/raw' }],
}),
}),
},
},
},
// Partial mock of Hono client for unit test isolation
// eslint-disable-next-line @typescript-eslint/no-explicit-any
} as any)
// Mock global fetch
const dummyBuffer = new ArrayBuffer(8)
const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue({
ok: true,
arrayBuffer: async () => dummyBuffer,
// Mocking Response object for unit test
// eslint-disable-next-line @typescript-eslint/no-explicit-any
} as any)
const onProgress = vi.fn()
const result = await importAssetIntoPremiere({
endpoint: 'http://test',
apiKey: 'key',
asset: mockAsset,
type: 'raw',
onProgress,
})
expect(result.success).toBe(true)
expect(result.fileName).toBe('Sample.mov')
expect(result.message).toContain('Successfully imported Sample.mov')
expect(mockFolder.createFile).toHaveBeenCalledWith('Sample.mov', { overwrite: false })
expect(premiereModule.importFilesIntoProject).toHaveBeenCalledWith(mockProject, [
'/Users/test/Downloads/Sample.mov',
])
expect(onProgress).toHaveBeenCalled()
fetchSpy.mockRestore()
})
it('automatically adds _1 suffix when name conflict exists in selected folder', async () => {
// Mocking incomplete Premiere Project object in unit test
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const mockProject = {} as any
vi.spyOn(premiereModule, 'getActiveProject').mockResolvedValue(mockProject)
const mockSaveFile = {
isFile: true as const,
isFolder: false as const,
name: 'Sample_1.mov',
nativePath: '/Users/test/Downloads/Sample_1.mov',
write: vi.fn().mockResolvedValue(undefined),
}
const mockFolder = {
isFile: false as const,
isFolder: true as const,
name: 'Downloads',
nativePath: '/Users/test/Downloads',
createFile: vi.fn().mockResolvedValue(mockSaveFile),
getEntries: vi
.fn()
.mockResolvedValue([{ name: 'Sample.mov', isFile: true, isFolder: false }]),
}
vi.spyOn(premiereModule, 'promptSelectFolder').mockResolvedValue(mockFolder)
vi.spyOn(premiereModule, 'writeBinaryFile').mockResolvedValue(undefined)
vi.spyOn(premiereModule, 'importFilesIntoProject').mockResolvedValue(true)
vi.spyOn(clientModule, 'getShumaiClient').mockReturnValue({
api: {
files: {
'download-links': {
$post: vi.fn().mockResolvedValue({
ok: true,
json: async () => ({
files: [{ id: 'asset-1', name: 'Sample.mov', url: 'https://s3.example.com/raw' }],
}),
}),
},
},
},
// Partial mock of Hono client for unit test isolation
// eslint-disable-next-line @typescript-eslint/no-explicit-any
} as any)
const dummyBuffer = new ArrayBuffer(8)
const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue({
ok: true,
arrayBuffer: async () => dummyBuffer,
// Mocking Response object for unit test
// eslint-disable-next-line @typescript-eslint/no-explicit-any
} as any)
const result = await importAssetIntoPremiere({
endpoint: 'http://test',
apiKey: 'key',
asset: mockAsset,
type: 'raw',
})
expect(result.success).toBe(true)
expect(result.fileName).toBe('Sample_1.mov')
expect(result.message).toContain('Successfully imported Sample_1.mov')
expect(mockFolder.createFile).toHaveBeenCalledWith('Sample_1.mov', { overwrite: false })
expect(premiereModule.importFilesIntoProject).toHaveBeenCalledWith(mockProject, [
'/Users/test/Downloads/Sample_1.mov',
])
fetchSpy.mockRestore()
})
it('resolves relative download URL with endpoint before fetching', async () => {
// Mocking incomplete Premiere Project object in unit test
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const mockProject = {} as any
vi.spyOn(premiereModule, 'getActiveProject').mockResolvedValue(mockProject)
const mockSaveFile = {
isFile: true as const,
isFolder: false as const,
name: 'Sample.mov',
nativePath: '/Users/test/Downloads/Sample.mov',
write: vi.fn().mockResolvedValue(undefined),
}
const mockFolder = {
isFile: false as const,
isFolder: true as const,
name: 'Downloads',
nativePath: '/Users/test/Downloads',
createFile: vi.fn().mockResolvedValue(mockSaveFile),
getEntries: vi.fn().mockResolvedValue([]),
}
vi.spyOn(premiereModule, 'promptSelectFolder').mockResolvedValue(mockFolder)
vi.spyOn(premiereModule, 'writeBinaryFile').mockResolvedValue(undefined)
vi.spyOn(premiereModule, 'importFilesIntoProject').mockResolvedValue(true)
vi.spyOn(clientModule, 'getShumaiClient').mockReturnValue({
api: {
files: {
'download-links': {
$post: vi.fn().mockResolvedValue({
ok: true,
json: async () => ({
files: [{ id: 'asset-1', name: 'Sample.mov', url: '/api/upload/local?key=test' }],
}),
}),
},
},
},
// eslint-disable-next-line @typescript-eslint/no-explicit-any
} as any)
const dummyBuffer = new ArrayBuffer(8)
const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue({
ok: true,
arrayBuffer: async () => dummyBuffer,
// eslint-disable-next-line @typescript-eslint/no-explicit-any
} as any)
const result = await importAssetIntoPremiere({
endpoint: 'http://test:3000',
apiKey: 'key',
asset: mockAsset,
type: 'raw',
})
expect(result.success).toBe(true)
expect(fetchSpy).toHaveBeenCalledWith('http://test:3000/api/upload/local?key=test')
fetchSpy.mockRestore()
})
})
})
+357
View File
@@ -0,0 +1,357 @@
import { getShumaiClient } from '../api/client'
import type { AssetSummary } from '../components/FileItem'
import {
getActiveProject,
importFilesIntoProject,
promptSelectFolder,
writeBinaryFile,
} from './premiere'
import { resolveAssetUrl } from '../utils/url'
export interface ProxyOption {
id: string
label: string
resolution: string
url: string
key: string
width?: number
height?: number
size?: number
}
export function formatResolutionLabel(width?: number, height?: number, res?: string): string {
if (res) {
const cleanRes = res.endsWith('p') ? res : `${res}p`
return `${cleanRes} (MP4)`
}
if (height) return `${height}p (MP4)`
if (width) {
if (width >= 3840) return '2160p (MP4)'
if (width >= 1920) return '1080p (MP4)'
if (width >= 1280) return '720p (MP4)'
if (width >= 960) return '540p (MP4)'
if (width >= 640) return '360p (MP4)'
}
return 'Proxy (MP4)'
}
export function getResolutionRank(label: string): number {
const match = label.match(/(\d+)p/) || label.match(/^(\d+)/)
return match ? parseInt(match[1], 10) : 0
}
/**
* Resolves the presigned download URL for the original / raw file.
*/
export async function resolveRawDownloadUrl(
endpoint: string,
apiKey: string,
assetId: string,
knownAsset?: AssetSummary,
): Promise<{ url: string; name?: string }> {
const client = getShumaiClient(endpoint, apiKey)
// 1. If original key is known directly from asset summary, presign via download-url endpoint
const directKey = knownAsset?.media?.original?.key
if (directKey) {
try {
const res = await client.api.files['download-url']?.$post({
json: { key: directKey, assetId },
})
if (res?.ok) {
const data = await res.json()
if (data.url) {
return { url: data.url, name: knownAsset?.name }
}
}
} catch (err) {
console.warn('Failed to resolve download URL via known key:', err)
}
}
// 2. Fetch full asset details via GET /api/files/:fileId to get the original media key
try {
const detailRes = await client.api.files[':fileId']?.$get({
param: { fileId: assetId },
})
if (detailRes?.ok) {
const assetData = await detailRes.json()
const originalKey = assetData.media?.original?.key
if (originalKey) {
const urlRes = await client.api.files['download-url']?.$post({
json: { key: originalKey, assetId },
})
if (urlRes?.ok) {
const urlData = await urlRes.json()
if (urlData.url) {
return { url: urlData.url, name: assetData.name || knownAsset?.name }
}
}
}
}
} catch (err) {
console.warn('Failed to fetch asset details for download URL:', err)
}
// 3. Fallback to POST /api/files/download-links batch resolution
const res = await client.api.files['download-links']?.$post({
json: { ids: [assetId] },
})
if (res?.ok) {
const data = await res.json()
const file = data.files?.[0]
if (file?.url) {
return { url: file.url, name: file.name || knownAsset?.name }
}
} else if (res) {
const errData = (await res.json().catch(() => ({}))) as { error?: string }
throw new Error(errData.error || `Failed to get download link (${res.status})`)
}
throw new Error('No download URL returned from server.')
}
/**
* Fetches available video proxy transcodes for an asset.
*/
export async function fetchVideoProxies(
endpoint: string,
apiKey: string,
assetId: string,
): Promise<ProxyOption[]> {
const client = getShumaiClient(endpoint, apiKey)
const res = await client.api.files[':fileId'].$get({
param: { fileId: assetId },
})
if (!res.ok) {
const errData = (await res.json().catch(() => ({}))) as { error?: string }
throw new Error(errData.error || `Failed to get asset details (${res.status})`)
}
const asset = await res.json()
const transcodes = asset.media?.videoTranscodes || []
if (!transcodes.length) return []
const proxies: ProxyOption[] = []
for (const t of transcodes) {
let url = t.url
if (!url && t.key) {
// If transcode url wasn't presigned yet, request via download-url endpoint
try {
const urlRes = await client.api.files['download-url'].$post({
json: { key: t.key, assetId },
})
if (urlRes.ok) {
const urlData = await urlRes.json()
url = urlData.url
}
} catch (err) {
console.warn(`Failed to presign transcode key ${t.key}:`, err)
}
}
if (url) {
const label = formatResolutionLabel(t.width, t.height)
proxies.push({
id: t.id || t.key,
label,
resolution: `${t.height || 0}p`,
url,
key: t.key,
width: t.width,
height: t.height,
size: t.size,
})
}
}
// Sort descending by resolution (1080p, 720p, 540p, 360p)
proxies.sort((a, b) => getResolutionRank(b.label) - getResolutionRank(a.label))
return proxies
}
/**
* Resolves a unique filename within the specified existing file names in a folder.
* If requestedName exists, it appends _1, _2, etc. before the file extension.
* Comparison is case-insensitive to safely handle Windows and macOS filesystems.
*/
export function getUniqueFileName(existingNames: string[], requestedName: string): string {
const existingSet = new Set(existingNames.map((n) => n.toLowerCase()))
if (!existingSet.has(requestedName.toLowerCase())) {
return requestedName
}
const dotIndex = requestedName.lastIndexOf('.')
const base = dotIndex > 0 ? requestedName.slice(0, dotIndex) : requestedName
const ext = dotIndex > 0 ? requestedName.slice(dotIndex) : ''
let counter = 1
while (true) {
const candidate = `${base}_${counter}${ext}`
if (!existingSet.has(candidate.toLowerCase())) {
return candidate
}
counter++
}
}
/**
* Reads existing file/folder names inside a UXP FolderEntry safely.
*/
export async function getFolderEntryNames(folder: UxpFolderEntry): Promise<string[]> {
try {
if (typeof folder.getEntries === 'function') {
const entries = await folder.getEntries()
return entries.map((e) => e.name)
}
const folderRecord = folder as unknown as Record<string, unknown>
if (typeof folderRecord.getFiles === 'function') {
const files = await (folderRecord.getFiles as () => Promise<Array<{ name: string }>>)()
return files.map((f) => f.name)
}
} catch (err) {
console.warn('Failed to read folder entries:', err)
}
return []
}
/**
* Creates a unique file entry in the target folder, preventing overwrites by auto-incrementing suffixes (_1, _2).
*/
export async function createUniqueFileInFolder(
folder: UxpFolderEntry,
requestedName: string,
): Promise<{ file: UxpFileEntry; name: string }> {
const existingNames = await getFolderEntryNames(folder)
const candidateName = getUniqueFileName(existingNames, requestedName)
try {
const file = await folder.createFile(candidateName, { overwrite: false })
return { file, name: candidateName }
} catch (err) {
console.warn(`Could not create file "${candidateName}" with overwrite: false, retrying...`, err)
const dotIndex = requestedName.lastIndexOf('.')
const base = dotIndex > 0 ? requestedName.slice(0, dotIndex) : requestedName
const ext = dotIndex > 0 ? requestedName.slice(dotIndex) : ''
for (let counter = 1; counter <= 50; counter++) {
const retryName = `${base}_${counter}${ext}`
try {
const file = await folder.createFile(retryName, { overwrite: false })
return { file, name: retryName }
} catch {
continue
}
}
const fallbackFile = await folder.createFile(candidateName, { overwrite: true })
return { file: fallbackFile, name: candidateName }
}
}
export interface ImportAssetOptions {
endpoint: string
apiKey: string
asset: AssetSummary
type: 'raw' | 'proxy'
proxyItem?: ProxyOption
onProgress?: (message: string) => void
}
export interface ImportResult {
success: boolean
cancelled?: boolean
message: string
fileName?: string
}
/**
* Orchestrates the full import workflow:
* 1. Checks active Premiere Pro project
* 2. Prompts user with native folder picker (Frame.io pattern)
* 3. Resolves download URL from Shumai S3 presigned URL
* 4. Resolves unique filename in folder with auto-increment (_1, _2) on collision
* 5. Downloads binary data and writes to disk
* 6. Calls Premiere project.importFiles
*/
export async function importAssetIntoPremiere({
endpoint,
apiKey,
asset,
type,
proxyItem,
onProgress,
}: ImportAssetOptions): Promise<ImportResult> {
// 1. Verify active Premiere project
const project = await getActiveProject()
if (!project) {
return {
success: false,
message: 'Please open or create a project in Premiere Pro first.',
}
}
// 2. Open native folder picker (Frame.io pattern)
const targetFolder = await promptSelectFolder()
if (!targetFolder) {
return {
success: false,
cancelled: true,
message: 'Import cancelled by user.',
}
}
// 3. Determine default filename & download URL
onProgress?.('Preparing download link...')
let downloadUrl: string
let defaultFileName: string
if (type === 'raw') {
const rawInfo = await resolveRawDownloadUrl(endpoint, apiKey, asset.id, asset)
downloadUrl = rawInfo.url
defaultFileName = rawInfo.name || asset.name
} else {
if (!proxyItem?.url) {
throw new Error('Proxy URL not available.')
}
downloadUrl = proxyItem.url
const rawName = asset.name
const dotIndex = rawName.lastIndexOf('.')
const baseName = dotIndex !== -1 ? rawName.slice(0, dotIndex) : rawName
const resTag = proxyItem ? proxyItem.label.split(' ')[0] : 'proxy'
defaultFileName = `${baseName}_proxy_${resTag}.mp4`
}
const resolvedDownloadUrl = resolveAssetUrl(downloadUrl, endpoint) || downloadUrl
// 4. Create unique file in destination folder with collision avoidance (_1, _2)
const { file: saveFile, name: finalFileName } = await createUniqueFileInFolder(
targetFolder,
defaultFileName,
)
// 5. Download binary data
onProgress?.(`Downloading ${finalFileName}...`)
const response = await fetch(resolvedDownloadUrl)
if (!response.ok) {
throw new Error(`Failed to download file (HTTP ${response.status})`)
}
const arrayBuffer = await response.arrayBuffer()
// 6. Write file to disk
onProgress?.(`Saving ${finalFileName} to disk...`)
await writeBinaryFile(saveFile, arrayBuffer)
// 7. Import into Premiere Pro
onProgress?.('Importing into Premiere Pro...')
const imported = await importFilesIntoProject(project, [saveFile.nativePath])
if (!imported) {
throw new Error(`Premiere Pro could not import "${finalFileName}".`)
}
return {
success: true,
fileName: finalFileName,
message: `Successfully imported ${finalFileName} into Premiere Pro.`,
}
}
@@ -0,0 +1,548 @@
import { describe, it, expect, vi, beforeEach } from 'vitest'
import {
saveSequenceLinkToCache,
getSequenceLinkFromCache,
removeSequenceLinkFromCache,
getAllSequenceLinksFromCache,
getAllLinkedSequences,
getSequenceLink,
saveSequenceLink,
removeSequenceLink,
normalizeGuid,
LINK_STORAGE_PROP_KEY,
} from './linkStorage'
import * as commentUtils from './commentUtils'
import type { Project, Sequence } from '@adobe/premierepro'
import type { LinkedSequenceAsset } from '../types/link'
const localStorageMock = (() => {
let store: Record<string, string> = {}
return {
getItem: (key: string) => store[key] || null,
setItem: (key: string, value: string) => {
store[key] = value.toString()
},
removeItem: (key: string) => {
delete store[key]
},
clear: () => {
store = {}
},
key: (index: number) => Object.keys(store)[index] || null,
get length() {
return Object.keys(store).length
},
}
})()
Object.defineProperty(globalThis, 'localStorage', {
value: localStorageMock,
configurable: true,
writable: true,
})
describe('linkStorage service', () => {
beforeEach(() => {
localStorage.clear()
vi.restoreAllMocks()
// Reset global require
// eslint-disable-next-line @typescript-eslint/no-explicit-any
delete (globalThis as any).require
// eslint-disable-next-line @typescript-eslint/no-explicit-any
delete (globalThis as any).window
})
const sampleLink: LinkedSequenceAsset = {
sequenceGuid: 'seq-guid-1',
sequenceName: 'Sequence 01',
assetId: 'asset-1',
assetName: 'video.mp4',
syncedCommentIds: ['comm-1', 'comm-2'],
lastSyncAt: 1000,
totalCommentsSynced: 2,
}
describe('cache operations (localStorage)', () => {
it('saves and retrieves link from cache', () => {
saveSequenceLinkToCache(sampleLink, 'proj-1')
const result = getSequenceLinkFromCache('seq-guid-1', 'proj-1')
expect(result).toEqual(sampleLink)
})
it('saves and retrieves link with endpoint from cache', () => {
const linkWithEndpoint: LinkedSequenceAsset = {
...sampleLink,
endpoint: 'https://staging.shumai.one',
}
saveSequenceLinkToCache(linkWithEndpoint, 'proj-1')
const result = getSequenceLinkFromCache('seq-guid-1', 'proj-1')
expect(result?.endpoint).toBe('https://staging.shumai.one')
})
it('returns null when link is not in cache', () => {
expect(getSequenceLinkFromCache('unknown-seq', 'proj-1')).toBeNull()
})
it('lists all links for a project', () => {
saveSequenceLinkToCache(sampleLink, 'proj-1')
const link2: LinkedSequenceAsset = {
...sampleLink,
sequenceGuid: 'seq-guid-2',
sequenceName: 'Sequence 02',
}
saveSequenceLinkToCache(link2, 'proj-1')
const all = getAllSequenceLinksFromCache('proj-1')
expect(all).toHaveLength(2)
expect(all.map((l) => l.sequenceGuid)).toContain('seq-guid-1')
expect(all.map((l) => l.sequenceGuid)).toContain('seq-guid-2')
})
it('removes a link from cache', () => {
saveSequenceLinkToCache(sampleLink, 'proj-1')
expect(getSequenceLinkFromCache('seq-guid-1', 'proj-1')).not.toBeNull()
removeSequenceLinkFromCache('seq-guid-1', 'proj-1')
expect(getSequenceLinkFromCache('seq-guid-1', 'proj-1')).toBeNull()
})
it('returns all links across projects when projectGuid is omitted', () => {
saveSequenceLinkToCache(sampleLink, 'proj-1')
const link2: LinkedSequenceAsset = {
...sampleLink,
sequenceGuid: 'seq-guid-2',
sequenceName: 'Sequence 02',
assetId: 'asset-2',
}
saveSequenceLinkToCache(link2, 'proj-2')
const all = getAllSequenceLinksFromCache()
expect(all).toHaveLength(2)
expect(all.map((l) => l.sequenceGuid)).toContain('seq-guid-1')
expect(all.map((l) => l.sequenceGuid)).toContain('seq-guid-2')
})
it('does not return links from default cache when projectGuid is specified', () => {
saveSequenceLinkToCache(sampleLink, null)
const result = getAllSequenceLinksFromCache('proj-unknown')
expect(result).toEqual([])
})
})
describe('host sequence properties integration', () => {
it('retrieves persistent property from sequence when available', async () => {
const mockProps = {
getValue: vi.fn().mockReturnValue(JSON.stringify(sampleLink)),
}
const mockPpro = {
Properties: {
getProperties: vi.fn().mockResolvedValue(mockProps),
},
}
// eslint-disable-next-line @typescript-eslint/no-explicit-any
;(globalThis as any).window = {
require: vi.fn().mockImplementation((name: string) => {
if (name === 'premierepro') return mockPpro
return null
}),
}
const mockSeq = { guid: 'seq-guid-1' }
const mockProj = { guid: 'proj-1' }
const link = await getSequenceLink(
mockSeq as unknown as Sequence,
mockProj as unknown as Project,
)
expect(link).toEqual(sampleLink)
expect(mockProps.getValue).toHaveBeenCalledWith(LINK_STORAGE_PROP_KEY)
})
it('saves persistent property and executes transaction', async () => {
const mockCompoundAction = { addAction: vi.fn() }
const mockProps = {
createSetValueAction: vi.fn().mockReturnValue({ id: 'action-set' }),
}
const mockPpro = {
Properties: {
getProperties: vi.fn().mockResolvedValue(mockProps),
PROPERTY_PERSISTENT: 1,
},
Constants: {
PropertyType: { PERSISTENT: 1 },
},
}
// eslint-disable-next-line @typescript-eslint/no-explicit-any
;(globalThis as any).window = {
require: vi.fn().mockImplementation((name: string) => {
if (name === 'premierepro') return mockPpro
return null
}),
}
const mockSeq = { guid: 'seq-guid-1' }
const mockProj = {
guid: 'proj-1',
lockedAccess: vi.fn((cb) => cb()),
executeTransaction: vi.fn((cb) => {
cb(mockCompoundAction)
return true
}),
}
const success = await saveSequenceLink(
mockProj as unknown as Project,
mockSeq as unknown as Sequence,
sampleLink,
)
expect(success).toBe(true)
expect(mockProps.createSetValueAction).toHaveBeenCalledWith(
LINK_STORAGE_PROP_KEY,
JSON.stringify(sampleLink),
1,
)
expect(mockCompoundAction.addAction).toHaveBeenCalledWith({ id: 'action-set' })
})
it('clears persistent property on removeSequenceLink', async () => {
const mockCompoundAction = { addAction: vi.fn() }
const mockProps = {
createClearValueAction: vi.fn().mockReturnValue({ id: 'action-clear' }),
}
const mockPpro = {
Properties: {
getProperties: vi.fn().mockResolvedValue(mockProps),
},
}
// eslint-disable-next-line @typescript-eslint/no-explicit-any
;(globalThis as any).window = {
require: vi.fn().mockImplementation((name: string) => {
if (name === 'premierepro') return mockPpro
return null
}),
}
const mockSeq = { guid: 'seq-guid-1' }
const mockProj = {
guid: 'proj-1',
lockedAccess: vi.fn((cb) => cb()),
executeTransaction: vi.fn((cb) => {
cb(mockCompoundAction)
return true
}),
}
const success = await removeSequenceLink(
mockProj as unknown as Project,
mockSeq as unknown as Sequence,
)
expect(success).toBe(true)
expect(mockProps.createClearValueAction).toHaveBeenCalledWith(LINK_STORAGE_PROP_KEY)
})
it('removes synced markers matching syncedMarkerGuids on removeSequenceLink, preserving manual markers', async () => {
const mockCompoundAction = { addAction: vi.fn() }
const mockProps = {
getValue: vi.fn().mockReturnValue(
JSON.stringify({
...sampleLink,
syncedMarkerGuids: ['synced-marker-1', 'synced-marker-2'],
}),
),
createClearValueAction: vi.fn().mockReturnValue({ id: 'action-clear' }),
}
const mockMarker1 = {
guid: 'synced-marker-1',
name: 'Director (edited)',
comments: 'Edited comment',
}
const mockMarker2 = { guid: 'synced-marker-2', name: 'Producer', comments: 'Another comment' }
const mockManualMarker = {
guid: 'manual-user-marker',
name: 'Editor Note',
comments: 'Manual marker',
}
const mockSeqMarkers = {
getMarkers: vi.fn().mockReturnValue([mockMarker1, mockManualMarker, mockMarker2]),
createRemoveMarkerAction: vi.fn().mockImplementation((marker) => ({
type: 'remove-marker',
guid: marker.guid,
})),
}
const mockPpro = {
Properties: {
getProperties: vi.fn().mockResolvedValue(mockProps),
},
Markers: {
getMarkers: vi.fn().mockResolvedValue(mockSeqMarkers),
},
}
// eslint-disable-next-line @typescript-eslint/no-explicit-any
;(globalThis as any).window = {
require: vi.fn().mockImplementation((name: string) => {
if (name === 'premierepro') return mockPpro
return null
}),
}
const mockSeq = { guid: 'seq-guid-1' }
const mockProj = {
guid: 'proj-1',
lockedAccess: vi.fn((cb) => cb()),
executeTransaction: vi.fn((cb) => {
cb(mockCompoundAction)
return true
}),
}
const success = await removeSequenceLink(
mockProj as unknown as Project,
mockSeq as unknown as Sequence,
)
expect(success).toBe(true)
// Only synced-marker-1 and synced-marker-2 should be removed; manual-user-marker must NOT be removed
expect(mockSeqMarkers.createRemoveMarkerAction).toHaveBeenCalledTimes(2)
expect(mockSeqMarkers.createRemoveMarkerAction).toHaveBeenCalledWith(mockMarker1)
expect(mockSeqMarkers.createRemoveMarkerAction).toHaveBeenCalledWith(mockMarker2)
expect(mockSeqMarkers.createRemoveMarkerAction).not.toHaveBeenCalledWith(mockManualMarker)
expect(mockCompoundAction.addAction).toHaveBeenCalledWith({
type: 'remove-marker',
guid: 'synced-marker-1',
})
expect(mockCompoundAction.addAction).toHaveBeenCalledWith({
type: 'remove-marker',
guid: 'synced-marker-2',
})
expect(mockProps.createClearValueAction).toHaveBeenCalledWith(LINK_STORAGE_PROP_KEY)
})
it('removes markers by comment matching fallback when syncedMarkerGuids is empty', async () => {
localStorage.setItem('shumai_uxp_endpoint', 'https://shumai.example.com')
localStorage.setItem('shumai_uxp_api_key', 'test-api-key')
vi.spyOn(commentUtils, 'fetchAssetComments').mockResolvedValue([
{
id: 'comm-1',
creator: {
id: 'u1',
name: 'Director',
} as unknown as import('@shumai/dtos').CommentInfo['creator'],
message: 'Please trim this scene',
} as unknown as import('@shumai/dtos').CommentInfo,
])
const mockCompoundAction = { addAction: vi.fn() }
const mockProps = {
getValue: vi.fn().mockReturnValue(
JSON.stringify({
...sampleLink,
syncedMarkerGuids: [],
}),
),
createClearValueAction: vi.fn().mockReturnValue({ id: 'action-clear' }),
}
const mockLegacyShumaiMarker = {
guid: 'legacy-guid-1',
getName: () => 'Director',
getComments: () => 'Please trim this scene',
}
const mockManualMarker = {
guid: 'manual-guid-2',
getName: () => 'Editor',
getComments: () => 'My own note',
}
const mockSeqMarkers = {
getMarkers: vi.fn().mockReturnValue([mockLegacyShumaiMarker, mockManualMarker]),
createRemoveMarkerAction: vi.fn().mockImplementation((marker) => ({
type: 'remove-marker',
guid: marker.guid,
})),
}
const mockPpro = {
Properties: {
getProperties: vi.fn().mockResolvedValue(mockProps),
},
Markers: {
getMarkers: vi.fn().mockResolvedValue(mockSeqMarkers),
},
}
// eslint-disable-next-line @typescript-eslint/no-explicit-any
;(globalThis as any).window = {
require: vi.fn().mockImplementation((name: string) => {
if (name === 'premierepro') return mockPpro
return null
}),
}
const mockSeq = { guid: 'seq-guid-1' }
const mockProj = {
guid: 'proj-1',
lockedAccess: vi.fn((cb) => cb()),
executeTransaction: vi.fn((cb) => {
cb(mockCompoundAction)
return true
}),
}
const success = await removeSequenceLink(
mockProj as unknown as Project,
mockSeq as unknown as Sequence,
)
expect(success).toBe(true)
expect(mockSeqMarkers.createRemoveMarkerAction).toHaveBeenCalledWith(mockLegacyShumaiMarker)
expect(mockSeqMarkers.createRemoveMarkerAction).not.toHaveBeenCalledWith(mockManualMarker)
})
it('attempts individual marker removals if compound batch remove returns false', async () => {
const mockCompoundAction = { addAction: vi.fn() }
const mockProps = {
getValue: vi.fn().mockReturnValue(
JSON.stringify({
...sampleLink,
syncedMarkerGuids: ['synced-1'],
}),
),
createClearValueAction: vi.fn().mockReturnValue({ id: 'action-clear' }),
}
const mockMarker = { guid: 'synced-1' }
const mockSeqMarkers = {
getMarkers: vi.fn().mockReturnValue([mockMarker]),
createRemoveMarkerAction: vi.fn().mockReturnValue({ type: 'remove-marker' }),
}
const mockPpro = {
Properties: {
getProperties: vi.fn().mockResolvedValue(mockProps),
},
Markers: {
getMarkers: vi.fn().mockResolvedValue(mockSeqMarkers),
},
}
// eslint-disable-next-line @typescript-eslint/no-explicit-any
;(globalThis as any).window = {
require: vi.fn().mockImplementation((name: string) => {
if (name === 'premierepro') return mockPpro
return null
}),
}
let txCount = 0
const mockProj = {
guid: 'proj-1',
lockedAccess: vi.fn((cb) => cb()),
executeTransaction: vi.fn((cb) => {
txCount++
cb(mockCompoundAction)
if (txCount === 1) return false // batch failed
return true // individual succeeded
}),
}
const mockSeq = { guid: 'seq-guid-1' }
const success = await removeSequenceLink(
mockProj as unknown as Project,
mockSeq as unknown as Sequence,
)
expect(success).toBe(true)
expect(txCount).toBeGreaterThanOrEqual(2)
})
it('skips fallback comment fetch if link endpoint does not match current session endpoint', async () => {
localStorage.setItem('shumai_uxp_endpoint', 'https://staging.shumai.one')
localStorage.setItem('shumai_uxp_api_key', 'test-key')
const fetchCommentsSpy = vi.spyOn(commentUtils, 'fetchAssetComments')
const mockSeq = {
guid: 'seq-diff-endpoint',
name: 'Diff Endpoint Seq',
}
const mockProj = {
guid: 'proj-diff',
lockedAccess: (fn: () => void) => fn(),
executeTransaction: () => true,
}
const linkFromLocal: LinkedSequenceAsset = {
...sampleLink,
sequenceGuid: 'seq-diff-endpoint',
endpoint: 'http://localhost:3000',
syncedMarkerGuids: [], // Trigger fallback
}
saveSequenceLinkToCache(linkFromLocal, 'proj-diff')
await removeSequenceLink(mockProj as unknown as Project, mockSeq as unknown as Sequence)
expect(fetchCommentsSpy).not.toHaveBeenCalled()
})
})
describe('getAllLinkedSequences', () => {
it('does not leak cached links across projects when a project has an empty sequence list', async () => {
saveSequenceLinkToCache(sampleLink, 'proj-A')
const defaultLink: LinkedSequenceAsset = {
...sampleLink,
sequenceGuid: 'seq-default',
sequenceName: 'Default Seq',
}
saveSequenceLinkToCache(defaultLink, null)
const mockProjB = {
guid: 'proj-B',
getSequences: vi.fn().mockResolvedValue([]),
}
const results = await getAllLinkedSequences(mockProjB as unknown as Project, [])
expect(results).toEqual([])
})
it('restores cached link only if the sequence actually exists in the project', async () => {
saveSequenceLinkToCache(sampleLink, 'proj-A')
const mockSeq1 = { guid: 'seq-guid-1' }
const mockSeq2 = { guid: 'seq-guid-2' }
const mockProjA = {
guid: 'proj-A',
getSequences: vi.fn().mockResolvedValue([mockSeq1]),
}
const results = await getAllLinkedSequences(mockProjA as unknown as Project, [
mockSeq1 as unknown as Sequence,
])
expect(results).toHaveLength(1)
expect(results[0].sequenceGuid).toBe('seq-guid-1')
const resultsSeq2 = await getAllLinkedSequences(mockProjA as unknown as Project, [
mockSeq2 as unknown as Sequence,
])
expect(resultsSeq2).toHaveLength(0)
})
})
describe('normalizeGuid', () => {
it('normalizes GUIDs with uppercase, braces, whitespace, and objects', () => {
expect(normalizeGuid('{1234-ABCD-5678}')).toBe('1234-abcd-5678')
expect(normalizeGuid(' ABC-DEF ')).toBe('abc-def')
expect(normalizeGuid({ toString: () => '{Guid-Obj}' })).toBe('guid-obj')
expect(normalizeGuid(null)).toBe('')
expect(normalizeGuid(undefined)).toBe('')
})
})
})
@@ -0,0 +1,472 @@
import type { Marker, Project, Sequence } from '@adobe/premierepro'
import { getPremiereModule } from './premiere'
import type { LinkedSequenceAsset } from '../types/link'
import { getStoredCredentials } from './storage'
import { fetchAssetComments, formatCommentBody } from './commentUtils'
import { isSameEndpoint } from '../utils/url'
export const LINK_STORAGE_PROP_KEY = 'shumai_linked_asset'
const STORAGE_PREFIX = '@shumai/premiere-uxp:project-links'
/**
* Normalizes a GUID or string identifier by removing curly braces,
* trimming whitespace, and converting to lower case for reliable comparison.
*/
export function normalizeGuid(guid: unknown): string {
if (!guid) return ''
const str =
typeof guid === 'string'
? guid
: typeof (guid as { toString?: () => string }).toString === 'function'
? (guid as { toString: () => string }).toString()
: String(guid)
return str.trim().toLowerCase().replace(/[{}]/g, '')
}
function getStorageKey(projectGuid?: string | null): string {
return `${STORAGE_PREFIX}:${projectGuid ? normalizeGuid(projectGuid) : 'default'}`
}
/**
* Reads all cached sequence links for a project from localStorage.
* If projectGuid is omitted or null, aggregates across all project keys in localStorage.
*/
export function getAllSequenceLinksFromCache(projectGuid?: string | null): LinkedSequenceAsset[] {
if (typeof localStorage === 'undefined') return []
try {
const normProj = projectGuid ? normalizeGuid(projectGuid) : null
if (normProj) {
const raw = localStorage.getItem(getStorageKey(normProj))
if (raw) {
const parsed = JSON.parse(raw)
if (Array.isArray(parsed)) return parsed
if (typeof parsed === 'object' && parsed !== null) {
return Object.values(parsed)
}
}
return []
}
// When projectGuid is not provided, aggregate all cached sequence links
const results: LinkedSequenceAsset[] = []
const seenGuids = new Set<string>()
// Check default key
const defaultRaw = localStorage.getItem(getStorageKey(null))
if (defaultRaw) {
try {
const parsed = JSON.parse(defaultRaw)
const items: LinkedSequenceAsset[] = Array.isArray(parsed)
? parsed
: typeof parsed === 'object' && parsed !== null
? Object.values(parsed)
: []
for (const item of items) {
const normSeq = normalizeGuid(item.sequenceGuid)
if (normSeq && !seenGuids.has(normSeq)) {
seenGuids.add(normSeq)
results.push(item)
}
}
} catch {
// Ignore JSON error
}
}
// Scan all keys matching STORAGE_PREFIX in localStorage
if (typeof localStorage.length === 'number') {
for (let i = 0; i < localStorage.length; i++) {
const key = typeof localStorage.key === 'function' ? localStorage.key(i) : null
if (key && key.startsWith(STORAGE_PREFIX)) {
const raw = localStorage.getItem(key)
if (raw) {
try {
const parsed = JSON.parse(raw)
const items: LinkedSequenceAsset[] = Array.isArray(parsed)
? parsed
: typeof parsed === 'object' && parsed !== null
? Object.values(parsed)
: []
for (const item of items) {
const normSeq = normalizeGuid(item.sequenceGuid)
if (normSeq && !seenGuids.has(normSeq)) {
seenGuids.add(normSeq)
results.push(item)
}
}
} catch {
// Ignore corrupted item
}
}
}
}
}
return results
} catch (err) {
console.warn('[linkStorage] Failed to read cached links from localStorage:', err)
return []
}
}
/**
* Gets a cached sequence link by sequence GUID from localStorage.
*/
export function getSequenceLinkFromCache(
sequenceGuid: string,
projectGuid?: string | null,
): LinkedSequenceAsset | null {
const normSeq = normalizeGuid(sequenceGuid)
const all = getAllSequenceLinksFromCache(projectGuid)
return all.find((item) => normalizeGuid(item.sequenceGuid) === normSeq) || null
}
/**
* Saves a sequence link in the local cache.
*/
export function saveSequenceLinkToCache(
linkData: LinkedSequenceAsset,
projectGuid?: string | null,
): void {
if (typeof localStorage === 'undefined') return
try {
const normSeq = normalizeGuid(linkData.sequenceGuid)
const normalizedData: LinkedSequenceAsset = {
...linkData,
sequenceGuid: normSeq,
...(linkData.syncedMarkerGuids != null
? { syncedMarkerGuids: linkData.syncedMarkerGuids.map(normalizeGuid).filter(Boolean) }
: {}),
}
if (projectGuid) {
const all = getAllSequenceLinksFromCache(projectGuid).filter(
(item) => normalizeGuid(item.sequenceGuid) !== normSeq,
)
all.push(normalizedData)
localStorage.setItem(getStorageKey(projectGuid), JSON.stringify(all))
}
// Always also update default key so it's accessible when projectGuid is unknown
const defaultAll = getAllSequenceLinksFromCache(null).filter(
(item) => normalizeGuid(item.sequenceGuid) !== normSeq,
)
defaultAll.push(normalizedData)
localStorage.setItem(getStorageKey(null), JSON.stringify(defaultAll))
} catch (err) {
console.warn('[linkStorage] Failed to save link to localStorage:', err)
}
}
/**
* Removes a sequence link from the local cache.
*/
export function removeSequenceLinkFromCache(
sequenceGuid: string,
projectGuid?: string | null,
): void {
if (typeof localStorage === 'undefined') return
try {
const normSeq = normalizeGuid(sequenceGuid)
if (projectGuid) {
const all = getAllSequenceLinksFromCache(projectGuid).filter(
(item) => normalizeGuid(item.sequenceGuid) !== normSeq,
)
localStorage.setItem(getStorageKey(projectGuid), JSON.stringify(all))
}
const defaultAll = getAllSequenceLinksFromCache(null).filter(
(item) => normalizeGuid(item.sequenceGuid) !== normSeq,
)
localStorage.setItem(getStorageKey(null), JSON.stringify(defaultAll))
// Also remove from any other keys matching STORAGE_PREFIX
if (typeof localStorage.length === 'number') {
for (let i = 0; i < localStorage.length; i++) {
const key = typeof localStorage.key === 'function' ? localStorage.key(i) : null
if (key && key.startsWith(STORAGE_PREFIX)) {
const raw = localStorage.getItem(key)
if (raw) {
try {
const parsed = JSON.parse(raw)
if (Array.isArray(parsed)) {
const filtered = parsed.filter(
(item) => normalizeGuid(item.sequenceGuid) !== normSeq,
)
localStorage.setItem(key, JSON.stringify(filtered))
}
} catch {
// Ignore
}
}
}
}
}
} catch (err) {
console.warn('[linkStorage] Failed to remove link from localStorage:', err)
}
}
/**
* Retrieves the persistent link metadata from a sequence's properties.
*/
export async function getSequenceLink(
sequence: Sequence,
project?: Project | null,
): Promise<LinkedSequenceAsset | null> {
const ppro = getPremiereModule()
const seqGuidStr = normalizeGuid(sequence.guid)
const prGuidStr = project?.guid ? normalizeGuid(project.guid) : null
// Check persistent sequence properties in Premiere
if (ppro?.Properties) {
try {
const properties = await ppro.Properties.getProperties(sequence)
const raw = properties.getValue(LINK_STORAGE_PROP_KEY)
if (raw) {
const parsed = JSON.parse(raw) as LinkedSequenceAsset
// Synchronize with cache
saveSequenceLinkToCache(parsed, prGuidStr)
return parsed
}
} catch (err) {
// Property might not exist or failed to load
console.debug('[linkStorage] No persistent property found or failed:', err)
}
}
// Fallback to local cache if sequence property was not available
return getSequenceLinkFromCache(seqGuidStr, prGuidStr)
}
/**
* Retrieves all linked sequence assets across a project.
*/
export async function getAllLinkedSequences(
project: Project,
allSequences?: Sequence[],
): Promise<LinkedSequenceAsset[]> {
const prGuidStr = project.guid ? normalizeGuid(project.guid) : null
const seqs = allSequences || (await project.getSequences()) || []
const results: LinkedSequenceAsset[] = []
const checkedGuids = new Set<string>()
for (const seq of seqs) {
const seqGuid = normalizeGuid(seq.guid)
if (seqGuid) checkedGuids.add(seqGuid)
const link = await getSequenceLink(seq, project)
if (link) {
results.push(link)
}
}
// Also check cache for any items matching known sequences
const cached = getAllSequenceLinksFromCache(prGuidStr)
for (const item of cached) {
const normItemSeq = normalizeGuid(item.sequenceGuid)
if (!results.some((r) => normalizeGuid(r.sequenceGuid) === normItemSeq)) {
if (checkedGuids.has(normItemSeq)) {
results.push(item)
}
}
}
return results
}
/**
* Saves the link metadata persistently on the sequence and in the cache.
*/
export async function saveSequenceLink(
project: Project,
sequence: Sequence,
linkData: LinkedSequenceAsset,
): Promise<boolean> {
const ppro = getPremiereModule()
const prGuidStr = project.guid ? normalizeGuid(project.guid) : null
// Always update cache first
saveSequenceLinkToCache(linkData, prGuidStr)
if (!ppro?.Properties) {
return true
}
try {
const properties = await ppro.Properties.getProperties(sequence)
const persistentType =
ppro.Constants?.PropertyType?.PERSISTENT ?? ppro.Properties.PROPERTY_PERSISTENT ?? 0
let success = false
project.lockedAccess(() => {
success = project.executeTransaction((compoundAction) => {
const setValAction = properties.createSetValueAction(
LINK_STORAGE_PROP_KEY,
JSON.stringify(linkData),
persistentType,
)
compoundAction.addAction(setValAction)
}, 'Save Shumai Link')
})
return success
} catch (err) {
console.warn('[linkStorage] Failed to set sequence persistent property:', err)
return true // Local cache succeeded
}
}
/**
* Removes the persistent link metadata from the sequence and cache,
* and deletes any markers that were synced from Shumai (matching Frame.io behavior).
*/
export async function removeSequenceLink(project: Project, sequence: Sequence): Promise<boolean> {
const ppro = getPremiereModule()
const seqGuidStr = normalizeGuid(sequence.guid)
const prGuidStr = project.guid ? normalizeGuid(project.guid) : null
console.log('[linkStorage] removeSequenceLink called for sequence:', sequence.name || seqGuidStr)
// Retrieve link metadata before clearing, to identify synced marker GUIDs
let linkData = await getSequenceLink(sequence, project)
if (!linkData) {
const cached = getAllSequenceLinksFromCache(prGuidStr)
linkData = cached.find((item) => normalizeGuid(item.sequenceGuid) === seqGuidStr) || null
}
console.log(
'[linkStorage] Retrieved linkData:',
linkData ? { assetId: linkData.assetId, guidsCount: linkData.syncedMarkerGuids?.length } : null,
)
// Remove from cache
removeSequenceLinkFromCache(seqGuidStr, prGuidStr)
// Remove synced markers from the sequence timeline
if (ppro?.Markers) {
try {
const sequenceMarkers = await ppro.Markers.getMarkers(sequence)
const allMarkers = sequenceMarkers.getMarkers() || []
console.log('[linkStorage] Found', allMarkers.length, 'markers on sequence timeline')
const targetGuids = new Set(
(linkData?.syncedMarkerGuids || []).map(normalizeGuid).filter(Boolean),
)
console.log('[linkStorage] targetGuids count:', targetGuids.size)
const markersToRemove: Marker[] = []
// 1. Match markers by GUID
if (targetGuids.size > 0) {
for (const m of allMarkers) {
const g = normalizeGuid(m.guid)
if (g && targetGuids.has(g)) {
markersToRemove.push(m)
}
}
}
// 2. Fallback: If targetGuids was empty/missing or didn't find markers, match by asset comments
if (markersToRemove.length === 0 && linkData?.assetId) {
console.log(
'[linkStorage] Fallback: attempting comment-based marker identification for asset:',
linkData.assetId,
)
try {
const creds = getStoredCredentials()
const canFetchComments =
creds?.endpoint &&
creds?.apiKey &&
(!linkData.endpoint || isSameEndpoint(linkData.endpoint, creds.endpoint))
if (canFetchComments) {
const comments = await fetchAssetComments(
creds.endpoint,
creds.apiKey,
linkData.assetId,
)
for (const comm of comments) {
const commBody = formatCommentBody(comm)
const commAuthor = comm.creator?.name || 'Comment'
for (const m of allMarkers) {
if (markersToRemove.includes(m)) continue
try {
const mName = m.getName()
const mComments = m.getComments()
if (
(mName === commAuthor && mComments === commBody) ||
(mComments && comm.message && mComments.includes(comm.message))
) {
markersToRemove.push(m)
break
}
} catch {
// ignore
}
}
}
}
} catch (err) {
console.warn('[linkStorage] Fallback comment fetch failed:', err)
}
}
console.log('[linkStorage] Total markers to remove:', markersToRemove.length)
if (markersToRemove.length > 0) {
let removeSuccess = false
try {
project.lockedAccess(() => {
removeSuccess = project.executeTransaction((compoundAction) => {
for (const marker of markersToRemove) {
const removeAction = sequenceMarkers.createRemoveMarkerAction(marker)
compoundAction.addAction(removeAction)
}
}, 'Remove Shumai Synced Markers')
})
} catch (err) {
console.error('[linkStorage] executeTransaction batch remove failed:', err)
}
console.log('[linkStorage] Batch remove result:', removeSuccess)
// If batch compound action did not succeed, attempt individual removals
if (!removeSuccess) {
console.warn('[linkStorage] Batch remove returned false, attempting individual removals')
for (const marker of markersToRemove) {
try {
project.lockedAccess(() => {
project.executeTransaction((compoundAction) => {
const removeAction = sequenceMarkers.createRemoveMarkerAction(marker)
compoundAction.addAction(removeAction)
}, 'Remove Shumai Synced Marker')
})
} catch (indErr) {
console.warn('[linkStorage] Failed individual remove:', indErr)
}
}
}
}
} catch (err) {
console.warn('[linkStorage] Failed to remove synced markers from sequence:', err)
}
}
if (!ppro?.Properties) {
return true
}
try {
const properties = await ppro.Properties.getProperties(sequence)
let success = false
project.lockedAccess(() => {
success = project.executeTransaction((compoundAction) => {
const clearAction = properties.createClearValueAction(LINK_STORAGE_PROP_KEY)
compoundAction.addAction(clearAction)
}, 'Unlink Shumai Asset')
})
console.log('[linkStorage] Clear property result:', success)
return success
} catch (err) {
console.warn('[linkStorage] Failed to clear sequence persistent property:', err)
return true // Cache was cleared
}
}
@@ -0,0 +1,405 @@
import { describe, it, expect, vi, beforeEach } from 'vitest'
import { formatCommentBody, syncCommentsToSequence } from './markers'
import type { Project, Sequence } from '@adobe/premierepro'
import type { CommentInfo } from '@shumai/dtos'
import type { LinkedSequenceAsset } from '../types/link'
const localStorageMock = (() => {
let store: Record<string, string> = {}
return {
getItem: (key: string) => store[key] || null,
setItem: (key: string, value: string) => {
store[key] = value.toString()
},
removeItem: (key: string) => {
delete store[key]
},
clear: () => {
store = {}
},
}
})()
Object.defineProperty(globalThis, 'localStorage', {
value: localStorageMock,
configurable: true,
writable: true,
})
describe('markers service', () => {
beforeEach(() => {
localStorage.clear()
vi.restoreAllMocks()
// Reset global require
// eslint-disable-next-line @typescript-eslint/no-explicit-any
delete (globalThis as any).require
// eslint-disable-next-line @typescript-eslint/no-explicit-any
delete (globalThis as any).window
})
describe('formatCommentBody', () => {
it('formats simple comment without replies', () => {
const comment: Partial<CommentInfo> = {
message: 'This is a test comment',
replies: [],
}
expect(formatCommentBody(comment as CommentInfo)).toBe('This is a test comment')
})
it('appends formatted replies beneath message', () => {
const comment: Partial<CommentInfo> = {
message: 'Original cut feedback',
replies: [
{
creator: { id: 'u2', name: 'Alice' },
message: 'Fixed in v2',
} as unknown as CommentInfo,
{
creator: { id: 'u3', name: 'Bob' },
message: 'Looks great now',
} as unknown as CommentInfo,
],
}
const formatted = formatCommentBody(comment as CommentInfo)
expect(formatted).toContain('Original cut feedback')
expect(formatted).toContain('--- Replies ---')
expect(formatted).toContain('Alice: Fixed in v2')
expect(formatted).toContain('Bob: Looks great now')
})
})
describe('syncCommentsToSequence', () => {
const existingLink: LinkedSequenceAsset = {
sequenceGuid: 'seq-guid-1',
sequenceName: 'Seq 1',
assetId: 'asset-1',
assetName: 'test.mp4',
syncedCommentIds: ['comm-1'],
lastSyncAt: 1000,
totalCommentsSynced: 1,
}
it('returns without creating markers if no new comments exist', async () => {
const comments: Partial<CommentInfo>[] = [
{ id: 'comm-1', second: 10, message: 'Already synced' },
]
const mockProject = {
guid: 'proj-1',
lockedAccess: vi.fn(),
executeTransaction: vi.fn(),
}
const mockSeq = { guid: 'seq-guid-1' }
const result = await syncCommentsToSequence(
mockProject as unknown as Project,
mockSeq as unknown as Sequence,
comments as CommentInfo[],
existingLink,
)
expect(result.addedCount).toBe(0)
expect(result.updatedLink.syncedCommentIds).toEqual(['comm-1'])
expect(mockProject.executeTransaction).not.toHaveBeenCalled()
})
it('creates markers for new comments, placing non-timestamped comments at time 0 (zeroPoint)', async () => {
const mockCompoundAction = { addAction: vi.fn() }
let callCount = 0
const mockSeqMarkers = {
getMarkers: vi.fn().mockImplementation(() => {
callCount++
if (callCount === 1) {
return [{ guid: 'old-guid-1' }]
}
return [{ guid: 'old-guid-1' }, { guid: 'marker-guid-2' }, { guid: 'marker-guid-3' }]
}),
createAddMarkerAction: vi.fn().mockImplementation((name, type, time, dur, comment) => {
return { name, type, time, dur, comment }
}),
}
const mockPpro = {
Marker: { MARKER_TYPE_COMMENT: 'CommentMarkerType' },
Markers: {
getMarkers: vi.fn().mockResolvedValue(mockSeqMarkers),
},
TickTime: {
TIME_ZERO: { ticks: '0' },
createWithSeconds: vi.fn((sec) => ({ seconds: sec })),
},
Properties: {
getProperties: vi.fn().mockResolvedValue({
createSetValueAction: vi.fn().mockReturnValue({}),
}),
},
}
// eslint-disable-next-line @typescript-eslint/no-explicit-any
;(globalThis as any).window = {
require: vi.fn().mockImplementation((name: string) => {
if (name === 'premierepro') return mockPpro
return null
}),
}
const comments: Partial<CommentInfo>[] = [
{ id: 'comm-1', second: 10, message: 'Already synced' },
{
id: 'comm-2',
second: 15.5,
message: 'New timestamped comment',
creator: { id: 'u1', name: 'Director' } as unknown as CommentInfo['creator'],
replies: [],
},
{
id: 'comm-3',
second: null,
message: 'General comment without timestamp',
creator: { id: 'u2', name: 'Producer' } as unknown as CommentInfo['creator'],
replies: [],
},
]
const mockProject = {
guid: 'proj-1',
lockedAccess: vi.fn((cb) => cb()),
executeTransaction: vi.fn((cb) => {
cb(mockCompoundAction)
return true
}),
}
const mockSeq = {
guid: 'seq-guid-1',
getZeroPoint: vi.fn().mockResolvedValue({ seconds: 3600 }), // 1hr timecode start
}
const result = await syncCommentsToSequence(
mockProject as unknown as Project,
mockSeq as unknown as Sequence,
comments as CommentInfo[],
existingLink,
)
expect(result.addedCount).toBe(2)
expect(result.updatedLink.syncedCommentIds).toEqual(['comm-1', 'comm-2', 'comm-3'])
expect(result.updatedLink.syncedMarkerGuids).toEqual(['marker-guid-2', 'marker-guid-3'])
expect(result.updatedLink.totalCommentsSynced).toBe(3)
// Time should be offset by zeroPoint (3600 + 15.5 = 3615.5 for comm-2, 3600 + 0 = 3600 for comm-3)
expect(mockPpro.TickTime.createWithSeconds).toHaveBeenCalledWith(3615.5)
expect(mockPpro.TickTime.createWithSeconds).toHaveBeenCalledWith(3600)
expect(mockSeqMarkers.createAddMarkerAction).toHaveBeenCalledWith(
'Director',
'CommentMarkerType',
{ seconds: 3615.5 },
mockPpro.TickTime.TIME_ZERO,
'New timestamped comment',
)
expect(mockSeqMarkers.createAddMarkerAction).toHaveBeenCalledWith(
'Producer',
'CommentMarkerType',
{ seconds: 3600 },
mockPpro.TickTime.TIME_ZERO,
'General comment without timestamp',
)
expect(mockSeqMarkers.createAddMarkerAction).toHaveBeenCalledTimes(2)
expect(mockCompoundAction.addAction).toHaveBeenCalled()
})
it('backfills missing marker GUIDs from sequence when syncedMarkerGuids is incomplete', async () => {
const existingLink: LinkedSequenceAsset = {
sequenceGuid: 'seq-guid-1',
sequenceName: 'Sequence 01',
assetId: 'asset-1',
assetName: 'video.mp4',
syncedCommentIds: ['comm-1'],
syncedMarkerGuids: [], // missing GUIDs from previous sync
totalCommentsSynced: 1,
lastSyncAt: 1000,
}
const mockLegacyMarker = {
guid: '{LEGACY-MARKER-GUID-1}',
getName: () => 'Director',
getComments: () => 'Existing comment message',
}
const mockSeqMarkers = {
getMarkers: vi.fn().mockReturnValue([mockLegacyMarker]),
createAddMarkerAction: vi.fn(),
}
const mockPpro = {
Marker: { MARKER_TYPE_COMMENT: 'CommentMarkerType' },
Markers: {
getMarkers: vi.fn().mockResolvedValue(mockSeqMarkers),
},
TickTime: {
TIME_ZERO: { ticks: '0' },
createWithSeconds: vi.fn((sec) => ({ seconds: sec })),
},
Properties: {
getProperties: vi.fn().mockResolvedValue({
createSetValueAction: vi.fn().mockReturnValue({}),
}),
},
}
// eslint-disable-next-line @typescript-eslint/no-explicit-any
;(globalThis as any).window = {
require: vi.fn().mockImplementation((name: string) => {
if (name === 'premierepro') return mockPpro
return null
}),
}
const comments: Partial<CommentInfo>[] = [
{
id: 'comm-1',
second: 10,
message: 'Existing comment message',
creator: { id: 'u1', name: 'Director' } as unknown as CommentInfo['creator'],
replies: [],
},
]
const mockProject = {
guid: 'proj-1',
lockedAccess: vi.fn((cb) => cb()),
executeTransaction: vi.fn(),
}
const mockSeq = {
guid: 'seq-guid-1',
getZeroPoint: vi.fn().mockResolvedValue({ seconds: 0 }),
}
const result = await syncCommentsToSequence(
mockProject as unknown as Project,
mockSeq as unknown as Sequence,
comments as CommentInfo[],
existingLink,
)
expect(result.addedCount).toBe(0)
expect(result.updatedLink.syncedMarkerGuids).toEqual(['legacy-marker-guid-1'])
expect(mockSeqMarkers.createAddMarkerAction).not.toHaveBeenCalled()
})
it('does not advance synced comments when executeTransaction returns false', async () => {
const mockSeqMarkers = {
getMarkers: vi.fn().mockReturnValue([]),
createAddMarkerAction: vi.fn().mockReturnValue({}),
}
const mockPpro = {
Marker: { MARKER_TYPE_COMMENT: 'CommentMarkerType' },
Markers: {
getMarkers: vi.fn().mockResolvedValue(mockSeqMarkers),
},
TickTime: {
TIME_ZERO: { ticks: '0' },
createWithSeconds: vi.fn((sec) => ({ seconds: sec })),
},
Properties: {
getProperties: vi.fn().mockResolvedValue({
createSetValueAction: vi.fn().mockReturnValue({}),
}),
},
}
// eslint-disable-next-line @typescript-eslint/no-explicit-any
;(globalThis as any).window = {
require: vi.fn().mockImplementation((name: string) => {
if (name === 'premierepro') return mockPpro
return null
}),
}
const comments: Partial<CommentInfo>[] = [
{ id: 'comm-1', second: 10, message: 'Already synced' },
{ id: 'comm-2', second: 20, message: 'New comment' },
]
const mockProject = {
guid: 'proj-1',
lockedAccess: vi.fn((cb) => cb()),
executeTransaction: vi.fn().mockReturnValue(false),
}
const mockSeq = {
guid: 'seq-guid-1',
getZeroPoint: vi.fn().mockResolvedValue({ seconds: 0 }),
}
const result = await syncCommentsToSequence(
mockProject as unknown as Project,
mockSeq as unknown as Sequence,
comments as CommentInfo[],
existingLink,
)
expect(result.addedCount).toBe(0)
expect(result.updatedLink.syncedCommentIds).toEqual(['comm-1'])
expect(result.updatedLink.totalCommentsSynced).toBe(1)
})
it('does not advance synced comments when executeTransaction throws an error', async () => {
const mockSeqMarkers = {
getMarkers: vi.fn().mockReturnValue([]),
createAddMarkerAction: vi.fn().mockReturnValue({}),
}
const mockPpro = {
Marker: { MARKER_TYPE_COMMENT: 'CommentMarkerType' },
Markers: {
getMarkers: vi.fn().mockResolvedValue(mockSeqMarkers),
},
TickTime: {
TIME_ZERO: { ticks: '0' },
createWithSeconds: vi.fn((sec) => ({ seconds: sec })),
},
Properties: {
getProperties: vi.fn().mockResolvedValue({
createSetValueAction: vi.fn().mockReturnValue({}),
}),
},
}
// eslint-disable-next-line @typescript-eslint/no-explicit-any
;(globalThis as any).window = {
require: vi.fn().mockImplementation((name: string) => {
if (name === 'premierepro') return mockPpro
return null
}),
}
const comments: Partial<CommentInfo>[] = [
{ id: 'comm-1', second: 10, message: 'Already synced' },
{ id: 'comm-2', second: 20, message: 'New comment' },
]
const mockProject = {
guid: 'proj-1',
lockedAccess: vi.fn(() => {
throw new Error('Transaction execution crashed')
}),
executeTransaction: vi.fn(),
}
const mockSeq = {
guid: 'seq-guid-1',
getZeroPoint: vi.fn().mockResolvedValue({ seconds: 0 }),
}
const result = await syncCommentsToSequence(
mockProject as unknown as Project,
mockSeq as unknown as Sequence,
comments as CommentInfo[],
existingLink,
)
expect(result.addedCount).toBe(0)
expect(result.updatedLink.syncedCommentIds).toEqual(['comm-1'])
expect(result.updatedLink.totalCommentsSynced).toBe(1)
})
})
})
+179
View File
@@ -0,0 +1,179 @@
import type { Project, Sequence } from '@adobe/premierepro'
import { getPremiereModule } from './premiere'
import type { LinkedSequenceAsset } from '../types/link'
import { normalizeGuid, saveSequenceLink } from './linkStorage'
import type { CommentInfo } from '@shumai/dtos'
import { fetchAssetComments, formatCommentBody } from './commentUtils'
export { fetchAssetComments, formatCommentBody }
export interface SyncCommentsResult {
updatedLink: LinkedSequenceAsset
addedCount: number
}
/**
* Synchronizes new Shumai comments to a Premiere Pro sequence as markers.
* Comments without timestamps (`second == null`) default to time 0 (sequence start),
* matching Frame.io convention. Newly created marker GUIDs are captured and stored
* so they can be accurately removed when the sequence is unlinked.
*/
export async function syncCommentsToSequence(
project: Project,
sequence: Sequence,
comments: CommentInfo[],
existingLink: LinkedSequenceAsset,
): Promise<SyncCommentsResult> {
const ppro = getPremiereModule()
const now = Date.now()
// Filter comments that have not been synced yet; non-timestamped comments default to time 0
const alreadySyncedSet = new Set(existingLink.syncedCommentIds)
const newComments = comments.filter((c) => !alreadySyncedSet.has(c.id))
const currentMarkerGuids = (existingLink.syncedMarkerGuids || [])
.map(normalizeGuid)
.filter(Boolean)
const needsGuidBackfill =
currentMarkerGuids.length < (existingLink.syncedCommentIds?.length || 0) &&
ppro?.Markers != null
if (newComments.length === 0 && !needsGuidBackfill) {
const updatedLink: LinkedSequenceAsset = {
...existingLink,
lastSyncAt: now,
}
await saveSequenceLink(project, sequence, updatedLink)
return { updatedLink, addedCount: 0 }
}
if (!ppro?.Markers || !ppro?.TickTime) {
console.warn('[markers] premierepro Markers or TickTime module not available')
return { updatedLink: existingLink, addedCount: 0 }
}
const newMarkerGuids: string[] = []
try {
const sequenceMarkers = await ppro.Markers.getMarkers(sequence)
let zeroPointSeconds = 0
try {
const zeroPoint = await sequence.getZeroPoint()
if (zeroPoint && typeof zeroPoint.seconds === 'number') {
zeroPointSeconds = zeroPoint.seconds
}
} catch {
// zeroPoint defaults to 0
}
// Capture existing marker GUIDs before adding new markers
let beforeGuids = new Set<string>()
try {
const beforeMarkers = sequenceMarkers.getMarkers() || []
beforeGuids = new Set(beforeMarkers.map((m) => normalizeGuid(m.guid)).filter(Boolean))
console.log('[markers] Existing markers before sync:', beforeMarkers.length)
} catch (err) {
console.warn('[markers] Could not get existing markers before sync:', err)
}
if (newComments.length > 0) {
let txSuccess = false
project.lockedAccess(() => {
txSuccess =
project.executeTransaction((compoundAction) => {
for (const comment of newComments) {
const markerSeconds = zeroPointSeconds + (comment.second ?? 0)
const startTime = ppro.TickTime.createWithSeconds(markerSeconds)
const duration = ppro.TickTime.TIME_ZERO
const markerName = comment.creator?.name || 'Comment'
const markerText = formatCommentBody(comment)
const addMarkerAction = sequenceMarkers.createAddMarkerAction(
markerName,
ppro.Marker.MARKER_TYPE_COMMENT,
startTime,
duration,
markerText,
)
compoundAction.addAction(addMarkerAction)
}
}, 'Sync Shumai Comments') === true
})
console.log('[markers] executeTransaction result:', txSuccess)
if (!txSuccess) {
console.warn('[markers] Failed to execute add markers transaction (returned false)')
return { updatedLink: existingLink, addedCount: 0 }
}
}
// Re-fetch fresh Markers object after transaction to ensure newly committed markers are seen
const freshSequenceMarkers = await ppro.Markers.getMarkers(sequence)
const afterMarkers = freshSequenceMarkers.getMarkers() || []
console.log('[markers] Markers after sync transaction:', afterMarkers.length)
// 1. Identify newly added markers by GUID difference
for (const m of afterMarkers) {
const guidStr = normalizeGuid(m.guid)
if (guidStr && !beforeGuids.has(guidStr) && !newMarkerGuids.includes(guidStr)) {
newMarkerGuids.push(guidStr)
}
}
// 2. Fallback / Backfill: Match any comment markers by content/author
const allExpectedComments = [...newComments]
if (needsGuidBackfill) {
const alreadySyncedComments = comments.filter((c) => alreadySyncedSet.has(c.id))
allExpectedComments.push(...alreadySyncedComments)
}
const currentKnownGuids = new Set([...currentMarkerGuids, ...newMarkerGuids])
for (const comment of allExpectedComments) {
const commentBody = formatCommentBody(comment)
const commentAuthor = comment.creator?.name || 'Comment'
for (const m of afterMarkers) {
const g = normalizeGuid(m.guid)
if (!g || currentKnownGuids.has(g)) continue
try {
const mName = m.getName()
const mComments = m.getComments()
if (
(mName === commentAuthor && mComments === commentBody) ||
(mComments && comment.message && mComments.includes(comment.message))
) {
newMarkerGuids.push(g)
currentKnownGuids.add(g)
break
}
} catch {
// ignore
}
}
}
console.log(
'[markers] Total newly captured/backfilled marker GUIDs:',
newMarkerGuids.length,
newMarkerGuids,
)
const updatedMarkerGuids = Array.from(
new Set([...currentMarkerGuids, ...newMarkerGuids.map(normalizeGuid)]),
)
const updatedLink: LinkedSequenceAsset = {
...existingLink,
syncedCommentIds: [...existingLink.syncedCommentIds, ...newComments.map((c) => c.id)],
syncedMarkerGuids: updatedMarkerGuids,
totalCommentsSynced: existingLink.totalCommentsSynced + newComments.length,
lastSyncAt: now,
}
await saveSequenceLink(project, sequence, updatedLink)
return { updatedLink, addedCount: newComments.length }
} catch (err) {
console.error('[markers] Failed to execute add markers transaction:', err)
return { updatedLink: existingLink, addedCount: 0 }
}
}
@@ -0,0 +1,248 @@
import { describe, it, expect, vi, beforeEach } from 'vitest'
import {
getActiveProject,
importFilesIntoProject,
promptSelectFolder,
promptSaveFile,
writeBinaryFile,
getPremiereModule,
getUxpModule,
} from './premiere'
import type { Project, Sequence } from '@adobe/premierepro'
describe('premiere service', () => {
beforeEach(() => {
vi.restoreAllMocks()
// Reset any global require mocks on globalThis
// eslint-disable-next-line @typescript-eslint/no-explicit-any
delete (globalThis as any).require
// Reset window mock on globalThis
// eslint-disable-next-line @typescript-eslint/no-explicit-any
delete (globalThis as any).window
})
describe('module getters', () => {
it('returns null when premierepro is not available', () => {
expect(getPremiereModule()).toBeNull()
})
it('returns null when uxp is not available', () => {
expect(getUxpModule()).toBeNull()
})
it('resolves premiere module from global require when present', () => {
const mockPpro = { Project: { getActiveProject: vi.fn() } }
// Mocking UXP window environment on globalThis
// eslint-disable-next-line @typescript-eslint/no-explicit-any
;(globalThis as any).window = {
require: vi.fn().mockImplementation((name: string) => {
if (name === 'premierepro') return mockPpro
return null
}),
}
expect(getPremiereModule()).toBe(mockPpro)
})
})
describe('getActiveProject', () => {
it('returns null when module is missing', async () => {
const project = await getActiveProject()
expect(project).toBeNull()
})
it('returns active project when available', async () => {
const mockProject = { name: 'MyProject.prproj' }
// Mocking UXP window environment on globalThis
// eslint-disable-next-line @typescript-eslint/no-explicit-any
;(globalThis as any).window = {
require: vi.fn().mockImplementation((name: string) => {
if (name === 'premierepro') {
return {
Project: {
getActiveProject: vi.fn().mockResolvedValue(mockProject),
},
}
}
return null
}),
}
const project = await getActiveProject()
expect(project).toBe(mockProject)
})
})
describe('importFilesIntoProject', () => {
it('returns false when filePaths is empty', async () => {
const project = { importFiles: vi.fn() } as unknown as Project
const success = await importFilesIntoProject(project, [])
expect(success).toBe(false)
expect(project.importFiles).not.toHaveBeenCalled()
})
it('calls project.importFiles with suppressUI true', async () => {
const project = {
importFiles: vi.fn().mockResolvedValue(true),
} as unknown as Project
const success = await importFilesIntoProject(project, ['/path/to/video.mp4'])
expect(success).toBe(true)
expect(project.importFiles).toHaveBeenCalledWith(['/path/to/video.mp4'], true, null, false)
})
it('handles import error gracefully', async () => {
const project = {
importFiles: vi.fn().mockRejectedValue(new Error('Import failed in host')),
} as unknown as Project
const success = await importFilesIntoProject(project, ['/path/to/video.mp4'])
expect(success).toBe(false)
})
})
describe('promptSelectFolder', () => {
it('throws when UXP storage is unavailable', async () => {
await expect(promptSelectFolder()).rejects.toThrow('UXP storage')
})
it('delegates to uxp.storage.localFileSystem.getFolder', async () => {
const mockFolder: UxpFolderEntry = {
isFile: false,
isFolder: true,
name: 'Downloads',
nativePath: '/Users/test/Downloads',
createFile: vi.fn(),
getEntries: vi.fn().mockResolvedValue([]),
}
// Mocking UXP window environment on globalThis
// eslint-disable-next-line @typescript-eslint/no-explicit-any
;(globalThis as any).window = {
require: vi.fn().mockImplementation((name: string) => {
if (name === 'uxp') {
return {
storage: {
localFileSystem: {
getFolder: vi.fn().mockResolvedValue(mockFolder),
},
},
}
}
return null
}),
}
const folder = await promptSelectFolder()
expect(folder).toBe(mockFolder)
})
})
describe('promptSaveFile', () => {
it('throws when UXP storage is unavailable', async () => {
await expect(promptSaveFile('test.mp4')).rejects.toThrow('UXP storage')
})
it('delegates to uxp.storage.localFileSystem.getFileForSaving', async () => {
const mockFile: UxpFileEntry = {
isFile: true,
isFolder: false,
name: 'test.mp4',
nativePath: '/path/test.mp4',
write: vi.fn(),
}
// Mocking UXP window environment on globalThis
// eslint-disable-next-line @typescript-eslint/no-explicit-any
;(globalThis as any).window = {
require: vi.fn().mockImplementation((name: string) => {
if (name === 'uxp') {
return {
storage: {
localFileSystem: {
getFileForSaving: vi.fn().mockResolvedValue(mockFile),
},
},
}
}
return null
}),
}
const file = await promptSaveFile('test.mp4')
expect(file).toBe(mockFile)
})
})
describe('writeBinaryFile', () => {
it('calls file.write with binary format option', async () => {
const mockFile: UxpFileEntry = {
isFile: true,
isFolder: false,
name: 'test.mp4',
nativePath: '/path/test.mp4',
write: vi.fn().mockResolvedValue(undefined),
}
// Mocking UXP window environment on globalThis
// eslint-disable-next-line @typescript-eslint/no-explicit-any
;(globalThis as any).window = {
require: vi.fn().mockImplementation((name: string) => {
if (name === 'uxp') {
return {
storage: {
formats: { binary: 'binary-format-token' },
},
}
}
return null
}),
}
const dummyBuffer = new ArrayBuffer(16)
await writeBinaryFile(mockFile, dummyBuffer)
expect(mockFile.write).toHaveBeenCalledWith(dummyBuffer, { format: 'binary-format-token' })
})
})
describe('sequence functions', () => {
it('getActiveSequence returns active sequence from project', async () => {
const { getActiveSequence } = await import('./premiere')
const mockSeq = { name: 'Seq 1', guid: 'guid-1' }
const mockProject = {
getActiveSequence: vi.fn().mockResolvedValue(mockSeq),
}
const seq = await getActiveSequence(mockProject as unknown as Project)
expect(seq).toBe(mockSeq)
})
it('getAllSequences returns array of sequences', async () => {
const { getAllSequences } = await import('./premiere')
const mockSeq1 = { name: 'Seq 1', guid: 'guid-1' }
const mockSeq2 = { name: 'Seq 2', guid: 'guid-2' }
const mockProject = {
getSequences: vi.fn().mockResolvedValue([mockSeq1, mockSeq2]),
}
const seqs = await getAllSequences(mockProject as unknown as Project)
expect(seqs).toHaveLength(2)
expect(seqs[0].name).toBe('Seq 1')
})
it('openSequenceInTimeline opens and activates sequence', async () => {
const { openSequenceInTimeline } = await import('./premiere')
const mockSeq = { name: 'Seq 1', guid: 'guid-1' }
const mockProject = {
openSequence: vi.fn().mockResolvedValue(true),
setActiveSequence: vi.fn().mockResolvedValue(true),
}
const result = await openSequenceInTimeline(
mockSeq as unknown as Sequence,
mockProject as unknown as Project,
)
expect(result).toBe(true)
expect(mockProject.openSequence).toHaveBeenCalledWith(mockSeq)
expect(mockProject.setActiveSequence).toHaveBeenCalledWith(mockSeq)
})
})
})
+178
View File
@@ -0,0 +1,178 @@
import type { Project, Sequence, premierepro } from '@adobe/premierepro'
/**
* Safely resolves the Premiere Pro host module (`premierepro`).
*/
export function getPremiereModule(): premierepro | null {
try {
// In UXP, host modules are available via require()
if (typeof window !== 'undefined' && 'require' in window) {
// Dynamic runtime property injected on window by Adobe UXP
// eslint-disable-next-line @typescript-eslint/no-explicit-any
return (window as any).require('premierepro')
}
if (typeof require !== 'undefined') {
// Adobe UXP host modules must be resolved dynamically at runtime via CommonJS require
// eslint-disable-next-line @typescript-eslint/no-require-imports
return require('premierepro')
}
} catch (err) {
console.warn('[UXP] premierepro module not available:', err)
}
return null
}
/**
* Safely resolves the UXP environment module (`uxp`).
*/
export function getUxpModule(): UxpModule | null {
try {
if (typeof window !== 'undefined' && 'require' in window) {
// Dynamic runtime property injected on window by Adobe UXP
// eslint-disable-next-line @typescript-eslint/no-explicit-any
return (window as any).require('uxp')
}
if (typeof require !== 'undefined') {
// Adobe UXP host modules must be resolved dynamically at runtime via CommonJS require
// eslint-disable-next-line @typescript-eslint/no-require-imports
return require('uxp')
}
} catch (err) {
console.warn('[UXP] uxp module not available:', err)
}
return null
}
/**
* Retrieves the currently active project in Premiere Pro.
*/
export async function getActiveProject(): Promise<Project | null> {
const ppro = getPremiereModule()
if (!ppro?.Project) {
return null
}
try {
return await ppro.Project.getActiveProject()
} catch (err) {
console.error('Failed to get active project:', err)
return null
}
}
/**
* Retrieves the currently active sequence of the project.
*/
export async function getActiveSequence(project?: Project | null): Promise<Sequence | null> {
const pr = project || (await getActiveProject())
if (!pr) return null
try {
const seq = await pr.getActiveSequence()
return seq || null
} catch (err) {
console.error('Failed to get active sequence:', err)
return null
}
}
/**
* Retrieves all sequences in the project.
*/
export async function getAllSequences(project?: Project | null): Promise<Sequence[]> {
const pr = project || (await getActiveProject())
if (!pr) return []
try {
const seqs = await pr.getSequences()
return seqs || []
} catch (err) {
console.error('Failed to get all sequences:', err)
return []
}
}
/**
* Opens and activates a sequence in the Premiere Pro timeline.
*/
export async function openSequenceInTimeline(
sequence: Sequence,
project?: Project | null,
): Promise<boolean> {
const pr = project || (await getActiveProject())
if (!pr) return false
try {
const opened = await pr.openSequence(sequence)
try {
await pr.setActiveSequence(sequence)
} catch {
// setActiveSequence may not be required if openSequence already focuses it
}
return opened ?? true
} catch (err) {
console.error('Failed to open sequence in timeline:', err)
return false
}
}
/**
* Imports one or more files into the Premiere Pro project root.
*/
export async function importFilesIntoProject(
project: Project,
filePaths: string[],
): Promise<boolean> {
if (!filePaths.length) return false
try {
return await project.importFiles(
filePaths,
true, // suppressUI
// @ts-expect-error Premiere Pro UXP requires null instead of undefined to default to project root
null, // targetBin; `null` defaults to project root
false, // asNumberedStills
)
} catch (err) {
console.error('Failed to import files into Premiere project:', err)
return false
}
}
/**
* Opens the native OS folder picker to ask the user where to save files.
* Returns the selected UxpFolderEntry, or null if the user cancelled.
*/
export async function promptSelectFolder(): Promise<UxpFolderEntry | null> {
const uxp = getUxpModule()
if (!uxp?.storage?.localFileSystem) {
throw new Error('UXP storage.localFileSystem is not available.')
}
try {
return await uxp.storage.localFileSystem.getFolder()
} catch (err) {
console.error('Error in promptSelectFolder:', err)
return null
}
}
/**
* Opens the native OS file picker to ask the user where to save a file.
* Returns the selected UxpFileEntry, or null if the user cancelled.
*/
export async function promptSaveFile(defaultName: string): Promise<UxpFileEntry | null> {
const uxp = getUxpModule()
if (!uxp?.storage?.localFileSystem) {
throw new Error('UXP storage.localFileSystem is not available.')
}
try {
return await uxp.storage.localFileSystem.getFileForSaving(defaultName)
} catch (err) {
console.error('Error in promptSaveFile:', err)
return null
}
}
/**
* Writes an ArrayBuffer into a UXP File entry as binary.
*/
export async function writeBinaryFile(file: UxpFileEntry, data: ArrayBuffer): Promise<void> {
const uxp = getUxpModule()
const format = uxp?.storage?.formats?.binary
await file.write(data, { format })
}
@@ -0,0 +1,55 @@
import { describe, it, expect, beforeEach } from 'vitest'
import { getStoredCredentials, saveStoredCredentials, clearStoredCredentials } from './storage'
const localStorageMock = (() => {
let store: Record<string, string> = {}
return {
getItem: (key: string) => store[key] || null,
setItem: (key: string, value: string) => {
store[key] = value.toString()
},
removeItem: (key: string) => {
delete store[key]
},
clear: () => {
store = {}
},
}
})()
Object.defineProperty(globalThis, 'localStorage', {
value: localStorageMock,
configurable: true,
writable: true,
})
describe('Storage Service', () => {
beforeEach(() => {
localStorage.clear()
})
it('returns null when no credentials are stored', () => {
expect(getStoredCredentials()).toBeNull()
})
it('saves and retrieves credentials correctly', () => {
saveStoredCredentials('http://localhost:3000', 'test-api-key')
const creds = getStoredCredentials()
expect(creds).toEqual({
endpoint: 'http://localhost:3000',
apiKey: 'test-api-key',
})
})
it('normalizes endpoint URL by stripping trailing slashes', () => {
saveStoredCredentials('https://api.shumai.io///', 'test-api-key')
const creds = getStoredCredentials()
expect(creds?.endpoint).toBe('https://api.shumai.io')
})
it('clears stored credentials', () => {
saveStoredCredentials('http://localhost:3000', 'test-api-key')
clearStoredCredentials()
expect(getStoredCredentials()).toBeNull()
})
})
+38
View File
@@ -0,0 +1,38 @@
export interface StoredCredentials {
endpoint: string
apiKey: string
}
const STORAGE_KEY_ENDPOINT = 'shumai_uxp_endpoint'
const STORAGE_KEY_API_KEY = 'shumai_uxp_api_key'
export function getStoredCredentials(): StoredCredentials | null {
try {
const endpoint = localStorage.getItem(STORAGE_KEY_ENDPOINT)
const apiKey = localStorage.getItem(STORAGE_KEY_API_KEY)
if (endpoint && apiKey) {
return { endpoint, apiKey }
}
} catch (err) {
console.error('Failed to read credentials from localStorage:', err)
}
return null
}
export function saveStoredCredentials(endpoint: string, apiKey: string): void {
try {
localStorage.setItem(STORAGE_KEY_ENDPOINT, endpoint.trim().replace(/\/+$/, ''))
localStorage.setItem(STORAGE_KEY_API_KEY, apiKey.trim())
} catch (err) {
console.error('Failed to save credentials to localStorage:', err)
}
}
export function clearStoredCredentials(): void {
try {
localStorage.removeItem(STORAGE_KEY_ENDPOINT)
localStorage.removeItem(STORAGE_KEY_API_KEY)
} catch (err) {
console.error('Failed to clear credentials from localStorage:', err)
}
}
+13
View File
@@ -0,0 +1,13 @@
export interface LinkedSequenceAsset {
sequenceGuid: string
sequenceName: string
assetId: string
assetName: string
assetThumbnailUrl?: string
endpoint?: string
projectId?: string
syncedCommentIds: string[]
syncedMarkerGuids?: string[]
lastSyncAt: number
totalCommentsSynced: number
}
+27
View File
@@ -0,0 +1,27 @@
export function formatDateAgo(dateInput?: string | number | Date | null): string {
if (!dateInput) return ''
const date =
typeof dateInput === 'string' || typeof dateInput === 'number' ? new Date(dateInput) : dateInput
if (isNaN(date.getTime())) return ''
const now = new Date()
const diffSec = Math.max(0, Math.floor((now.getTime() - date.getTime()) / 1000))
if (diffSec < 60) return 'just now'
const diffMin = Math.floor(diffSec / 60)
if (diffMin < 60) return `${diffMin}m ago`
const diffHours = Math.floor(diffMin / 60)
if (diffHours < 24) return `${diffHours}h ago`
const diffDays = Math.floor(diffHours / 24)
if (diffDays === 1) return 'yesterday'
if (diffDays < 30) return `${diffDays}d ago`
const diffMonths = Math.floor(diffDays / 30)
if (diffMonths < 12) return `${diffMonths}mo ago`
const diffYears = Math.floor(diffMonths / 12)
return `${diffYears}y ago`
}
@@ -0,0 +1,44 @@
import { describe, it, expect } from 'vitest'
import { formatBytes, formatDuration } from './format'
describe('formatBytes', () => {
it('handles null, undefined, 0 and invalid inputs', () => {
expect(formatBytes(null)).toBe('0 B')
expect(formatBytes(undefined)).toBe('0 B')
expect(formatBytes(0)).toBe('0 B')
expect(formatBytes(-100)).toBe('0 B')
expect(formatBytes(NaN)).toBe('0 B')
})
it('formats bytes correctly', () => {
expect(formatBytes(500)).toBe('500 B')
expect(formatBytes(1024)).toBe('1.0 KB')
expect(formatBytes(1536)).toBe('1.5 KB')
expect(formatBytes(1048576)).toBe('1.0 MB')
expect(formatBytes(1073741824)).toBe('1.0 GB')
})
})
describe('formatDuration', () => {
it('returns null for invalid or non-positive durations', () => {
expect(formatDuration(null)).toBeNull()
expect(formatDuration(undefined)).toBeNull()
expect(formatDuration(0)).toBeNull()
expect(formatDuration(-15)).toBeNull()
expect(formatDuration(NaN)).toBeNull()
})
it('formats seconds into MM:SS format', () => {
expect(formatDuration(5.4)).toBe('00:05')
expect(formatDuration(59)).toBe('00:59')
expect(formatDuration(60)).toBe('01:00')
expect(formatDuration(65)).toBe('01:05')
expect(formatDuration(3599)).toBe('59:59')
})
it('formats hours into H:MM:SS format', () => {
expect(formatDuration(3600)).toBe('1:00:00')
expect(formatDuration(3665)).toBe('1:01:05')
expect(formatDuration(36665)).toBe('10:11:05')
})
})
+26
View File
@@ -0,0 +1,26 @@
/**
* Formats a byte count into a human-readable size string (e.g. 1.2 MB, 450 KB).
*/
export function formatBytes(bytes?: number | null): string {
if (bytes == null || bytes === 0 || isNaN(bytes) || bytes < 0) return '0 B'
const units = ['B', 'KB', 'MB', 'GB', 'TB']
const i = Math.floor(Math.log(bytes) / Math.log(1024))
const safeIndex = Math.min(Math.max(0, i), units.length - 1)
return `${(bytes / Math.pow(1024, safeIndex)).toFixed(safeIndex === 0 ? 0 : 1)} ${units[safeIndex]}`
}
/**
* Formats duration in seconds into MM:SS or H:MM:SS format (e.g. 02:45, 1:12:30).
* Returns null if duration is invalid, zero or negative.
*/
export function formatDuration(seconds?: number | null): string | null {
if (seconds == null || isNaN(seconds) || seconds <= 0) return null
const totalSecs = Math.round(seconds)
const hours = Math.floor(totalSecs / 3600)
const minutes = Math.floor((totalSecs % 3600) / 60)
const secs = totalSecs % 60
if (hours > 0) {
return `${hours}:${minutes.toString().padStart(2, '0')}:${secs.toString().padStart(2, '0')}`
}
return `${minutes.toString().padStart(2, '0')}:${secs.toString().padStart(2, '0')}`
}
+72
View File
@@ -0,0 +1,72 @@
import { describe, it, expect } from 'vitest'
import { resolveAssetUrl, normalizeEndpoint, isSameEndpoint } from './url'
describe('resolveAssetUrl', () => {
it('returns undefined for empty or null inputs', () => {
expect(resolveAssetUrl(null, 'http://localhost:3000')).toBeUndefined()
expect(resolveAssetUrl(undefined, 'http://localhost:3000')).toBeUndefined()
expect(resolveAssetUrl('', 'http://localhost:3000')).toBeUndefined()
})
it('returns original url if endpoint is not provided', () => {
expect(resolveAssetUrl('/files/123')).toBe('/files/123')
expect(resolveAssetUrl('http://example.com/img.png')).toBe('http://example.com/img.png')
})
it('prepends endpoint to relative paths', () => {
expect(resolveAssetUrl('/files/shumai/cat.png', 'http://localhost:3000')).toBe(
'http://localhost:3000/files/shumai/cat.png',
)
expect(resolveAssetUrl('/files/shumai/cat.png', 'http://localhost:3000/')).toBe(
'http://localhost:3000/files/shumai/cat.png',
)
})
it('preserves absolute URLs intact even when hosts differ', () => {
const localRaw = 'http://localhost:3000/files/shumai/files/cat.webp'
const endpoint = 'http://127.0.0.1:3000'
expect(resolveAssetUrl(localRaw, endpoint)).toBe(localRaw)
const remoteEndpoint = 'https://shumai.example.com'
expect(resolveAssetUrl(localRaw, remoteEndpoint)).toBe(localRaw)
})
it('keeps matching absolute URLs intact', () => {
const raw = 'http://localhost:3000/files/shumai/cat.png'
expect(resolveAssetUrl(raw, 'http://localhost:3000')).toBe(raw)
})
it('preserves remote cloud storage presigned URLs without rewriting host', () => {
const r2Url =
'https://04e37a3c563610bccea6a3ce6f8618ca.r2.cloudflarestorage.com/shumai/files/01KYKNT8NEJ3Q1G6A6K08M2XHC/Float%2002-480p.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Signature=8112ab30'
const endpoint = 'https://staging.shumai.one'
expect(resolveAssetUrl(r2Url, endpoint)).toBe(r2Url)
})
})
describe('normalizeEndpoint', () => {
it('handles empty and null values', () => {
expect(normalizeEndpoint('')).toBe('')
expect(normalizeEndpoint(null)).toBe('')
expect(normalizeEndpoint(undefined)).toBe('')
})
it('trims whitespace and trailing slashes and converts to lower case', () => {
expect(normalizeEndpoint(' https://STAGING.shumai.one/// ')).toBe('https://staging.shumai.one')
expect(normalizeEndpoint('http://localhost:3000/')).toBe('http://localhost:3000')
})
})
describe('isSameEndpoint', () => {
it('returns true when endpoints match ignoring slashes and casing', () => {
expect(isSameEndpoint('https://staging.shumai.one/', 'https://STAGING.shumai.one')).toBe(true)
expect(isSameEndpoint('http://localhost:3000', 'http://localhost:3000/')).toBe(true)
})
it('returns false when endpoints differ', () => {
expect(isSameEndpoint('http://localhost:3000', 'https://staging.shumai.one')).toBe(false)
expect(isSameEndpoint('http://localhost:3000', 'http://127.0.0.1:3000')).toBe(false)
expect(isSameEndpoint('', 'http://localhost:3000')).toBe(false)
expect(isSameEndpoint(null, undefined)).toBe(false)
})
})

Some files were not shown because too many files have changed in this diff Show More