canopycms 0.0.0

package/src/api/branch-merge.test.ts

@@ -0,0 +1,163 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { markAsMerged } from './branch-merge'
+import type { ApiContext, ApiRequest } from './types'
+import type { BranchName } from '../paths/types'
+import { RESERVED_GROUPS } from '../authorization'
+import { mockConsole } from '../test-utils/console-spy.js'
+
+// Extract handler for testing
+const markAsMergedHandler = markAsMerged.handler
+
+vi.mock('../branch-metadata', () => {
+  return {
+    BranchMetadataFileManager: vi.fn().mockImplementation(() => ({
+      save: vi.fn().mockResolvedValue(undefined),
+    })),
+    getBranchMetadataFileManager: vi.fn().mockImplementation(() => ({
+      save: vi.fn().mockResolvedValue(undefined),
+    })),
+  }
+})
+
+describe('branch merge api - markAsMerged', () => {
+  let ctx: ApiContext
+  let req: ApiRequest
+  let mockGithubService: any
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+
+    mockGithubService = {
+      getPullRequest: vi.fn().mockResolvedValue({ merged: true }),
+    }
+
+    ctx = {
+      services: {
+        checkBranchAccess: vi.fn().mockResolvedValue({ allowed: true }),
+        githubService: mockGithubService,
+      } as any,
+      getBranchContext: vi.fn().mockResolvedValue({
+        baseRoot: '/test',
+        branchRoot: '/test/feature-x',
+        branch: {
+          name: 'feature/x',
+          status: 'submitted',
+          createdBy: 'user1',
+          updatedAt: new Date().toISOString(),
+          pullRequestNumber: 42,
+        },
+      }),
+    } as any
+
+    req = {
+      user: { userId: 'admin1', groups: [RESERVED_GROUPS.ADMINS] },
+      body: {},
+    } as any
+  })
+
+  it('marks a submitted branch as archived after PR is merged', async () => {
+    const result = await markAsMergedHandler(ctx, req, { branch: 'feature/x' as BranchName })
+
+    expect(result.ok).toBe(true)
+    expect(result.status).toBe(200)
+    expect(result.data?.branch.status).toBe('archived')
+  })
+
+  it('verifies PR is merged on GitHub before marking', async () => {
+    await markAsMergedHandler(ctx, req, { branch: 'feature/x' as BranchName })
+
+    expect(mockGithubService.getPullRequest).toHaveBeenCalledWith(42)
+  })
+
+  it('returns 404 if branch not found', async () => {
+    ctx.getBranchContext = vi.fn().mockResolvedValue(null)
+
+    const result = await markAsMergedHandler(ctx, req, {
+      branch: 'nonexistent' as BranchName,
+    })
+
+    expect(result.ok).toBe(false)
+    expect(result.status).toBe(404)
+    expect(result.error).toContain('not found')
+  })
+
+  it('returns 403 if user lacks admin access', async () => {
+    req.user.groups = [] // Not an admin
+
+    const result = await markAsMergedHandler(ctx, req, { branch: 'feature/x' as BranchName })
+
+    expect(result.ok).toBe(false)
+    expect(result.status).toBe(403)
+    expect(result.error).toContain('Admin access required')
+  })
+
+  it('returns 400 if branch is not submitted', async () => {
+    ctx.getBranchContext = vi.fn().mockResolvedValue({
+      baseRoot: '/test',
+      branchRoot: '/test/feature-x',
+      branch: {
+        name: 'feature/x',
+        status: 'editing',
+        createdBy: 'user1',
+        updatedAt: new Date().toISOString(),
+      },
+    })
+
+    const result = await markAsMergedHandler(ctx, req, { branch: 'feature/x' as BranchName })
+
+    expect(result.ok).toBe(false)
+    expect(result.status).toBe(400)
+    expect(result.error).toContain('status is "editing"')
+  })
+
+  it('returns 400 if branch has no PR', async () => {
+    ctx.getBranchContext = vi.fn().mockResolvedValue({
+      baseRoot: '/test',
+      branchRoot: '/test/feature-x',
+      branch: {
+        name: 'feature/x',
+        status: 'submitted',
+        createdBy: 'user1',
+        updatedAt: new Date().toISOString(),
+      },
+    })
+
+    const result = await markAsMergedHandler(ctx, req, { branch: 'feature/x' as BranchName })
+
+    expect(result.ok).toBe(false)
+    expect(result.status).toBe(400)
+    expect(result.error).toContain('no pull request')
+  })
+
+  it('returns 400 if PR is not merged on GitHub', async () => {
+    mockGithubService.getPullRequest = vi.fn().mockResolvedValue({ merged: false })
+
+    const result = await markAsMergedHandler(ctx, req, { branch: 'feature/x' as BranchName })
+
+    expect(result.ok).toBe(false)
+    expect(result.status).toBe(400)
+    expect(result.error).toContain('not merged on GitHub')
+  })
+
+  it('handles github service errors gracefully', async () => {
+    const consoleSpy = mockConsole()
+    mockGithubService.getPullRequest = vi.fn().mockRejectedValue(new Error('API error'))
+
+    const result = await markAsMergedHandler(ctx, req, { branch: 'feature/x' as BranchName })
+
+    // Should still succeed (manual override allowed)
+    expect(result.ok).toBe(true)
+    expect(result.status).toBe(200)
+    expect(consoleSpy).toHaveErrored('Failed to verify PR merge status')
+    consoleSpy.restore()
+  })
+
+  it('works without github service (manual mode)', async () => {
+    ctx.services.githubService = undefined
+
+    const result = await markAsMergedHandler(ctx, req, { branch: 'feature/x' as BranchName })
+
+    expect(result.ok).toBe(true)
+    expect(result.status).toBe(200)
+  })
+})

