Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

8.1 KB
Raw Blame
/**
 * Semantic ids through the create routes: a Project or Agent id is chosen by its creator —
 * a lowercase letter first, then lowercase letters, digits and underscores — and checked for
 * collisions against the DB and the directory (built-in reserved ids included). The hyphen is
 * a reserved separator: a non-admin's Project id is "<username>-<suffix>", an admin's has none.
 *
 * - An admin creates a Project under a valid id (its display name defaulting to the id) and is
 *   refused an invalid one; a DB-taken, directory-only-taken or reserved id is a 409.
 * - A non-admin's Project id must carry their own prefix and a valid suffix.
 * - A Project creation that fails midway rolls back its row and directory, so the same id can
 *   be retried; an Agent creation that fails midway rolls back its directory the same way.
 * - An Agent id is validated the same way, initializes the Agent, collides within its Project
 *   (built-ins included) but not across Projects, and its display name is free-form.
 *
 * Every case creates distinct ids, so one app serves them all.
 */
import fs from "node:fs/promises";
import path from "node:path";
import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
import type { AgentCreateResponse, ProjectCreateResponse } from "../src/api/types.js";
import { apiClient, createTestApp, loginAdmin, provisionUser } from "./helpers.js";
import type { TestApp } from "./helpers.js";

// "项目" stays Chinese on purpose: ids must reject CJK (ASCII lowercase only).
const BAD_IDS = ["Foo", "1abc", "a", "-abc", "a-b", "a b", "a.b", "项目", "a".repeat(65)];

