paperclip/cli/src/__tests__/onboard.test.ts

import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { onboard } from "../commands/onboard.js";
import type { PaperclipConfig } from "../config/schema.js";

const runCommandMock = vi.hoisted(() => vi.fn());

vi.mock("../commands/run.js", () => ({
  runCommand: runCommandMock,
}));

const ORIGINAL_ENV = { ...process.env };
const ORIGINAL_CWD = process.cwd();
const ORIGINAL_PATH = process.env.PATH;
const ORIGINAL_EXIT_CODE = process.exitCode;

function createExistingConfigFixture() {
  const root = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-onboard-"));
  const runtimeRoot = path.join(root, "runtime");
  const configPath = path.join(root, ".paperclip", "config.json");
  const config: PaperclipConfig = {
    $meta: {
      version: 1,
      updatedAt: "2026-03-29T00:00:00.000Z",
      source: "configure",
    },
    database: {
      mode: "embedded-postgres",
      embeddedPostgresDataDir: path.join(runtimeRoot, "db"),
      embeddedPostgresPort: 54329,
      backup: {
        enabled: true,
        intervalMinutes: 60,
        retentionDays: 30,
        dir: path.join(runtimeRoot, "backups"),
      },
    },
    logging: {
      mode: "file",
      logDir: path.join(runtimeRoot, "logs"),
    },
    server: {
      deploymentMode: "local_trusted",
      exposure: "private",
      host: "127.0.0.1",
      port: 3100,
      allowedHostnames: [],
      serveUi: true,
    },
    auth: {
      baseUrlMode: "auto",
      disableSignUp: false,
    },
    telemetry: {
      enabled: true,
    },
    storage: {
      provider: "local_disk",
      localDisk: {
        baseDir: path.join(runtimeRoot, "storage"),
      },
      s3: {
        bucket: "paperclip",
        region: "us-east-1",
        prefix: "",
        forcePathStyle: false,
      },
    },
    secrets: {
      provider: "local_encrypted",
      strictMode: false,
      localEncrypted: {
        keyFilePath: path.join(runtimeRoot, "secrets", "master.key"),
      },
    },
  };

  fs.mkdirSync(path.dirname(configPath), { recursive: true });
  fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });

  return { configPath, configText: fs.readFileSync(configPath, "utf8") };
}

function createFreshConfigPath() {
  const root = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-onboard-fresh-"));
  return path.join(root, ".paperclip", "config.json");
}