package/src/api/branch-merge.ts

@@ -0,0 +1,113 @@
+import { z } from 'zod'
+import { branchNameSchema } from './validators'
+import type { ApiContext, ApiRequest, ApiResponse } from './types'
+import type { BranchContext } from '../types'
+import { getBranchMetadataFileManager } from '../branch-metadata'
+import { defineEndpoint } from './route-builder'
+
+const markAsMergedParamsSchema = z.object({
+  branch: branchNameSchema,
+})
+
+export interface MarkAsMergedParams {
+  branch: string
+}
+
+/** Response type for branch merge operations */
+export type BranchMergeResponse = ApiResponse<{
+  branch: { name: string; status: string }
+}>
+
+const markAsMergedHandler = async (
+  gc: { branchContext: BranchContext },
+  ctx: ApiContext,
+  _req: ApiRequest,
+  params: z.infer<typeof markAsMergedParamsSchema>,
+): Promise<BranchMergeResponse> => {
+  const { branchContext } = gc
+  const { branch: branchName } = params
+
+  // Verify branch is submitted with a PR
+  if (branchContext.branch.status !== 'submitted') {
+    return {
+      ok: false,
+      status: 400,
+      error: `Cannot mark as merged: branch status is "${branchContext.branch.status}", expected "submitted"`,
+    }
+  }
+
+  if (!branchContext.branch.pullRequestNumber) {
+    return {
+      ok: false,
+      status: 400,
+      error: 'Cannot mark as merged: no pull request associated with this branch',
+    }
+  }
+
+  // Optionally verify PR is actually merged via GitHub API
+  if (ctx.services.githubService) {
+    try {
+      const pr = await ctx.services.githubService.getPullRequest(
+        branchContext.branch.pullRequestNumber,
+      )
+      if (!pr.merged) {
+        return {
+          ok: false,
+          status: 400,
+          error: `Cannot mark as merged: PR #${branchContext.branch.pullRequestNumber} is not merged on GitHub`,
+        }
+      }
+    } catch (err) {
+      console.error(`CanopyCMS: Failed to verify PR merge status for ${branchName}:`, err)
+      // Don't fail if we can't verify - allow manual override
+    }
+  }
+
+  // Update branch status to 'archived'
+  const meta = getBranchMetadataFileManager(branchContext.branchRoot, branchContext.baseRoot)
+  await meta.save({
+    branch: {
+      status: 'archived',
+    },
+  })
+
+  // Optionally delete remote branch (disabled by default for safety)
+  // if (ctx.services.githubService && req.body?.deleteRemoteBranch) {
+  //   try {
+  //     await ctx.services.githubService.deleteBranch(branchName)
+  //   } catch (err) {
+  //     console.error(`CanopyCMS: Failed to delete remote branch ${branchName}:`, err)
+  //   }
+  // }
+
+  // Comments.json is already in the branch workspace at .canopycms/comments.json
+  // It will be preserved with the archived branch - no action needed
+
+  return {
+    ok: true,
+    status: 200,
+    data: {
+      branch: {
+        name: branchName,
+        status: 'archived',
+      },
+    },
+  }
+}
+
+/**
+ * Mark a branch as merged and archived after PR is merged on GitHub
+ * POST /:branch/mark-merged
+ */
+export const markAsMerged = defineEndpoint({
+  namespace: 'workflow',
+  name: 'markMerged',
+  method: 'POST',
+  path: '/:branch/mark-merged',
+  params: markAsMergedParamsSchema,
+  responseType: 'BranchMergeResponse',
+  response: {} as BranchMergeResponse,
+  defaultMockData: { branch: { name: 'test-branch', status: 'archived' } },
+  guards: ['admin', 'branch'] as const,
+  handler: markAsMergedHandler,
+})