describe("semantic ids", () => {
  let t: TestApp;
  let admin: ReturnType<typeof apiClient>;
  let api: ReturnType<typeof apiClient>;

  beforeAll(async () => {
    t = await createTestApp();
    admin = apiClient(t.app, (await loginAdmin(t.app)).cookie);
    api = apiClient(t.app, (await provisionUser(t.app, "ida")).cookie);
  });
  afterAll(async () => {
    await t.cleanup();
  });

  it("gives an admin's Project a valid bare id, its name defaulting to the id, and refuses an invalid one", async () => {
    for (const bad of BAD_IDS) {
      const res = await admin.post("/api/projects", { projectId: bad, name: "x" });
      expect(res.status, `projectId=${bad}`).toBe(400);
    }

    const created = await admin.post("/api/projects", { projectId: "my_proj_2" });
    expect(created.status).toBe(201);
    const { project } = (await created.json()) as ProjectCreateResponse;
    expect(project.projectId).toBe("my_proj_2");
    expect(project.name).toBe("my_proj_2"); // No display name given: defaults to the id
    await expect(fs.access(path.join(t.root, "my_proj_2"))).resolves.toBeUndefined();
  });

  it("refuses a DB-taken, directory-only or reserved Project id as taken", async () => {
    expect((await admin.post("/api/projects", { projectId: "taken", name: "a" })).status).toBe(201);
    expect((await admin.post("/api/projects", { projectId: "taken", name: "b" })).status).toBe(409);
    // A directory that exists but isn't tracked (e.g. created by the CLI) is also considered taken.
    await fs.mkdir(path.join(t.root, "dir_only"), { recursive: true });
    expect((await admin.post("/api/projects", { projectId: "dir_only", name: "c" })).status).toBe(
      409,
    );
    // default_project is already tracked by admin.
    expect(
      (await admin.post("/api/projects", { projectId: "default_project", name: "d" })).status,
    ).toBe(409);
  });

  it("makes a non-admin's Project id carry their own prefix and a valid suffix", async () => {
    // No prefix / prefix only / suffix with a hyphen or an invalid character: 400.
    for (const bad of ["blog", "ida", "ida-", "idablog", "proj_ida", "ida-sub-x", "ida-Bad"]) {
      const res = await api.post("/api/projects", { projectId: bad, name: "x" });
      expect(res.status, `projectId=${bad}`).toBe(400);
      const body = (await res.json()) as { error: { code: string } };
      expect(body.error.code, `projectId=${bad}`).toBe("project_id_prefix_required");
    }
    // With the prefix: created normally.
    const created = await api.post("/api/projects", { projectId: "ida-blog" });
    expect(created.status).toBe(201);
    await expect(fs.access(path.join(t.root, "ida-blog"))).resolves.toBeUndefined();
  });

  it("rolls back a Project creation that fails midway, so the same id can be retried", async () => {
    // Inject a config write failure (handleError logs the stack trace: silence it so it doesn't
    // clutter output). The app is shared, so the real writer goes back whatever happens.
    vi.spyOn(console, "error").mockImplementation(() => {});
    const original = t.deps.projectConfigService.writeInitialConfig;
    t.deps.projectConfigService.writeInitialConfig = async () => {
      throw new Error("config write blew up");
    };
    try {
      expect((await admin.post("/api/projects", { projectId: "flaky", name: "x" })).status).toBe(
        500,
      );
    } finally {
      t.deps.projectConfigService.writeInitialConfig = original;
    }
    // No leftovers: neither the directory nor the DB row exist, so the id isn't held by an orphaned directory.
    await expect(fs.access(path.join(t.root, "flaky"))).rejects.toThrow();
    expect(
      t.deps.db.prepare("SELECT 1 AS x FROM projects WHERE project_id = ?").get("flaky"),
    ).toBeUndefined();
    expect((await admin.post("/api/projects", { projectId: "flaky", name: "x" })).status).toBe(201);
  });

  it("rolls back an Agent creation that fails midway, so the same id can be retried", async () => {
    vi.spyOn(console, "error").mockImplementation(() => {});
    const original = t.deps.agentConfigService.updateConfig;
    t.deps.agentConfigService.updateConfig = async () => {
      throw new Error("config write blew up");
    };
    try {
      expect(
        (await api.post("/api/projects/ida-default_project/agents", { agentId: "flaky" })).status,
      ).toBe(500);
    } finally {
      t.deps.agentConfigService.updateConfig = original;
    }
    await expect(
      fs.access(path.join(t.root, "ida-default_project", "agents", "flaky")),
    ).rejects.toThrow();
    expect(
      (await api.post("/api/projects/ida-default_project/agents", { agentId: "flaky" })).status,
    ).toBe(201);
  });

  it("validates an Agent id, initializes the Agent, and checks collisions within its Project only", async () => {
    for (const bad of BAD_IDS) {
      const res = await api.post("/api/projects/ida-default_project/agents", {
        agentId: bad,
        name: "x",
      });
      expect(res.status, `agentId=${bad}`).toBe(400);
    }

    // Unlike ids, display names are free-form — a CJK name must round-trip untouched.
    const created = await api.post("/api/projects/ida-default_project/agents", {
      agentId: "crawler",
      name: "爬虫",
    });
    expect(created.status).toBe(201);
    const { agent } = (await created.json()) as AgentCreateResponse;
    expect(agent.agentId).toBe("crawler");
    expect(agent.name).toBe("爬虫");
    await expect(
      fs.access(
        path.join(
          t.root,
          "ida-default_project",
          "agents",
          "crawler",
          "agent_state",
          "system_config.yaml",
        ),
      ),
    ).resolves.toBeUndefined();

    // Both a duplicate within the same Project and a built-in reserved id are blocked by the collision check.
    expect(
      (
        await api.post("/api/projects/ida-default_project/agents", {
          agentId: "crawler",
          name: "y",
        })
      ).status,
    ).toBe(409);
    expect(
      (
        await api.post("/api/projects/ida-default_project/agents", {
          agentId: "default_agent",
          name: "y",
        })
      ).status,
    ).toBe(409);

    // Agent id uniqueness is scoped to the Project: another Project can reuse the
    // same id; the name defaults to the id.
    expect((await api.post("/api/projects", { projectId: "ida-other" })).status).toBe(201);
    const noName = await api.post("/api/projects/ida-other/agents", { agentId: "crawler" });
    expect(noName.status).toBe(201);
    expect(((await noName.json()) as AgentCreateResponse).agent.name).toBe("crawler");
  });
});