describe("onboard", () => {
  beforeEach(() => {
    process.env = { ...ORIGINAL_ENV };
    delete process.env.PAPERCLIP_AGENT_JWT_SECRET;
    delete process.env.PAPERCLIP_TOOL_ACTION_SIGNING_SECRET;
    delete process.env.PAPERCLIP_SECRETS_MASTER_KEY;
    delete process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE;
    delete process.env.PAPERCLIP_DB_BACKUP_DIR;
    delete process.env.PAPERCLIP_DB_BACKUP_ENABLED;
    delete process.env.PAPERCLIP_DB_BACKUP_INTERVAL_MINUTES;
    delete process.env.PAPERCLIP_DB_BACKUP_RETENTION_DAYS;
    delete process.env.PAPERCLIP_STORAGE_PROVIDER;
    delete process.env.PAPERCLIP_STORAGE_LOCAL_DIR;
    delete process.env.PAPERCLIP_SECRETS_PROVIDER;
    delete process.env.PAPERCLIP_SECRETS_STRICT_MODE;
    delete process.env.PAPERCLIP_HOME;
    delete process.env.PAPERCLIP_CONFIG;
    delete process.env.PAPERCLIP_INSTANCE_ID;
    delete process.env.PAPERCLIP_BIND;
    delete process.env.PAPERCLIP_BIND_HOST;
    delete process.env.PAPERCLIP_TAILNET_BIND_HOST;
    delete process.env.PAPERCLIP_OPEN_ON_LISTEN;
    delete process.env.PAPERCLIP_NO_BROWSER;
    delete process.env.HOST;
    runCommandMock.mockReset();
  });

  afterEach(() => {
    process.env = { ...ORIGINAL_ENV };
    process.chdir(ORIGINAL_CWD);
    process.exitCode = ORIGINAL_EXIT_CODE;
  });

  it("preserves an existing config when rerun without flags", async () => {
    const fixture = createExistingConfigFixture();

    await onboard({ config: fixture.configPath });

    expect(fs.readFileSync(fixture.configPath, "utf8")).toBe(fixture.configText);
    expect(fs.existsSync(`${fixture.configPath}.backup`)).toBe(false);
    expect(fs.existsSync(path.join(path.dirname(fixture.configPath), ".env"))).toBe(true);
  });

  it("preserves an existing config when rerun with --yes", async () => {
    const fixture = createExistingConfigFixture();

    await onboard({ config: fixture.configPath, yes: true, invokedByRun: true });

    expect(fs.readFileSync(fixture.configPath, "utf8")).toBe(fixture.configText);
    expect(fs.existsSync(`${fixture.configPath}.backup`)).toBe(false);
    expect(fs.existsSync(path.join(path.dirname(fixture.configPath), ".env"))).toBe(true);
  });

  it("does not opt into opening a browser for a non-interactive existing setup", async () => {
    const fixture = createExistingConfigFixture();

    await onboard({ config: fixture.configPath, yes: true });

    expect(runCommandMock).toHaveBeenCalledWith({ config: fixture.configPath, repair: true, yes: true });
    expect(process.env.PAPERCLIP_OPEN_ON_LISTEN).toBeUndefined();
  });

  it.each([
    ["existing", () => createExistingConfigFixture().configPath],
    ["fresh", () => createFreshConfigPath()],
  ])("opens the browser once while an interactive %s setup starts", async (_label, configPathForTest) => {
    const configPath = configPathForTest();
    const stdinIsTTY = process.stdin.isTTY;
    const stdoutIsTTY = process.stdout.isTTY;
    let openOnListenDuringRun: string | undefined;
    Object.defineProperty(process.stdin, "isTTY", { configurable: true, value: true });
    Object.defineProperty(process.stdout, "isTTY", { configurable: true, value: true });
    runCommandMock.mockImplementation(async () => {
      openOnListenDuringRun = process.env.PAPERCLIP_OPEN_ON_LISTEN;
    });

    try {
      await onboard({ config: configPath, yes: true });
    } finally {
      Object.defineProperty(process.stdin, "isTTY", { configurable: true, value: stdinIsTTY });
      Object.defineProperty(process.stdout, "isTTY", { configurable: true, value: stdoutIsTTY });
    }

    expect(runCommandMock).toHaveBeenCalledWith({ config: configPath, repair: true, yes: true });
    expect(openOnListenDuringRun).toBe("true");
    expect(process.env.PAPERCLIP_OPEN_ON_LISTEN).toBeUndefined();
  });

  it.each([
    ["PAPERCLIP_NO_BROWSER", "1"],
    ["PAPERCLIP_OPEN_ON_LISTEN", "false"],
  ])("respects the interactive browser opt-out %s", async (key, value) => {
    const configPath = createFreshConfigPath();
    const stdinIsTTY = process.stdin.isTTY;
    const stdoutIsTTY = process.stdout.isTTY;
    let openOnListenDuringRun: string | undefined;
    Object.defineProperty(process.stdin, "isTTY", { configurable: true, value: true });
    Object.defineProperty(process.stdout, "isTTY", { configurable: true, value: true });
    process.env[key] = value;
    runCommandMock.mockImplementation(async () => {
      openOnListenDuringRun = process.env.PAPERCLIP_OPEN_ON_LISTEN;
    });

    try {
      await onboard({ config: configPath, yes: true });
    } finally {
      Object.defineProperty(process.stdin, "isTTY", { configurable: true, value: stdinIsTTY });
      Object.defineProperty(process.stdout, "isTTY", { configurable: true, value: stdoutIsTTY });
    }

    expect(runCommandMock).toHaveBeenCalledWith({ config: configPath, repair: true, yes: true });
    expect(openOnListenDuringRun).not.toBe("true");
    expect(process.env[key]).toBe(value);
  });

  it("backs up invalid config bytes and refuses --yes replacement", async () => {
    const configPath = createFreshConfigPath();
    const invalidBytes = Buffer.from('{"database": invalid}\n', "utf8");
    fs.mkdirSync(path.dirname(configPath), { recursive: true });
    fs.writeFileSync(configPath, invalidBytes);

    await onboard({ config: configPath, yes: true, invokedByRun: true });

    expect(process.exitCode).toBe(1);
    expect(fs.readFileSync(configPath)).toEqual(invalidBytes);
    expect(fs.readFileSync(`${configPath}.invalid-1`)).toEqual(invalidBytes);
    expect(fs.existsSync(`${configPath}.backup`)).toBe(false);
  });

  it("keeps --yes onboarding on local trusted loopback defaults", async () => {
    const configPath = createFreshConfigPath();
    process.env.HOST = "0.0.0.0";
    process.env.PAPERCLIP_BIND = "lan";

    await onboard({ config: configPath, yes: true, invokedByRun: true });

    const raw = JSON.parse(fs.readFileSync(configPath, "utf8")) as PaperclipConfig;
    expect(raw.server.deploymentMode).toBe("local_trusted");
    expect(raw.server.exposure).toBe("private");
    expect(raw.server.bind).toBe("loopback");
    expect(raw.server.host).toBe("127.0.0.1");
  });

  it("creates instance-root config and data paths for a fresh PAPERCLIP_HOME", async () => {
    const home = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-onboard-home-"));
    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-onboard-cwd-"));
    process.chdir(cwd);
    process.env.PAPERCLIP_HOME = home;

    await onboard({ yes: true, invokedByRun: true });

    const instanceRoot = path.join(home, "instances", "default");
    const configPath = path.join(instanceRoot, "config.json");
    const raw = JSON.parse(fs.readFileSync(configPath, "utf8")) as PaperclipConfig;

    expect(raw.database.embeddedPostgresDataDir).toBe(path.join(instanceRoot, "db"));
    expect(raw.database.backup.dir).toBe(path.join(instanceRoot, "data", "backups"));
    expect(raw.logging.logDir).toBe(path.join(instanceRoot, "logs"));
    expect(raw.storage.localDisk.baseDir).toBe(path.join(instanceRoot, "data", "storage"));
    expect(raw.secrets.localEncrypted.keyFilePath).toBe(path.join(instanceRoot, "secrets", "master.key"));
    expect(fs.existsSync(path.join(instanceRoot, ".env"))).toBe(true);
    expect(fs.readFileSync(path.join(instanceRoot, ".env"), "utf8"))
      .toContain("PAPERCLIP_TOOL_ACTION_SIGNING_SECRET=");
    expect(fs.existsSync(path.join(instanceRoot, "secrets", "master.key"))).toBe(true);
  });

  it("supports authenticated/private quickstart bind presets", async () => {
    const configPath = createFreshConfigPath();
    process.env.PAPERCLIP_TAILNET_BIND_HOST = "100.64.0.8";

    await onboard({ config: configPath, yes: true, invokedByRun: true, bind: "tailnet" });

    const raw = JSON.parse(fs.readFileSync(configPath, "utf8")) as PaperclipConfig;
    expect(raw.server.deploymentMode).toBe("authenticated");
    expect(raw.server.exposure).toBe("private");
    expect(raw.server.bind).toBe("tailnet");
    expect(raw.server.host).toBe("100.64.0.8");
  });

  it("keeps tailnet quickstart on loopback until tailscale is available", async () => {
    const configPath = createFreshConfigPath();
    delete process.env.PAPERCLIP_TAILNET_BIND_HOST;
    process.env.PATH = "";

    try {
      await onboard({ config: configPath, yes: true, invokedByRun: true, bind: "tailnet" });
    } finally {
      process.env.PATH = ORIGINAL_PATH;
    }

    const raw = JSON.parse(fs.readFileSync(configPath, "utf8")) as PaperclipConfig;
    expect(raw.server.deploymentMode).toBe("authenticated");
    expect(raw.server.exposure).toBe("private");
    expect(raw.server.bind).toBe("tailnet");
    expect(raw.server.host).toBe("127.0.0.1");
  });

  it("ignores deployment env overrides during --yes quickstart", async () => {
    const configPath = createFreshConfigPath();
    process.env.PAPERCLIP_DEPLOYMENT_MODE = "authenticated";

    await onboard({ config: configPath, yes: true, invokedByRun: true });

    const raw = JSON.parse(fs.readFileSync(configPath, "utf8")) as PaperclipConfig;
    expect(raw.server.deploymentMode).toBe("local_trusted");
    expect(raw.server.exposure).toBe("private");
    expect(raw.server.bind).toBe("loopback");
    expect(raw.server.host).toBe("127.0.0.1");
  });
});