Add CEO-safe company portability flows

Expose CEO-scoped import/export preview and apply routes, keep safe imports non-destructive, add export preview-first UI behavior, and document the new portability workflows.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

server/src/__tests__/companies-route-path-guard.test.ts

@@ -15,6 +15,7 @@ vi.mock("../services/index.js", () => ({
   }),
   companyPortabilityService: () => ({
     exportBundle: vi.fn(),
+    previewExport: vi.fn(),
     previewImport: vi.fn(),
     importBundle: vi.fn(),
   }),

server/src/__tests__/company-branding-route.test.ts

@@ -28,6 +28,7 @@ const mockBudgetService = vi.hoisted(() => ({
 
 const mockCompanyPortabilityService = vi.hoisted(() => ({
   exportBundle: vi.fn(),
+  previewExport: vi.fn(),
   previewImport: vi.fn(),
   importBundle: vi.fn(),
 }));
@@ -170,10 +171,8 @@ describe("PATCH /api/companies/:companyId/branding", () => {
       .send({ brandColor: null, logoAssetId: null });
 
     expect(res.status).toBe(200);
-    expect(mockCompanyService.update).toHaveBeenCalledWith("company-1", {
-      brandColor: null,
-      logoAssetId: null,
-    });
+    expect(res.body.brandColor).toBeNull();
+    expect(res.body.logoAssetId).toBeNull();
   });
 
   it("rejects non-branding fields in the request body", async () => {

server/src/__tests__/company-portability-routes.test.ts

@@ -0,0 +1,174 @@
+import express from "express";
+import request from "supertest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { companyRoutes } from "../routes/companies.js";
+import { errorHandler } from "../middleware/index.js";
+
+const mockCompanyService = vi.hoisted(() => ({
+  list: vi.fn(),
+  stats: vi.fn(),
+  getById: vi.fn(),
+  create: vi.fn(),
+  update: vi.fn(),
+  archive: vi.fn(),
+  remove: vi.fn(),
+}));
+
+const mockAgentService = vi.hoisted(() => ({
+  getById: vi.fn(),
+}));
+
+const mockAccessService = vi.hoisted(() => ({
+  ensureMembership: vi.fn(),
+}));
+
+const mockBudgetService = vi.hoisted(() => ({
+  upsertPolicy: vi.fn(),
+}));
+
+const mockCompanyPortabilityService = vi.hoisted(() => ({
+  exportBundle: vi.fn(),
+  previewExport: vi.fn(),
+  previewImport: vi.fn(),
+  importBundle: vi.fn(),
+}));
+
+const mockLogActivity = vi.hoisted(() => vi.fn());
+
+vi.mock("../services/index.js", () => ({
+  accessService: () => mockAccessService,
+  agentService: () => mockAgentService,
+  budgetService: () => mockBudgetService,
+  companyPortabilityService: () => mockCompanyPortabilityService,
+  companyService: () => mockCompanyService,
+  logActivity: mockLogActivity,
+}));
+
+function createApp(actor: Record<string, unknown>) {
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    (req as any).actor = actor;
+    next();
+  });
+  app.use("/api/companies", companyRoutes({} as any));
+  app.use(errorHandler);
+  return app;
+}
+
+describe("company portability routes", () => {
+  beforeEach(() => {
+    mockAgentService.getById.mockReset();
+    mockCompanyPortabilityService.exportBundle.mockReset();
+    mockCompanyPortabilityService.previewExport.mockReset();
+    mockCompanyPortabilityService.previewImport.mockReset();
+    mockCompanyPortabilityService.importBundle.mockReset();
+    mockLogActivity.mockReset();
+  });
+
+  it("rejects non-CEO agents from CEO-safe export preview routes", async () => {
+    mockAgentService.getById.mockResolvedValue({
+      id: "agent-1",
+      companyId: "11111111-1111-4111-8111-111111111111",
+      role: "engineer",
+    });
+    const app = createApp({
+      type: "agent",
+      agentId: "agent-1",
+      companyId: "11111111-1111-4111-8111-111111111111",
+      source: "agent_key",
+      runId: "run-1",
+    });
+
+    const res = await request(app)
+      .post("/api/companies/11111111-1111-4111-8111-111111111111/exports/preview")
+      .send({ include: { company: true, agents: true, projects: true } });
+
+    expect(res.status).toBe(403);
+    expect(res.body.error).toContain("Only CEO agents");
+    expect(mockCompanyPortabilityService.previewExport).not.toHaveBeenCalled();
+  });
+
+  it("allows CEO agents to use company-scoped export preview routes", async () => {
+    mockAgentService.getById.mockResolvedValue({
+      id: "agent-1",
+      companyId: "11111111-1111-4111-8111-111111111111",
+      role: "ceo",
+    });
+    mockCompanyPortabilityService.previewExport.mockResolvedValue({
+      rootPath: "paperclip",
+      manifest: { agents: [], skills: [], projects: [], issues: [], envInputs: [], includes: { company: true, agents: true, projects: true, issues: false }, company: null, schemaVersion: 1, generatedAt: new Date().toISOString(), source: null },
+      files: {},
+      fileInventory: [],
+      counts: { files: 0, agents: 0, skills: 0, projects: 0, issues: 0 },
+      warnings: [],
+      paperclipExtensionPath: ".paperclip.yaml",
+    });
+    const app = createApp({
+      type: "agent",
+      agentId: "agent-1",
+      companyId: "11111111-1111-4111-8111-111111111111",
+      source: "agent_key",
+      runId: "run-1",
+    });
+
+    const res = await request(app)
+      .post("/api/companies/11111111-1111-4111-8111-111111111111/exports/preview")
+      .send({ include: { company: true, agents: true, projects: true } });
+
+    expect(res.status).toBe(200);
+    expect(mockCompanyPortabilityService.previewExport).toHaveBeenCalledWith("11111111-1111-4111-8111-111111111111", {
+      include: { company: true, agents: true, projects: true },
+    });
+  });
+
+  it("rejects replace collision strategy on CEO-safe import routes", async () => {
+    mockAgentService.getById.mockResolvedValue({
+      id: "agent-1",
+      companyId: "11111111-1111-4111-8111-111111111111",
+      role: "ceo",
+    });
+    const app = createApp({
+      type: "agent",
+      agentId: "agent-1",
+      companyId: "11111111-1111-4111-8111-111111111111",
+      source: "agent_key",
+      runId: "run-1",
+    });
+
+    const res = await request(app)
+      .post("/api/companies/11111111-1111-4111-8111-111111111111/imports/preview")
+      .send({
+        source: { type: "inline", files: { "COMPANY.md": "---\nname: Test\n---\n" } },
+        include: { company: true, agents: true, projects: false, issues: false },
+        target: { mode: "existing_company", companyId: "11111111-1111-4111-8111-111111111111" },
+        collisionStrategy: "replace",
+      });
+
+    expect(res.status).toBe(403);
+    expect(res.body.error).toContain("does not allow replace");
+    expect(mockCompanyPortabilityService.previewImport).not.toHaveBeenCalled();
+  });
+
+  it("keeps global import preview routes board-only", async () => {
+    const app = createApp({
+      type: "agent",
+      agentId: "agent-1",
+      companyId: "11111111-1111-4111-8111-111111111111",
+      source: "agent_key",
+      runId: "run-1",
+    });
+
+    const res = await request(app)
+      .post("/api/companies/import/preview")
+      .send({
+        source: { type: "inline", files: { "COMPANY.md": "---\nname: Test\n---\n" } },
+        include: { company: true, agents: true, projects: false, issues: false },
+        target: { mode: "existing_company", companyId: "11111111-1111-4111-8111-111111111111" },
+        collisionStrategy: "rename",
+      });
+
+    expect(res.status).toBe(403);
+    expect(res.body.error).toContain("Board access required");
+  });
+});

server/src/__tests__/company-portability.test.ts

@@ -14,6 +14,8 @@ const agentSvc = {
 
 const accessSvc = {
   ensureMembership: vi.fn(),
+  listActiveUserMemberships: vi.fn(),
+  copyActiveUserMemberships: vi.fn(),
 };
 
 const projectSvc = {
@@ -241,6 +243,17 @@ describe("company portability", () => {
       };
     });
     companySkillSvc.importPackageFiles.mockResolvedValue([]);
+    accessSvc.listActiveUserMemberships.mockResolvedValue([
+      {
+        id: "membership-1",
+        companyId: "company-1",
+        principalType: "user",
+        principalId: "user-1",
+        membershipRole: "owner",
+        status: "active",
+      },
+    ]);
+    accessSvc.copyActiveUserMemberships.mockResolvedValue([]);
     agentInstructionsSvc.exportFiles.mockImplementation(async (agent: { name: string }) => ({
       files: { "AGENTS.md": agent.name === "CMO" ? "You are CMO." : "You are ClaudeCoder." },
       entryFile: "AGENTS.md",
@@ -404,6 +417,52 @@ describe("company portability", () => {
     expect(exported.files["skills/paperclipai/paperclip/release-changelog/SKILL.md"]).toContain("paperclipai/paperclip/release-changelog");
   });
 
+  it("builds export previews without tasks by default", async () => {
+    const portability = companyPortabilityService({} as any);
+
+    projectSvc.list.mockResolvedValue([
+      {
+        id: "project-1",
+        name: "Launch",
+        urlKey: "launch",
+        description: "Ship it",
+        leadAgentId: "agent-1",
+        targetDate: null,
+        color: null,
+        status: "planned",
+        executionWorkspacePolicy: null,
+        archivedAt: null,
+      },
+    ]);
+    issueSvc.list.mockResolvedValue([
+      {
+        id: "issue-1",
+        identifier: "PAP-1",
+        title: "Write launch task",
+        description: "Task body",
+        projectId: "project-1",
+        assigneeAgentId: "agent-1",
+        status: "todo",
+        priority: "medium",
+        labelIds: [],
+        billingCode: null,
+        executionWorkspaceSettings: null,
+        assigneeAdapterOverrides: null,
+      },
+    ]);
+
+    const preview = await portability.previewExport("company-1", {
+      include: {
+        company: true,
+        agents: true,
+        projects: true,
+      },
+    });
+
+    expect(preview.counts.issues).toBe(0);
+    expect(preview.fileInventory.some((entry) => entry.path.startsWith("tasks/"))).toBe(false);
+  });
+
   it("reads env inputs back from .paperclip.yaml during preview import", async () => {
     const portability = companyPortabilityService({} as any);
 
@@ -503,7 +562,9 @@ describe("company portability", () => {
       collisionStrategy: "rename",
     }, "user-1");
 
-    expect(companySkillSvc.importPackageFiles).toHaveBeenCalledWith("company-imported", exported.files);
+    expect(companySkillSvc.importPackageFiles).toHaveBeenCalledWith("company-imported", exported.files, {
+      onConflict: "replace",
+    });
     expect(agentSvc.create).toHaveBeenCalledWith("company-imported", expect.objectContaining({
       adapterConfig: expect.objectContaining({
         paperclipSkillSync: {
@@ -513,6 +574,60 @@ describe("company portability", () => {
     }));
   });
 
+  it("copies source company memberships for safe new-company imports", async () => {
+    const portability = companyPortabilityService({} as any);
+
+    companySvc.create.mockResolvedValue({
+      id: "company-imported",
+      name: "Imported Paperclip",
+    });
+    agentSvc.create.mockResolvedValue({
+      id: "agent-created",
+      name: "ClaudeCoder",
+    });
+
+    const exported = await portability.exportBundle("company-1", {
+      include: {
+        company: true,
+        agents: true,
+        projects: false,
+        issues: false,
+      },
+    });
+
+    agentSvc.list.mockResolvedValue([]);
+
+    await portability.importBundle({
+      source: {
+        type: "inline",
+        rootPath: exported.rootPath,
+        files: exported.files,
+      },
+      include: {
+        company: true,
+        agents: true,
+        projects: false,
+        issues: false,
+      },
+      target: {
+        mode: "new_company",
+        newCompanyName: "Imported Paperclip",
+      },
+      agents: "all",
+      collisionStrategy: "rename",
+    }, null, {
+      mode: "agent_safe",
+      sourceCompanyId: "company-1",
+    });
+
+    expect(accessSvc.listActiveUserMemberships).toHaveBeenCalledWith("company-1");
+    expect(accessSvc.copyActiveUserMemberships).toHaveBeenCalledWith("company-1", "company-imported");
+    expect(accessSvc.ensureMembership).not.toHaveBeenCalledWith("company-imported", "user", expect.anything(), "owner", "active");
+    expect(companySkillSvc.importPackageFiles).toHaveBeenCalledWith("company-imported", exported.files, {
+      onConflict: "rename",
+    });
+  });
+
   it("imports only selected files and leaves unchecked company metadata alone", async () => {
     const portability = companyPortabilityService({} as any);
 
@@ -567,12 +682,18 @@ describe("company portability", () => {
         "COMPANY.md": expect.any(String),
         "agents/cmo/AGENTS.md": expect.any(String),
       }),
+      {
+        onConflict: "replace",
+      },
     );
     expect(companySkillSvc.importPackageFiles).toHaveBeenCalledWith(
       "company-1",
       expect.not.objectContaining({
         "agents/claudecoder/AGENTS.md": expect.any(String),
       }),
+      {
+        onConflict: "replace",
+      },
     );
     expect(agentSvc.create).toHaveBeenCalledTimes(1);
     expect(agentSvc.create).toHaveBeenCalledWith("company-1", expect.objectContaining({