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
This commit is contained in:
Yiling-J
2026-11-13 11:43:08 +08:00
committed by GitHub
parent 97c2939b5e
commit c55804a548
20 changed files with 369 additions and 66 deletions
+2
View File
@@ -77,6 +77,8 @@ Add any additional context, caveats, or follow-up work.
## Workspace Architecture
**Single-team design**: Each instance has one team, automatically created when the first user signs up.
The project is a Bun Workspaces monorepo (Bun runtime, Hono API, Prisma + Pgvector18 DB, React + Tailwind CSS + Shadcn UI frontend):
- **`packages/webui`**: React frontend (`bun run dev` runs on port 3000).
+1
View File
@@ -8,6 +8,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
### 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
+7 -1
View File
@@ -105,7 +105,7 @@ When the output is piped instead of shown in a terminal, tables are printed as t
### 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.
@@ -113,6 +113,12 @@ 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. Folders are listed first.
+26
View File
@@ -4,6 +4,7 @@ import {
copyAssets,
createComment,
createFolder,
createProject,
createVersionStack,
deleteAsset,
downloadAsset,
@@ -118,6 +119,31 @@ describe('shumai-cli', () => {
})
})
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()
@@ -73,6 +73,7 @@ describe('operation-backed agent tools', () => {
'create_comment',
'create_file',
'create_folder',
'create_project',
'create_version',
'create_version_stack',
'delete_asset',
@@ -103,6 +104,12 @@ describe('operation-backed agent tools', () => {
const params = (name: string) =>
Object.keys((getTool(name).parameters as unknown as { properties: object }).properties)
expect(params('create_folder')).toEqual(['parent', 'name'])
expect(params('create_project')).toEqual([
'name',
'teamId',
'coverImageKey',
'enableNotification',
])
expect(params('rename_asset')).toEqual(['assetId', 'name'])
expect(params('move_assets')).toEqual(['assetIds', 'newParentId'])
expect(params('delete_asset')).toEqual(['assetId'])
@@ -141,6 +148,49 @@ describe('operation-backed agent tools', () => {
})
})
describe('create_project', () => {
it('uses ctx.teamId when teamId is omitted and logs project_create audit', async () => {
vi.spyOn(projectService, 'createProject').mockResolvedValue({
id: 'proj-new',
name: 'Campaign',
teamId: 'team-1',
rootFolder: 'root-new',
enableNotification: true,
updatedAt: '2026-01-01T00:00:00.000Z',
} satisfies ProjectInfo)
const { output } = await run('create_project', { name: 'Campaign' })
expect(authzService.hasPermission).toHaveBeenCalledWith({
user: { id: 'user-1' },
permission: Permission.Edit,
type: ResourceType.Team,
id: 'team-1',
})
expect(projectService.createProject).toHaveBeenCalledWith(
{ id: 'user-1' },
{ teamId: 'team-1', name: 'Campaign', coverImageKey: undefined, enableNotification: true },
)
expect(auditLogService.logAction).toHaveBeenCalledWith(
expect.objectContaining({
action: AuditAction.project_create,
teamId: 'team-1',
projectId: 'proj-new',
itemId: 'proj-new',
userId: 'user-1',
agentId: 'agent-1',
via: 'agent',
}),
)
expect(output).toEqual({
id: 'proj-new',
name: 'Campaign',
teamId: 'team-1',
rootFolderId: 'root-new',
})
})
})
describe('list_assets', () => {
beforeEach(() => {
vi.spyOn(assetService, 'listChildren').mockResolvedValue({
@@ -82,6 +82,34 @@ describe('MCP server and /api/ops (integration)', () => {
expect(audit).toMatchObject({ userId: owner.id, teamId, projectId, via: 'mcp' })
})
it('lets an MCP client create a project without specifying teamId and create a folder in it', async () => {
const client = await connect(ownerToken)
const createdProject = await client.callTool({
name: 'create_project',
arguments: { name: 'MCP Created Project' },
})
expect(createdProject.isError).toBeFalsy()
const created = createdProject.structuredContent as {
id: string
name: string
teamId: string
rootFolderId: string
}
expect(created).toMatchObject({
id: expect.any(String),
name: 'MCP Created Project',
teamId,
rootFolderId: expect.any(String),
})
const createdFolder = await client.callTool({
name: 'create_folder',
arguments: { parent: created.rootFolderId, name: 'Inside New Project' },
})
expect(createdFolder.isError).toBeFalsy()
})
it("enforces the token owner's permissions", async () => {
const client = await connect(reviewerToken)
+1
View File
@@ -59,6 +59,7 @@ describe('MCP server', () => {
'create_comment',
'create_file',
'create_folder',
'create_project',
'create_version',
'create_version_stack',
'delete_asset',
+28 -13
View File
@@ -5,7 +5,12 @@ import { authzService, Permission, ResourceType } from '@shumai/core/src/authz/a
import { projectService } from '@shumai/core/src/project/project'
import { assetService } from '@shumai/core/src/asset/asset'
import type { ProjectInfo } from '@shumai/dtos'
import { copyAssetsOp, moveAssetsOp, runOperation } from '@shumai/core/src/operations'
import {
copyAssetsOp,
createProjectOp,
moveAssetsOp,
runOperation,
} from '@shumai/core/src/operations'
vi.mock('./middleware/auth', () => ({
authMiddleware: async (
@@ -98,12 +103,24 @@ describe('project api', () => {
)
})
it('POST /teams/:teamId/projects', async () => {
vi.mocked(projectService.createProject).mockResolvedValue({
it('POST /teams/:teamId/projects runs create_project and returns ProjectInfo', async () => {
vi.mocked(runOperation).mockResolvedValue({
id: 'foo',
name: 'foo.png',
teamId: 't',
rootFolderId: 'root1',
})
const projectInfo: ProjectInfo = {
id: 'foo',
name: 'foo.png',
teamId: 't',
rootFolder: 'root1',
coverImage: 'http://s3/bucket/key',
} as any) // eslint-disable-line @typescript-eslint/no-explicit-any
coverImageKey: 'key',
enableNotification: true,
updatedAt: '2026-01-01T00:00:00.000Z',
}
vi.mocked(projectService.getProject).mockResolvedValue(projectInfo)
const res = await app.request('/teams/t/projects', {
method: 'POST',
@@ -113,15 +130,13 @@ describe('project api', () => {
expect(res.status).toBe(200)
const json = await res.json()
expect(json.id).toBe('foo')
expect(json.name).toBe('foo.png')
expect(json.coverImage).toBe('http://s3/bucket/key')
expect(authzService.hasPermission).toHaveBeenCalledWith({
user: expect.anything(),
permission: Permission.Edit,
type: ResourceType.Team,
id: 't',
})
expect(json).toEqual(projectInfo)
expect(runOperation).toHaveBeenCalledWith(
createProjectOp,
{ userId: 'user1', via: 'api' },
{ teamId: 't', name: 'foo.png', coverImageKey: 'key', enableNotification: true },
)
expect(projectService.getProject).toHaveBeenCalledWith('foo')
})
it('PUT /projects/:projectId', async () => {
+12 -21
View File
@@ -18,7 +18,12 @@ import {
import { listMembersQuerySchema, AuditAction } from '@shumai/dtos'
import type { Prisma } from '@shumai/db'
import { auditLogService } from '@shumai/core/src/auditLog/auditLog'
import { copyAssetsOp, moveAssetsOp, runOperation } from '@shumai/core/src/operations'
import {
copyAssetsOp,
createProjectOp,
moveAssetsOp,
runOperation,
} from '@shumai/core/src/operations'
type User = Prisma.UserGetPayload<Record<string, never>>
@@ -50,27 +55,13 @@ const route = new Hono<{ Variables: { user: User } }>()
const user = c.get('user')
const req = c.req.valid('json')
await authzService.hasPermission({
user,
permission: Permission.Edit,
type: ResourceType.Team,
id: teamId,
})
const newProject = await runOperation(
createProjectOp,
{ userId: user.id, via: 'api' },
{ teamId, ...req },
)
const newProject = await projectService.createProject(user, {
teamId,
...req,
})
await auditLogService.logAction({
action: AuditAction.project_create,
teamId,
userId: user.id,
projectId: newProject.id,
itemId: newProject.id,
})
return c.json(newProject)
return c.json(await projectService.getProject(newProject.id))
})
.put('/projects/:projectId', zValidator('json', updateProjectRequestSchema), async (c) => {
const projectId = c.req.param('projectId')
+10 -12
View File
@@ -77,7 +77,6 @@ vi.mock('@shumai/core/src/workflowTask/workflowTask', () => ({
describe('team api', () => {
const app = new Hono().use('*', authMiddleware).route('/', teamRoute)
let mockCreateTeam: any // eslint-disable-line @typescript-eslint/no-explicit-any
let mockGetUserTeams: any // eslint-disable-line @typescript-eslint/no-explicit-any
let mockGetMe: any // eslint-disable-line @typescript-eslint/no-explicit-any
let mockGetTeamMembers: any // eslint-disable-line @typescript-eslint/no-explicit-any
@@ -90,7 +89,6 @@ describe('team api', () => {
let mockUpdateMe: any // eslint-disable-line @typescript-eslint/no-explicit-any
beforeEach(() => {
mockCreateTeam = vi.spyOn(teamService, 'createTeam')
mockGetUserTeams = vi.spyOn(teamService, 'getUserTeams')
mockGetMe = vi.spyOn(teamService, 'getMe')
mockGetTeamMembers = vi.spyOn(teamService, 'getTeamMembers')
@@ -108,9 +106,13 @@ describe('team api', () => {
vi.restoreAllMocks()
})
it('POST /teams creates a new team', async () => {
const mockTeam = { id: 't1', name: 'New Team', updatedAt: new Date() }
mockCreateTeam.mockResolvedValue(mockTeam)
it('POST /teams returns 404 without creating a team or writing an audit entry', async () => {
const createTeam = vi.spyOn(teamService, 'createTeam').mockResolvedValue({
id: 't1',
name: 'New Team',
updatedAt: new Date(),
})
const { auditLogService } = await import('@shumai/core/src/auditLog/auditLog')
const res = await app.request('/teams', {
method: 'POST',
@@ -120,13 +122,9 @@ describe('team api', () => {
}),
})
expect(res.status).toBe(200)
const data = await res.json()
expect(data.id).toBe('t1')
expect(mockCreateTeam).toHaveBeenCalledWith(
expect.objectContaining({ id: 'user1' }),
expect.objectContaining({ name: 'New Team' }),
)
expect(res.status).toBe(404)
expect(createTeam).not.toHaveBeenCalled()
expect(auditLogService.logAction).not.toHaveBeenCalled()
})
it('GET /teams returns user teams', async () => {
-14
View File
@@ -4,7 +4,6 @@ import { authzService, Permission, ResourceType } from '@shumai/core/src/authz/a
import { teamService } from '@shumai/core/src/team/team'
import { userMetadataService } from '@shumai/core/src/user-metadata/user-metadata'
import {
createTeamRequestSchema,
getUserTeamsRequestSchema,
updateTeamSettingsRequestSchema,
listMembersQuerySchema,
@@ -35,19 +34,6 @@ import type { Prisma } from '@shumai/db'
type User = Prisma.UserGetPayload<Record<string, never>>
const route = new Hono<{ Variables: { user: User } }>()
.post('/teams', zValidator('json', createTeamRequestSchema), async (c) => {
const user = c.get('user')
const req = c.req.valid('json')
const newTeam = await teamService.createTeam(user, req)
await auditLogService.logAction({
action: AuditAction.team_create,
teamId: newTeam.id,
userId: user.id,
itemId: newTeam.id,
})
return c.json(newTeam)
})
.get('/teams', zValidator('query', getUserTeamsRequestSchema), async (c) => {
const user = c.get('user')
const pg = c.req.valid('query')
+1
View File
@@ -32,6 +32,7 @@ export { listCommentsOp } from './comment/list-comments'
export { resolveCommentOp } from './comment/resolve-comment'
export { listMetadataFieldsOp } from './metadata/list-metadata-fields'
export { updateAssetMetadataOp } from './metadata/update-asset-metadata'
export { createProjectOp } from './project/create-project'
export { listProjectsOp } from './project/list-projects'
export { completeUploadOp } from './upload/complete-upload'
export { createFileOp } from './upload/create-file'
@@ -6,6 +6,7 @@ import { projectService } from '@shumai/core/src/project/project'
import { assetService } from '@shumai/core/src/asset/asset'
import {
createFolderOp,
createProjectOp,
deleteAssetOp,
listAssetsOp,
listProjectsOp,
@@ -262,6 +263,97 @@ describe('asset and project Operations', () => {
})
})
describe('create_project', () => {
it('creates a project with explicit teamId and logs audit with via and agentId', async () => {
const agentUser = await prisma.user.create({
data: { name: 'Ops Agent', email: 'ops-agent@test.com', password: 'pw', type: 'agent' },
})
const agent = await prisma.agent.create({
data: {
id: agentUser.id,
type: 'chat',
teamId,
config: { provider: 'openai', model: 'gpt-4o' },
},
})
const created = await runOperation(
createProjectOp,
{ userId: owner.id, via: 'agent', agentId: agent.id },
{ name: ' Agent Project ', teamId },
)
expect(created).toEqual({
id: expect.any(String),
name: 'Agent Project',
teamId,
rootFolderId: expect.any(String),
})
const row = await prisma.project.findUniqueOrThrow({ where: { id: created.id } })
expect(row.rootFolderId).toBe(created.rootFolderId)
expect(row.shareRootId).toEqual(expect.any(String))
const [audit] = await auditRows(AuditAction.project_create)
expect(audit).toMatchObject({
teamId,
projectId: created.id,
itemId: created.id,
userId: owner.id,
agentId: agent.id,
via: 'agent',
})
})
it('resolves teamId from ctx.teamId or sole team membership when omitted', async () => {
const fromCtx = await runOperation(
createProjectOp,
{ userId: owner.id, via: 'agent', teamId },
{ name: 'From Context' },
)
expect(fromCtx.teamId).toBe(teamId)
const fromSoleMembership = await runOperation(createProjectOp, as(owner, 'cli'), {
name: 'From Sole Team',
})
expect(fromSoleMembership.teamId).toBe(teamId)
})
it('rejects omitted teamId when the user belongs to multiple teams', async () => {
const secondTeam = await prisma.team.create({ data: { name: 'Second Team' } })
await prisma.teamMember.create({
data: { teamId: secondTeam.id, userId: owner.id, role: 'owner' },
})
await expect(
runOperation(createProjectOp, as(owner, 'mcp'), { name: 'Ambiguous' }),
).rejects.toMatchObject({ status: 400 })
expect(await prisma.project.count({ where: { name: 'Ambiguous' } })).toBe(0)
expect(await auditRows(AuditAction.project_create)).toHaveLength(0)
})
it('rejects reviewers, project-scoped members, and non-members with no side effects', async () => {
const projectScoped = await prisma.user.create({
data: { name: 'Scoped', email: 'ops-scoped@test.com', password: 'pw' },
})
await prisma.teamMember.create({
data: { teamId, userId: projectScoped.id, role: 'editor', scope: 'project' },
})
for (const user of [reviewer, projectScoped, outsider]) {
await expect(
runOperation(createProjectOp, as(user), { name: 'Blocked', teamId }),
).rejects.toMatchObject({ status: 403 })
}
await expect(
runOperation(createProjectOp, as(outsider), { name: 'NoTeam' }),
).rejects.toMatchObject({ status: 403 })
expect(await prisma.project.count({ where: { name: { in: ['Blocked', 'NoTeam'] } } })).toBe(0)
expect(await auditRows(AuditAction.project_create)).toHaveLength(0)
})
})
describe('list_projects', () => {
it("lists the caller's projects with their root folder", async () => {
const result = await runOperation(listProjectsOp, as(reviewer), {})
@@ -0,0 +1,64 @@
import { HTTPException } from 'hono/http-exception'
import { createProject } from '@shumai/operations'
import { AuditAction } from '@shumai/dtos'
import { Permission, ResourceType } from '@shumai/core/src/authz/authz'
import { projectService } from '@shumai/core/src/project/project'
import { teamService } from '@shumai/core/src/team/team'
import type { OperationContext } from '../context'
import { asBadRequest, badRequest } from '../errors'
import { implementOperation } from '../implement'
async function resolveTeamId(
inputTeamId: string | undefined,
ctx: OperationContext,
): Promise<string> {
if (inputTeamId) return inputTeamId
if (ctx.teamId) return ctx.teamId
const teams = await teamService.getUserTeams({
userId: ctx.userId,
pagination: { first: 2 },
})
if (teams.data.length === 1) return teams.data[0].id
if (teams.data.length === 0) {
throw new HTTPException(403, { message: 'User is not a member of any team' })
}
throw badRequest('Multiple teams found for user; specify teamId')
}
export const createProjectOp = implementOperation(createProject, {
authz: async (input, ctx) => {
const teamId = await resolveTeamId(input.teamId, ctx)
return [{ permission: Permission.Edit, type: ResourceType.Team, id: teamId }]
},
prepare: async (input, ctx) => ({
teamId: await resolveTeamId(input.teamId, ctx),
}),
execute: async (input, ctx, { teamId }) => {
const project = await asBadRequest(() =>
projectService.createProject(
{ id: ctx.userId },
{
teamId,
name: input.name,
coverImageKey: input.coverImageKey,
enableNotification: input.enableNotification ?? true,
},
),
)
return {
id: project.id,
name: project.name,
teamId: project.teamId,
rootFolderId: project.rootFolder ?? null,
}
},
audit: (_input, output) => [
{
action: AuditAction.project_create,
itemId: output.id,
teamId: output.teamId,
projectId: output.id,
},
],
})
+2
View File
@@ -17,6 +17,7 @@ import { resolveCommentOp } from './comment/resolve-comment'
import type { Operation } from './implement'
import { listMetadataFieldsOp } from './metadata/list-metadata-fields'
import { updateAssetMetadataOp } from './metadata/update-asset-metadata'
import { createProjectOp } from './project/create-project'
import { listProjectsOp } from './project/list-projects'
import { completeUploadOp } from './upload/complete-upload'
import { createFileOp } from './upload/create-file'
@@ -43,6 +44,7 @@ function defineRegistry<const TOps extends readonly Operation[]>(
/** Every implemented Operation. Each definition in `@shumai/operations` must appear exactly once. */
export const operations = defineRegistry([
createProjectOp,
listProjectsOp,
listAssetsOp,
searchAssetsOp,
-5
View File
@@ -4,11 +4,6 @@ import { paginationPageInfoSchema, paginationParamsSchema } from './pagination'
export { UserType, TeamMemberScope }
export const createTeamRequestSchema = z.object({
name: z.string(),
})
export type CreateTeamRequest = z.infer<typeof createTeamRequestSchema>
export const teamInfoSchema = z.object({
id: z.string(),
name: z.string(),
+1
View File
@@ -19,6 +19,7 @@ export { createComment } from './comment/create-comment'
export { resolveComment } from './comment/resolve-comment'
export * from './metadata/list-metadata-fields'
export * from './metadata/update-asset-metadata'
export { createProject } from './project/create-project'
export { listProjects } from './project/list-projects'
export * from './upload/create-file'
export { createVersion } from './upload/create-version'
@@ -0,0 +1,40 @@
import { z } from 'zod'
import { defineOperation } from '../define'
import { projectSummarySchema } from '../schemas'
export const createProject = defineOperation({
name: 'create_project',
title: 'Create Project',
description:
'Create a new project in the team. Returns the created project, including its rootFolderId ' +
'to use as the parent for asset operations.',
input: z.object({
name: z.string().trim().min(1).describe('The name of the new project to create.'),
teamId: z
.string()
.min(1)
.optional()
.describe('Optional team ID. Uses the active or sole team when omitted.'),
coverImageKey: z
.string()
.min(1)
.optional()
.describe('Optional S3 storage key for the project cover image.'),
enableNotification: z
.boolean()
.optional()
.describe('Whether project notifications are enabled (defaults to true).'),
}),
output: projectSummarySchema,
surfaces: ['agent', 'mcp', 'cli'],
annotations: { readOnly: false, destructive: false },
cli: {
command: ['project', 'create'],
description: 'Create a new project.',
positional: ['name'],
flags: { teamId: ['-t', '--team'] },
omit: ['coverImageKey', 'enableNotification'],
format: (output) =>
`Created project "${output.name}" (ID: ${output.id}, rootFolderId: ${output.rootFolderId ?? ''})`,
},
})
+2
View File
@@ -23,6 +23,7 @@ describe('operation registry', () => {
'create_comment',
'create_file',
'create_folder',
'create_project',
'create_version',
'create_version_stack',
'delete_asset',
@@ -122,6 +123,7 @@ describe('operation registry', () => {
.filter((d) => d.cli)
.map((d) => [d.name, [...(d.cli?.command ?? []), ...(d.cli?.aliases ?? [])]])
expect(commands).toEqual([
['create_project', ['project', 'create']],
['list_projects', ['project', 'ls']],
['list_assets', ['ls']],
['search_assets', ['search']],
+2
View File
@@ -16,6 +16,7 @@ import { resolveComment } from './comment/resolve-comment'
import type { AnyOperationDefinition, Surface } from './define'
import { listMetadataFields } from './metadata/list-metadata-fields'
import { updateAssetMetadata } from './metadata/update-asset-metadata'
import { createProject } from './project/create-project'
import { listProjects } from './project/list-projects'
import { completeUpload } from './upload/complete-upload'
import { createFile } from './upload/create-file'
@@ -29,6 +30,7 @@ import { removeVersion } from './version/remove-version'
* `@shumai/core/src/operations/registry.ts` (enforced by the type checker).
*/
export const operationDefinitions = [
createProject,
listProjects,
listAssets,
searchAssets,