package/src/api/branch-review.test.ts

@@ -0,0 +1,297 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { BranchName } from '../paths/types'
+
+const mockMetadataSave = vi.fn().mockResolvedValue({
+  schemaVersion: 1,
+  branch: {
+    name: 'feature/x',
+    status: 'editing',
+    access: {},
+    createdBy: 'u1',
+    createdAt: 'now',
+    updatedAt: 'now',
+  },
+})
+
+vi.mock('../branch-metadata', () => ({
+  BranchMetadataFileManager: vi.fn().mockImplementation(() => ({
+    save: mockMetadataSave,
+  })),
+  getBranchMetadataFileManager: vi.fn().mockImplementation(() => ({
+    save: mockMetadataSave,
+  })),
+}))
+
+import { requestChanges, approveBranch } from './branch-review'
+import { RESERVED_GROUPS } from '../authorization'
+import { mockConsole, createMockApiContext, createMockBranchContext } from '../test-utils'
+
+// Extract handlers for testing
+const requestChangesHandler = requestChanges.handler
+const approveBranchHandler = approveBranch.handler
+
+const baseContext = createMockBranchContext({
+  branchName: 'feature/x',
+  status: 'submitted',
+  pullRequestNumber: 123,
+  pullRequestUrl: 'https://github.com/owner/repo/pull/123',
+})
+
+const makeCtx = (githubService?: any) =>
+  createMockApiContext({
+    branchContext: baseContext,
+    services: githubService ? { githubService } : undefined,
+  })
+
+describe('branch review api - requestChanges', () => {
+  it('returns 404 if branch not found', async () => {
+    const ctx = makeCtx()
+    ctx.getBranchContext = vi.fn().mockResolvedValue(null)
+    const res = await requestChangesHandler(
+      ctx,
+      {
+        user: {
+          type: 'authenticated',
+          userId: 'u1',
+          groups: [RESERVED_GROUPS.ADMINS],
+        },
+      },
+      { branch: 'missing' as BranchName },
+      {},
+    )
+    expect(res.status).toBe(404)
+    expect(res.error).toBe('Branch not found')
+  })
+
+  it('returns 403 if user not admin/reviewer', async () => {
+    const res = await requestChangesHandler(
+      makeCtx(),
+      { user: { type: 'authenticated', userId: 'u1', groups: [] } },
+      { branch: 'feature/x' as BranchName },
+      {},
+    )
+    expect(res.status).toBe(403)
+    expect(res.error).toContain('Reviewer access required')
+  })
+
+  it('returns 400 if branch not submitted', async () => {
+    const ctx = makeCtx()
+    ctx.getBranchContext = vi.fn().mockResolvedValue({
+      ...baseContext,
+      branch: { ...baseContext.branch, status: 'editing' },
+    })
+    const res = await requestChangesHandler(
+      ctx,
+      {
+        user: {
+          type: 'authenticated',
+          userId: 'u1',
+          groups: [RESERVED_GROUPS.ADMINS],
+        },
+      },
+      { branch: 'feature/x' as BranchName },
+      {},
+    )
+    expect(res.status).toBe(400)
+    expect(res.error).toContain("Only 'submitted' branches can have changes requested")
+  })
+
+  it('requests changes when allowed (admin)', async () => {
+    const res = await requestChangesHandler(
+      makeCtx(),
+      {
+        user: {
+          type: 'authenticated',
+          userId: 'u1',
+          groups: [RESERVED_GROUPS.ADMINS],
+        },
+      },
+      { branch: 'feature/x' as BranchName },
+      {},
+    )
+    expect(res.ok).toBe(true)
+    expect(res.status).toBe(200)
+  })
+
+  it('requests changes when allowed (reviewer)', async () => {
+    const res = await requestChangesHandler(
+      makeCtx(),
+      {
+        user: {
+          type: 'authenticated',
+          userId: 'u1',
+          groups: [RESERVED_GROUPS.REVIEWERS],
+        },
+      },
+      { branch: 'feature/x' as BranchName },
+      {},
+    )
+    expect(res.ok).toBe(true)
+    expect(res.status).toBe(200)
+  })
+
+  it('converts PR to draft if github service available', async () => {
+    const convertToDraft = vi.fn().mockResolvedValue(undefined)
+    const githubService = { convertToDraft }
+    const res = await requestChangesHandler(
+      makeCtx(githubService),
+      {
+        user: {
+          type: 'authenticated',
+          userId: 'u1',
+          groups: [RESERVED_GROUPS.ADMINS],
+        },
+      },
+      { branch: 'feature/x' as BranchName },
+      {},
+    )
+    expect(res.ok).toBe(true)
+    expect(convertToDraft).toHaveBeenCalledWith(123)
+  })
+
+  it('handles github service errors gracefully', async () => {
+    const consoleSpy = mockConsole()
+    const convertToDraft = vi.fn().mockRejectedValue(new Error('API error'))
+    const githubService = { convertToDraft }
+    const res = await requestChangesHandler(
+      makeCtx(githubService),
+      {
+        user: {
+          type: 'authenticated',
+          userId: 'u1',
+          groups: [RESERVED_GROUPS.ADMINS],
+        },
+      },
+      { branch: 'feature/x' as BranchName },
+      {},
+    )
+    // Should still succeed even if GitHub API fails
+    expect(res.ok).toBe(true)
+    expect(res.status).toBe(200)
+    expect(consoleSpy).toHaveErrored('Failed to convert PR to draft')
+    consoleSpy.restore()
+  })
+
+  it('skips PR conversion if no PR number', async () => {
+    const convertToDraft = vi.fn()
+    const githubService = { convertToDraft }
+    const ctx = makeCtx(githubService)
+    ctx.getBranchContext = vi.fn().mockResolvedValue({
+      ...baseContext,
+      branch: { ...baseContext.branch, pullRequestNumber: undefined },
+    })
+    const res = await requestChangesHandler(
+      ctx,
+      {
+        user: {
+          type: 'authenticated',
+          userId: 'u1',
+          groups: [RESERVED_GROUPS.ADMINS],
+        },
+      },
+      { branch: 'feature/x' as BranchName },
+      {},
+    )
+    expect(res.ok).toBe(true)
+    expect(convertToDraft).not.toHaveBeenCalled()
+  })
+
+  it('accepts optional comment parameter', async () => {
+    const res = await requestChangesHandler(
+      makeCtx(),
+      {
+        user: {
+          type: 'authenticated',
+          userId: 'u1',
+          groups: [RESERVED_GROUPS.ADMINS],
+        },
+      },
+      { branch: 'feature/x' as BranchName },
+      { comment: 'Please fix the typo' },
+    )
+    expect(res.ok).toBe(true)
+  })
+})
+
+describe('branch review api - approveBranch', () => {
+  it('returns 404 if branch not found', async () => {
+    const ctx = makeCtx()
+    ctx.getBranchContext = vi.fn().mockResolvedValue(null)
+    const res = await approveBranchHandler(
+      ctx,
+      {
+        user: {
+          type: 'authenticated',
+          userId: 'u1',
+          groups: [RESERVED_GROUPS.ADMINS],
+        },
+      },
+      { branch: 'missing' as BranchName },
+    )
+    expect(res.status).toBe(404)
+    expect(res.error).toBe('Branch not found')
+  })
+
+  it('returns 403 if user not admin/reviewer', async () => {
+    const res = await approveBranchHandler(
+      makeCtx(),
+      { user: { type: 'authenticated', userId: 'u1', groups: [] } },
+      { branch: 'feature/x' as BranchName },
+    )
+    expect(res.status).toBe(403)
+    expect(res.error).toContain('Reviewer access required')
+  })
+
+  it('returns 400 if branch not submitted', async () => {
+    const ctx = makeCtx()
+    ctx.getBranchContext = vi.fn().mockResolvedValue({
+      ...baseContext,
+      branch: { ...baseContext.branch, status: 'editing' },
+    })
+    const res = await approveBranchHandler(
+      ctx,
+      {
+        user: {
+          type: 'authenticated',
+          userId: 'u1',
+          groups: [RESERVED_GROUPS.ADMINS],
+        },
+      },
+      { branch: 'feature/x' as BranchName },
+    )
+    expect(res.status).toBe(400)
+    expect(res.error).toContain("Only 'submitted' branches can be approved")
+  })
+
+  it('approves branch when allowed (admin)', async () => {
+    const res = await approveBranchHandler(
+      makeCtx(),
+      {
+        user: {
+          type: 'authenticated',
+          userId: 'u1',
+          groups: [RESERVED_GROUPS.ADMINS],
+        },
+      },
+      { branch: 'feature/x' as BranchName },
+    )
+    expect(res.ok).toBe(true)
+    expect(res.status).toBe(200)
+  })
+
+  it('approves branch when allowed (reviewer)', async () => {
+    const res = await approveBranchHandler(
+      makeCtx(),
+      {
+        user: {
+          type: 'authenticated',
+          userId: 'u1',
+          groups: [RESERVED_GROUPS.REVIEWERS],
+        },
+      },
+      { branch: 'feature/x' as BranchName },
+    )
+    expect(res.ok).toBe(true)
+    expect(res.status).toBe(200)
+  })
+})

package/src/api/branch-review.ts

@@ -0,0 +1,136 @@
+import { z } from 'zod'
+import { branchNameSchema } from './validators'
+import type { ApiContext, ApiRequest } from './types'
+import type { BranchContext } from '../types'
+import type { BranchResponse } from './branch'
+import { getBranchMetadataFileManager } from '../branch-metadata'
+import { defineEndpoint } from './route-builder'
+import { syncConvertToDraft } from './github-sync'
+
+export interface RequestChangesBody {
+  comment?: string
+}
+
+const branchParamSchema = z.object({
+  branch: branchNameSchema,
+})
+
+const requestChangesBodySchema = z.object({
+  comment: z.string().optional(),
+})
+
+const requestChangesHandler = async (
+  gc: { branchContext: BranchContext },
+  ctx: ApiContext,
+  _req: ApiRequest,
+  _params: z.infer<typeof branchParamSchema>,
+  _body?: z.infer<typeof requestChangesBodySchema>,
+): Promise<BranchResponse> => {
+  const { branchContext } = gc
+
+  // Verify branch is submitted
+  if (branchContext.branch.status !== 'submitted') {
+    return {
+      ok: false,
+      status: 400,
+      error: `Cannot request changes on branch with status '${branchContext.branch.status}'. Only 'submitted' branches can have changes requested.`,
+    }
+  }
+
+  // Convert PR to draft (sync via githubService, or async via task queue)
+  await syncConvertToDraft(ctx, branchContext)
+
+  // Update branch status to 'editing'
+  const meta = getBranchMetadataFileManager(branchContext.branchRoot, branchContext.baseRoot)
+
+  const updated = await meta.save({
+    branch: { name: branchContext.branch.name, status: 'editing' },
+  })
+
+  // TODO: Optionally record comment in .canopycms/comments.json when comment system is implemented
+
+  return { ok: true, status: 200, data: { branch: updated.branch } }
+}
+
+const approveBranchHandler = async (
+  gc: { branchContext: BranchContext },
+  _ctx: ApiContext,
+  _req: ApiRequest,
+  _params: z.infer<typeof branchParamSchema>,
+): Promise<BranchResponse> => {
+  const { branchContext } = gc
+
+  // Verify branch is submitted
+  if (branchContext.branch.status !== 'submitted') {
+    return {
+      ok: false,
+      status: 400,
+      error: `Cannot approve branch with status '${branchContext.branch.status}'. Only 'submitted' branches can be approved.`,
+    }
+  }
+
+  // Update branch status to 'approved'
+  const meta = getBranchMetadataFileManager(branchContext.branchRoot, branchContext.baseRoot)
+
+  const updated = await meta.save({
+    branch: { name: branchContext.branch.name, status: 'approved' },
+  })
+
+  // TODO: Optionally call githubService.approvePullRequest() when GitHub integration is needed
+
+  return { ok: true, status: 200, data: { branch: updated.branch } }
+}
+
+/**
+ * Request changes on a submitted branch (reviewer action)
+ * POST /:branch/request-changes
+ */
+export const requestChanges = defineEndpoint({
+  namespace: 'workflow',
+  name: 'requestChanges',
+  method: 'POST',
+  path: '/:branch/request-changes',
+  params: branchParamSchema,
+  body: requestChangesBodySchema,
+  bodyType: 'RequestChangesBody',
+  responseType: 'BranchResponse',
+  response: {} as BranchResponse,
+  defaultMockData: {
+    branch: {
+      name: 'test-branch',
+      status: 'editing',
+      access: {},
+      createdBy: 'user-1',
+      createdAt: '2024-01-01',
+      updatedAt: '2024-01-01',
+    },
+  },
+  guards: ['reviewer', 'branch'] as const,
+  handler: requestChangesHandler,
+})
+
+/**
+ * Approve a branch (optional for v1)
+ * POST /:branch/approve
+ */
+export const approveBranch = defineEndpoint({
+  namespace: 'workflow',
+  name: 'approve',
+  method: 'POST',
+  path: '/:branch/approve',
+  params: branchParamSchema,
+  responseType: 'BranchResponse',
+  response: {} as BranchResponse,
+  defaultMockData: {
+    branch: {
+      name: 'test-branch',
+      status: 'approved',
+      access: {},
+      createdBy: 'user-1',
+      createdAt: '2024-01-01',
+      updatedAt: '2024-01-01',
+    },
+  },
+  guards: ['reviewer', 'branch'] as const,
+  handler: approveBranchHandler,
+})