Jannik/PaperClipAI
1
0 Fork 0
mirror of https://github.com/paperclipai/paperclip.git synced 2026-11-11 05:11:49 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge origin/master into PAPA-415-duplicate-subtasks

Browse Source
This commit is contained in:
Devin Foley committed 2026-05-28 13:25:35 -07:00
2 parents 9bf93a10b2 9eac727cf1
commit 2ef6ede6e0
220 files changed
+60211 -1676
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

Dockerfile
+1
View File
@@ -22,6 +22,7 @@ COPY packages/shared/package.json packages/shared/
COPY packages/db/package.json packages/db/
COPY packages/adapter-utils/package.json packages/adapter-utils/
COPY packages/mcp-server/package.json packages/mcp-server/
COPY packages/skills-catalog/package.json packages/skills-catalog/
COPY packages/adapters/acpx-local/package.json packages/adapters/acpx-local/
COPY packages/adapters/claude-local/package.json packages/adapters/claude-local/
COPY packages/adapters/codex-local/package.json packages/adapters/codex-local/
README.md
+13 -20
View File
@@ -1,5 +1,5 @@
<p align="center">
<img src="doc/assets/header.png" alt="Paperclip — runs your business" width="720" />
<img src="doc/assets/banner.jpg" alt="Paperclip is the app people use to manage AI agents for work." width="720" />
</p>
<p align="center">
@@ -7,7 +7,8 @@
<a href="https://paperclip.ing/docs"><strong>Docs</strong></a> &middot;
<a href="https://github.com/paperclipai/paperclip"><strong>GitHub</strong></a> &middot;
<a href="https://discord.gg/m4HZY7xNG3"><strong>Discord</strong></a> &middot;
<a href="https://x.com/papercliping"><strong>Twitter</strong></a>
<a href="https://x.com/papercliping"><strong>Twitter</strong></a> &middot;
<a href="https://paperclip.ing"><strong>Website</strong></a>
</p>
<p align="center">
@@ -24,15 +25,15 @@
<br/>
## What is Paperclip?
# Paperclip is the app people use to manage AI agents for work.
# Open-source orchestration for zero-human companies
Open-source orchestration for teams of AI agents.
**If OpenClaw is an _employee_, Paperclip is the _company_**
**If OpenClaw is an _employee_, Paperclip is the _company_.**
Paperclip is a Node.js server and React UI that orchestrates a team of AI agents to run a business. Bring your own agents, assign goals, and track your agents' work and costs from one dashboard.
Paperclip is a Node.js server and React UI that orchestrates a team of AI agents to run a business. Bring your own agents, assign goals, and track work and costs from one dashboard.
It looks like a task manager — but under the hood it has org charts, budgets, governance, goal alignment, and agent coordination.
It looks like a task manager. Under the hood: org charts, budgets, governance, goal alignment, and agent coordination.
**Manage business goals, not pull requests.**
@@ -44,10 +45,6 @@ It looks like a task manager — but under the hood it has org charts, budgets,
<br/>
> **COMING SOON: Clipmart** — Download and run entire companies with one click. Browse pre-built company templates — full org structures, agent configs, and skills — and import them into your Paperclip instance in seconds.
<br/>
<div align="center">
<table>
<tr>
@@ -113,7 +110,7 @@ Every conversation traced. Every decision explained. Full tool-call tracing and
<tr>
<td align="center">
<h3>🛡️ Governance</h3>
You're the board. Approve hires, override strategy, pause or terminate any agent — at any time.
Approve hires, override strategy, pause or terminate any agent — at any time.
</td>
<td align="center">
<h3>📊 Org Chart</h3>
@@ -222,7 +219,7 @@ Paperclip is a full control plane, not a wrapper. Before you build any of this y
</td>
<td>
**Governance & Approvals** — Board approval workflows, execution policies with review/approval stages, decision tracking, budget hard-stops, agent pause/resume/terminate, and full audit logging. You're the board — nothing ships without your sign-off.
**Governance & Approvals** — Board approval workflows, execution policies with review/approval stages, decision tracking, budget hard-stops, agent pause/resume/terminate, and full audit logging. Nothing ships without your sign-off.
</td>
</tr>
@@ -317,7 +314,7 @@ This starts the API server at `http://localhost:3100`. An embedded PostgreSQL da
**What does a typical setup look like?**
Locally, a single Node.js process manages an embedded Postgres and local file storage. For production, point it at your own Postgres and deploy however you like. Configure projects, agents, and goals — the agents take care of the rest.
If you're a solo-entreprenuer you can use Tailscale to access Paperclip on the go. Then later you can deploy to e.g. Vercel when you need it.
If you're a solo entrepreneur you can use Tailscale to access Paperclip on the go. Then later you can deploy to e.g. Vercel when you need it.
**Can I run multiple companies?**
Yes. A single deployment can run an unlimited number of companies with complete data isolation.
@@ -418,7 +415,7 @@ We welcome contributions. See the [contributing guide](CONTRIBUTING.md) for deta
## License
MIT &copy; 2026 Paperclip
MIT &copy; 2026 [Paperclip Labs, Inc](https://paperclip.ing)
## Star History
@@ -429,9 +426,5 @@ MIT &copy; 2026 Paperclip
---
<p align="center">
<img src="doc/assets/footer.jpg" alt="" width="720" />
</p>
<p align="center">
<sub>Open source under MIT. Built for people who want to run companies, not babysit agents.</sub>
<sub>Open source under MIT. Built for people who want to get work done, not babysit agents.</sub>
</p>
cli/src/__tests__/skills.test.ts
+506
View File
@@ -0,0 +1,506 @@
import { Command } from "commander";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { registerSkillsCommands } from "../commands/client/skills.js";
import { resolveCompanySkillReference } from "../commands/client/skills.js";
const ORIGINAL_ENV = { ...process.env };
function makeProgram(): Command {
const program = new Command();
program.exitOverride();
program.configureOutput({
writeOut: () => undefined,
writeErr: () => undefined,
});
registerSkillsCommands(program);
return program;
}
async function runCommand(args: string[]): Promise<void> {
await makeProgram().parseAsync(args, { from: "user" });
}
function jsonResponse(body: unknown, status = 200): Response {
return new Response(JSON.stringify(body), {
status,
headers: { "content-type": "application/json" },
});
}
function skill(overrides: Record<string, unknown> = {}) {
return {
id: "11111111-1111-1111-1111-111111111111",
companyId: "company-1",
key: "paperclip/review-prs",
slug: "review-prs",
name: "Review PRs",
description: "Review pull requests",
markdown: "# Review PRs",
sourceType: "local_path",
sourceLocator: null,
sourceRef: null,
trustLevel: "markdown_only",
compatibility: "compatible",
fileInventory: [{ path: "SKILL.md", kind: "skill" }],
metadata: null,
createdAt: "2026-05-26T00:00:00.000Z",
updatedAt: "2026-05-26T00:00:00.000Z",
attachedAgentCount: 2,
editable: true,
editableReason: null,
sourceLabel: null,
sourceBadge: "local",
sourcePath: null,
...overrides,
};
}
function catalogSkill(overrides: Record<string, unknown> = {}) {
return {
id: "paperclipai:bundled:software-development:github-pr-workflow",
key: "paperclipai/bundled/software-development/github-pr-workflow",
kind: "bundled",
category: "software-development",
slug: "github-pr-workflow",
name: "github-pr-workflow",
description: "Prepare pull requests, review responses, and verification notes.",
path: "catalog/bundled/software-development/github-pr-workflow",
entrypoint: "SKILL.md",
trustLevel: "markdown_only",
compatibility: "compatible",
defaultInstall: false,
recommendedForRoles: ["engineer"],
requires: [],
tags: ["github", "pull-requests"],
files: [{ path: "SKILL.md", kind: "skill", sizeBytes: 128, sha256: "sha256:abc" }],
contentHash: "sha256:catalog",
...overrides,
};
}
function agent(overrides: Record<string, unknown> = {}) {
return {
id: "agent-1",
companyId: "company-1",
name: "Coder",
role: "engineer",
status: "active",
reportsTo: null,
budgetMonthlyCents: 0,
spentMonthlyCents: 0,
adapterType: "codex_local",
adapterConfig: {},
runtimeConfig: {},
permissions: {},
createdAt: "2026-05-26T00:00:00.000Z",
updatedAt: "2026-05-26T00:00:00.000Z",
...overrides,
};
}
describe("skills CLI helpers", () => {
it("resolves skill refs by id, key, or unique normalized slug", () => {
const rows = [
skill({ id: "skill-a", key: "paperclip/a", slug: "alpha", name: "Alpha" }),
skill({ id: "skill-b", key: "paperclip/b", slug: "beta-skill", name: "Beta" }),
];
expect(resolveCompanySkillReference(rows, "skill-a").key).toBe("paperclip/a");
expect(resolveCompanySkillReference(rows, "paperclip/b").id).toBe("skill-b");
expect(resolveCompanySkillReference(rows, "Beta Skill").id).toBe("skill-b");
});
it("rejects ambiguous slug refs", () => {
const rows = [
skill({ id: "skill-a", key: "paperclip/a", slug: "same", name: "A" }),
skill({ id: "skill-b", key: "paperclip/b", slug: "same", name: "B" }),
];
expect(() => resolveCompanySkillReference(rows, "same")).toThrow(/Ambiguous skill slug/);
});
});
describe("skills CLI commands", () => {
let fetchMock: ReturnType<typeof vi.fn>;
let logSpy: ReturnType<typeof vi.spyOn>;
let writeChunks: unknown[];
beforeEach(() => {
process.env = { ...ORIGINAL_ENV };
delete process.env.PAPERCLIP_API_URL;
delete process.env.PAPERCLIP_API_KEY;
delete process.env.PAPERCLIP_COMPANY_ID;
fetchMock = vi.fn();
vi.stubGlobal("fetch", fetchMock);
logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
writeChunks = [];
vi.spyOn(process.stdout, "write").mockImplementation((chunk: string | Uint8Array) => {
writeChunks.push(chunk);
return true;
});
});
afterEach(() => {
process.env = { ...ORIGINAL_ENV };
vi.unstubAllGlobals();
vi.restoreAllMocks();
});
it("lists company skills as JSON through the shared client context", async () => {
const rows = [skill()];
fetchMock.mockResolvedValueOnce(jsonResponse(rows));
await runCommand([
"skills",
"list",
"--company-id",
"company-1",
"--api-base",
"http://paperclip.test",
"--api-key",
"token",
"--json",
]);
expect(fetchMock).toHaveBeenCalledWith(
"http://paperclip.test/api/companies/company-1/skills",
expect.objectContaining({
method: "GET",
headers: expect.objectContaining({ authorization: "Bearer token" }),
}),
);
expect(JSON.parse(String(logSpy.mock.calls[0]?.[0]))).toEqual(rows);
});
it("resolves a skill slug before reading detail", async () => {
fetchMock
.mockResolvedValueOnce(jsonResponse([skill()]))
.mockResolvedValueOnce(jsonResponse({ ...skill(), usedByAgents: [] }));
await runCommand([
"skills",
"show",
"Review PRs",
"--company-id",
"company-1",
"--api-base",
"http://paperclip.test",
"--api-key",
"token",
"--json",
]);
expect(fetchMock).toHaveBeenNthCalledWith(
2,
"http://paperclip.test/api/companies/company-1/skills/11111111-1111-1111-1111-111111111111",
expect.objectContaining({ method: "GET" }),
);
});
it("prints skill files as raw pipeable content in human mode", async () => {
fetchMock
.mockResolvedValueOnce(jsonResponse([skill()]))
.mockResolvedValueOnce(jsonResponse({
skillId: "11111111-1111-1111-1111-111111111111",
path: "SKILL.md",
kind: "skill",
content: "# Review PRs",
language: "markdown",
markdown: true,
editable: true,
}));
await runCommand([
"skills",
"file",
"review-prs",
"--company-id",
"company-1",
"--api-base",
"http://paperclip.test",
"--api-key",
"token",
]);
expect(logSpy).not.toHaveBeenCalled();
expect(writeChunks.join("")).toBe("# Review PRs\n");
});
it("browses catalog skills with filters in table output", async () => {
fetchMock.mockResolvedValueOnce(jsonResponse([catalogSkill()]));
await runCommand([
"skills",
"browse",
"--kind",
"bundled",
"--category",
"software-development",
"--query",
"github",
"--api-base",
"http://paperclip.test",
"--api-key",
"token",
]);
expect(fetchMock).toHaveBeenCalledWith(
"http://paperclip.test/api/skills/catalog?kind=bundled&category=software-development&q=github",
expect.objectContaining({ method: "GET" }),
);
const rendered = logSpy.mock.calls.map((call) => String(call[0])).join("\n");
expect(rendered).toContain("id");
expect(rendered).toContain("paperclipai:bundled:software-development:github-pr-workflow");
expect(rendered).toContain("roles");
});
it("searches catalog skills as JSON", async () => {
const rows = [catalogSkill()];
fetchMock.mockResolvedValueOnce(jsonResponse(rows));
await runCommand([
"skills",
"search",
"pull requests",
"--kind",
"bundled",
"--api-base",
"http://paperclip.test",
"--api-key",
"token",
"--json",
]);
expect(fetchMock).toHaveBeenCalledWith(
"http://paperclip.test/api/skills/catalog?kind=bundled&q=pull+requests",
expect.objectContaining({ method: "GET" }),
);
expect(JSON.parse(String(logSpy.mock.calls[0]?.[0]))).toEqual(rows);
});
it("inspects catalog skill detail by query ref so keys with slashes work", async () => {
const detail = catalogSkill();
fetchMock.mockResolvedValueOnce(jsonResponse(detail));
await runCommand([
"skills",
"inspect",
"paperclipai/bundled/software-development/github-pr-workflow",
"--api-base",
"http://paperclip.test",
"--api-key",
"token",
"--json",
]);
expect(fetchMock).toHaveBeenCalledWith(
"http://paperclip.test/api/skills/catalog/ref?ref=paperclipai%2Fbundled%2Fsoftware-development%2Fgithub-pr-workflow",
expect.objectContaining({ method: "GET" }),
);
expect(JSON.parse(String(logSpy.mock.calls[0]?.[0]))).toEqual(detail);
});
it("installs catalog skills into the company library without agent sync", async () => {
const result = {
action: "created",
skill: skill({
key: "paperclipai/bundled/software-development/github-pr-workflow",
slug: "pr-flow",
sourceType: "catalog",
}),
catalogSkill: catalogSkill(),
warnings: [],
};
fetchMock.mockResolvedValueOnce(jsonResponse(result, 201));
await runCommand([
"skills",
"install",
"github-pr-workflow",
"--as",
"pr-flow",
"--force",
"--company-id",
"company-1",
"--api-base",
"http://paperclip.test",
"--api-key",
"token",
"--json",
]);
expect(fetchMock).toHaveBeenCalledWith(
"http://paperclip.test/api/companies/company-1/skills/install-catalog",
expect.objectContaining({
method: "POST",
body: JSON.stringify({
catalogSkillId: "github-pr-workflow",
slug: "pr-flow",
force: true,
}),
}),
);
expect(JSON.parse(String(logSpy.mock.calls[0]?.[0]))).toEqual(result);
});
it("passes force to skill updates", async () => {
fetchMock
.mockResolvedValueOnce(jsonResponse([skill()]))
.mockResolvedValueOnce(jsonResponse(skill({ sourceRef: "sha256:new" })));
await runCommand([
"skills",
"update",
"review-prs",
"--force",
"--company-id",
"company-1",
"--api-base",
"http://paperclip.test",
"--api-key",
"token",
"--json",
]);
expect(fetchMock).toHaveBeenNthCalledWith(
2,
"http://paperclip.test/api/companies/company-1/skills/11111111-1111-1111-1111-111111111111/install-update",
expect.objectContaining({
method: "POST",
body: JSON.stringify({ force: true }),
}),
);
});
it("audits installed skill bytes through the server", async () => {
const audit = {
skillId: "11111111-1111-1111-1111-111111111111",
installedHash: "sha256:installed",
originHash: "sha256:origin",
verdict: "warning",
codes: ["network_reference"],
findings: [{
code: "network_reference",
severity: "warning",
message: "Skill content references network-capable commands or URLs.",
path: "SKILL.md",
}],
scannedAt: "2026-05-26T00:00:00.000Z",
scanVersion: "skills-audit-v1",
};
fetchMock
.mockResolvedValueOnce(jsonResponse([skill()]))
.mockResolvedValueOnce(jsonResponse(audit));
await runCommand([
"skills",
"audit",
"review-prs",
"--company-id",
"company-1",
"--api-base",
"http://paperclip.test",
"--api-key",
"token",
"--json",
]);
expect(fetchMock).toHaveBeenNthCalledWith(
2,
"http://paperclip.test/api/companies/company-1/skills/11111111-1111-1111-1111-111111111111/audit",
expect.objectContaining({
method: "POST",
body: JSON.stringify({}),
}),
);
expect(JSON.parse(String(logSpy.mock.calls[0]?.[0]))).toEqual(audit);
});
it("requires confirmation for reset and sends force when confirmed", async () => {
fetchMock
.mockResolvedValueOnce(jsonResponse([skill({ sourceType: "catalog" })]))
.mockResolvedValueOnce(jsonResponse(skill({ sourceType: "catalog" })));
await runCommand([
"skills",
"reset",
"review-prs",
"--yes",
"--force",
"--company-id",
"company-1",
"--api-base",
"http://paperclip.test",
"--api-key",
"token",
"--json",
]);
expect(fetchMock).toHaveBeenNthCalledWith(
2,
"http://paperclip.test/api/companies/company-1/skills/11111111-1111-1111-1111-111111111111/reset",
expect.objectContaining({
method: "POST",
body: JSON.stringify({ force: true }),
}),
);
});
it("syncs desired company skill refs to an agent and returns the runtime snapshot", async () => {
const snapshot = {
adapterType: "codex_local",
supported: true,
mode: "persistent",
desiredSkills: ["paperclip/review-prs"],
entries: [
{
key: "paperclip/review-prs",
runtimeName: "review-prs",
desired: true,
managed: true,
required: false,
state: "installed",
origin: "company_managed",
detail: null,
},
],
warnings: [],
};
fetchMock
.mockResolvedValueOnce(jsonResponse(agent()))
.mockResolvedValueOnce(jsonResponse(snapshot));
await runCommand([
"skills",
"agent",
"sync",
"coder",
"--skill",
"review-prs",
"--skill",
"paperclip/qa",
"--company-id",
"company-1",
"--api-base",
"http://paperclip.test",
"--api-key",
"token",
"--json",
]);
expect(fetchMock).toHaveBeenNthCalledWith(
1,
"http://paperclip.test/api/agents/coder?companyId=company-1",
expect.objectContaining({ method: "GET" }),
);
expect(fetchMock).toHaveBeenNthCalledWith(
2,
"http://paperclip.test/api/agents/agent-1/skills/sync",
expect.objectContaining({
method: "POST",
body: JSON.stringify({ desiredSkills: ["review-prs", "paperclip/qa"] }),
}),
);
expect(JSON.parse(String(logSpy.mock.calls[0]?.[0]))).toEqual(snapshot);
});
});
cli/src/commands/client/skills.ts
+1017
View File
File diff suppressed because it is too large. Load diff
cli/src/index.ts
+2
View File
@@ -20,6 +20,7 @@ import { registerRoutineCommands } from "./commands/routines.js";
import { registerFeedbackCommands } from "./commands/client/feedback.js";
import { registerSecretCommands } from "./commands/client/secrets.js";
import { registerCloudCommands } from "./commands/client/cloud.js";
import { registerSkillsCommands } from "./commands/client/skills.js";
import { applyDataDirOverride, type DataDirOptionLike } from "./config/data-dir.js";
import { loadPaperclipEnvFile } from "./config/env.js";
import { initTelemetryFromConfigFile, flushTelemetry } from "./telemetry.js";
@@ -151,6 +152,7 @@ registerRoutineCommands(program);
registerFeedbackCommands(program);
registerSecretCommands(program);
registerCloudCommands(program);
registerSkillsCommands(program);
registerWorktreeCommands(program);
registerEnvLabCommands(program);
registerPluginCommands(program);
doc/CLI.md
+118
View File
@@ -143,6 +143,124 @@ pnpm paperclipai agent local-cli codexcoder --company-id <company-id>
pnpm paperclipai agent local-cli claudecoder --company-id <company-id>
```
## Skills Commands
`paperclipai skills` covers three distinct operations:
1. **Company install** — adds or updates a row in `company_skills` for the
whole company. This is what `skills install`, `skills import`, `skills create`,
and `skills scan-projects` do.
2. **Agent attach** — replaces an agent's *desired* company skill set
(`skills agent sync`/`clear`). This is a desired-state operation on the
agent's adapter config; it does not change the company library.
3. **Adapter runtime sync** — the adapter reconciles the desired skill set
with files on disk and reports an `AgentSkillSnapshot` (`skills agent list`).
`skills agent sync` triggers this automatically after updating desired state.
Required Paperclip runtime skills (heartbeat, etc.) remain server-enforced and
are added on top of whatever the desired set names.
### Catalog (app-shipped skills)
The Paperclip app ships a curated catalog under `@paperclipai/skills-catalog`.
Browse and inspect commands never mutate company state; `install` adds a catalog
skill to the company library.
```sh
pnpm paperclipai skills browse [--kind bundled|optional] [--category <slug>] [--query <text>]
pnpm paperclipai skills search "<text>" [--kind bundled|optional] [--category <slug>]
pnpm paperclipai skills inspect <catalog-id-or-key-or-slug>
pnpm paperclipai skills install <catalog-id-or-key-or-slug> [--as <slug>] [--force] --company-id <company-id>
```
Catalog semantics:
- **Bundled** skills live in `packages/skills-catalog/catalog/bundled/<category>/<slug>`
and are recommended defaults for most companies. They use canonical key
`paperclipai/bundled/<category>/<slug>`.
- **Optional** skills live in `packages/skills-catalog/catalog/optional/<category>/<slug>`
and are role-specific or domain-specific (browser, AWS ops, etc.). Same key
shape with `optional` in place of `bundled`.
- `skills install` materializes the catalog files into a company-managed skill
directory and records provenance (`catalogId`, `catalogKey`, `packageVersion`,
`originHash`, …) so future updates and audit decisions stay consistent.
- `--as <slug>` overrides the company skill slug. `--force` may replace a
same-key catalog-managed skill but never bypasses hard validation or hard-stop
audit findings.
Examples:
```sh
pnpm paperclipai skills browse --kind bundled --company-id <company-id>
pnpm paperclipai skills search "pull request" --kind bundled
pnpm paperclipai skills inspect github-pr-workflow
pnpm paperclipai skills install github-pr-workflow --company-id <company-id>
pnpm paperclipai skills install paperclipai:optional:browser:agent-browser --company-id <company-id>
```
External GitHub, skills.sh, local-path, and URL sources still go through
`skills import`; catalog commands are for the app-shipped catalog only.
### Company library
```sh
pnpm paperclipai skills list --company-id <company-id>
pnpm paperclipai skills show <skill-id-or-key-or-slug> --company-id <company-id>
pnpm paperclipai skills file <skill-id-or-key-or-slug> [--path SKILL.md] --company-id <company-id>
pnpm paperclipai skills import <source> --company-id <company-id>
pnpm paperclipai skills create --name "Review PRs" [--slug review-prs] [--description "..."] [--body-file SKILL.md] --company-id <company-id>
pnpm paperclipai skills scan-projects [--project-id <id>...] [--workspace-id <id>...] --company-id <company-id>
pnpm paperclipai skills check [skill-id-or-key-or-slug] --company-id <company-id>
pnpm paperclipai skills update <skill-id-or-key-or-slug> [--force] --company-id <company-id>
pnpm paperclipai skills update --all [--force] --company-id <company-id>
pnpm paperclipai skills audit [skill-id-or-key-or-slug] --company-id <company-id>
pnpm paperclipai skills reset <skill-id-or-key-or-slug> [--yes] [--force] --company-id <company-id>
pnpm paperclipai skills remove <skill-id-or-key-or-slug> --yes --company-id <company-id>
```
`skills import <source>` accepts a skills.sh URL, the equivalent
`<owner>/<repo>/<skill>` shorthand, a GitHub URL, a local path, or an
`npx skills add …` command. See `references/company-skills.md` in the agent
skill bundle for the source-type table.
`skills check`, `skills update`, `skills audit`, and `skills reset` are the
maintenance loop for catalog-installed skills:
- `check` reports whether each skill's installed bytes match its pinned origin
(`hasUpdate`, `installedHash`, `originHash`, `updateHoldReason`,
`auditVerdict`).
- `update` installs the pinned update through the existing install-update API.
`--all` checks every company skill and updates only those with
`hasUpdate=true`. `--force` discards local-modification or soft-audit holds;
hard-stop audit findings still block the update.
- `audit` re-scans installed bytes and reports findings without executing
anything.
- `reset` reinstalls a catalog-managed skill from its pinned origin, discarding
local edits. Prompts in a TTY; requires `--yes` for non-interactive use.
### Agent attach
```sh
pnpm paperclipai skills agent list <agent-id-or-shortname> --company-id <company-id>
pnpm paperclipai skills agent sync <agent-id-or-shortname> --skill <skill-id-or-key-or-slug> [--skill <skill-id-or-key-or-slug>...] --company-id <company-id>
pnpm paperclipai skills agent clear <agent-id-or-shortname> --yes --company-id <company-id>
```
`skills agent sync` replaces the agent's non-required desired skill set (it is
not additive) and returns the resulting adapter `AgentSkillSnapshot`.
`skills agent clear` sends an empty desired list. Required Paperclip skills are
still enforced by the server in both cases.
### Notes
- Skill references accept company skill `id`, canonical `key`, or unique
`slug`; catalog references accept catalog `id`, `key`, or unique `slug`.
- `skills file` prints raw file content in human mode so it can be piped.
- `skills create --body-file -` reads the skill markdown body from stdin.
- `skills remove`, `skills reset`, and `skills agent clear` prompt in a TTY and
require `--yes` in non-interactive use.
- `--json` prints the raw API result for each command.
## Secrets Commands
```sh
doc/DATABASE.md
+11
View File
@@ -143,6 +143,17 @@ The database mode is controlled by `DATABASE_URL`:
Your Drizzle schema (`packages/db/src/schema/`) stays the same regardless of mode.
## Resource membership tables
Paperclip stores current-user sidebar membership state in:
- `project_memberships`
- `agent_memberships`
These rows are company-scoped and user-scoped. A missing row means the user is joined, so existing users keep seeing projects and agents in the sidebar until they explicitly leave them. Rows only control sidebar visibility; they do not affect project/agent detail access, all-pages, selectors, assignment flows, or existing company permissions.
Both tables use a unique key on `(company_id, user_id, resource_id)` and keep `state` as `joined` or `left`. Join/leave mutations are idempotent board-user `/me` operations and write activity entries when the effective state changes.
## Plugin database namespaces
The plugin runtime tracks plugin-owned database namespaces and migrations in `plugin_database_namespaces` and `plugin_migrations`. Hosted deployments that separate runtime and migration connections should set `DATABASE_MIGRATION_URL`; plugin namespace migration work uses the migration connection when present.
doc/DEPLOYMENT-MODES.md
+34 -3
View File
@@ -125,19 +125,50 @@ When running `authenticated` mode, if the only instance admin is `local-board`,
This prevents lockout when a user migrates from long-running local trusted usage to authenticated mode.
## 8. Current Code Reality (As Of 2026-02-23)
## 8. First Admin Setup For Fresh Authenticated Installs
Fresh authenticated installs start in `bootstrap_pending` until the first
`instance_admin` exists.
For `authenticated/private`, Paperclip supports a browser-first setup path:
1. open the Paperclip URL from the private network or appliance UI
2. sign in or create a Paperclip account
3. choose `Claim this instance` on the setup screen
That browser claim promotes the signed-in session user to the first instance
admin and then falls through to normal onboarding. The endpoint is available
only to real browser session actors in `authenticated/private`; unauthenticated
requests, agent keys, board API keys, and local implicit board actors are
rejected.
The CLI fallback remains supported in all authenticated setup states:
```sh
pnpm paperclipai auth bootstrap-ceo
```
That command prints a one-time first-admin invite URL. Browser claim and
bootstrap invite acceptance share the same first-admin transaction, so whichever
path wins first makes later attempts return a conflict.
For `authenticated/public`, browser first-admin claim is intentionally disabled.
Public deployments must use the high-entropy bootstrap invite path unless a
future public-hosted setup design explicitly changes this policy.
## 9. Current Code Reality (As Of 2026-02-23)
- runtime values are `local_trusted | authenticated`
- `authenticated` uses Better Auth sessions and bootstrap invite flow
- `local_trusted` ensures a real local Board user principal in `authUsers` with `instance_user_roles` admin access
- company creation ensures creator membership in `company_memberships` so user assignment/access flows remain consistent
## 9. Naming and Compatibility Policy
## 10. Naming and Compatibility Policy
- canonical naming is `local_trusted` and `authenticated` with `private/public` exposure
- no long-term compatibility alias layer for discarded naming variants
## 10. Relationship to Other Docs
## 11. Relationship to Other Docs
- implementation plan: `doc/plans/deployment-auth-mode-consolidation.md`
- V1 contract: `doc/SPEC-implementation.md`
doc/DEVELOPING.md
+63
View File
@@ -72,6 +72,13 @@ pnpm dev --bind lan
```
This runs dev as `authenticated/private` with a private-network bind preset.
On a fresh authenticated/private instance, open the app, sign in or create an
account, and use the setup screen to claim the first instance admin from the
browser. The CLI fallback remains:
```sh
pnpm paperclipai auth bootstrap-ceo
```
For Tailscale-only reachability on a detected tailnet address:
@@ -413,6 +420,62 @@ eval "$(pnpm paperclipai worktree env)"
For project execution worktrees, Paperclip can also run a project-defined provision command after it creates or reuses an isolated git worktree. Configure this on the project's execution workspace policy (`workspaceStrategy.provisionCommand`). The command runs inside the derived worktree and receives `PAPERCLIP_WORKSPACE_*`, `PAPERCLIP_PROJECT_ID`, `PAPERCLIP_AGENT_ID`, and `PAPERCLIP_ISSUE_*` environment variables so each repo can bootstrap itself however it wants.
## App-Shipped Skills Catalog
The Paperclip app ships a curated catalog of company skills out of the box. The
catalog is a workspace package at `packages/skills-catalog`:
```text
packages/skills-catalog/
catalog/
bundled/<category>/<slug>/SKILL.md # recommended defaults
optional/<category>/<slug>/SKILL.md # role/domain-specific
generated/catalog.json # checked-in manifest
scripts/
build-catalog-manifest.ts # regenerate generated/catalog.json
validate-catalog.ts # validation only
src/ # builder + types consumed by server/CLI
```
Server and CLI import the generated manifest; they do not crawl repository
paths at request time. Root `skills/` remains reserved for Paperclip runtime
skills and is not part of the catalog.
Validate the catalog without writing the manifest:
```sh
pnpm --filter @paperclipai/skills-catalog validate
```
Regenerate `generated/catalog.json` after editing any catalog `SKILL.md`,
frontmatter, file inventory, category, or slug:
```sh
pnpm --filter @paperclipai/skills-catalog build:manifest
```
The package's `build` script runs `build:manifest` and then `tsc`; tests live
under `pnpm --filter @paperclipai/skills-catalog test`. Validation fails when:
- a catalog entry is not under `catalog/bundled/<category>/<slug>` or
`catalog/optional/<category>/<slug>`
- `SKILL.md` is missing or the frontmatter `name`/`description` is empty
- the frontmatter `key` disagrees with the generated canonical key
- two catalog entries share an `id`, `key`, or `slug`
- file inventory contains absolute paths, `..`, broken symlinks, or files
outside the skill directory
- the regenerated manifest differs from the checked-in
`generated/catalog.json`
Trust level is derived from inventory: `markdown_only` (markdown + references
only), `assets` (other non-script files), or `scripts_executables` (any
executable script). The build contract is documented in
`doc/plans/2026-05-26-skills-cli-catalog-contract.md`.
CI runs `pnpm --filter @paperclipai/skills-catalog validate` and the package's
vitest suite, so always regenerate the manifest in the same commit as the
catalog change.
## Quick Health Checks
In another terminal:
doc/DOCKER.md
+10
View File
@@ -117,6 +117,16 @@ services:
- bootstrap invite URL defaults
- hostname allowlist defaults (hostname extracted from URL)
For fresh `authenticated/private` Docker or appliance-style installs, the first
admin can now be claimed entirely from the browser after sign-in. Open the
Paperclip URL, sign in or create an account, then choose `Claim this instance`
on the setup screen. This browser claim is disabled for `authenticated/public`;
public deployments should run the high-entropy CLI invite fallback instead:
```sh
pnpm paperclipai auth bootstrap-ceo
```
Granular overrides remain available if needed (`PAPERCLIP_AUTH_PUBLIC_BASE_URL`, `BETTER_AUTH_URL`, `BETTER_AUTH_TRUSTED_ORIGINS`, `PAPERCLIP_ALLOWED_HOSTNAMES`).
Set `PAPERCLIP_ALLOWED_HOSTNAMES` explicitly only when you need additional hostnames beyond the public URL host (for example Tailscale/LAN aliases or multiple private hostnames).
doc/SPEC-implementation.md
+51 -8
View File
@@ -311,7 +311,32 @@ Invariant: each event must attach to agent and company; rollups are aggregation,
- `details` jsonb null
- `created_at` timestamptz not null default now()
## 7.12 `company_secrets` + `company_secret_versions`
## 7.12 `project_memberships` + `agent_memberships`
Per-user project/agent membership is personal visibility state for board users. It only controls whether a resource appears in the current user's sidebar; it must not grant or revoke access to all-pages, detail pages, selectors, assignment flows, search, or existing permissions.
`project_memberships`:
- `id` uuid pk
- `company_id` uuid fk `companies.id` not null
- `project_id` uuid fk `projects.id` not null
- `user_id` text not null
- `state` enum-like text: `joined | left`
- `created_at` timestamptz not null default now()
- `updated_at` timestamptz not null default now()
- unique `(company_id, user_id, project_id)`
`agent_memberships` mirrors the same shape with `agent_id` instead of `project_id` and unique `(company_id, user_id, agent_id)`.
Invariants:
- Missing membership rows mean `joined` for backward compatibility.
- Mutations are board-user-only `/me` operations; agent API keys are rejected.
- Viewer-role board users may update only their own membership rows through the narrow self-service helper.
- Target project/agent ownership is checked against the path company before mutation.
- Successful state changes write `resource_membership.joined` or `resource_membership.left` activity entries.
## 7.13 `company_secrets` + `company_secret_versions`
- Secret values are not stored inline in `agents.adapter_config.env`.
- Agent env entries should use secret refs for sensitive values.
@@ -325,7 +350,7 @@ Operational policy:
- Activity and approval payloads must not persist raw sensitive values.
- Config revisions may include redacted placeholders; such revisions are non-restorable for redacted fields.
## 7.13 Required Indexes
## 7.14 Required Indexes
- `agents(company_id, status)`
- `agents(company_id, reports_to)`
@@ -343,8 +368,12 @@ Operational policy:
- `issue_attachments(company_id, issue_id)`
- `company_secrets(company_id, name)` unique
- `company_secret_versions(secret_id, version)` unique
- `project_memberships(company_id, user_id)`
- `project_memberships(company_id, user_id, project_id)` unique
- `agent_memberships(company_id, user_id)`
- `agent_memberships(company_id, user_id, agent_id)` unique
## 7.14 `assets` + `issue_attachments`
## 7.15 `assets` + `issue_attachments`
- `assets` stores provider-backed object metadata (not inline bytes):
- `id` uuid pk
@@ -623,14 +652,28 @@ Server behavior:
- `GET /projects/:projectId`
- `PATCH /projects/:projectId`
## 10.6 Approvals
## 10.6 Current-user Resource Memberships
- `GET /companies/:companyId/resource-memberships/me`
- `PUT /companies/:companyId/resource-memberships/me/projects/:projectId`
- `PUT /companies/:companyId/resource-memberships/me/agents/:agentId`
Request payload:
```json
{ "state": "joined" }
```
Allowed states are `joined` and `left`. Endpoints require a concrete board user and active company membership, reject agent API keys, and only mutate the caller's own sidebar visibility state. Joining/leaving is idempotent; missing rows read as `joined`.
## 10.7 Approvals
- `GET /companies/:companyId/approvals?status=pending`
- `POST /companies/:companyId/approvals`
- `POST /approvals/:approvalId/approve`
- `POST /approvals/:approvalId/reject`
## 10.7 Cost and Budgets
## 10.8 Cost and Budgets
- `POST /companies/:companyId/cost-events`
- `GET /companies/:companyId/costs/summary`
@@ -639,7 +682,7 @@ Server behavior:
- `PATCH /companies/:companyId/budgets`
- `PATCH /agents/:agentId/budgets`
## 10.8 Activity and Dashboard
## 10.9 Activity and Dashboard
- `GET /companies/:companyId/activity`
- `GET /companies/:companyId/dashboard`
@@ -651,7 +694,7 @@ Dashboard payload must include:
- month-to-date spend and budget utilization
- pending approvals count
## 10.9 Error Semantics
## 10.10 Error Semantics
- `400` validation error
- `401` unauthenticated
@@ -661,7 +704,7 @@ Dashboard payload must include:
- `422` semantic rule violation
- `500` server error
## 10.10 Current Implementation API Addenda
## 10.11 Current Implementation API Addenda
The current app also exposes V1-supporting surfaces for:
doc/assets/banner.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 404 KiB

doc/plans/2026-03-14-adapter-skill-sync-rollout.md
+64 -50
View File
@@ -1,6 +1,6 @@
# 2026-03-14 Adapter Skill Sync Rollout
Status: Proposed
Status: Implemented for local adapters; gateway remains unsupported
Date: 2026-03-14
Audience: Product and engineering
Related:
@@ -25,8 +25,10 @@ Paperclip currently has these adapters:
- `claude_local`
- `codex_local`
- `cursor_local`
- `cursor`
- `gemini_local`
- `grok_local`
- `acpx_local`
- `opencode_local`
- `pi_local`
- `openclaw_gateway`
@@ -39,12 +41,14 @@ The current skill API supports:
Current implementation state:
- `codex_local`: implemented, `persistent`
- `codex_local`: implemented, `ephemeral`
- `claude_local`: implemented, `ephemeral`
- `cursor_local`: not yet implemented, but technically suited to `persistent`
- `gemini_local`: not yet implemented, but technically suited to `persistent`
- `pi_local`: not yet implemented, but technically suited to `persistent`
- `opencode_local`: not yet implemented; likely `persistent`, but with special handling because it currently injects into Claude’s shared skills home
- `cursor`: implemented, `persistent`
- `gemini_local`: implemented, `persistent`
- `pi_local`: implemented, `persistent`
- `opencode_local`: implemented, `persistent`, with shared Claude skills home caveats
- `acpx_local`: implemented, `ephemeral` for Claude/Codex sub-agents and `unsupported` for custom commands
- `grok_local`: implemented, `ephemeral`
- `openclaw_gateway`: not yet implemented; blocked on gateway protocol support, so `unsupported` for now
## 3. Product Principles
@@ -64,8 +68,7 @@ These adapters have a stable local skills directory that Paperclip can read and
Candidates:
- `codex_local`
- `cursor_local`
- `cursor`
- `gemini_local`
- `pi_local`
- `opencode_local` with caveats
@@ -84,7 +87,10 @@ These adapters do not have a meaningful Paperclip-owned persistent install state
Current adapter:
- `codex_local`
- `claude_local`
- `acpx_local` when configured for Claude or Codex
- `grok_local`
Expected UX:
@@ -99,6 +105,7 @@ These adapters cannot support skill sync without new external capabilities.
Current adapter:
- `acpx_local` when configured for custom commands
- `openclaw_gateway`
Expected UX:
@@ -114,7 +121,7 @@ Expected UX:
Target mode:
- `persistent`
- `ephemeral`
Current state:
@@ -122,15 +129,15 @@ Current state:
Requirements to finish:
- keep as reference implementation
- tighten tests around external custom skills and stale removal
- ensure imported company skills can be attached and synced without manual path work
- keep runtime-mounted snapshots separate from persistent install snapshots
- ensure imported company skills can be attached and mounted without manual path work
- keep `CODEX_HOME/skills` mutation scoped to heartbeat execution, not `skills/sync`
Success criteria:
- list installed managed and external skills
- sync desired skills into `CODEX_HOME/skills`
- preserve external user-managed skills
- desired skills are stored in Paperclip
- selected skills are linked into the effective `CODEX_HOME/skills` during runs
- no persistent installed/stale state is reported from `skills/sync`
### 5.2 Claude Local
@@ -162,18 +169,11 @@ Target mode:
Technical basis:
- runtime already injects Paperclip skills into `~/.cursor/skills`
- Paperclip reconciles desired skills into `~/.cursor/skills`
Implementation work:
Current state:
1. Add `listSkills` for Cursor.
2. Add `syncSkills` for Cursor.
3. Reuse the same managed-symlink pattern as Codex.
4. Distinguish:
- managed Paperclip skills
- external skills already present
- missing desired skills
- stale managed skills
- implemented
Testing:
@@ -194,14 +194,11 @@ Target mode:
Technical basis:
- runtime already injects Paperclip skills into `~/.gemini/skills`
- Paperclip reconciles desired skills into `~/.gemini/skills`
Implementation work:
Current state:
1. Add `listSkills` for Gemini.
2. Add `syncSkills` for Gemini.
3. Reuse managed-symlink conventions from Codex/Cursor.
4. Verify auth remains untouched while skills are reconciled.
- implemented
Potential caveat:
@@ -219,14 +216,11 @@ Target mode:
Technical basis:
- runtime already injects Paperclip skills into `~/.pi/agent/skills`
- Paperclip reconciles desired skills into `~/.pi/agent/skills`
Implementation work:
Current state:
1. Add `listSkills` for Pi.
2. Add `syncSkills` for Pi.
3. Reuse managed-symlink helpers.
4. Verify session-file behavior remains independent from skill sync.
- implemented
Success criteria:
@@ -250,9 +244,7 @@ This is product-risky because:
Plan:
Phase 1:
- implement `listSkills` and `syncSkills`
- implemented `listSkills` and `syncSkills`
- treat it as `persistent`
- explicitly label the home as shared in UI copy
- only remove stale managed Paperclip skills that are clearly marked as Paperclip-managed
@@ -290,6 +282,30 @@ Future target:
- likely a fourth truth model eventually, such as remote-managed persistent state
- for now, keep the current API and treat gateway as unsupported
### 5.8 ACPX Local
Target mode:
- `ephemeral` for built-in Claude/Codex ACPX sub-agents
- `unsupported` for custom ACP commands
Success criteria:
- Claude/Codex ACPX snapshots show skills as configured for the next session
- custom command snapshots keep desired skills tracked only and do not imply runtime sync
### 5.9 Grok Local
Target mode:
- `ephemeral`
Success criteria:
- desired skills are stored in Paperclip
- selected skills are copied into the execution workspace for the next run
- no persistent installed/stale state is reported from `skills/sync`
## 6. API Plan
## 6.1 Keep the current minimal adapter API
@@ -333,14 +349,13 @@ Additional UI requirement for shared-home adapters:
Ship:
- `cursor_local`
- `cursor`
- `gemini_local`
- `pi_local`
Rationale:
Status:
- these are the closest to Codex in architecture
- they already inject into stable local skill homes
- implemented
### Phase 2: OpenCode shared-home support
@@ -348,10 +363,9 @@ Ship:
- `opencode_local`
Rationale:
Status:
- technically feasible now
- needs slightly more careful product language because of the shared Claude skills home
- implemented with shared Claude skills-home warning
### Phase 3: Gateway support decision
@@ -390,10 +404,10 @@ Adapter-wide skill support is ready when all are true:
The recommended immediate order is:
1. `cursor_local`
1. `cursor`
2. `gemini_local`
3. `pi_local`
4. `opencode_local`
5. defer `openclaw_gateway`
That gets Paperclip from “skills work for Codex and Claude” to “skills work for the whole local-adapter family,” which is the meaningful V1 milestone.
The local-adapter family now has explicit truth models. The remaining V1 boundary is `openclaw_gateway`, which should stay unsupported until the gateway protocol can report real remote skill state.
doc/plans/2026-05-26-skills-cli-catalog-contract.md
+486
View File
@@ -0,0 +1,486 @@
# Skills CLI And Catalog Contract
Status: Phase A engineering contract
Date: 2026-05-26
Source plan: approved Paperclip skills CLI and catalog plan
This document freezes the first implementation contract for the `paperclipai skills`
command group and the app-shipped skills catalog. It is intentionally a build
contract, not a full product spec.
## Decisions
- `paperclipai skills` manages Paperclip company skills. It does not manage
local adapter homes directly.
- Installing a skill means adding or updating a company-scoped
`company_skills` record.
- Attaching a skill to an agent is a separate agent desired-state operation.
- Adapter runtime sync is a third step handled through adapter skill APIs.
- Root `skills/` remains reserved for Paperclip runtime and operational skills.
- App-shipped catalog skills live in `packages/skills-catalog`, not root
`skills/`.
- Catalog skills are inspectable before install. Inspection never mutates company
state.
- External sources continue to use the existing company skill import API in the
first release. No separate marketplace, tap, or source registry is part of this
phase.
- Agent desired skills continue to live in
`adapterConfig.paperclipSkillSync.desiredSkills` for the first release. Do not
add a normalized `agent_skills` table unless later implementation evidence
requires it.
## Terms
- Company skill: a row in `company_skills`, owned by one company.
- Catalog skill: an app-shipped skill entry in `@paperclipai/skills-catalog`.
- Skill ref: a user-supplied company skill reference. The CLI accepts company
skill `id`, canonical `key`, or unique `slug`.
- Catalog ref: a user-supplied catalog reference. The CLI accepts catalog `id`,
canonical `key`, or unique `slug`.
- Desired skills: the skill key set stored on the agent adapter config.
- Runtime snapshot: the adapter-reported `AgentSkillSnapshot` for desired,
installed, missing, stale, external, required, or unsupported skills.
## CLI Contract
All skills commands use the existing client command stack:
- Global client options: `--data-dir`, `--config`, `--context`, `--profile`,
`--api-base`, `--api-key`, and `--json`.
- Company-scoped commands also accept `-C, --company-id <id>` and otherwise use
`PAPERCLIP_COMPANY_ID` or the active context profile.
- Human output goes to stdout. Errors go to stderr.
- `--json` prints pretty JSON and no decorative labels.
- Successful commands exit `0`. Validation, API, or conflict errors exit `1`.
- API errors use the existing `API error <status>: <message>` formatting.
- Mutating commands print a short summary in human mode and the raw result in
JSON mode.
- Commands that can delete or clear state must prompt in a TTY. In non-TTY mode
they must require `--yes`.
### Company Skill Commands
These commands are Phase B and must work over existing APIs.
| Command | Behavior | JSON output |
|---|---|---|
| `skills list` | Lists company skills from `GET /api/companies/:companyId/skills`. Human rows include `id`, `key`, `slug`, `name`, `source`, `trust`, `compatibility`, and `attachedAgents`. | `CompanySkillListItem[]` |
| `skills show <skill-ref>` | Resolves `id`, `key`, or unique `slug`, then reads detail. Ambiguous slugs are conflicts. | `CompanySkillDetail` |
| `skills file <skill-ref> [--path <path>]` | Resolves the skill, reads a file with default `SKILL.md`, and prints raw file content in human mode. This command must remain pipeable. | `CompanySkillFileDetail` |
| `skills import <source>` | Calls existing import API. Source may be a local path, GitHub URL, skills.sh URL or command, `owner/repo`, `owner/repo/skill`, or URL-like source already accepted by the server. | `CompanySkillImportResult` |
| `skills create --name <name> [--slug <slug>] [--description <text>] [--body-file <path|->]` | Creates a managed local company skill. If `--body-file` is omitted, the server default body is used. `-` reads markdown from stdin. | `CompanySkill` |
| `skills scan-projects [--project-id <id>...] [--workspace-id <id>...]` | Calls project scan. Repeated flags become arrays. With neither flag, scan all accessible project workspaces. | `CompanySkillProjectScanResult` |
| `skills check [skill-ref]` | Reads update status for one skill, or for every listed company skill when no ref is provided. Unsupported statuses are shown, not hidden. | `CompanySkillCheckRow[]` |
| `skills update <skill-ref>` | Installs the update for one skill through the existing install-update API. | `CompanySkillUpdateRow` |
| `skills update --all` | Checks all skills, installs only those with `hasUpdate=true`, and reports skipped unsupported or current skills. | `CompanySkillUpdateRow[]` |
| `skills remove <skill-ref> [--yes]` | Deletes one company skill after confirmation. | `CompanySkill` |
`CompanySkillCheckRow` is a CLI-side shape:
```ts
interface CompanySkillCheckRow {
skill: Pick<CompanySkillListItem, "id" | "key" | "slug" | "name">;
status: CompanySkillUpdateStatus;
}
```
`CompanySkillUpdateRow` is a CLI-side shape:
```ts
interface CompanySkillUpdateRow {
skillRef: string;
action: "updated" | "skipped" | "failed";
skill?: CompanySkill;
status?: CompanySkillUpdateStatus;
reason?: string;
}
```
### Agent Skill Commands
These commands are Phase B and use existing agent skill APIs.
| Command | Behavior | JSON output |
|---|---|---|
| `skills agent list <agent-ref>` | Resolves the agent using existing agent reference behavior, then prints the adapter `AgentSkillSnapshot`. Human rows include `key`, `runtimeName`, `desired`, `managed`, `required`, `state`, `origin`, and `detail`. | `AgentSkillSnapshot` |
| `skills agent sync <agent-ref> --skill <skill-ref>...` | Replaces the agent's non-required desired skill set with the supplied refs and triggers adapter sync. Required Paperclip skills remain enforced by the server. | `AgentSkillSnapshot` |
| `skills agent clear <agent-ref> [--yes]` | Clears non-required desired skills by sending an empty desired list, then returns the adapter snapshot. | `AgentSkillSnapshot` |
The word `sync` is deliberate: it is a desired-state replacement, not an append.
An additive command can be added later if operators need it.
### Catalog CLI Commands
These commands are Phase E and depend on the catalog APIs from Phase D.
| Command | Behavior | JSON output |
|---|---|---|
| `skills browse [--kind bundled|optional] [--category <slug>] [--query <text>]` | Lists app-shipped catalog skills. Human rows include `id`, `key`, `kind`, `category`, `slug`, `name`, `trust`, and `recommendedForRoles`. | `CatalogSkillListItem[]` |
| `skills search <query> [--kind bundled|optional] [--category <slug>]` | Alias for catalog browse with `query`. | `CatalogSkillListItem[]` |
| `skills inspect <catalog-ref>` | Shows app-shipped catalog detail and file inventory. Does not mutate company state. | `CatalogSkillDetail` |
| `skills install <catalog-ref> [--as <slug>] [--force]` | Installs a catalog skill into a company library. `--as` overrides the company skill slug. `--force` may replace a same-key catalog skill but must not bypass hard validation or dangerous security findings. | `CompanySkillInstallCatalogResult` |
Catalog commands are for the app-shipped Paperclip catalog only. External GitHub,
skills.sh, local path, and URL installs remain under `skills import <source>` in
the first release.
## Catalog Package Contract
Add a workspace package:
```text
packages/skills-catalog/
package.json
tsconfig.json
src/
index.ts
types.ts
catalog/
bundled/
<category>/
<slug>/
SKILL.md
references/
scripts/
assets/
optional/
<category>/
<slug>/
SKILL.md
references/
scripts/
assets/
generated/
catalog.json
scripts/
build-catalog-manifest.ts
validate-catalog.ts
```
Package name: `@paperclipai/skills-catalog`.
The package exports:
- `catalogManifest`
- `catalogSkills`
- `resolveCatalogSkillRef(ref)`
- `getCatalogSkill(id)`
- TypeScript types for every manifest shape
Server and CLI code must import the generated manifest. They must not crawl
arbitrary repository paths at request time.
## Catalog Manifest
The generated artifact is `packages/skills-catalog/generated/catalog.json`.
It is checked in and regenerated by the package build or validation script.
```ts
interface CatalogManifest {
schemaVersion: 1;
packageName: "@paperclipai/skills-catalog";
packageVersion: string;
generatedAt: string;
skills: CatalogSkill[];
}
interface CatalogSkill {
id: string;
key: string;
kind: "bundled" | "optional";
category: string;
slug: string;
name: string;
description: string;
path: string;
entrypoint: "SKILL.md";
trustLevel: "markdown_only" | "assets" | "scripts_executables";
compatibility: "compatible" | "unknown" | "invalid";
defaultInstall: boolean;
recommendedForRoles: string[];
requires: string[];
tags: string[];
files: CatalogSkillFile[];
contentHash: string;
}
interface CatalogSkillFile {
path: string;
kind: "skill" | "markdown" | "reference" | "script" | "asset" | "other";
sizeBytes: number;
sha256: string;
}
```
`id` is path-safe:
```text
paperclipai:<kind>:<category>:<slug>
```
`key` is the canonical company skill key installed into `company_skills`:
```text
paperclipai/<kind>/<category>/<slug>
```
Example:
```json
{
"id": "paperclipai:bundled:software-development:github-pr-workflow",
"key": "paperclipai/bundled/software-development/github-pr-workflow",
"kind": "bundled",
"category": "software-development",
"slug": "github-pr-workflow",
"name": "github-pr-workflow",
"description": "Prepare pull requests, review responses, and verification notes.",
"path": "catalog/bundled/software-development/github-pr-workflow",
"entrypoint": "SKILL.md",
"trustLevel": "markdown_only",
"compatibility": "compatible",
"defaultInstall": false,
"recommendedForRoles": ["engineer"],
"requires": [],
"tags": ["github", "pull-requests"],
"files": [
{
"path": "SKILL.md",
"kind": "skill",
"sizeBytes": 1200,
"sha256": "..."
}
],
"contentHash": "sha256:..."
}
```
## Catalog Skill Frontmatter
Each catalog `SKILL.md` must include:
```yaml
---
name: github-pr-workflow
description: Prepare pull requests, review responses, and verification notes.
key: paperclipai/bundled/software-development/github-pr-workflow
recommendedForRoles:
- engineer
tags:
- github
- pull-requests
---
```
Optional frontmatter:
- `slug`
- `defaultInstall`
- `requires`
- `metadata`
The manifest generator owns `kind`, `category`, `path`, `files`,
`trustLevel`, `compatibility`, and `contentHash`.
## Catalog Validation Rules
Validation must fail when:
- A catalog entry is not under `catalog/bundled/<category>/<slug>` or
`catalog/optional/<category>/<slug>`.
- `SKILL.md` is missing.
- `category` or `slug` is not a lowercase URL slug.
- `name` or `description` frontmatter is missing or empty.
- The frontmatter `key`, when present, does not equal the generated key.
- Two catalog entries have the same `id`, `key`, or `slug`.
- File inventory includes absolute paths, `..` segments, broken symlinks, or
files outside the skill directory.
- A file exceeds the package-level size limit chosen by implementation.
- A skill marked `compatible` cannot be parsed as Agent Skills markdown.
- The generated manifest differs from the checked-in
`generated/catalog.json`.
Trust level is derived from inventory:
- `scripts_executables` when any file is classified as `script`.
- `assets` when any file is classified as `asset` or `other` and no script is
present.
- `markdown_only` when all files are markdown, references, or `SKILL.md`.
Validation must report all discovered catalog errors when practical, not just
the first one.
## Catalog API Contract
Phase D adds read APIs and one company install API.
```text
GET /api/skills/catalog
GET /api/skills/catalog/:catalogId
GET /api/skills/catalog/:catalogId/files?path=SKILL.md
POST /api/companies/:companyId/skills/install-catalog
```
`GET /api/skills/catalog` accepts:
- `kind=bundled|optional`
- `category=<slug>`
- `q=<text>`
`catalogId` is the path-safe manifest `id`. The server should also support
resolution by `key` or unique `slug` where the ref is carried in a query or body,
but route parameters use `id` to avoid slash handling ambiguity.
Install request:
```ts
interface CompanySkillInstallCatalogRequest {
catalogSkillId: string;
slug?: string | null;
force?: boolean;
}
```
Install result:
```ts
interface CompanySkillInstallCatalogResult {
action: "created" | "updated" | "unchanged";
skill: CompanySkill;
catalogSkill: CatalogSkill;
warnings: string[];
}
```
Install behavior:
- Creates or updates a company skill with `sourceType="catalog"`.
- Uses catalog `key` as the company skill canonical key.
- Uses catalog `slug` unless `slug` is provided.
- Materializes the catalog files into a company-managed skill directory so
existing skill file reads continue to work.
- Stores provenance in metadata:
- `catalogId`
- `catalogKey`
- `catalogKind`
- `catalogCategory`
- `catalogPath`
- `packageName`
- `packageVersion`
- `originHash`
- `originVersion`
- `userModifiedAt`
- `updateHoldReason`
- Writes activity log entries for install and update.
- Returns `409` for duplicate slug/key conflicts that cannot be resolved safely.
- Returns `422` for invalid, incompatible, or hard-blocked catalog entries.
- `force` may replace a same-key catalog-managed skill. It must not bypass
company boundaries, permission checks, hard validation, or hard security
findings.
## Error Semantics
Use existing HTTP semantics:
- `400`: invalid CLI arguments, invalid query/body shape, or malformed refs.
- `401`: missing or invalid auth.
- `403`: authenticated principal lacks access or mutation permission.
- `404`: skill, catalog entry, agent, file, company, or source not found.
- `409`: ambiguous slug, duplicate key/slug, update conflict, or unsafe overwrite.
- `422`: semantic violation such as invalid skill content or unsupported source.
- `500`: unexpected server failure.
CLI messages should name the next useful correction, for example:
- `Skill slug "review" is ambiguous. Use an id or key.`
- `Company ID is required. Pass --company-id, set PAPERCLIP_COMPANY_ID, or set a context profile.`
- `Catalog skill contains executable scripts and cannot be force-installed until security review semantics allow it.`
## Phase Acceptance Criteria
Phase A is complete when this contract is available in the repo and the issue
thread links it.
Phase B, CLI MVP:
- `paperclipai skills --help` exposes the Phase B command group.
- All Phase B commands work against existing company skills and agent skills
APIs without schema or server changes.
- Skill refs resolve by id, key, or unique slug.
- Human and JSON output are covered by focused CLI tests.
- `doc/CLI.md` documents company install vs agent desired sync vs runtime sync.
Phase C, catalog package:
- `packages/skills-catalog` is a workspace package.
- Build or validation regenerates `generated/catalog.json`.
- Validation covers frontmatter, id/key/slug uniqueness, directory shape, file
inventory, trust derivation, and stale generated output.
- Server and CLI can import the manifest without crawling arbitrary paths.
- Root `skills/` is not expanded with the app-shipped catalog.
Phase D, catalog APIs:
- Catalog list/detail/file APIs are read-only and covered by tests.
- Install-from-catalog creates auditable company-scoped skill records with
provenance metadata and materialized files.
- Company boundary and mutation permission checks match or exceed existing
company skill mutations.
- Duplicate and unsafe overwrite behavior is explicit and tested.
Phase E, catalog CLI:
- Operators can browse, search, inspect, and install app-shipped catalog skills.
- External source behavior remains routed through `skills import`.
- Output and errors follow the Phase B CLI conventions.
- Catalog install is clearly distinct from agent attach/sync in help and docs.
Phase F, update/reset/audit:
- Security review records decisions for origin hash, user modification detection,
reset, audit findings, and force behavior.
- Implementation follows the review or records explicit deferrals.
- Mutating reset/update actions are activity logged.
- Tests cover dangerous findings, force behavior, and unchanged/current states.
Phase G, adapter truth model:
- Adapter snapshots accurately report `unsupported`, `persistent`, or
`ephemeral`.
- Desired, missing, installed, stale, external, and required states are tested.
- External adapter plugins remain dynamically loaded. No hardcoded plugin imports
are added.
Phase H, UI:
- The existing Company Skills page is extended rather than replaced.
- UX guidance covers Company, Bundled, Optional, and External source views.
- Install preview shows source, trust, provenance, update state, and file
inventory.
- Agent attach/detach states are clear.
- Frontend handoff includes screenshots or equivalent browser evidence.
Phase I, initial skill content:
- Bundled and optional entries use the finalized frontmatter and category rules.
- Skill descriptions are specific enough for browse/search.
- No script-bearing skill lands without explicit security review evidence.
- Validation fixtures or tests cover representative content.
Phase J, QA and docs:
- QA validates CLI, catalog APIs, UI install, agent sync, portability, and adapter
snapshots against a dev instance.
- Blocking defects are linked as first-class issues.
- `doc/CLI.md`, `doc/DEVELOPING.md`, and skill workflow docs match shipped
behavior.
## Deferrals
- No cloud marketplace.
- No user-home tap registry.
- No hidden curator or autonomous catalog mutator.
- No normalized `agent_skills` table in the first release.
- No skill sets or bundles in the first release.
- No automatic install of every optional catalog skill.
- No replacement of company import/export as the portability path.
doc/spec/invite-flow.md
+24 -26
View File
@@ -32,7 +32,7 @@ flowchart TD
Accepted[Invite state: accepted]
BootstrapDone[Bootstrap accepted<br/>no join request]
HumanReuse{Matching human join request<br/>already exists for same user/email?}
HumanPending[Join request<br/>pending_approval]
HumanPending[Legacy human join request<br/>pending_approval]
HumanApproved[Join request<br/>approved]
HumanRejected[Join request<br/>rejected]
AgentPending[Agent join request<br/>pending_approval<br/>+ optional claim secret]
@@ -52,12 +52,10 @@ flowchart TD
BootstrapDone --> Accepted
Active --> HumanReuse: human accept
HumanReuse --> HumanPending: reuse existing pending request
HumanReuse --> HumanApproved: reuse existing approved request
HumanReuse --> HumanPending: no reusable request<br/>create new request
HumanPending --> HumanApproved: board approves
HumanReuse --> HumanApproved: reuse existing pending/approved request<br/>ensure active membership
HumanReuse --> HumanApproved: no reusable request<br/>create and approve request
HumanPending --> HumanApproved: same invitee replays accepted invite<br/>or board approves legacy request
HumanPending --> HumanRejected: board rejects
HumanPending --> Accepted
HumanApproved --> Accepted
Active --> AgentPending: agent accept
@@ -150,7 +148,8 @@ stateDiagram-v2
state AcceptedInviteSummary {
[*] --> SummaryBranch
SummaryBranch --> PendingApprovalReload: joinRequestStatus=pending_approval
SummaryBranch --> AcceptPending: human joinRequestStatus=pending_approval/approved<br/>and membership missing
SummaryBranch --> PendingApprovalReload: agent joinRequestStatus=pending_approval
SummaryBranch --> OpeningCompany: joinRequestStatus=approved<br/>and human invite user is now a member
SummaryBranch --> RejectedReload: joinRequestStatus=rejected
SummaryBranch --> ConsumedReload: approved agent invite or other consumed state
@@ -177,6 +176,7 @@ sequenceDiagram
participant Landing as Invite landing UI
participant Auth as Auth session
participant Join as join_requests table
participant Membership as company_memberships + grants
Board->>Settings: Choose role and click Create invite
Settings->>API: POST /api/companies/:companyId/invites
@@ -197,15 +197,19 @@ sequenceDiagram
API->>Join: Look for reusable human join request
alt Reusable pending or approved request exists
API->>Invites: Mark invite accepted
API-->>Landing: Existing join request status
API->>Membership: Ensure active membership and role grants
API->>Join: Mark join request approved if needed
API-->>Landing: approved join request
else No reusable request exists
API->>Invites: Mark invite accepted
API->>Join: Insert pending_approval join request
API-->>Landing: New pending_approval join request
API->>Membership: Ensure active membership and role grants
API->>Join: Mark join request approved
API-->>Landing: approved join request
end
```
### Human Approval And Reload Path
### Legacy Human Reload And Repair Path
```mermaid
sequenceDiagram
@@ -214,8 +218,6 @@ sequenceDiagram
participant Landing as Invite landing UI
participant API as Access routes
participant Join as join_requests table
actor Approver as Company admin
participant Queue as Access queue UI
participant Membership as company_memberships + grants
Invitee->>Landing: Reload consumed invite URL
@@ -223,20 +225,15 @@ sequenceDiagram
API->>Join: Load join request by inviteId
API-->>Landing: joinRequestStatus + joinRequestType
alt joinRequestStatus = pending_approval
Landing-->>Invitee: Show waiting-for-approval panel
Approver->>Queue: Review request in Company Settings -> Access
Queue->>API: POST /companies/:companyId/join-requests/:requestId/approve
API->>Membership: Ensure membership and grants
API->>Join: Mark join request approved
Invitee->>Landing: Refresh after approval
Landing->>API: GET /api/invites/:token
API->>Join: Reload approved join request
alt human joinRequestStatus = pending_approval or approved but membership missing
Landing->>API: POST /api/invites/:token/accept (requestType=human)
API->>Membership: Ensure active membership and role grants
API->>Join: Mark join request approved if needed
API-->>Landing: approved status
Landing-->>Invitee: Opening company and redirect
else joinRequestStatus = rejected
Landing-->>Invitee: Show rejected error panel
else joinRequestStatus = approved but membership missing
else agent invite or unavailable consumed state
Landing-->>Invitee: Fall through to consumed/unavailable state
end
```
@@ -286,14 +283,15 @@ sequenceDiagram
## Notes
- `GET /api/invites/:token` treats `revoked` and `expired` invites as unavailable. Accepted invites remain resolvable when they already have a linked join request, and the summary now includes `joinRequestStatus` plus `joinRequestType`.
- Human acceptance consumes the invite immediately and then either creates a new join request or reuses an existing `pending_approval` or `approved` human join request for the same user/email.
- Human acceptance consumes the invite, creates or reuses the matching human join request, immediately marks it `approved`, and ensures an active company membership with the invite's selected role/grants.
- The landing page has two layers of post-accept UI:
- immediate mutation-result UI from `POST /api/invites/:token/accept`
- reload-time summary UI from `GET /api/invites/:token` once the invite has already been consumed
- Reload behavior for accepted company invites is now status-sensitive:
- `pending_approval` re-renders the waiting-for-approval panel
- human `pending_approval` or `approved` states replay acceptance for the same signed-in user/email so legacy consumed invites can repair missing membership
- agent `pending_approval` re-renders the waiting-for-approval panel
- `rejected` renders the "This join request was not approved." error panel
- `approved` only becomes a success path for human invites after membership is visible to the current session; otherwise the page falls through to the generic consumed/unavailable state
- `approved` becomes a success path for human invites after membership is visible to the current session
- `GET /api/invites/:token/logo` still rejects accepted invites, so accepted-invite reload states may fall back to the generated company icon even though the summary payload still carries `companyLogoUrl`.
- The only accepted-invite replay path in the current implementation is `POST /api/invites/:token/accept` for `agent` requests with `adapterType=openclaw_gateway`, and only when the existing join request is still `pending_approval` or already `approved`.
- Accepted-invite replay is supported for matching human invitees to repair/complete membership, and for `agent` requests with `adapterType=openclaw_gateway` when the existing join request is still `pending_approval` or already `approved`.
- `bootstrap_ceo` invites are one-time and do not create join requests.
docs/cli/control-plane-commands.md
+23
View File
@@ -63,6 +63,29 @@ pnpm paperclipai agent list
pnpm paperclipai agent get <agent-id>
```
## Skills Commands
```sh
# Browse app-shipped catalog skills without changing company state
pnpm paperclipai skills browse [--kind bundled|optional] [--category software-development] [--query github]
pnpm paperclipai skills search "pull request" [--json]
# Inspect catalog metadata and file inventory before install
pnpm paperclipai skills inspect github-pr-workflow
# Install a catalog skill into the company skill library
# This does not attach the skill to any agent.
pnpm paperclipai skills install github-pr-workflow --company-id <company-id>
pnpm paperclipai skills install github-pr-workflow --as pr-flow --force --company-id <company-id>
# External sources still use import instead of catalog install
pnpm paperclipai skills import ./skills/my-skill --company-id <company-id>
pnpm paperclipai skills import owner/repo/path/to/skill --company-id <company-id>
# Attach desired company skills to an agent after install/import
pnpm paperclipai skills agent sync <agent-id> --skill github-pr-workflow --company-id <company-id>
```
## Approval Commands
```sh
packages/adapter-utils/src/server-utils.test.ts
+182
View File
@@ -6,6 +6,8 @@ import { describe, expect, it } from "vitest";
import {
applyPaperclipWorkspaceEnv,
appendWithByteCap,
buildPersistentSkillSnapshot,
buildRuntimeMountedSkillSnapshot,
buildInvocationEnvForLogs,
DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
materializePaperclipSkillCopy,
@@ -205,6 +207,186 @@ describe("materializePaperclipSkillCopy", () => {
});
});
describe("adapter skill snapshots", () => {
const requiredEntry = {
key: "paperclipai/paperclip/paperclip",
runtimeName: "paperclip",
source: "/runtime/paperclip",
required: true,
requiredReason: "Required for Paperclip heartbeats.",
};
const optionalEntry = {
key: "company/ascii-heart",
runtimeName: "ascii-heart",
source: "/runtime/ascii-heart",
};
it("reports runtime-mounted adapters as configured or missing without install state", () => {
const snapshot = buildRuntimeMountedSkillSnapshot({
adapterType: "codex_local",
availableEntries: [requiredEntry],
desiredSkills: [requiredEntry.key, "missing-skill"],
configuredDetail: "Mounted on next run.",
});
expect(snapshot).toMatchObject({
supported: true,
mode: "ephemeral",
desiredSkills: [requiredEntry.key, "missing-skill"],
});
expect(snapshot.entries).toEqual([
expect.objectContaining({
key: "missing-skill",
state: "missing",
origin: "external_unknown",
desired: true,
}),
expect.objectContaining({
key: requiredEntry.key,
state: "configured",
origin: "paperclip_required",
required: true,
detail: "Mounted on next run.",
}),
]);
});
it("reports source-missing company runtime skills without orphan warnings", () => {
const snapshot = buildRuntimeMountedSkillSnapshot({
adapterType: "codex_local",
availableEntries: [{
key: "company/example/reflection-coach",
runtimeName: "reflection-coach--abc123",
source: "/paperclip/skills/example/__runtime__/reflection-coach--abc123",
sourceStatus: "missing",
missingDetail: "Company skill exists, but its local source is missing.",
}],
desiredSkills: ["company/example/reflection-coach"],
configuredDetail: "Mounted on next run.",
});
expect(snapshot.warnings).toEqual([]);
expect(snapshot.entries).toEqual([
expect.objectContaining({
key: "company/example/reflection-coach",
state: "missing",
origin: "company_managed",
sourcePath: null,
detail: "Company skill exists, but its local source is missing.",
}),
]);
});
it("keeps unsupported runtime-mounted adapters in tracked-only state", () => {
const snapshot = buildRuntimeMountedSkillSnapshot({
adapterType: "acpx_local",
availableEntries: [requiredEntry],
desiredSkills: [requiredEntry.key],
configuredDetail: "Mounted on next run.",
mode: "unsupported",
unsupportedDetail: "Tracked only.",
});
expect(snapshot.supported).toBe(false);
expect(snapshot.mode).toBe("unsupported");
expect(snapshot.entries).toContainEqual(expect.objectContaining({
key: requiredEntry.key,
desired: true,
state: "available",
detail: "Tracked only.",
}));
});
it("can surface read-only external skills for runtime-mounted adapters", () => {
const snapshot = buildRuntimeMountedSkillSnapshot({
adapterType: "claude_local",
availableEntries: [requiredEntry],
desiredSkills: [requiredEntry.key],
configuredDetail: "Mounted on next run.",
externalInstalled: new Map([
["crack-python", { targetPath: "/home/me/.claude/skills/crack-python", kind: "directory" }],
]),
externalLocationLabel: "~/.claude/skills",
externalDetail: "Installed outside Paperclip management in the Claude skills home.",
});
expect(snapshot.entries).toContainEqual(expect.objectContaining({
key: "crack-python",
runtimeName: "crack-python",
state: "external",
managed: false,
origin: "user_installed",
locationLabel: "~/.claude/skills",
readOnly: true,
}));
});
it("reports persistent adapter installed, stale, external, and missing states", () => {
const snapshot = buildPersistentSkillSnapshot({
adapterType: "cursor",
availableEntries: [requiredEntry, optionalEntry],
desiredSkills: [requiredEntry.key, "missing-skill"],
installed: new Map([
["paperclip", { targetPath: "/runtime/paperclip", kind: "symlink" }],
["ascii-heart", { targetPath: "/other/ascii-heart", kind: "directory" }],
["old-managed", { targetPath: "/runtime/old-managed", kind: "symlink" }],
]),
skillsHome: "/home/me/.cursor/skills",
locationLabel: "~/.cursor/skills",
installedDetail: "Installed in the Cursor skills home.",
missingDetail: "Configured but not linked.",
externalConflictDetail: "Name occupied externally.",
externalDetail: "Installed outside Paperclip management.",
});
expect(snapshot.mode).toBe("persistent");
expect(snapshot.entries).toContainEqual(expect.objectContaining({
key: requiredEntry.key,
state: "installed",
managed: true,
origin: "paperclip_required",
}));
expect(snapshot.entries).toContainEqual(expect.objectContaining({
key: optionalEntry.key,
state: "external",
managed: false,
detail: "Installed outside Paperclip management.",
}));
expect(snapshot.entries).toContainEqual(expect.objectContaining({
key: "missing-skill",
state: "missing",
origin: "external_unknown",
}));
expect(snapshot.entries).toContainEqual(expect.objectContaining({
key: "old-managed",
state: "external",
origin: "user_installed",
}));
});
it("reports stale managed persistent skills when Paperclip owns an undesired available skill", () => {
const snapshot = buildPersistentSkillSnapshot({
adapterType: "cursor",
availableEntries: [optionalEntry],
desiredSkills: [],
installed: new Map([
["ascii-heart", { targetPath: "/runtime/ascii-heart", kind: "symlink" }],
]),
skillsHome: "/home/me/.cursor/skills",
missingDetail: "Configured but not linked.",
externalConflictDetail: "Name occupied externally.",
externalDetail: "Installed outside Paperclip management.",
});
expect(snapshot.entries).toContainEqual(expect.objectContaining({
key: optionalEntry.key,
desired: false,
state: "stale",
managed: true,
}));
});
});
describe("runChildProcess", () => {
it("does not arm a timeout when timeoutSec is 0", async () => {
const result = await runChildProcess(
packages/adapter-utils/src/server-utils.ts
+177
View File
@@ -133,6 +133,8 @@ export interface PaperclipSkillEntry {
key: string;
runtimeName: string;
source: string;
sourceStatus?: "available" | "missing";
missingDetail?: string | null;
required?: boolean;
requiredReason?: string | null;
}
@@ -161,6 +163,22 @@ interface PersistentSkillSnapshotOptions {
warnings?: string[];
}
interface RuntimeMountedSkillSnapshotOptions {
adapterType: string;
availableEntries: PaperclipSkillEntry[];
desiredSkills: string[];
configuredDetail: string | ((entry: PaperclipSkillEntry) => string | null);
missingDetail?: string;
mode?: "ephemeral" | "unsupported";
supported?: boolean;
unsupportedDetail?: string | ((entry: PaperclipSkillEntry) => string | null);
warnings?: string[];
externalInstalled?: Map<string, InstalledSkillTarget>;
externalLocationLabel?: string | null;
externalDetail?: string;
skillsHome?: string;
}
function normalizePathSlashes(value: string): string {
return value.replaceAll("\\", "/");
}
@@ -193,6 +211,26 @@ function buildManagedSkillOrigin(entry: { required?: boolean }): Pick<
};
}
function isPaperclipSkillSourceMissing(entry: PaperclipSkillEntry) {
return entry.sourceStatus === "missing";
}
function resolvePaperclipSkillMissingDetail(
entry: PaperclipSkillEntry,
fallback: string,
) {
return entry.missingDetail?.trim() || fallback;
}
function resolveSkillDetail(
detail: string | ((entry: PaperclipSkillEntry) => string | null) | null | undefined,
entry: PaperclipSkillEntry,
): string | null {
if (typeof detail === "function") return detail(entry);
if (typeof detail === "string") return detail;
return null;
}
function resolveInstalledEntryTarget(
skillsHome: string,
entryName: string,
@@ -1381,6 +1419,120 @@ export async function readInstalledSkillTargets(skillsHome: string): Promise<Map
return out;
}
export function buildRuntimeMountedSkillSnapshot(
options: RuntimeMountedSkillSnapshotOptions,
): AdapterSkillSnapshot {
const {
adapterType,
availableEntries,
desiredSkills,
configuredDetail,
missingDetail = "Paperclip cannot find this skill in the local runtime skills directory.",
mode = "ephemeral",
externalInstalled,
externalLocationLabel,
externalDetail = "Installed outside Paperclip management.",
skillsHome,
} = options;
const supported = options.supported ?? mode !== "unsupported";
const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
const desiredSet = new Set(desiredSkills);
const entries: AdapterSkillEntry[] = [];
const warnings = [...(options.warnings ?? [])];
for (const available of availableEntries) {
const desired = desiredSet.has(available.key);
if (isPaperclipSkillSourceMissing(available)) {
entries.push({
key: available.key,
runtimeName: available.runtimeName,
desired,
managed: true,
state: "missing",
sourcePath: null,
targetPath: null,
detail: resolvePaperclipSkillMissingDetail(available, missingDetail),
required: Boolean(available.required),
requiredReason: available.requiredReason ?? null,
...buildManagedSkillOrigin(available),
});
continue;
}
const configured = supported && mode === "ephemeral" && desired;
entries.push({
key: available.key,
runtimeName: available.runtimeName,
desired,
managed: true,
state: configured ? "configured" : "available",
sourcePath: available.source,
targetPath: null,
detail: desired
? configured
? resolveSkillDetail(configuredDetail, available)
: resolveSkillDetail(
options.unsupportedDetail
?? "Desired state is stored in Paperclip only; this adapter cannot apply skills at runtime.",
available,
)
: null,
required: Boolean(available.required),
requiredReason: available.requiredReason ?? null,
...buildManagedSkillOrigin(available),
});
}
for (const desiredSkill of desiredSkills) {
if (availableByKey.has(desiredSkill)) continue;
warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
entries.push({
key: desiredSkill,
runtimeName: null,
desired: true,
managed: true,
state: "missing",
sourcePath: null,
targetPath: null,
detail: missingDetail,
origin: "external_unknown",
originLabel: "External or unavailable",
readOnly: false,
});
}
if (externalInstalled) {
for (const [name, installedEntry] of externalInstalled.entries()) {
if (availableEntries.some((entry) => entry.runtimeName === name)) continue;
entries.push({
key: name,
runtimeName: name,
desired: false,
managed: false,
state: "external",
origin: "user_installed",
originLabel: "User-installed",
locationLabel: skillLocationLabel(externalLocationLabel),
readOnly: true,
sourcePath: null,
targetPath: installedEntry.targetPath ?? (skillsHome ? path.join(skillsHome, name) : null),
detail: externalDetail,
});
}
}
entries.sort((left, right) => left.key.localeCompare(right.key));
return {
adapterType,
supported,
mode,
desiredSkills,
entries,
warnings,
};
}
export function buildPersistentSkillSnapshot(
options: PersistentSkillSnapshotOptions,
): AdapterSkillSnapshot {
@@ -1404,6 +1556,26 @@ export function buildPersistentSkillSnapshot(
for (const available of availableEntries) {
const installedEntry = installed.get(available.runtimeName) ?? null;
const desired = desiredSet.has(available.key);
if (isPaperclipSkillSourceMissing(available)) {
entries.push({
key: available.key,
runtimeName: available.runtimeName,
desired,
managed: true,
state: "missing",
sourcePath: null,
targetPath: path.join(skillsHome, available.runtimeName),
detail: resolvePaperclipSkillMissingDetail(
available,
missingDetail,
),
required: Boolean(available.required),
requiredReason: available.requiredReason ?? null,
...buildManagedSkillOrigin(available),
});
continue;
}
let state: AdapterSkillEntry["state"] = "available";
let managed = false;
let detail: string | null = null;
@@ -1496,6 +1668,11 @@ function normalizeConfiguredPaperclipRuntimeSkills(value: unknown): PaperclipSki
key,
runtimeName,
source,
sourceStatus: entry.sourceStatus === "missing" ? "missing" : "available",
missingDetail:
typeof entry.missingDetail === "string" && entry.missingDetail.trim().length > 0
? entry.missingDetail.trim()
: null,
required: asBoolean(entry.required, false),
requiredReason:
typeof entry.requiredReason === "string" && entry.requiredReason.trim().length > 0
packages/adapters/acpx-local/src/server/skills.ts
+7 -46
View File
@@ -2,10 +2,10 @@ import path from "node:path";
import { fileURLToPath } from "node:url";
import type {
AdapterSkillContext,
AdapterSkillEntry,
AdapterSkillSnapshot,
} from "@paperclipai/adapter-utils";
import {
buildRuntimeMountedSkillSnapshot,
readPaperclipRuntimeSkillEntries,
resolvePaperclipDesiredSkillNames,
} from "@paperclipai/adapter-utils/server-utils";
@@ -35,9 +35,7 @@ function unsupportedDetail(): string {
async function buildAcpxSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
const acpxAgent = normalizeAcpxSkillAgent(config);
const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
const desiredSet = new Set(desiredSkills);
const supported = acpxAgent !== "custom";
const warnings: string[] = supported
? []
@@ -45,53 +43,16 @@ async function buildAcpxSkillSnapshot(config: Record<string, unknown>): Promise<
"Custom ACP commands do not expose a Paperclip skill integration contract yet; selected skills are tracked only.",
];
const entries: AdapterSkillEntry[] = availableEntries.map((entry) => {
const desired = desiredSet.has(entry.key);
return {
key: entry.key,
runtimeName: entry.runtimeName,
desired,
managed: true,
state: desired ? "configured" : "available",
origin: entry.required ? "paperclip_required" : "company_managed",
originLabel: entry.required ? "Required by Paperclip" : "Managed by Paperclip",
readOnly: false,
sourcePath: entry.source,
targetPath: null,
detail: desired ? (supported ? configuredDetail(acpxAgent) : unsupportedDetail()) : null,
required: Boolean(entry.required),
requiredReason: entry.requiredReason ?? null,
};
});
for (const desiredSkill of desiredSkills) {
if (availableByKey.has(desiredSkill)) continue;
warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
entries.push({
key: desiredSkill,
runtimeName: null,
desired: true,
managed: true,
state: "missing",
origin: "external_unknown",
originLabel: "External or unavailable",
readOnly: false,
sourcePath: null,
targetPath: null,
detail: "Paperclip cannot find this skill in the local runtime skills directory.",
});
}
entries.sort((left, right) => left.key.localeCompare(right.key));
return {
return buildRuntimeMountedSkillSnapshot({
adapterType: "acpx_local",
availableEntries,
desiredSkills,
supported,
mode: supported ? "ephemeral" : "unsupported",
desiredSkills,
entries,
configuredDetail: configuredDetail(acpxAgent),
unsupportedDetail: unsupportedDetail(),
warnings,
};
});
}
export async function listAcpxSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {
packages/adapters/claude-local/src/server/skills.ts
+9 -66
View File
@@ -3,10 +3,10 @@ import path from "node:path";
import { fileURLToPath } from "node:url";
import type {
AdapterSkillContext,
AdapterSkillEntry,
AdapterSkillSnapshot,
} from "@paperclipai/adapter-utils";
import {
buildRuntimeMountedSkillSnapshot,
readPaperclipRuntimeSkillEntries,
readInstalledSkillTargets,
resolvePaperclipDesiredSkillNames,
@@ -30,76 +30,19 @@ function resolveClaudeSkillsHome(config: Record<string, unknown>) {
async function buildClaudeSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
const desiredSet = new Set(desiredSkills);
const skillsHome = resolveClaudeSkillsHome(config);
const installed = await readInstalledSkillTargets(skillsHome);
const entries: AdapterSkillEntry[] = availableEntries.map((entry) => ({
key: entry.key,
runtimeName: entry.runtimeName,
desired: desiredSet.has(entry.key),
managed: true,
state: desiredSet.has(entry.key) ? "configured" : "available",
origin: entry.required ? "paperclip_required" : "company_managed",
originLabel: entry.required ? "Required by Paperclip" : "Managed by Paperclip",
readOnly: false,
sourcePath: entry.source,
targetPath: null,
detail: desiredSet.has(entry.key)
? "Will be materialized into the stable Paperclip-managed Claude prompt bundle on the next run."
: null,
required: Boolean(entry.required),
requiredReason: entry.requiredReason ?? null,
}));
const warnings: string[] = [];
for (const desiredSkill of desiredSkills) {
if (availableByKey.has(desiredSkill)) continue;
warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
entries.push({
key: desiredSkill,
runtimeName: null,
desired: true,
managed: true,
state: "missing",
origin: "external_unknown",
originLabel: "External or unavailable",
readOnly: false,
sourcePath: undefined,
targetPath: undefined,
detail: "Paperclip cannot find this skill in the local runtime skills directory.",
});
}
for (const [name, installedEntry] of installed.entries()) {
if (availableEntries.some((entry) => entry.runtimeName === name)) continue;
entries.push({
key: name,
runtimeName: name,
desired: false,
managed: false,
state: "external",
origin: "user_installed",
originLabel: "User-installed",
locationLabel: "~/.claude/skills",
readOnly: true,
sourcePath: null,
targetPath: installedEntry.targetPath ?? path.join(skillsHome, name),
detail: "Installed outside Paperclip management in the Claude skills home.",
});
}
entries.sort((left, right) => left.key.localeCompare(right.key));
return {
return buildRuntimeMountedSkillSnapshot({
adapterType: "claude_local",
supported: true,
mode: "ephemeral",
availableEntries,
desiredSkills,
entries,
warnings,
};
configuredDetail: "Will be materialized into the stable Paperclip-managed Claude prompt bundle on the next run.",
externalInstalled: installed,
externalLocationLabel: "~/.claude/skills",
externalDetail: "Installed outside Paperclip management in the Claude skills home.",
skillsHome,
});
}
export async function listClaudeSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {
packages/adapters/codex-local/src/server/skills.ts
+5 -48
View File
@@ -2,10 +2,10 @@ import path from "node:path";
import { fileURLToPath } from "node:url";
import type {
AdapterSkillContext,
AdapterSkillEntry,
AdapterSkillSnapshot,
} from "@paperclipai/adapter-utils";
import {
buildRuntimeMountedSkillSnapshot,
readPaperclipRuntimeSkillEntries,
resolvePaperclipDesiredSkillNames,
} from "@paperclipai/adapter-utils/server-utils";
@@ -16,56 +16,13 @@ async function buildCodexSkillSnapshot(
config: Record<string, unknown>,
): Promise<AdapterSkillSnapshot> {
const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
const desiredSet = new Set(desiredSkills);
const entries: AdapterSkillEntry[] = availableEntries.map((entry) => ({
key: entry.key,
runtimeName: entry.runtimeName,
desired: desiredSet.has(entry.key),
managed: true,
state: desiredSet.has(entry.key) ? "configured" : "available",
origin: entry.required ? "paperclip_required" : "company_managed",
originLabel: entry.required ? "Required by Paperclip" : "Managed by Paperclip",
readOnly: false,
sourcePath: entry.source,
targetPath: null,
detail: desiredSet.has(entry.key)
? "Will be linked into the effective CODEX_HOME/skills/ directory on the next run."
: null,
required: Boolean(entry.required),
requiredReason: entry.requiredReason ?? null,
}));
const warnings: string[] = [];
for (const desiredSkill of desiredSkills) {
if (availableByKey.has(desiredSkill)) continue;
warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
entries.push({
key: desiredSkill,
runtimeName: null,
desired: true,
managed: true,
state: "missing",
origin: "external_unknown",
originLabel: "External or unavailable",
readOnly: false,
sourcePath: null,
targetPath: null,
detail: "Paperclip cannot find this skill in the local runtime skills directory.",
});
}
entries.sort((left, right) => left.key.localeCompare(right.key));
return {
return buildRuntimeMountedSkillSnapshot({
adapterType: "codex_local",
supported: true,
mode: "ephemeral",
availableEntries,
desiredSkills,
entries,
warnings,
};
configuredDetail: "Will be linked into the effective CODEX_HOME/skills/ directory on the next run.",
});
}
export async function listCodexSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {
packages/adapters/grok-local/src/server/skills.ts
+5 -48
View File
@@ -2,10 +2,10 @@ import path from "node:path";
import { fileURLToPath } from "node:url";
import type {
AdapterSkillContext,
AdapterSkillEntry,
AdapterSkillSnapshot,
} from "@paperclipai/adapter-utils";
import {
buildRuntimeMountedSkillSnapshot,
readPaperclipRuntimeSkillEntries,
resolvePaperclipDesiredSkillNames,
} from "@paperclipai/adapter-utils/server-utils";
@@ -16,56 +16,13 @@ async function buildGrokSkillSnapshot(
config: Record<string, unknown>,
): Promise<AdapterSkillSnapshot> {
const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
const desiredSet = new Set(desiredSkills);
const entries: AdapterSkillEntry[] = availableEntries.map((entry) => ({
key: entry.key,
runtimeName: entry.runtimeName,
desired: desiredSet.has(entry.key),
managed: true,
state: desiredSet.has(entry.key) ? "configured" : "available",
origin: entry.required ? "paperclip_required" : "company_managed",
originLabel: entry.required ? "Required by Paperclip" : "Managed by Paperclip",
readOnly: false,
sourcePath: entry.source,
targetPath: null,
detail: desiredSet.has(entry.key)
? "Will be copied into `.claude/skills` in the execution workspace on the next run."
: null,
required: Boolean(entry.required),
requiredReason: entry.requiredReason ?? null,
}));
const warnings: string[] = [];
for (const desiredSkill of desiredSkills) {
if (availableByKey.has(desiredSkill)) continue;
warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
entries.push({
key: desiredSkill,
runtimeName: null,
desired: true,
managed: true,
state: "missing",
origin: "external_unknown",
originLabel: "External or unavailable",
readOnly: false,
sourcePath: null,
targetPath: null,
detail: "Paperclip cannot find this skill in the local runtime skills directory.",
});
}
entries.sort((left, right) => left.key.localeCompare(right.key));
return {
return buildRuntimeMountedSkillSnapshot({
adapterType: "grok_local",
supported: true,
mode: "ephemeral",
availableEntries,
desiredSkills,
entries,
warnings,
};
configuredDetail: "Will be copied into `.claude/skills` in the execution workspace on the next run.",
});
}
export async function listGrokSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {
packages/db/src/migrations/0090_resource_memberships.sql
+55
View File
@@ -0,0 +1,55 @@
CREATE TABLE IF NOT EXISTS "agent_memberships" (
"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
"company_id" uuid NOT NULL,
"agent_id" uuid NOT NULL,
"user_id" text NOT NULL,
"state" text DEFAULT 'joined' NOT NULL,
"created_at" timestamp with time zone DEFAULT now() NOT NULL,
"updated_at" timestamp with time zone DEFAULT now() NOT NULL
);
--> statement-breakpoint
CREATE TABLE IF NOT EXISTS "project_memberships" (
"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
"company_id" uuid NOT NULL,
"project_id" uuid NOT NULL,
"user_id" text NOT NULL,
"state" text DEFAULT 'joined' NOT NULL,
"created_at" timestamp with time zone DEFAULT now() NOT NULL,
"updated_at" timestamp with time zone DEFAULT now() NOT NULL
);
--> statement-breakpoint
DO $$ BEGIN
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'agent_memberships_company_id_companies_id_fk') THEN
ALTER TABLE "agent_memberships" ADD CONSTRAINT "agent_memberships_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;
END IF;
END $$;
--> statement-breakpoint
DO $$ BEGIN
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'agent_memberships_agent_id_agents_id_fk') THEN
ALTER TABLE "agent_memberships" ADD CONSTRAINT "agent_memberships_agent_id_agents_id_fk" FOREIGN KEY ("agent_id") REFERENCES "public"."agents"("id") ON DELETE cascade ON UPDATE no action;
END IF;
END $$;
--> statement-breakpoint
DO $$ BEGIN
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'project_memberships_company_id_companies_id_fk') THEN
ALTER TABLE "project_memberships" ADD CONSTRAINT "project_memberships_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;
END IF;
END $$;
--> statement-breakpoint
DO $$ BEGIN
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'project_memberships_project_id_projects_id_fk') THEN
ALTER TABLE "project_memberships" ADD CONSTRAINT "project_memberships_project_id_projects_id_fk" FOREIGN KEY ("project_id") REFERENCES "public"."projects"("id") ON DELETE cascade ON UPDATE no action;
END IF;
END $$;
--> statement-breakpoint
CREATE INDEX IF NOT EXISTS "agent_memberships_company_user_idx" ON "agent_memberships" USING btree ("company_id","user_id");
--> statement-breakpoint
CREATE INDEX IF NOT EXISTS "agent_memberships_agent_idx" ON "agent_memberships" USING btree ("agent_id");
--> statement-breakpoint
CREATE UNIQUE INDEX IF NOT EXISTS "agent_memberships_company_user_agent_uq" ON "agent_memberships" USING btree ("company_id","user_id","agent_id");
--> statement-breakpoint
CREATE INDEX IF NOT EXISTS "project_memberships_company_user_idx" ON "project_memberships" USING btree ("company_id","user_id");
--> statement-breakpoint
CREATE INDEX IF NOT EXISTS "project_memberships_project_idx" ON "project_memberships" USING btree ("project_id");
--> statement-breakpoint
CREATE UNIQUE INDEX IF NOT EXISTS "project_memberships_company_user_project_uq" ON "project_memberships" USING btree ("company_id","user_id","project_id");
packages/db/src/migrations/0091_old_swarm.sql
+189
View File
@@ -0,0 +1,189 @@
CREATE TABLE IF NOT EXISTS "document_annotation_threads" (
"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
"company_id" uuid NOT NULL,
"issue_id" uuid NOT NULL,
"document_id" uuid NOT NULL,
"document_key" text NOT NULL,
"status" text DEFAULT 'open' NOT NULL,
"anchor_state" text DEFAULT 'active' NOT NULL,
"original_revision_id" uuid,
"original_revision_number" integer NOT NULL,
"current_revision_id" uuid,
"current_revision_number" integer NOT NULL,
"selected_text" text NOT NULL,
"prefix_text" text DEFAULT '' NOT NULL,
"suffix_text" text DEFAULT '' NOT NULL,
"normalized_start" integer NOT NULL,
"normalized_end" integer NOT NULL,
"markdown_start" integer NOT NULL,
"markdown_end" integer NOT NULL,
"anchor_confidence" text DEFAULT 'exact' NOT NULL,
"anchor_selector" jsonb NOT NULL,
"created_by_agent_id" uuid,
"created_by_user_id" text,
"resolved_by_agent_id" uuid,
"resolved_by_user_id" text,
"resolved_at" timestamp with time zone,
"created_at" timestamp with time zone DEFAULT now() NOT NULL,
"updated_at" timestamp with time zone DEFAULT now() NOT NULL
);
--> statement-breakpoint
CREATE TABLE IF NOT EXISTS "document_annotation_comments" (
"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
"company_id" uuid NOT NULL,
"thread_id" uuid NOT NULL,
"issue_id" uuid NOT NULL,
"document_id" uuid NOT NULL,
"body" text NOT NULL,
"author_type" text NOT NULL,
"author_agent_id" uuid,
"author_user_id" text,
"created_by_run_id" uuid,
"created_at" timestamp with time zone DEFAULT now() NOT NULL,
"updated_at" timestamp with time zone DEFAULT now() NOT NULL
);
--> statement-breakpoint
CREATE TABLE IF NOT EXISTS "document_annotation_anchor_snapshots" (
"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
"company_id" uuid NOT NULL,
"thread_id" uuid NOT NULL,
"document_id" uuid NOT NULL,
"from_revision_id" uuid,
"from_revision_number" integer,
"to_revision_id" uuid,
"to_revision_number" integer NOT NULL,
"previous_anchor" jsonb NOT NULL,
"next_anchor" jsonb,
"anchor_state" text NOT NULL,
"anchor_confidence" text NOT NULL,
"failure_reason" text,
"created_at" timestamp with time zone DEFAULT now() NOT NULL
);
--> statement-breakpoint
DO $$ BEGIN
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'document_annotation_threads_company_id_companies_id_fk') THEN
ALTER TABLE "document_annotation_threads" ADD CONSTRAINT "document_annotation_threads_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;
END IF;
END $$;
--> statement-breakpoint
DO $$ BEGIN
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'document_annotation_threads_issue_id_issues_id_fk') THEN
ALTER TABLE "document_annotation_threads" ADD CONSTRAINT "document_annotation_threads_issue_id_issues_id_fk" FOREIGN KEY ("issue_id") REFERENCES "public"."issues"("id") ON DELETE cascade ON UPDATE no action;
END IF;
END $$;
--> statement-breakpoint
DO $$ BEGIN
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'document_annotation_threads_document_id_documents_id_fk') THEN
ALTER TABLE "document_annotation_threads" ADD CONSTRAINT "document_annotation_threads_document_id_documents_id_fk" FOREIGN KEY ("document_id") REFERENCES "public"."documents"("id") ON DELETE cascade ON UPDATE no action;
END IF;
END $$;
--> statement-breakpoint
DO $$ BEGIN
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'document_annotation_threads_original_revision_id_document_revisions_id_fk') THEN
ALTER TABLE "document_annotation_threads" ADD CONSTRAINT "document_annotation_threads_original_revision_id_document_revisions_id_fk" FOREIGN KEY ("original_revision_id") REFERENCES "public"."document_revisions"("id") ON DELETE set null ON UPDATE no action;
END IF;
END $$;
--> statement-breakpoint
DO $$ BEGIN
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'document_annotation_threads_current_revision_id_document_revisions_id_fk') THEN
ALTER TABLE "document_annotation_threads" ADD CONSTRAINT "document_annotation_threads_current_revision_id_document_revisions_id_fk" FOREIGN KEY ("current_revision_id") REFERENCES "public"."document_revisions"("id") ON DELETE set null ON UPDATE no action;
END IF;
END $$;
--> statement-breakpoint
DO $$ BEGIN
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'document_annotation_threads_created_by_agent_id_agents_id_fk') THEN
ALTER TABLE "document_annotation_threads" ADD CONSTRAINT "document_annotation_threads_created_by_agent_id_agents_id_fk" FOREIGN KEY ("created_by_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;
END IF;
END $$;
--> statement-breakpoint
DO $$ BEGIN
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'document_annotation_threads_resolved_by_agent_id_agents_id_fk') THEN
ALTER TABLE "document_annotation_threads" ADD CONSTRAINT "document_annotation_threads_resolved_by_agent_id_agents_id_fk" FOREIGN KEY ("resolved_by_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;
END IF;
END $$;
--> statement-breakpoint
DO $$ BEGIN
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'document_annotation_comments_company_id_companies_id_fk') THEN
ALTER TABLE "document_annotation_comments" ADD CONSTRAINT "document_annotation_comments_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;
END IF;
END $$;
--> statement-breakpoint
DO $$ BEGIN
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'document_annotation_comments_thread_id_document_annotation_threads_id_fk') THEN
ALTER TABLE "document_annotation_comments" ADD CONSTRAINT "document_annotation_comments_thread_id_document_annotation_threads_id_fk" FOREIGN KEY ("thread_id") REFERENCES "public"."document_annotation_threads"("id") ON DELETE cascade ON UPDATE no action;
END IF;
END $$;
--> statement-breakpoint
DO $$ BEGIN
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'document_annotation_comments_issue_id_issues_id_fk') THEN
ALTER TABLE "document_annotation_comments" ADD CONSTRAINT "document_annotation_comments_issue_id_issues_id_fk" FOREIGN KEY ("issue_id") REFERENCES "public"."issues"("id") ON DELETE cascade ON UPDATE no action;
END IF;
END $$;
--> statement-breakpoint
DO $$ BEGIN
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'document_annotation_comments_document_id_documents_id_fk') THEN
ALTER TABLE "document_annotation_comments" ADD CONSTRAINT "document_annotation_comments_document_id_documents_id_fk" FOREIGN KEY ("document_id") REFERENCES "public"."documents"("id") ON DELETE cascade ON UPDATE no action;
END IF;
END $$;
--> statement-breakpoint
DO $$ BEGIN
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'document_annotation_comments_author_agent_id_agents_id_fk') THEN
ALTER TABLE "document_annotation_comments" ADD CONSTRAINT "document_annotation_comments_author_agent_id_agents_id_fk" FOREIGN KEY ("author_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;
END IF;
END $$;
--> statement-breakpoint
DO $$ BEGIN
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'document_annotation_comments_created_by_run_id_heartbeat_runs_id_fk') THEN
ALTER TABLE "document_annotation_comments" ADD CONSTRAINT "document_annotation_comments_created_by_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("created_by_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE set null ON UPDATE no action;
END IF;
END $$;
--> statement-breakpoint
DO $$ BEGIN
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'document_annotation_anchor_snapshots_company_id_companies_id_fk') THEN
ALTER TABLE "document_annotation_anchor_snapshots" ADD CONSTRAINT "document_annotation_anchor_snapshots_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;
END IF;
END $$;
--> statement-breakpoint
DO $$ BEGIN
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'document_annotation_anchor_snapshots_thread_id_document_annotation_threads_id_fk') THEN
ALTER TABLE "document_annotation_anchor_snapshots" ADD CONSTRAINT "document_annotation_anchor_snapshots_thread_id_document_annotation_threads_id_fk" FOREIGN KEY ("thread_id") REFERENCES "public"."document_annotation_threads"("id") ON DELETE cascade ON UPDATE no action;
END IF;
END $$;
--> statement-breakpoint
DO $$ BEGIN
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'document_annotation_anchor_snapshots_document_id_documents_id_fk') THEN
ALTER TABLE "document_annotation_anchor_snapshots" ADD CONSTRAINT "document_annotation_anchor_snapshots_document_id_documents_id_fk" FOREIGN KEY ("document_id") REFERENCES "public"."documents"("id") ON DELETE cascade ON UPDATE no action;
END IF;
END $$;
--> statement-breakpoint
DO $$ BEGIN
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'document_annotation_anchor_snapshots_from_revision_id_document_revisions_id_fk') THEN
ALTER TABLE "document_annotation_anchor_snapshots" ADD CONSTRAINT "document_annotation_anchor_snapshots_from_revision_id_document_revisions_id_fk" FOREIGN KEY ("from_revision_id") REFERENCES "public"."document_revisions"("id") ON DELETE set null ON UPDATE no action;
END IF;
END $$;
--> statement-breakpoint
DO $$ BEGIN
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'document_annotation_anchor_snapshots_to_revision_id_document_revisions_id_fk') THEN
ALTER TABLE "document_annotation_anchor_snapshots" ADD CONSTRAINT "document_annotation_anchor_snapshots_to_revision_id_document_revisions_id_fk" FOREIGN KEY ("to_revision_id") REFERENCES "public"."document_revisions"("id") ON DELETE set null ON UPDATE no action;
END IF;
END $$;
--> statement-breakpoint
CREATE INDEX IF NOT EXISTS "document_annotation_threads_company_document_status_idx" ON "document_annotation_threads" USING btree ("company_id","document_id","status");
--> statement-breakpoint
CREATE INDEX IF NOT EXISTS "document_annotation_threads_company_issue_status_idx" ON "document_annotation_threads" USING btree ("company_id","issue_id","status");
--> statement-breakpoint
CREATE INDEX IF NOT EXISTS "document_annotation_threads_company_current_revision_open_idx" ON "document_annotation_threads" USING btree ("company_id","document_id","current_revision_id","status");
--> statement-breakpoint
CREATE INDEX IF NOT EXISTS "document_annotation_threads_company_anchor_state_idx" ON "document_annotation_threads" USING btree ("company_id","anchor_state");
--> statement-breakpoint
CREATE INDEX IF NOT EXISTS "document_annotation_comments_company_thread_created_at_idx" ON "document_annotation_comments" USING btree ("company_id","thread_id","created_at");
--> statement-breakpoint
CREATE INDEX IF NOT EXISTS "document_annotation_comments_company_issue_created_at_idx" ON "document_annotation_comments" USING btree ("company_id","issue_id","created_at");
--> statement-breakpoint
CREATE INDEX IF NOT EXISTS "document_annotation_comments_company_document_created_at_idx" ON "document_annotation_comments" USING btree ("company_id","document_id","created_at");
--> statement-breakpoint
CREATE INDEX IF NOT EXISTS "document_annotation_comments_body_search_idx" ON "document_annotation_comments" USING gin ("body" gin_trgm_ops);
--> statement-breakpoint
CREATE INDEX IF NOT EXISTS "document_annotation_anchor_snapshots_company_thread_created_at_idx" ON "document_annotation_anchor_snapshots" USING btree ("company_id","thread_id","created_at");
--> statement-breakpoint
CREATE INDEX IF NOT EXISTS "document_annotation_anchor_snapshots_company_document_revision_idx" ON "document_annotation_anchor_snapshots" USING btree ("company_id","document_id","to_revision_number");
packages/db/src/migrations/0090_demonic_grey_gargoyle.sql → packages/db/src/migrations/0092_mighty_puma.sql
+18 -17
View File
@@ -1,21 +1,22 @@
CREATE TABLE "issue_plan_decompositions" (
"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
"company_id" uuid NOT NULL,
"source_issue_id" uuid NOT NULL,
"accepted_plan_revision_id" uuid NOT NULL,
"accepted_interaction_id" uuid,
"status" text DEFAULT 'in_flight' NOT NULL,
"request_fingerprint" text NOT NULL,
"requested_child_count" integer DEFAULT 0 NOT NULL,
"requested_children" jsonb DEFAULT '[]'::jsonb NOT NULL,
"child_issue_ids" jsonb DEFAULT '[]'::jsonb NOT NULL,
"owner_agent_id" uuid,
"owner_user_id" text,
"owner_run_id" uuid,
"completed_at" timestamp with time zone,
"created_at" timestamp with time zone DEFAULT now() NOT NULL,
"updated_at" timestamp with time zone DEFAULT now() NOT NULL
);--> statement-breakpoint
"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
"company_id" uuid NOT NULL,
"source_issue_id" uuid NOT NULL,
"accepted_plan_revision_id" uuid NOT NULL,
"accepted_interaction_id" uuid,
"status" text DEFAULT 'in_flight' NOT NULL,
"request_fingerprint" text NOT NULL,
"requested_child_count" integer DEFAULT 0 NOT NULL,
"requested_children" jsonb DEFAULT '[]'::jsonb NOT NULL,
"child_issue_ids" jsonb DEFAULT '[]'::jsonb NOT NULL,
"owner_agent_id" uuid,
"owner_user_id" text,
"owner_run_id" uuid,
"completed_at" timestamp with time zone,
"created_at" timestamp with time zone DEFAULT now() NOT NULL,
"updated_at" timestamp with time zone DEFAULT now() NOT NULL
);
--> statement-breakpoint
ALTER TABLE "issue_plan_decompositions" ADD CONSTRAINT "issue_plan_decompositions_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
ALTER TABLE "issue_plan_decompositions" ADD CONSTRAINT "issue_plan_decompositions_source_issue_id_issues_id_fk" FOREIGN KEY ("source_issue_id") REFERENCES "public"."issues"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
ALTER TABLE "issue_plan_decompositions" ADD CONSTRAINT "issue_plan_decompositions_accepted_plan_revision_id_document_revisions_id_fk" FOREIGN KEY ("accepted_plan_revision_id") REFERENCES "public"."document_revisions"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
packages/db/src/migrations/meta/0090_snapshot.json
+302 -702
View File
File diff suppressed because it is too large. Load diff
packages/db/src/migrations/meta/0091_snapshot.json
+18843
View File
File diff suppressed because it is too large. Load diff
packages/db/src/migrations/meta/0092_snapshot.json
+19543
View File
File diff suppressed because it is too large. Load diff
packages/db/src/migrations/meta/_journal.json
+16 -2
View File
@@ -635,8 +635,22 @@
{
"idx": 90,
"version": "7",
"when": 1779597488245,
"tag": "0090_demonic_grey_gargoyle",
"when": 1779573019125,
"tag": "0090_resource_memberships",
"breakpoints": true
},
{
"idx": 91,
"version": "7",
"when": 1778810394522,
"tag": "0091_old_swarm",
"breakpoints": true
},
{
"idx": 92,
"version": "7",
"when": 1779999768200,
"tag": "0092_mighty_puma",
"breakpoints": true
}
]
packages/db/src/schema/agent_memberships.ts
+25
View File
@@ -0,0 +1,25 @@
import { pgTable, uuid, text, timestamp, uniqueIndex, index } from "drizzle-orm/pg-core";
import { agents } from "./agents.js";
import { companies } from "./companies.js";
export const agentMemberships = pgTable(
"agent_memberships",
{
id: uuid("id").primaryKey().defaultRandom(),
companyId: uuid("company_id").notNull().references(() => companies.id, { onDelete: "cascade" }),
agentId: uuid("agent_id").notNull().references(() => agents.id, { onDelete: "cascade" }),
userId: text("user_id").notNull(),
state: text("state").notNull().default("joined"),
createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
},
(table) => ({
companyUserIdx: index("agent_memberships_company_user_idx").on(table.companyId, table.userId),
agentIdx: index("agent_memberships_agent_idx").on(table.agentId),
companyUserAgentUq: uniqueIndex("agent_memberships_company_user_agent_uq").on(
table.companyId,
table.userId,
table.agentId,
),
}),
);
packages/db/src/schema/document_annotation_anchor_snapshots.ts
+42
View File
@@ -0,0 +1,42 @@
import type {
DocumentAnnotationAnchorConfidence,
DocumentAnnotationAnchorSnapshot,
DocumentAnnotationAnchorState,
} from "@paperclipai/shared";
import { index, integer, jsonb, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
import { companies } from "./companies.js";
import { documentAnnotationThreads } from "./document_annotation_threads.js";
import { documentRevisions } from "./document_revisions.js";
import { documents } from "./documents.js";
export const documentAnnotationAnchorSnapshots = pgTable(
"document_annotation_anchor_snapshots",
{
id: uuid("id").primaryKey().defaultRandom(),
companyId: uuid("company_id").notNull().references(() => companies.id),
threadId: uuid("thread_id").notNull().references(() => documentAnnotationThreads.id, { onDelete: "cascade" }),
documentId: uuid("document_id").notNull().references(() => documents.id, { onDelete: "cascade" }),
fromRevisionId: uuid("from_revision_id").references(() => documentRevisions.id, { onDelete: "set null" }),
fromRevisionNumber: integer("from_revision_number"),
toRevisionId: uuid("to_revision_id").references(() => documentRevisions.id, { onDelete: "set null" }),
toRevisionNumber: integer("to_revision_number").notNull(),
previousAnchor: jsonb("previous_anchor").$type<DocumentAnnotationAnchorSnapshot>().notNull(),
nextAnchor: jsonb("next_anchor").$type<DocumentAnnotationAnchorSnapshot | null>(),
anchorState: text("anchor_state").$type<DocumentAnnotationAnchorState>().notNull(),
anchorConfidence: text("anchor_confidence").$type<DocumentAnnotationAnchorConfidence>().notNull(),
failureReason: text("failure_reason"),
createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
},
(table) => ({
companyThreadCreatedAtIdx: index("document_annotation_anchor_snapshots_company_thread_created_at_idx").on(
table.companyId,
table.threadId,
table.createdAt,
),
companyDocumentRevisionIdx: index("document_annotation_anchor_snapshots_company_document_revision_idx").on(
table.companyId,
table.documentId,
table.toRevisionNumber,
),
}),
);
packages/db/src/schema/document_annotation_comments.ts
+44
View File
@@ -0,0 +1,44 @@
import type { IssueCommentAuthorType } from "@paperclipai/shared";
import { index, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
import { agents } from "./agents.js";
import { companies } from "./companies.js";
import { documentAnnotationThreads } from "./document_annotation_threads.js";
import { documents } from "./documents.js";
import { heartbeatRuns } from "./heartbeat_runs.js";
import { issues } from "./issues.js";
export const documentAnnotationComments = pgTable(
"document_annotation_comments",
{
id: uuid("id").primaryKey().defaultRandom(),
companyId: uuid("company_id").notNull().references(() => companies.id),
threadId: uuid("thread_id").notNull().references(() => documentAnnotationThreads.id, { onDelete: "cascade" }),
issueId: uuid("issue_id").notNull().references(() => issues.id, { onDelete: "cascade" }),
documentId: uuid("document_id").notNull().references(() => documents.id, { onDelete: "cascade" }),
body: text("body").notNull(),
authorType: text("author_type").$type<IssueCommentAuthorType>().notNull(),
authorAgentId: uuid("author_agent_id").references(() => agents.id, { onDelete: "set null" }),
authorUserId: text("author_user_id"),
createdByRunId: uuid("created_by_run_id").references(() => heartbeatRuns.id, { onDelete: "set null" }),
createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
},
(table) => ({
companyThreadCreatedAtIdx: index("document_annotation_comments_company_thread_created_at_idx").on(
table.companyId,
table.threadId,
table.createdAt,
),
companyIssueCreatedAtIdx: index("document_annotation_comments_company_issue_created_at_idx").on(
table.companyId,
table.issueId,
table.createdAt,
),
companyDocumentCreatedAtIdx: index("document_annotation_comments_company_document_created_at_idx").on(
table.companyId,
table.documentId,
table.createdAt,
),
bodySearchIdx: index("document_annotation_comments_body_search_idx").using("gin", table.body.op("gin_trgm_ops")),
}),
);
packages/db/src/schema/document_annotation_threads.ts
+70
View File
@@ -0,0 +1,70 @@
import type {
DocumentAnnotationAnchorConfidence,
DocumentAnnotationAnchorSelector,
DocumentAnnotationAnchorState,
DocumentAnnotationThreadStatus,
} from "@paperclipai/shared";
import { index, integer, jsonb, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
import { agents } from "./agents.js";
import { companies } from "./companies.js";
import { documentRevisions } from "./document_revisions.js";
import { documents } from "./documents.js";
import { issues } from "./issues.js";
export const documentAnnotationThreads = pgTable(
"document_annotation_threads",
{
id: uuid("id").primaryKey().defaultRandom(),
companyId: uuid("company_id").notNull().references(() => companies.id),
issueId: uuid("issue_id").notNull().references(() => issues.id, { onDelete: "cascade" }),
documentId: uuid("document_id").notNull().references(() => documents.id, { onDelete: "cascade" }),
documentKey: text("document_key").notNull(),
status: text("status").$type<DocumentAnnotationThreadStatus>().notNull().default("open"),
anchorState: text("anchor_state").$type<DocumentAnnotationAnchorState>().notNull().default("active"),
originalRevisionId: uuid("original_revision_id").references(() => documentRevisions.id, { onDelete: "set null" }),
originalRevisionNumber: integer("original_revision_number").notNull(),
currentRevisionId: uuid("current_revision_id").references(() => documentRevisions.id, { onDelete: "set null" }),
currentRevisionNumber: integer("current_revision_number").notNull(),
selectedText: text("selected_text").notNull(),
prefixText: text("prefix_text").notNull().default(""),
suffixText: text("suffix_text").notNull().default(""),
normalizedStart: integer("normalized_start").notNull(),
normalizedEnd: integer("normalized_end").notNull(),
markdownStart: integer("markdown_start").notNull(),
markdownEnd: integer("markdown_end").notNull(),
anchorConfidence: text("anchor_confidence")
.$type<DocumentAnnotationAnchorConfidence>()
.notNull()
.default("exact"),
anchorSelector: jsonb("anchor_selector").$type<DocumentAnnotationAnchorSelector>().notNull(),
createdByAgentId: uuid("created_by_agent_id").references(() => agents.id, { onDelete: "set null" }),
createdByUserId: text("created_by_user_id"),
resolvedByAgentId: uuid("resolved_by_agent_id").references(() => agents.id, { onDelete: "set null" }),
resolvedByUserId: text("resolved_by_user_id"),
resolvedAt: timestamp("resolved_at", { withTimezone: true }),
createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
},
(table) => ({
companyDocumentStatusIdx: index("document_annotation_threads_company_document_status_idx").on(
table.companyId,
table.documentId,
table.status,
),
companyIssueStatusIdx: index("document_annotation_threads_company_issue_status_idx").on(
table.companyId,
table.issueId,
table.status,
),
companyCurrentRevisionOpenIdx: index("document_annotation_threads_company_current_revision_open_idx").on(
table.companyId,
table.documentId,
table.currentRevisionId,
table.status,
),
companyAnchorStateIdx: index("document_annotation_threads_company_anchor_state_idx").on(
table.companyId,
table.anchorState,
),
}),
);
packages/db/src/schema/index.ts
+5
View File
@@ -6,6 +6,7 @@ export { cloudUpstreamConnections, cloudUpstreamRuns } from "./cloud_upstreams.j
export { instanceUserRoles } from "./instance_user_roles.js";
export { userSidebarPreferences } from "./user_sidebar_preferences.js";
export { agents } from "./agents.js";
export { agentMemberships } from "./agent_memberships.js";
export { boardApiKeys } from "./board_api_keys.js";
export { cliAuthChallenges } from "./cli_auth_challenges.js";
export { companyMemberships } from "./company_memberships.js";
@@ -21,6 +22,7 @@ export { agentRuntimeState } from "./agent_runtime_state.js";
export { agentTaskSessions } from "./agent_task_sessions.js";
export { agentWakeupRequests } from "./agent_wakeup_requests.js";
export { projects } from "./projects.js";
export { projectMemberships } from "./project_memberships.js";
export { projectWorkspaces } from "./project_workspaces.js";
export { executionWorkspaces } from "./execution_workspaces.js";
export { environments } from "./environments.js";
@@ -54,6 +56,9 @@ export { issueAttachments } from "./issue_attachments.js";
export { documents } from "./documents.js";
export { documentRevisions } from "./document_revisions.js";
export { issueDocuments } from "./issue_documents.js";
export { documentAnnotationThreads } from "./document_annotation_threads.js";
export { documentAnnotationComments } from "./document_annotation_comments.js";
export { documentAnnotationAnchorSnapshots } from "./document_annotation_anchor_snapshots.js";
export { heartbeatRuns } from "./heartbeat_runs.js";
export { heartbeatRunEvents } from "./heartbeat_run_events.js";
export { heartbeatRunWatchdogDecisions } from "./heartbeat_run_watchdog_decisions.js";
packages/db/src/schema/project_memberships.ts
+25
View File
@@ -0,0 +1,25 @@
import { pgTable, uuid, text, timestamp, uniqueIndex, index } from "drizzle-orm/pg-core";
import { companies } from "./companies.js";
import { projects } from "./projects.js";
export const projectMemberships = pgTable(
"project_memberships",
{
id: uuid("id").primaryKey().defaultRandom(),
companyId: uuid("company_id").notNull().references(() => companies.id, { onDelete: "cascade" }),
projectId: uuid("project_id").notNull().references(() => projects.id, { onDelete: "cascade" }),
userId: text("user_id").notNull(),
state: text("state").notNull().default("joined"),
createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
},
(table) => ({
companyUserIdx: index("project_memberships_company_user_idx").on(table.companyId, table.userId),
projectIdx: index("project_memberships_project_idx").on(table.projectId),
companyUserProjectUq: uniqueIndex("project_memberships_company_user_project_uq").on(
table.companyId,
table.userId,
table.projectId,
),
}),
);
packages/plugins/create-paperclip-plugin/README.md
+1 -1
View File
@@ -34,7 +34,7 @@ Inside this repo, the generated package uses `@paperclipai/plugin-sdk` via `work
Outside this repo, the scaffold snapshots `@paperclipai/plugin-sdk` from your local Paperclip checkout into a `.paperclip-sdk/` tarball and points the generated package at that local file by default. You can override the SDK source explicitly:
```bash
node packages/plugins/create-paperclip-plugin/dist/index.js @acme/my-plugin \
node packages/plugins/create-paperclip-plugin/dist/bin.js @acme/my-plugin \
--output /absolute/path/to/plugins \
--sdk-path /absolute/path/to/paperclip/packages/plugins/sdk
```
packages/plugins/create-paperclip-plugin/package.json
+3 -2
View File
@@ -13,7 +13,7 @@
},
"type": "module",
"bin": {
"create-paperclip-plugin": "./dist/index.js"
"create-paperclip-plugin": "./dist/bin.js"
},
"exports": {
".": "./src/index.ts"
@@ -21,7 +21,7 @@
"publishConfig": {
"access": "public",
"bin": {
"create-paperclip-plugin": "./dist/index.js"
"create-paperclip-plugin": "./dist/bin.js"
},
"exports": {
".": {
@@ -38,6 +38,7 @@
"scripts": {
"build": "tsc",
"clean": "rm -rf dist",
"test": "pnpm -w exec vitest run --root packages/plugins/create-paperclip-plugin --config vitest.config.ts",
"typecheck": "tsc --noEmit"
},
"dependencies": {
packages/plugins/create-paperclip-plugin/src/bin.ts
+62
View File
@@ -0,0 +1,62 @@
#!/usr/bin/env node
import path from "node:path";
import { pathToFileURL } from "node:url";
import { scaffoldPluginProject, type ScaffoldPluginOptions } from "./index.js";
interface RunCliDeps {
cwd?: string;
stdout?: (message: string) => void;
stderr?: (message: string) => void;
exit?: (code: number) => never;
}
function parseArg(argv: string[], name: string): string | undefined {
const index = argv.indexOf(name);
if (index === -1) return undefined;
return argv[index + 1];
}
/** Convert `@scope/name` to an output directory basename (`name`). */
function packageToDirName(pluginName: string): string {
return pluginName.replace(/^@[^/]+\//, "");
}
/** CLI wrapper for `scaffoldPluginProject`. */
export function runCli(argv = process.argv, deps: RunCliDeps = {}): string | undefined {
const pluginName = argv[2];
const stderr = deps.stderr ?? console.error;
const stdout = deps.stdout ?? console.log;
const exit = deps.exit ?? process.exit;
if (!pluginName) {
stderr("Usage: create-paperclip-plugin <name> [--template default|connector|workspace] [--output <dir>] [--sdk-path <paperclip-sdk-path>]");
exit(1);
}
const template = (parseArg(argv, "--template") ?? "default") as ScaffoldPluginOptions["template"];
const outputRoot = parseArg(argv, "--output") ?? deps.cwd ?? process.cwd();
const targetDir = path.resolve(outputRoot, packageToDirName(pluginName));
const out = scaffoldPluginProject({
pluginName,
outputDir: targetDir,
template,
displayName: parseArg(argv, "--display-name"),
description: parseArg(argv, "--description"),
author: parseArg(argv, "--author"),
category: parseArg(argv, "--category") as ScaffoldPluginOptions["category"] | undefined,
sdkPath: parseArg(argv, "--sdk-path"),
});
stdout(`Created plugin scaffold at ${out}`);
return out;
}
function isMainModule(): boolean {
const entrypoint = process.argv[1];
return entrypoint ? import.meta.url === pathToFileURL(entrypoint).href : false;
}
if (isMainModule()) {
runCli();
}
packages/plugins/create-paperclip-plugin/src/entrypoints.test.ts
+74
View File
@@ -0,0 +1,74 @@
import fs from "node:fs";
import path from "node:path";
import { afterEach, describe, expect, it } from "vitest";
const tempDirs: string[] = [];
function makeTempDir(): string {
const dir = fs.mkdtempSync(path.join(process.cwd(), ".tmp-create-paperclip-plugin-"));
tempDirs.push(dir);
return dir;
}
afterEach(() => {
while (tempDirs.length > 0) {
const dir = tempDirs.pop();
if (dir) fs.rmSync(dir, { recursive: true, force: true });
}
});
describe("create-paperclip-plugin entrypoints", () => {
it("keeps src/index.ts import-safe when process.argv points at another bundled CLI", async () => {
const originalArgv = process.argv;
const outputRoot = makeTempDir();
try {
process.argv = [process.execPath, path.resolve("cli/dist/index.js"), "demo-plugin", "--output", outputRoot];
const library = await import("./index.js");
expect(library.scaffoldPluginProject).toBeTypeOf("function");
expect(fs.existsSync(path.join(outputRoot, "demo-plugin"))).toBe(false);
} finally {
process.argv = originalArgv;
}
});
it("runs scaffolding from src/bin.ts", async () => {
const { runCli } = await import("./bin.js");
const outputRoot = makeTempDir();
const stdout: string[] = [];
const outputDir = path.join(outputRoot, "demo-plugin");
const result = runCli(
[
process.execPath,
"create-paperclip-plugin",
"demo-plugin",
"--output",
outputRoot,
"--sdk-path",
path.resolve("packages/plugins/sdk"),
],
{
stdout: (message) => stdout.push(message),
stderr: (message) => {
throw new Error(message);
},
exit: (code) => {
throw new Error(`unexpected exit ${code}`);
},
},
);
expect(result).toBe(outputDir);
expect(stdout).toEqual([`Created plugin scaffold at ${outputDir}`]);
expect(JSON.parse(fs.readFileSync(path.join(outputDir, "package.json"), "utf8"))).toMatchObject({
name: "demo-plugin",
paperclipPlugin: {
manifest: "./dist/manifest.js",
worker: "./dist/worker.js",
ui: "./dist/ui/",
},
});
});
});
packages/plugins/create-paperclip-plugin/src/index.ts
-39
View File
@@ -1,4 +1,3 @@
#!/usr/bin/env node
import { execFileSync } from "node:child_process";
import fs from "node:fs";
import path from "node:path";
@@ -699,41 +698,3 @@ paperclipai plugin install ${shellQuote(toPosixPath(outputDir))}
return outputDir;
}
function parseArg(name: string): string | undefined {
const index = process.argv.indexOf(name);
if (index === -1) return undefined;
return process.argv[index + 1];
}
/** CLI wrapper for `scaffoldPluginProject`. */
function runCli() {
const pluginName = process.argv[2];
if (!pluginName) {
// eslint-disable-next-line no-console
console.error("Usage: create-paperclip-plugin <name> [--template default|connector|workspace] [--output <dir>] [--sdk-path <paperclip-sdk-path>]");
process.exit(1);
}
const template = (parseArg("--template") ?? "default") as PluginTemplate;
const outputRoot = parseArg("--output") ?? process.cwd();
const targetDir = path.resolve(outputRoot, packageToDirName(pluginName));
const out = scaffoldPluginProject({
pluginName,
outputDir: targetDir,
template,
displayName: parseArg("--display-name"),
description: parseArg("--description"),
author: parseArg("--author"),
category: parseArg("--category") as ScaffoldPluginOptions["category"] | undefined,
sdkPath: parseArg("--sdk-path"),
});
// eslint-disable-next-line no-console
console.log(`Created plugin scaffold at ${out}`);
}
if (import.meta.url === `file://${process.argv[1]}`) {
runCli();
}
packages/plugins/create-paperclip-plugin/tsconfig.json
+2 -1
View File
@@ -5,5 +5,6 @@
"rootDir": "src",
"types": ["node"]
},
"include": ["src"]
"include": ["src"],
"exclude": ["src/**/*.test.ts"]
}
packages/plugins/create-paperclip-plugin/vitest.config.ts
+8
View File
@@ -0,0 +1,8 @@
import { defineConfig } from "vitest/config";
export default defineConfig({
test: {
environment: "node",
include: ["src/**/*.test.ts"],
},
});
packages/plugins/sdk/src/index.ts
+2
View File
@@ -129,6 +129,8 @@ export type {
// JSON-RPC protocol types
export type {
JsonRpcId,
JsonRpcInvocationScope,
JsonRpcInvocationContext,
JsonRpcRequest,
JsonRpcSuccessResponse,
JsonRpcError,
packages/plugins/sdk/src/protocol.ts
+13
View File
@@ -87,6 +87,19 @@ export const JSONRPC_VERSION = "2.0" as const;
*/
export type JsonRpcId = string | number;
/**
* Host-owned scope attached to a host→worker invocation. Workers may echo the
* invocation id on nested worker→host calls, but they never author this scope.
*/
export interface JsonRpcInvocationScope {
readonly companyId?: string | null;
}
export interface JsonRpcInvocationContext {
readonly id: string;
readonly scope: JsonRpcInvocationScope;
}
/**
* A JSON-RPC 2.0 request message.
*
packages/shared/src/api.ts
+1
View File
@@ -18,6 +18,7 @@ export const API = {
dashboard: `${API_PREFIX}/dashboard`,
sidebarBadges: `${API_PREFIX}/sidebar-badges`,
sidebarPreferences: `${API_PREFIX}/sidebar-preferences`,
resourceMemberships: `${API_PREFIX}/resource-memberships`,
invites: `${API_PREFIX}/invites`,
joinRequests: `${API_PREFIX}/join-requests`,
members: `${API_PREFIX}/members`,
packages/shared/src/constants.ts
+16
View File
@@ -281,6 +281,22 @@ export function isSystemIssueDocumentKey(key: string): key is SystemIssueDocumen
export const ISSUE_REFERENCE_SOURCE_KINDS = ["title", "description", "comment", "document"] as const;
export type IssueReferenceSourceKind = (typeof ISSUE_REFERENCE_SOURCE_KINDS)[number];
export const DOCUMENT_ANNOTATION_THREAD_STATUSES = ["open", "resolved"] as const;
export type DocumentAnnotationThreadStatus = (typeof DOCUMENT_ANNOTATION_THREAD_STATUSES)[number];
export const DOCUMENT_ANNOTATION_ANCHOR_STATES = ["active", "stale", "orphaned"] as const;
export type DocumentAnnotationAnchorState = (typeof DOCUMENT_ANNOTATION_ANCHOR_STATES)[number];
export const DOCUMENT_ANNOTATION_ANCHOR_CONFIDENCES = [
"exact",
"duplicate",
"fuzzy",
"ambiguous",
"missing",
] as const;
export type DocumentAnnotationAnchorConfidence =
(typeof DOCUMENT_ANNOTATION_ANCHOR_CONFIDENCES)[number];
export const ISSUE_EXECUTION_POLICY_MODES = ["normal", "auto"] as const;
export type IssueExecutionPolicyMode = (typeof ISSUE_EXECUTION_POLICY_MODES)[number];
packages/shared/src/document-anchors.test.ts
+183
View File
@@ -0,0 +1,183 @@
import { describe, expect, it } from "vitest";
import {
createDocumentAnchorSelector,
projectMarkdownToText,
remapDocumentAnchor,
resolveProjectionRange,
verifyDocumentAnchorSelector,
} from "./document-anchors.js";
function selectorFor(markdown: string, quote: string) {
const projection = projectMarkdownToText(markdown);
const start = projection.text.indexOf(quote);
expect(start).toBeGreaterThanOrEqual(0);
const range = resolveProjectionRange(projection, start, start + quote.length);
expect(range).not.toBeNull();
return createDocumentAnchorSelector(projection, range!);
}
describe("document text projection", () => {
it("projects markdown into normalized rendered text with source ranges", () => {
const markdown = [
"# Heading",
"",
"- Ship **bold** [link text](https://example.com) and `code span`.",
"| Name | Value |",
"| --- | --- |",
"| Alpha | Beta |",
].join("\n");
const projection = projectMarkdownToText(markdown);
expect(projection.text).toContain("Heading");
expect(projection.text).toContain("Ship bold link text and code span.");
expect(projection.text).toContain("Name Value");
expect(projection.text).toContain("Alpha Beta");
expect(projection.text).not.toContain("https://example.com");
expect(projection.positions).toHaveLength(projection.text.length);
const linkStart = projection.text.indexOf("link text");
const range = resolveProjectionRange(projection, linkStart, linkStart + "link text".length);
expect(range?.markdownStart).toBe(markdown.indexOf("link text"));
expect(range?.markdownEnd).toBe(markdown.indexOf("link text") + "link text".length);
});
it("normalizes whitespace while retaining markdown offsets", () => {
const markdown = "First line\n\nSecond\t\tline";
const projection = projectMarkdownToText(markdown);
expect(projection.text).toBe("First line Second line");
const range = resolveProjectionRange(projection, projection.text.indexOf("Second"), projection.text.length);
expect(range?.markdownStart).toBe(markdown.indexOf("Second"));
expect(range?.markdownEnd).toBe(markdown.length);
});
it("preserves non-link punctuation", () => {
const markdown = "Keep (parenthetical) [plain brackets] visible.";
const projection = projectMarkdownToText(markdown);
expect(projection.text).toBe("Keep (parenthetical) [plain brackets] visible.");
});
});
describe("document anchor verification and remapping", () => {
it("verifies a selector against its base revision", () => {
const markdown = "Intro text with **selected text** inside.";
const selector = selectorFor(markdown, "selected text");
const result = verifyDocumentAnchorSelector({ markdown, selector });
expect(result.ok).toBe(true);
expect(result.anchor?.selectedText).toBe("selected text");
expect(result.anchor?.markdownStart).toBe(markdown.indexOf("selected text"));
});
it("remaps exact anchors after surrounding text moves", () => {
const selector = selectorFor("Alpha paragraph.\n\nTarget sentence here.\n\nOmega paragraph.", "Target sentence here.");
const previousAnchor = {
selectedText: selector.quote.exact,
prefixText: selector.quote.prefix,
suffixText: selector.quote.suffix,
normalizedStart: selector.position.normalizedStart,
normalizedEnd: selector.position.normalizedEnd,
markdownStart: selector.position.markdownStart,
markdownEnd: selector.position.markdownEnd,
};
const result = remapDocumentAnchor({
previousAnchor,
nextMarkdown: "Omega paragraph.\n\nAlpha paragraph.\n\nTarget sentence here.",
});
expect(result.anchorState).toBe("active");
expect(result.confidence).toBe("exact");
expect(result.anchor?.selectedText).toBe("Target sentence here.");
});
it("uses context and proximity to disambiguate duplicate quotes", () => {
const selector = selectorFor("One apple near the start.\n\nTwo apple near the end.", "apple");
const previousAnchor = {
selectedText: selector.quote.exact,
prefixText: selector.quote.prefix,
suffixText: selector.quote.suffix,
normalizedStart: selector.position.normalizedStart,
normalizedEnd: selector.position.normalizedEnd,
markdownStart: selector.position.markdownStart,
markdownEnd: selector.position.markdownEnd,
};
const result = remapDocumentAnchor({
previousAnchor,
nextMarkdown: "Zero apple elsewhere.\n\nOne apple near the start.\n\nTwo apple near the end.",
});
expect(result.anchorState).toBe("active");
expect(result.confidence).toBe("duplicate");
expect(result.anchor?.prefixText).toContain("One");
});
it("marks duplicate anchors ambiguous when context cannot distinguish them", () => {
const selector = selectorFor("apple apple", "apple");
const previousAnchor = {
selectedText: selector.quote.exact,
prefixText: "",
suffixText: "",
normalizedStart: selector.position.normalizedStart,
normalizedEnd: selector.position.normalizedEnd,
markdownStart: selector.position.markdownStart,
markdownEnd: selector.position.markdownEnd,
};
const result = remapDocumentAnchor({ previousAnchor, nextMarkdown: "apple apple" });
expect(result.anchorState).toBe("stale");
expect(result.confidence).toBe("ambiguous");
});
it("keeps edited anchors as stale fuzzy matches", () => {
const selector = selectorFor("We rely on an important launch assumption for scope.", "important launch assumption");
const previousAnchor = {
selectedText: selector.quote.exact,
prefixText: selector.quote.prefix,
suffixText: selector.quote.suffix,
normalizedStart: selector.position.normalizedStart,
normalizedEnd: selector.position.normalizedEnd,
markdownStart: selector.position.markdownStart,
markdownEnd: selector.position.markdownEnd,
};
const result = remapDocumentAnchor({
previousAnchor,
nextMarkdown: "We rely on an important product launch assumption for scope.",
});
expect(result.anchorState).toBe("stale");
expect(result.confidence).toBe("fuzzy");
expect(result.anchor?.selectedText).toBe("important product launch assumption");
});
it("marks deleted anchors orphaned and allows future remapping from the latest known anchor", () => {
const selector = selectorFor("Keep this reviewed phrase in mind.", "reviewed phrase");
const previousAnchor = {
selectedText: selector.quote.exact,
prefixText: selector.quote.prefix,
suffixText: selector.quote.suffix,
normalizedStart: selector.position.normalizedStart,
normalizedEnd: selector.position.normalizedEnd,
markdownStart: selector.position.markdownStart,
markdownEnd: selector.position.markdownEnd,
};
const missing = remapDocumentAnchor({ previousAnchor, nextMarkdown: "The target disappeared." });
const recovered = remapDocumentAnchor({
previousAnchor,
nextMarkdown: "The target came back: reviewed phrase.",
});
expect(missing.anchorState).toBe("orphaned");
expect(missing.confidence).toBe("missing");
expect(missing.anchor).toBeNull();
expect(recovered.anchorState).toBe("active");
expect(recovered.anchor?.selectedText).toBe("reviewed phrase");
});
});
packages/shared/src/document-anchors.ts
+464
View File
@@ -0,0 +1,464 @@
import type {
DocumentAnnotationAnchorConfidence,
DocumentAnnotationAnchorState,
} from "./constants.js";
import type {
DocumentAnnotationAnchorSelector,
DocumentAnnotationAnchorSnapshot,
DocumentTextPosition,
DocumentTextProjection,
DocumentTextRange,
} from "./types/document-annotation.js";
export interface CreateDocumentAnchorSelectorOptions {
contextLength?: number;
}
export interface VerifyDocumentAnchorSelectorInput {
markdown: string;
selector: DocumentAnnotationAnchorSelector;
contextLength?: number;
}
export interface VerifyDocumentAnchorSelectorResult {
ok: boolean;
anchor: DocumentAnnotationAnchorSnapshot | null;
projection: DocumentTextProjection;
reason: "verified" | "quote_mismatch" | "position_mismatch" | "invalid_range";
}
export interface RemapDocumentAnchorInput {
previousAnchor: DocumentAnnotationAnchorSnapshot;
nextMarkdown: string;
contextLength?: number;
}
export interface RemapDocumentAnchorResult {
anchorState: DocumentAnnotationAnchorState;
confidence: DocumentAnnotationAnchorConfidence;
anchor: DocumentAnnotationAnchorSnapshot | null;
projection: DocumentTextProjection;
reason: "exact" | "duplicate" | "fuzzy" | "ambiguous" | "missing";
}
interface Candidate {
start: number;
end: number;
score: number;
reason: RemapDocumentAnchorResult["reason"];
}
const DEFAULT_CONTEXT_LENGTH = 48;
export function normalizeAnchorText(value: string): string {
return value.replace(/\s+/g, " ").trim();
}
export function projectMarkdownToText(markdown: string): DocumentTextProjection {
const builder = new ProjectionBuilder(markdown);
const lines = markdown.match(/[^\n]*(?:\n|$)/g) ?? [markdown];
let offset = 0;
let inFence = false;
for (const rawLine of lines) {
if (rawLine === "") continue;
const hasNewline = rawLine.endsWith("\n");
const line = hasNewline ? rawLine.slice(0, -1) : rawLine;
const fenceMatch = line.match(/^\s*(```+|~~~+)/);
if (fenceMatch) {
inFence = !inFence;
offset += rawLine.length;
builder.addSeparator(offset - (hasNewline ? 1 : 0));
continue;
}
if (inFence) {
builder.addText(line, offset);
builder.addSeparator(offset + line.length);
offset += rawLine.length;
continue;
}
const { text, sourceOffset } = stripBlockSyntax(line, offset);
addInlineMarkdownText(builder, text, sourceOffset);
builder.addSeparator(offset + line.length);
offset += rawLine.length;
}
return builder.toProjection();
}
export function resolveProjectionRange(
projection: DocumentTextProjection,
normalizedStart: number,
normalizedEnd: number,
): DocumentTextRange | null {
if (
normalizedStart < 0
|| normalizedEnd <= normalizedStart
|| normalizedEnd > projection.text.length
|| normalizedStart >= projection.positions.length
|| normalizedEnd - 1 >= projection.positions.length
) {
return null;
}
return {
text: projection.text.slice(normalizedStart, normalizedEnd),
normalizedStart,
normalizedEnd,
markdownStart: projection.positions[normalizedStart]?.sourceStart ?? 0,
markdownEnd: projection.positions[normalizedEnd - 1]?.sourceEnd ?? 0,
};
}
export function createDocumentAnchorSelector(
projection: DocumentTextProjection,
range: DocumentTextRange,
options: CreateDocumentAnchorSelectorOptions = {},
): DocumentAnnotationAnchorSelector {
const contextLength = options.contextLength ?? DEFAULT_CONTEXT_LENGTH;
return {
quote: {
exact: range.text,
prefix: projection.text.slice(Math.max(0, range.normalizedStart - contextLength), range.normalizedStart),
suffix: projection.text.slice(range.normalizedEnd, range.normalizedEnd + contextLength),
},
position: {
normalizedStart: range.normalizedStart,
normalizedEnd: range.normalizedEnd,
markdownStart: range.markdownStart,
markdownEnd: range.markdownEnd,
},
};
}
export function selectorToAnchorSnapshot(selector: DocumentAnnotationAnchorSelector): DocumentAnnotationAnchorSnapshot {
return {
selectedText: selector.quote.exact,
prefixText: selector.quote.prefix,
suffixText: selector.quote.suffix,
normalizedStart: selector.position.normalizedStart,
normalizedEnd: selector.position.normalizedEnd,
markdownStart: selector.position.markdownStart,
markdownEnd: selector.position.markdownEnd,
};
}
export function anchorSnapshotToSelector(anchor: DocumentAnnotationAnchorSnapshot): DocumentAnnotationAnchorSelector {
return {
quote: {
exact: anchor.selectedText,
prefix: anchor.prefixText,
suffix: anchor.suffixText,
},
position: {
normalizedStart: anchor.normalizedStart,
normalizedEnd: anchor.normalizedEnd,
markdownStart: anchor.markdownStart,
markdownEnd: anchor.markdownEnd,
},
};
}
export function verifyDocumentAnchorSelector(
input: VerifyDocumentAnchorSelectorInput,
): VerifyDocumentAnchorSelectorResult {
const projection = projectMarkdownToText(input.markdown);
const range = resolveProjectionRange(
projection,
input.selector.position.normalizedStart,
input.selector.position.normalizedEnd,
);
if (!range) {
return { ok: false, anchor: null, projection, reason: "invalid_range" };
}
if (normalizeAnchorText(range.text) !== normalizeAnchorText(input.selector.quote.exact)) {
return { ok: false, anchor: null, projection, reason: "quote_mismatch" };
}
if (
range.markdownStart !== input.selector.position.markdownStart
|| range.markdownEnd !== input.selector.position.markdownEnd
) {
return { ok: false, anchor: null, projection, reason: "position_mismatch" };
}
const selector = createDocumentAnchorSelector(projection, range, {
contextLength: input.contextLength ?? DEFAULT_CONTEXT_LENGTH,
});
return { ok: true, anchor: selectorToAnchorSnapshot(selector), projection, reason: "verified" };
}
export function remapDocumentAnchor(input: RemapDocumentAnchorInput): RemapDocumentAnchorResult {
const projection = projectMarkdownToText(input.nextMarkdown);
const contextLength = input.contextLength ?? DEFAULT_CONTEXT_LENGTH;
const quote = normalizeAnchorText(input.previousAnchor.selectedText);
if (!quote) {
return { anchorState: "orphaned", confidence: "missing", anchor: null, projection, reason: "missing" };
}
const exactCandidates = findOccurrences(projection.text, quote).map((start) => scoreCandidate({
projection,
start,
end: start + quote.length,
previousAnchor: input.previousAnchor,
reason: "exact",
contextLength,
}));
if (exactCandidates.length > 0) {
exactCandidates.sort((a, b) => b.score - a.score);
const [best, second] = exactCandidates;
if (exactCandidates.length > 1 && (!second || Math.abs(best.score - second.score) < 0.05)) {
return {
anchorState: "stale",
confidence: "ambiguous",
anchor: buildAnchorSnapshot(projection, best.start, best.end, contextLength),
projection,
reason: "ambiguous",
};
}
return {
anchorState: "active",
confidence: exactCandidates.length === 1 ? "exact" : "duplicate",
anchor: buildAnchorSnapshot(projection, best.start, best.end, contextLength),
projection,
reason: exactCandidates.length === 1 ? "exact" : "duplicate",
};
}
const fuzzy = findFuzzyCandidate(projection, input.previousAnchor, contextLength);
if (fuzzy && fuzzy.score >= 0.58) {
return {
anchorState: "stale",
confidence: "fuzzy",
anchor: buildAnchorSnapshot(projection, fuzzy.start, fuzzy.end, contextLength),
projection,
reason: "fuzzy",
};
}
return { anchorState: "orphaned", confidence: "missing", anchor: null, projection, reason: "missing" };
}
function stripBlockSyntax(line: string, absoluteOffset: number): { text: string; sourceOffset: number } {
const blockMatch = line.match(/^\s{0,3}(?:(#{1,6})\s+|(?:[-+*]|\d+[.)])\s+|>\s?)/);
if (!blockMatch) return { text: line, sourceOffset: absoluteOffset };
return { text: line.slice(blockMatch[0].length), sourceOffset: absoluteOffset + blockMatch[0].length };
}
function addInlineMarkdownText(builder: ProjectionBuilder, text: string, sourceOffset: number): void {
for (let index = 0; index < text.length; index += 1) {
const char = text[index] ?? "";
const absolute = sourceOffset + index;
const rest = text.slice(index);
const image = rest.match(/^!\[([^\]]*)\]\(([^)]*)\)/);
if (image) {
const altStart = absolute + 2;
builder.addText(image[1] ?? "", altStart);
index += image[0].length - 1;
continue;
}
const link = rest.match(/^\[([^\]]+)\]\(([^)]*)\)/);
if (link) {
const labelStart = absolute + 1;
builder.addText(link[1] ?? "", labelStart);
index += link[0].length - 1;
continue;
}
if (char === "`") {
const closing = text.indexOf("`", index + 1);
if (closing > index + 1) {
builder.addText(text.slice(index + 1, closing), absolute + 1);
index = closing;
continue;
}
}
if (char === "|" || char === "\t") {
builder.addSeparator(absolute);
continue;
}
if (isMarkdownFormattingChar(char, text, index)) continue;
builder.addChar(char, absolute, absolute + 1);
}
}
function isMarkdownFormattingChar(char: string, text: string, index: number): boolean {
if (char === "*" || char === "_" || char === "~") return true;
if (char === "\\" && index + 1 < text.length) return true;
return false;
}
function findOccurrences(text: string, quote: string): number[] {
const starts: number[] = [];
let start = text.indexOf(quote);
while (start !== -1) {
starts.push(start);
start = text.indexOf(quote, start + 1);
}
return starts;
}
function scoreCandidate(args: {
projection: DocumentTextProjection;
start: number;
end: number;
previousAnchor: DocumentAnnotationAnchorSnapshot;
reason: Candidate["reason"];
contextLength: number;
}): Candidate {
const before = args.projection.text.slice(Math.max(0, args.start - args.contextLength), args.start);
const after = args.projection.text.slice(args.end, args.end + args.contextLength);
const prefixScore = suffixOverlapScore(args.previousAnchor.prefixText, before);
const suffixScore = prefixOverlapScore(args.previousAnchor.suffixText, after);
const distance = Math.abs(args.start - args.previousAnchor.normalizedStart);
const proximity = 1 / (1 + distance / 200);
return {
start: args.start,
end: args.end,
score: prefixScore * 0.35 + suffixScore * 0.35 + proximity * 0.3,
reason: args.reason,
};
}
function findFuzzyCandidate(
projection: DocumentTextProjection,
previousAnchor: DocumentAnnotationAnchorSnapshot,
contextLength: number,
): Candidate | null {
const words = normalizeAnchorText(previousAnchor.selectedText).split(" ").filter(Boolean);
if (words.length === 0) return null;
const textWords = [...projection.text.matchAll(/\S+/g)].map((match) => ({
text: match[0],
start: match.index ?? 0,
end: (match.index ?? 0) + match[0].length,
}));
const windowSizes = new Set([words.length - 1, words.length, words.length + 1, words.length + 2].filter((n) => n > 0));
let best: Candidate | null = null;
for (const size of windowSizes) {
for (let index = 0; index + size <= textWords.length; index += 1) {
const window = textWords.slice(index, index + size);
const candidateText = window.map((word) => word.text).join(" ");
const similarity = similarityScore(normalizeAnchorText(previousAnchor.selectedText), candidateText);
if (similarity < 0.45) continue;
const scored = scoreCandidate({
projection,
start: window[0]?.start ?? 0,
end: window[window.length - 1]?.end ?? 0,
previousAnchor,
reason: "fuzzy",
contextLength,
});
scored.score = scored.score * 0.35 + similarity * 0.65;
if (!best || scored.score > best.score) best = scored;
}
}
return best;
}
function buildAnchorSnapshot(
projection: DocumentTextProjection,
normalizedStart: number,
normalizedEnd: number,
contextLength: number,
): DocumentAnnotationAnchorSnapshot {
const range = resolveProjectionRange(projection, normalizedStart, normalizedEnd);
if (!range) {
return {
selectedText: "",
prefixText: "",
suffixText: "",
normalizedStart,
normalizedEnd,
markdownStart: 0,
markdownEnd: 0,
};
}
const selector = createDocumentAnchorSelector(projection, range, { contextLength });
return selectorToAnchorSnapshot(selector);
}
function prefixOverlapScore(expectedPrefix: string, actualPrefix: string): number {
const expected = normalizeAnchorText(expectedPrefix);
const actual = normalizeAnchorText(actualPrefix);
if (!expected) return 0.5;
for (let size = Math.min(expected.length, actual.length); size > 0; size -= 1) {
if (expected.slice(0, size) === actual.slice(0, size)) return size / expected.length;
}
return 0;
}
function suffixOverlapScore(expectedPrefix: string, actualPrefix: string): number {
const expected = normalizeAnchorText(expectedPrefix);
const actual = normalizeAnchorText(actualPrefix);
if (!expected) return 0.5;
for (let size = Math.min(expected.length, actual.length); size > 0; size -= 1) {
if (expected.slice(-size) === actual.slice(-size)) return size / expected.length;
}
return 0;
}
function similarityScore(left: string, right: string): number {
if (left === right) return 1;
const leftWords = new Set(left.toLowerCase().split(/\s+/).filter(Boolean));
const rightWords = new Set(right.toLowerCase().split(/\s+/).filter(Boolean));
const intersection = [...leftWords].filter((word) => rightWords.has(word)).length;
const union = new Set([...leftWords, ...rightWords]).size || 1;
const jaccard = intersection / union;
const lengthRatio = Math.min(left.length, right.length) / Math.max(left.length, right.length, 1);
return jaccard * 0.75 + lengthRatio * 0.25;
}
class ProjectionBuilder {
private text = "";
private positions: DocumentTextPosition[] = [];
private pendingSpace: DocumentTextPosition | null = null;
constructor(private readonly source: string) {}
addText(text: string, sourceOffset: number): void {
for (let index = 0; index < text.length; index += 1) {
this.addChar(text[index] ?? "", sourceOffset + index, sourceOffset + index + 1);
}
}
addSeparator(sourceOffset: number): void {
this.addChar(" ", sourceOffset, sourceOffset + 1);
}
addChar(char: string, sourceStart: number, sourceEnd: number): void {
if (/\s/.test(char)) {
if (this.text.length > 0 && !this.pendingSpace) {
this.pendingSpace = { sourceStart, sourceEnd };
}
return;
}
if (this.pendingSpace && this.text.length > 0) {
this.text += " ";
this.positions.push(this.pendingSpace);
}
this.pendingSpace = null;
this.text += char;
this.positions.push({ sourceStart, sourceEnd });
}
toProjection(): DocumentTextProjection {
return {
source: this.source,
text: this.text,
positions: this.positions,
};
}
}
packages/shared/src/index.ts
+86
View File
@@ -45,6 +45,9 @@ export {
SYSTEM_ISSUE_DOCUMENT_KEYS,
isSystemIssueDocumentKey,
ISSUE_REFERENCE_SOURCE_KINDS,
DOCUMENT_ANNOTATION_THREAD_STATUSES,
DOCUMENT_ANNOTATION_ANCHOR_STATES,
DOCUMENT_ANNOTATION_ANCHOR_CONFIDENCES,
ISSUE_EXECUTION_POLICY_MODES,
ISSUE_EXECUTION_STAGE_TYPES,
ISSUE_MONITOR_SCHEDULED_BY,
@@ -164,6 +167,9 @@ export {
type IssueTreeHoldStatus,
type SystemIssueDocumentKey,
type IssueReferenceSourceKind,
type DocumentAnnotationThreadStatus,
type DocumentAnnotationAnchorState,
type DocumentAnnotationAnchorConfidence,
type IssueExecutionPolicyMode,
type IssueExecutionStageType,
type IssueMonitorScheduledBy,
@@ -290,6 +296,13 @@ export type {
CompanySkillUsageAgent,
CompanySkillDetail,
CompanySkillUpdateStatus,
CompanySkillAuditSeverity,
CompanySkillAuditVerdict,
CompanySkillUpdateHoldReason,
CompanySkillAuditFinding,
CompanySkillAuditResult,
CompanySkillInstallUpdateRequest,
CompanySkillResetRequest,
CompanySkillImportRequest,
CompanySkillImportResult,
CompanySkillProjectScanRequest,
@@ -299,6 +312,14 @@ export type {
CompanySkillCreateRequest,
CompanySkillFileDetail,
CompanySkillFileUpdateRequest,
CatalogSkillKind,
CatalogSkillFileKind,
CatalogSkillFile,
CatalogSkill,
CatalogSkillListQuery,
CatalogSkillFileDetail,
CompanySkillInstallCatalogRequest,
CompanySkillInstallCatalogResult,
AgentSkillSyncMode,
AgentSkillState,
AgentSkillOrigin,
@@ -376,6 +397,20 @@ export type {
IssueWorkProductProvider,
IssueWorkProductStatus,
IssueWorkProductReviewState,
CreateDocumentAnnotationCommentRequest,
CreateDocumentAnnotationThreadRequest,
DocumentAnnotationAnchorRemapSnapshot,
DocumentAnnotationAnchorSelector,
DocumentAnnotationAnchorSnapshot,
DocumentAnnotationComment,
DocumentAnnotationTextPositionSelector,
DocumentAnnotationTextQuoteSelector,
DocumentAnnotationThread,
DocumentAnnotationThreadWithComments,
DocumentTextPosition,
DocumentTextProjection,
DocumentTextRange,
UpdateDocumentAnnotationThreadRequest,
Issue,
IssueAssigneeAdapterOverrides,
IssueBlockerAttention,
@@ -660,11 +695,39 @@ export {
type IssueReferenceMatch,
} from "./issue-references.js";
export {
anchorSnapshotToSelector,
createDocumentAnchorSelector,
normalizeAnchorText,
projectMarkdownToText,
remapDocumentAnchor,
resolveProjectionRange,
selectorToAnchorSnapshot,
verifyDocumentAnchorSelector,
type CreateDocumentAnchorSelectorOptions,
type RemapDocumentAnchorInput,
type RemapDocumentAnchorResult,
type VerifyDocumentAnchorSelectorInput,
type VerifyDocumentAnchorSelectorResult,
} from "./document-anchors.js";
export {
sidebarOrderPreferenceSchema,
upsertSidebarOrderPreferenceSchema,
type UpsertSidebarOrderPreference,
} from "./validators/sidebar-preferences.js";
export {
resourceMembershipStateSchema,
updateResourceMembershipSchema,
type UpdateResourceMembership,
} from "./validators/resource-memberships.js";
export {
RESOURCE_MEMBERSHIP_STATES,
type ResourceMembershipResourceType,
type ResourceMembershipState,
type ResourceMemberships,
type ResourceMembershipUpdateResult,
} from "./types/resource-memberships.js";
export { workspaceRuntimeControlTargetSchema } from "./validators/execution-workspace.js";
export {
@@ -789,6 +852,18 @@ export {
type CreateProjectWorkspace,
type UpdateProjectWorkspace,
projectExecutionWorkspacePolicySchema,
createDocumentAnnotationCommentSchema,
createDocumentAnnotationThreadSchema,
documentAnnotationAnchorConfidenceSchema,
documentAnnotationAnchorSelectorSchema,
documentAnnotationAnchorStateSchema,
documentAnnotationTextPositionSelectorSchema,
documentAnnotationTextQuoteSelectorSchema,
documentAnnotationThreadStatusSchema,
updateDocumentAnnotationThreadSchema,
type CreateDocumentAnnotationComment,
type CreateDocumentAnnotationThread,
type UpdateDocumentAnnotationThread,
companySearchQuerySchema,
COMPANY_SEARCH_DEFAULT_LIMIT,
COMPANY_SEARCH_MAX_LIMIT,
@@ -1008,6 +1083,8 @@ export {
companySkillUsageAgentSchema,
companySkillDetailSchema,
companySkillUpdateStatusSchema,
companySkillAuditFindingSchema,
companySkillAuditResultSchema,
companySkillImportSchema,
companySkillProjectScanRequestSchema,
companySkillProjectScanSkippedSchema,
@@ -1016,6 +1093,15 @@ export {
companySkillCreateSchema,
companySkillFileDetailSchema,
companySkillFileUpdateSchema,
catalogSkillKindSchema,
catalogSkillFileSchema,
catalogSkillSchema,
catalogSkillListQuerySchema,
catalogSkillFileDetailSchema,
companySkillInstallCatalogSchema,
companySkillInstallCatalogResultSchema,
companySkillInstallUpdateSchema,
companySkillResetSchema,
portabilityIncludeSchema,
portabilityEnvInputSchema,
portabilityCompanyManifestEntrySchema,
packages/shared/src/types/company-skill.ts
+108
View File
@@ -51,6 +51,10 @@ export interface CompanySkillListItem {
sourceLabel: string | null;
sourceBadge: CompanySkillSourceBadge;
sourcePath: string | null;
catalogKind: "bundled" | "optional" | null;
originHash: string | null;
packageName: string | null;
packageVersion: string | null;
}
export interface CompanySkillUsageAgent {
@@ -84,6 +88,49 @@ export interface CompanySkillUpdateStatus {
currentRef: string | null;
latestRef: string | null;
hasUpdate: boolean;
installedHash: string | null;
originHash: string | null;
userModifiedAt: string | null;
updateHoldReason: CompanySkillUpdateHoldReason | null;
auditVerdict: CompanySkillAuditVerdict | null;
auditCodes: string[];
}
export type CompanySkillAuditSeverity = "warning" | "error";
export type CompanySkillAuditVerdict = "pass" | "warning" | "fail";
export type CompanySkillUpdateHoldReason =
| "local_modifications"
| "audit_hard_stop"
| "origin_unavailable"
| "compatibility_invalid"
| "operator_hold";
export interface CompanySkillAuditFinding {
code: string;
severity: CompanySkillAuditSeverity;
message: string;
path: string | null;
}
export interface CompanySkillAuditResult {
skillId: string;
installedHash: string | null;
originHash: string | null;
verdict: CompanySkillAuditVerdict;
codes: string[];
findings: CompanySkillAuditFinding[];
scannedAt: string;
scanVersion: string;
}
export interface CompanySkillInstallUpdateRequest {
force?: boolean;
}
export interface CompanySkillResetRequest {
force?: boolean;
}
export interface CompanySkillImportRequest {
@@ -155,3 +202,64 @@ export interface CompanySkillFileUpdateRequest {
path: string;
content: string;
}
export type CatalogSkillKind = "bundled" | "optional";
export type CatalogSkillFileKind = CompanySkillFileInventoryEntry["kind"];
export interface CatalogSkillFile {
path: string;
kind: CatalogSkillFileKind;
sizeBytes: number;
sha256: string;
}
export interface CatalogSkill {
id: string;
key: string;
kind: CatalogSkillKind;
category: string;
slug: string;
name: string;
description: string;
path: string;
entrypoint: "SKILL.md";
trustLevel: CompanySkillTrustLevel;
compatibility: CompanySkillCompatibility;
defaultInstall: boolean;
recommendedForRoles: string[];
requires: string[];
tags: string[];
files: CatalogSkillFile[];
contentHash: string;
packageName?: string;
packageVersion?: string;
}
export interface CatalogSkillListQuery {
kind?: CatalogSkillKind;
category?: string;
q?: string;
}
export interface CatalogSkillFileDetail {
catalogSkillId: string;
path: string;
kind: CatalogSkillFileKind;
content: string;
language: string | null;
markdown: boolean;
}
export interface CompanySkillInstallCatalogRequest {
catalogSkillId: string;
slug?: string | null;
force?: boolean;
}
export interface CompanySkillInstallCatalogResult {
action: "created" | "updated" | "unchanged";
skill: CompanySkill;
catalogSkill: CatalogSkill;
warnings: string[];
}
packages/shared/src/types/document-annotation.ts
+134
View File
@@ -0,0 +1,134 @@
import type {
DocumentAnnotationAnchorConfidence,
DocumentAnnotationAnchorState,
DocumentAnnotationThreadStatus,
IssueCommentAuthorType,
} from "../constants.js";
export interface DocumentTextPosition {
sourceStart: number;
sourceEnd: number;
}
export interface DocumentTextProjection {
source: string;
text: string;
positions: DocumentTextPosition[];
}
export interface DocumentTextRange {
text: string;
normalizedStart: number;
normalizedEnd: number;
markdownStart: number;
markdownEnd: number;
}
export interface DocumentAnnotationTextQuoteSelector {
exact: string;
prefix: string;
suffix: string;
}
export interface DocumentAnnotationTextPositionSelector {
normalizedStart: number;
normalizedEnd: number;
markdownStart: number;
markdownEnd: number;
}
export interface DocumentAnnotationAnchorSelector {
quote: DocumentAnnotationTextQuoteSelector;
position: DocumentAnnotationTextPositionSelector;
}
export interface DocumentAnnotationAnchorSnapshot {
selectedText: string;
prefixText: string;
suffixText: string;
normalizedStart: number;
normalizedEnd: number;
markdownStart: number;
markdownEnd: number;
}
export interface DocumentAnnotationThread {
id: string;
companyId: string;
issueId: string;
documentId: string;
documentKey: string;
status: DocumentAnnotationThreadStatus;
anchorState: DocumentAnnotationAnchorState;
anchorConfidence: DocumentAnnotationAnchorConfidence;
originalRevisionId: string | null;
originalRevisionNumber: number;
currentRevisionId: string | null;
currentRevisionNumber: number;
selectedText: string;
prefixText: string;
suffixText: string;
normalizedStart: number;
normalizedEnd: number;
markdownStart: number;
markdownEnd: number;
anchorSelector: DocumentAnnotationAnchorSelector;
createdByAgentId: string | null;
createdByUserId: string | null;
resolvedByAgentId: string | null;
resolvedByUserId: string | null;
resolvedAt: Date | null;
createdAt: Date;
updatedAt: Date;
}
export interface DocumentAnnotationComment {
id: string;
companyId: string;
threadId: string;
issueId: string;
documentId: string;
body: string;
authorType: IssueCommentAuthorType;
authorAgentId: string | null;
authorUserId: string | null;
createdByRunId: string | null;
createdAt: Date;
updatedAt: Date;
}
export interface DocumentAnnotationAnchorRemapSnapshot {
id: string;
companyId: string;
threadId: string;
documentId: string;
fromRevisionId: string | null;
fromRevisionNumber: number | null;
toRevisionId: string | null;
toRevisionNumber: number;
previousAnchor: DocumentAnnotationAnchorSnapshot;
nextAnchor: DocumentAnnotationAnchorSnapshot | null;
anchorState: DocumentAnnotationAnchorState;
anchorConfidence: DocumentAnnotationAnchorConfidence;
failureReason: string | null;
createdAt: Date;
}
export interface DocumentAnnotationThreadWithComments extends DocumentAnnotationThread {
comments: DocumentAnnotationComment[];
}
export interface CreateDocumentAnnotationThreadRequest {
baseRevisionId: string;
baseRevisionNumber: number;
selector: DocumentAnnotationAnchorSelector;
body: string;
}
export interface CreateDocumentAnnotationCommentRequest {
body: string;
}
export interface UpdateDocumentAnnotationThreadRequest {
status?: DocumentAnnotationThreadStatus;
}
packages/shared/src/types/index.ts
+39
View File
@@ -51,6 +51,13 @@ export type {
CompanySkillUsageAgent,
CompanySkillDetail,
CompanySkillUpdateStatus,
CompanySkillAuditSeverity,
CompanySkillAuditVerdict,
CompanySkillUpdateHoldReason,
CompanySkillAuditFinding,
CompanySkillAuditResult,
CompanySkillInstallUpdateRequest,
CompanySkillResetRequest,
CompanySkillImportRequest,
CompanySkillImportResult,
CompanySkillProjectScanRequest,
@@ -60,6 +67,14 @@ export type {
CompanySkillCreateRequest,
CompanySkillFileDetail,
CompanySkillFileUpdateRequest,
CatalogSkillKind,
CatalogSkillFileKind,
CatalogSkillFile,
CatalogSkill,
CatalogSkillListQuery,
CatalogSkillFileDetail,
CompanySkillInstallCatalogRequest,
CompanySkillInstallCatalogResult,
} from "./company-skill.js";
export type {
AgentSkillSyncMode,
@@ -89,6 +104,22 @@ export type {
AdapterEnvironmentTestResult,
} from "./agent.js";
export type { AssetImage } from "./asset.js";
export type {
CreateDocumentAnnotationCommentRequest,
CreateDocumentAnnotationThreadRequest,
DocumentAnnotationAnchorRemapSnapshot,
DocumentAnnotationAnchorSelector,
DocumentAnnotationAnchorSnapshot,
DocumentAnnotationComment,
DocumentAnnotationTextPositionSelector,
DocumentAnnotationTextQuoteSelector,
DocumentAnnotationThread,
DocumentAnnotationThreadWithComments,
DocumentTextPosition,
DocumentTextProjection,
DocumentTextRange,
UpdateDocumentAnnotationThreadRequest,
} from "./document-annotation.js";
export type { Project, ProjectCodebase, ProjectCodebaseOrigin, ProjectGoalRef, ProjectManagedByPlugin, ProjectWorkspace } from "./project.js";
export type {
CompanySearchHighlight,
@@ -333,6 +364,14 @@ export type {
} from "./user-profile.js";
export type { SidebarBadges } from "./sidebar-badges.js";
export type { SidebarOrderPreference } from "./sidebar-preferences.js";
export type {
ResourceMembershipResourceType,
ResourceMembershipState,
ResourceMemberships,
ResourceMembershipUpdateResult,
UpdateResourceMembership,
} from "./resource-memberships.js";
export { RESOURCE_MEMBERSHIP_STATES } from "./resource-memberships.js";
export type { InboxDismissal } from "./inbox-dismissal.js";
export type {
AccessUserProfile,
packages/shared/src/types/resource-memberships.ts
+21
View File
@@ -0,0 +1,21 @@
export const RESOURCE_MEMBERSHIP_STATES = ["joined", "left"] as const;
export type ResourceMembershipState = (typeof RESOURCE_MEMBERSHIP_STATES)[number];
export type ResourceMembershipResourceType = "project" | "agent";
export interface ResourceMemberships {
projectMemberships: Record<string, ResourceMembershipState>;
agentMemberships: Record<string, ResourceMembershipState>;
updatedAt: Date | null;
}
export interface UpdateResourceMembership {
state: ResourceMembershipState;
}
export interface ResourceMembershipUpdateResult {
resourceType: ResourceMembershipResourceType;
resourceId: string;
state: ResourceMembershipState;
updatedAt: Date;
}
packages/shared/src/types/workspace-runtime.ts
+4
View File
@@ -168,7 +168,11 @@ export interface ExecutionWorkspaceSummary {
id: string;
name: string;
mode: Exclude<ExecutionWorkspaceMode, "inherit" | "reuse_existing" | "agent_default"> | "adapter_managed" | "cloud_sandbox";
status: ExecutionWorkspaceStatus;
cwd: string | null;
branchName: string | null;
projectWorkspaceId: string | null;
lastUsedAt: Date;
}
export interface ExecutionWorkspace {
packages/shared/src/validators/company-skill.test.ts
+158
View File
@@ -0,0 +1,158 @@
import { describe, expect, it } from "vitest";
import {
catalogSkillFileDetailSchema,
catalogSkillListQuerySchema,
companySkillAuditResultSchema,
companySkillInstallCatalogResultSchema,
companySkillInstallCatalogSchema,
companySkillInstallUpdateSchema,
companySkillResetSchema,
companySkillUpdateStatusSchema,
} from "./company-skill.js";
const catalogSkill = {
id: "paperclipai:bundled:software-development:review",
key: "paperclipai/bundled/software-development/review",
kind: "bundled",
category: "software-development",
slug: "review",
name: "review",
description: "Review code",
path: "catalog/bundled/software-development/review",
entrypoint: "SKILL.md",
trustLevel: "markdown_only",
compatibility: "compatible",
defaultInstall: false,
recommendedForRoles: ["engineer"],
requires: [],
tags: ["review"],
files: [{ path: "SKILL.md", kind: "skill", sizeBytes: 8, sha256: "abc" }],
contentHash: "sha256:abc",
};
const companySkill = {
id: "00000000-0000-4000-8000-000000000001",
companyId: "00000000-0000-4000-8000-000000000002",
key: catalogSkill.key,
slug: catalogSkill.slug,
name: catalogSkill.name,
description: catalogSkill.description,
markdown: "# Review\n",
sourceType: "catalog",
sourceLocator: "/tmp/review",
sourceRef: catalogSkill.contentHash,
trustLevel: "markdown_only",
compatibility: "compatible",
fileInventory: [{ path: "SKILL.md", kind: "skill" }],
metadata: {
sourceKind: "catalog",
catalogId: catalogSkill.id,
originHash: catalogSkill.contentHash,
},
createdAt: "2026-05-26T00:00:00.000Z",
updatedAt: "2026-05-26T00:00:00.000Z",
};
describe("company skill catalog validators", () => {
it("accepts catalog list and install request shapes", () => {
expect(catalogSkillListQuerySchema.parse({
kind: "bundled",
category: "software-development",
q: "review",
})).toEqual({
kind: "bundled",
category: "software-development",
q: "review",
});
expect(companySkillInstallCatalogSchema.parse({
catalogSkillId: catalogSkill.id,
slug: "team-review",
force: true,
})).toEqual({
catalogSkillId: catalogSkill.id,
slug: "team-review",
force: true,
});
});
it("rejects invalid catalog filter and install payloads", () => {
expect(() => catalogSkillListQuerySchema.parse({ kind: "external" })).toThrow();
expect(() => companySkillInstallCatalogSchema.parse({ force: true })).toThrow();
});
it("accepts catalog file and install result responses", () => {
expect(catalogSkillFileDetailSchema.parse({
catalogSkillId: catalogSkill.id,
path: "SKILL.md",
kind: "skill",
content: "# Review\n",
language: "markdown",
markdown: true,
})).toMatchObject({
catalogSkillId: catalogSkill.id,
path: "SKILL.md",
});
expect(companySkillInstallCatalogResultSchema.parse({
action: "created",
skill: companySkill,
catalogSkill,
warnings: [],
})).toMatchObject({
action: "created",
skill: {
key: catalogSkill.key,
sourceType: "catalog",
},
catalogSkill: {
id: catalogSkill.id,
},
});
});
it("accepts update status, audit, update, and reset contract shapes", () => {
expect(companySkillUpdateStatusSchema.parse({
supported: true,
reason: null,
trackingRef: catalogSkill.id,
currentRef: "sha256:old",
latestRef: catalogSkill.contentHash,
hasUpdate: true,
installedHash: "sha256:installed",
originHash: catalogSkill.contentHash,
userModifiedAt: "2026-05-26T00:00:00.000Z",
updateHoldReason: "local_modifications",
auditVerdict: "warning",
auditCodes: ["local_modifications"],
})).toMatchObject({
supported: true,
updateHoldReason: "local_modifications",
auditVerdict: "warning",
});
expect(companySkillAuditResultSchema.parse({
skillId: companySkill.id,
installedHash: "sha256:installed",
originHash: catalogSkill.contentHash,
verdict: "fail",
codes: ["remote_fetch_exec"],
findings: [{
code: "remote_fetch_exec",
severity: "error",
message: "Remote-fetch or dynamic execution pattern is not allowed.",
path: "SKILL.md",
}],
scannedAt: "2026-05-26T00:00:00.000Z",
scanVersion: "skills-audit-v1",
})).toMatchObject({
verdict: "fail",
codes: ["remote_fetch_exec"],
});
expect(companySkillInstallUpdateSchema.parse(undefined)).toEqual({});
expect(companySkillInstallUpdateSchema.parse({ force: true })).toEqual({ force: true });
expect(companySkillResetSchema.parse(undefined)).toEqual({});
expect(companySkillResetSchema.parse({ force: true })).toEqual({ force: true });
});
});
packages/shared/src/validators/company-skill.ts
+105
View File
@@ -35,6 +35,10 @@ export const companySkillListItemSchema = companySkillSchema.extend({
editableReason: z.string().nullable(),
sourceLabel: z.string().nullable(),
sourceBadge: companySkillSourceBadgeSchema,
catalogKind: z.enum(["bundled", "optional"]).nullable(),
originHash: z.string().nullable(),
packageName: z.string().nullable(),
packageVersion: z.string().nullable(),
});
export const companySkillUsageAgentSchema = z.object({
@@ -64,8 +68,46 @@ export const companySkillUpdateStatusSchema = z.object({
currentRef: z.string().nullable(),
latestRef: z.string().nullable(),
hasUpdate: z.boolean(),
installedHash: z.string().nullable(),
originHash: z.string().nullable(),
userModifiedAt: z.string().nullable(),
updateHoldReason: z.enum([
"local_modifications",
"audit_hard_stop",
"origin_unavailable",
"compatibility_invalid",
"operator_hold",
]).nullable(),
auditVerdict: z.enum(["pass", "warning", "fail"]).nullable(),
auditCodes: z.array(z.string()),
});
export const companySkillAuditFindingSchema = z.object({
code: z.string().min(1),
severity: z.enum(["warning", "error"]),
message: z.string().min(1),
path: z.string().nullable(),
});
export const companySkillAuditResultSchema = z.object({
skillId: z.string().uuid(),
installedHash: z.string().nullable(),
originHash: z.string().nullable(),
verdict: z.enum(["pass", "warning", "fail"]),
codes: z.array(z.string()),
findings: z.array(companySkillAuditFindingSchema),
scannedAt: z.string().min(1),
scanVersion: z.string().min(1),
});
export const companySkillInstallUpdateSchema = z.object({
force: z.boolean().optional(),
}).default({});
export const companySkillResetSchema = z.object({
force: z.boolean().optional(),
}).default({});
export const companySkillImportSchema = z.object({
source: z.string().min(1),
});
@@ -131,7 +173,70 @@ export const companySkillFileUpdateSchema = z.object({
content: z.string(),
});
export const catalogSkillKindSchema = z.enum(["bundled", "optional"]);
export const catalogSkillFileSchema = z.object({
path: z.string().min(1),
kind: z.enum(["skill", "markdown", "reference", "script", "asset", "other"]),
sizeBytes: z.number().int().nonnegative(),
sha256: z.string().min(1),
});
export const catalogSkillSchema = z.object({
id: z.string().min(1),
key: z.string().min(1),
kind: catalogSkillKindSchema,
category: z.string().min(1),
slug: z.string().min(1),
name: z.string().min(1),
description: z.string(),
path: z.string().min(1),
entrypoint: z.literal("SKILL.md"),
trustLevel: companySkillTrustLevelSchema,
compatibility: companySkillCompatibilitySchema,
defaultInstall: z.boolean(),
recommendedForRoles: z.array(z.string()),
requires: z.array(z.string()),
tags: z.array(z.string()),
files: z.array(catalogSkillFileSchema),
contentHash: z.string().min(1),
packageName: z.string().min(1).optional(),
packageVersion: z.string().min(1).optional(),
});
export const catalogSkillListQuerySchema = z.object({
kind: catalogSkillKindSchema.optional(),
category: z.string().min(1).optional(),
q: z.string().min(1).optional(),
});
export const catalogSkillFileDetailSchema = z.object({
catalogSkillId: z.string().min(1),
path: z.string().min(1),
kind: z.enum(["skill", "markdown", "reference", "script", "asset", "other"]),
content: z.string(),
language: z.string().nullable(),
markdown: z.boolean(),
});
export const companySkillInstallCatalogSchema = z.object({
catalogSkillId: z.string().min(1),
slug: z.string().min(1).nullable().optional(),
force: z.boolean().optional(),
});
export const companySkillInstallCatalogResultSchema = z.object({
action: z.enum(["created", "updated", "unchanged"]),
skill: companySkillSchema,
catalogSkill: catalogSkillSchema,
warnings: z.array(z.string()),
});
export type CompanySkillImport = z.infer<typeof companySkillImportSchema>;
export type CompanySkillProjectScan = z.infer<typeof companySkillProjectScanRequestSchema>;
export type CompanySkillCreate = z.infer<typeof companySkillCreateSchema>;
export type CompanySkillFileUpdate = z.infer<typeof companySkillFileUpdateSchema>;
export type CatalogSkillListQuery = z.infer<typeof catalogSkillListQuerySchema>;
export type CompanySkillInstallCatalog = z.infer<typeof companySkillInstallCatalogSchema>;
export type CompanySkillInstallUpdate = z.infer<typeof companySkillInstallUpdateSchema>;
export type CompanySkillReset = z.infer<typeof companySkillResetSchema>;
packages/shared/src/validators/document-annotation.ts
+65
View File
@@ -0,0 +1,65 @@
import { z } from "zod";
import {
DOCUMENT_ANNOTATION_ANCHOR_CONFIDENCES,
DOCUMENT_ANNOTATION_ANCHOR_STATES,
DOCUMENT_ANNOTATION_THREAD_STATUSES,
} from "../constants.js";
import { multilineTextSchema } from "./text.js";
export const documentAnnotationThreadStatusSchema = z.enum(DOCUMENT_ANNOTATION_THREAD_STATUSES);
export const documentAnnotationAnchorStateSchema = z.enum(DOCUMENT_ANNOTATION_ANCHOR_STATES);
export const documentAnnotationAnchorConfidenceSchema = z.enum(DOCUMENT_ANNOTATION_ANCHOR_CONFIDENCES);
export const documentAnnotationTextQuoteSelectorSchema = z.object({
exact: z.string().min(1).max(10_000),
prefix: z.string().max(1_000).default(""),
suffix: z.string().max(1_000).default(""),
}).strict();
export const documentAnnotationTextPositionSelectorSchema = z.object({
normalizedStart: z.number().int().nonnegative(),
normalizedEnd: z.number().int().nonnegative(),
markdownStart: z.number().int().nonnegative(),
markdownEnd: z.number().int().nonnegative(),
}).strict().superRefine((value, ctx) => {
if (value.normalizedEnd <= value.normalizedStart) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: "normalizedEnd must be greater than normalizedStart",
path: ["normalizedEnd"],
});
}
if (value.markdownEnd <= value.markdownStart) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: "markdownEnd must be greater than markdownStart",
path: ["markdownEnd"],
});
}
});
export const documentAnnotationAnchorSelectorSchema = z.object({
quote: documentAnnotationTextQuoteSelectorSchema,
position: documentAnnotationTextPositionSelectorSchema,
}).strict();
export const createDocumentAnnotationThreadSchema = z.object({
baseRevisionId: z.string().uuid(),
baseRevisionNumber: z.number().int().positive(),
selector: documentAnnotationAnchorSelectorSchema,
body: multilineTextSchema.pipe(z.string().min(1).max(20_000)),
}).strict();
export const createDocumentAnnotationCommentSchema = z.object({
body: multilineTextSchema.pipe(z.string().min(1).max(20_000)),
}).strict();
export const updateDocumentAnnotationThreadSchema = z.object({
status: documentAnnotationThreadStatusSchema.optional(),
}).strict().refine((value) => value.status != null, {
message: "At least one field must be provided",
});
export type CreateDocumentAnnotationThread = z.infer<typeof createDocumentAnnotationThreadSchema>;
export type CreateDocumentAnnotationComment = z.infer<typeof createDocumentAnnotationCommentSchema>;
export type UpdateDocumentAnnotationThread = z.infer<typeof updateDocumentAnnotationThreadSchema>;
packages/shared/src/validators/index.ts
+35
View File
@@ -51,6 +51,11 @@ export {
upsertSidebarOrderPreferenceSchema,
type UpsertSidebarOrderPreference,
} from "./sidebar-preferences.js";
export {
resourceMembershipStateSchema,
updateResourceMembershipSchema,
type UpdateResourceMembership,
} from "./resource-memberships.js";
export {
companySkillSourceTypeSchema,
companySkillTrustLevelSchema,
@@ -62,6 +67,8 @@ export {
companySkillUsageAgentSchema,
companySkillDetailSchema,
companySkillUpdateStatusSchema,
companySkillAuditFindingSchema,
companySkillAuditResultSchema,
companySkillImportSchema,
companySkillProjectScanRequestSchema,
companySkillProjectScanSkippedSchema,
@@ -70,10 +77,23 @@ export {
companySkillCreateSchema,
companySkillFileDetailSchema,
companySkillFileUpdateSchema,
catalogSkillKindSchema,
catalogSkillFileSchema,
catalogSkillSchema,
catalogSkillListQuerySchema,
catalogSkillFileDetailSchema,
companySkillInstallCatalogSchema,
companySkillInstallCatalogResultSchema,
companySkillInstallUpdateSchema,
companySkillResetSchema,
type CompanySkillImport,
type CompanySkillProjectScan,
type CompanySkillCreate,
type CompanySkillFileUpdate,
type CatalogSkillListQuery,
type CompanySkillInstallCatalog,
type CompanySkillInstallUpdate,
type CompanySkillReset,
} from "./company-skill.js";
export {
agentSkillStateSchema,
@@ -147,6 +167,21 @@ export {
type ProjectExecutionWorkspacePolicy,
} from "./project.js";
export {
createDocumentAnnotationCommentSchema,
createDocumentAnnotationThreadSchema,
documentAnnotationAnchorConfidenceSchema,
documentAnnotationAnchorSelectorSchema,
documentAnnotationAnchorStateSchema,
documentAnnotationTextPositionSelectorSchema,
documentAnnotationTextQuoteSelectorSchema,
documentAnnotationThreadStatusSchema,
updateDocumentAnnotationThreadSchema,
type CreateDocumentAnnotationComment,
type CreateDocumentAnnotationThread,
type UpdateDocumentAnnotationThread,
} from "./document-annotation.js";
export {
createIssueSchema,
createIssueInputSchema,
packages/shared/src/validators/resource-memberships.ts
+10
View File
@@ -0,0 +1,10 @@
import { z } from "zod";
import { RESOURCE_MEMBERSHIP_STATES } from "../types/resource-memberships.js";
export const resourceMembershipStateSchema = z.enum(RESOURCE_MEMBERSHIP_STATES);
export const updateResourceMembershipSchema = z.object({
state: resourceMembershipStateSchema,
});
export type UpdateResourceMembership = z.infer<typeof updateResourceMembershipSchema>;
packages/skills-catalog/catalog/bundled/docs/doc-maintenance/SKILL.md
+75
View File
@@ -0,0 +1,75 @@
---
name: doc-maintenance
description: Keep project docs aligned with recent code and feature changes — detect drift, update affected pages, and add release-relevant notes without rewriting unchanged sections.
key: paperclipai/bundled/docs/doc-maintenance
recommendedForRoles:
- engineer
- product
- devrel
tags:
- docs
- documentation
- release-notes
---
# Doc Maintenance
Keep the documentation honest with minimum churn. The goal is alignment between docs and behavior, not stylistic rewrites or cosmetic re-organization. Reviewers should be able to read a diff and see "this updates docs to match recent behavior changes".
## When to use
- A PR or recent set of merges changed user-visible behavior: CLI flags, API shapes, default values, configuration keys, endpoints, environment variables, supported versions.
- A user-reported bug traced back to outdated documentation.
- A release is being cut and the docs need a pass against the merged commits.
- A new feature shipped but only the engineer's PR description describes how to use it.
## When not to use
- The change is internal-only (private helper rename, refactor) with no user-visible impact.
- You want to "improve the docs" without a behavior anchor. That is a separate scoped project, not maintenance — make a plan first.
## The pass
1. **Establish the baseline.** Get the commit range you are documenting against (since last release tag, since last merged-doc commit, or since a specific PR).
2. **Enumerate user-visible changes.** Read commits and PR descriptions. List, for each change, what a user can now do differently.
3. **Map changes to docs.** For each change, find every page that mentions the affected concept. Common targets: README, CLI reference, API reference, configuration reference, migration guide, FAQ, examples.
4. **Update precisely.** Edit only the lines that need to change. Do not rewrap paragraphs you did not modify — it pollutes the diff.
5. **Add new entries where needed.** New CLI flag → CLI reference entry. New env var → configuration reference entry. New endpoint → API reference entry. Don't only add it to the changelog.
6. **Update examples and snippets.** Code blocks in docs are wrong faster than prose. Re-run any example that touches new behavior.
7. **Write the release note.** One sentence per user-visible change. Group by Added / Changed / Fixed / Deprecated / Removed. Link to the relevant PRs and docs section.
8. **Cross-check.** Search the docs for the old behavior wording and remove or update stragglers.
## Style baseline
- Voice: second person ("you can pass `--json` to ..."). Avoid "we" except in narrative pages.
- Tense: present, not future. The behavior exists once shipped.
- Headings: imperative ("Configure the cache") or noun-phrase ("Cache configuration"), match the surrounding page.
- Code blocks: include the language tag so syntax highlighting works.
- Cross-links: link the first mention of a concept on each page; do not link every occurrence.
- Avoid promising future behavior. If something is unreleased, mark it `experimental` or omit it.
## Drift detection
A doc page is drifting if any of these are true:
- It documents a flag, key, or endpoint that no longer exists.
- An example does not run as written.
- A default value in the docs does not match the code.
- A supported-versions list excludes a version the project actually supports, or includes one it dropped.
- A "Coming soon" section references a feature that shipped or was cancelled.
When you find drift, fix it in the same pass and note it in the release note's `Fixed` group.
## Release-note rules
- One sentence per item. If two sentences are needed, the item is likely two items.
- User impact first, internal cause second. `Faster cold start (avoid full bundle download on first run)` beats `Refactor bootstrap loader`.
- Link the PR for engineering readers and the docs page for users.
- Mark breaking changes explicitly: `**Breaking:**` prefix. Include migration steps inline or via link.
## Anti-patterns
- Massive doc PRs that bundle stylistic rewrites with real updates. Reviewers cannot tell which lines reflect actual behavior changes.
- "Updated docs" commit messages with no detail. Make the commit say what changed and why.
- Adding to the changelog without updating the reference docs the changelog points to.
- Marking a feature as available before its code lands. Documentation must follow behavior, not promise it.
packages/skills-catalog/catalog/bundled/paperclip-operations/issue-triage/SKILL.md
+74
View File
@@ -0,0 +1,74 @@
---
name: issue-triage
description: Triage Paperclip inbox issues that are stale, blocked, in-review, or assigned-but-not-progressing, and decide a single next action per issue (resume, reassign, unblock, escalate, or close).
key: paperclipai/bundled/paperclip-operations/issue-triage
recommendedForRoles:
- manager
- ceo
- engineer
tags:
- paperclip
- triage
- inbox
- workflow
---
# Issue Triage
Convert a noisy inbox into a small set of clear next actions. Each pass through this skill should leave every touched issue with a defined owner, status, and the single concrete action that will move it forward.
## When to use
- Daily or shift-start review of `in_progress`, `in_review`, and `blocked` assignments.
- An inbox has many open assignments and no clear priority.
- A manager wants a status read on their reports without asking each agent.
- You are woken by a comment that suggests an old issue stalled.
## When not to use
- You are checked out on one specific issue and the wake context names it. Work that issue, do not triage the whole inbox.
- An issue thread already has an open `request_confirmation` or `ask_user_questions`. Wait for the response — re-triage is noise.
## Inputs
- `GET /api/agents/me/inbox-lite` for the compact assignment list.
- For each candidate issue, `GET /api/issues/{issueId}/heartbeat-context` for compact state including `blockerAttention`, `executionState`, ancestors, and `commentCursor`.
- Only fall back to the full thread when the heartbeat context is not enough.
## Per-issue triage decision
For each issue, classify into exactly one of:
1. **Resume** — execution path is alive. Confirm the assignee is set and let the heartbeat continue. Do not comment.
2. **Wake-needed** — assignee is stalled with no live continuation. Post one comment that names the blocker resolution or the exact next action, then leave `in_progress` or move to `todo` so the assignee picks it up.
3. **Reassign** — the assignee is not the right specialty. Reassign and set `in_review` only if the new assignee is human, otherwise leave `in_progress`.
4. **Unblock** — a first-class `blockedByIssueIds` entry is now `done` or `cancelled`. If `cancelled`, replace or remove it from `blockedByIssueIds`. The blockers-resolved wake will fire automatically when all are `done`.
5. **Escalate** — the issue needs board, CTO, or user input. Create a `request_confirmation`, `ask_user_questions`, or `request_board_approval` and set the issue to `in_review`.
6. **Close** — work is complete, duplicate, or no longer relevant. Set `done` or `cancelled` with a one-line reason.
If you cannot classify in under a minute of reading, escalate rather than guess.
## Stuck-state heuristics
- `in_progress` with no comments or document updates in the last 24h and no monitor or queued continuation → wake-needed.
- `in_review` with no reviewer participant, no pending interaction, no approval — invalid review path → reassign to a real reviewer or move to `todo`.
- `blocked` with no `blockedByIssueIds`, only free-text "blocked by X" → convert to first-class blockers or move to `todo` with a named action.
- `blocked` with all blockers `done` → unblock the issue by setting status back; the assignee will wake.
- Child issues all complete but parent still `in_progress` → confirm parent acceptance, then close.
## Don't-do list
- Do not @-mention agents during triage; mentions cost budget. Use direct reassignment instead.
- Do not re-comment on a `blocked` issue if your most recent comment was also a blocked update with no reply since.
- Do not cancel cross-team issues. Reassign to the responsible manager with a comment.
- Do not change status without a comment that explains the change.
## Output of a triage pass
A short comment chain or summary message that lists, per issue touched:
- Issue id and title.
- Verdict (resume / wake-needed / reassign / unblock / escalate / close).
- The one action you took or asked for.
This is the bar for "the triage is done."
packages/skills-catalog/catalog/bundled/paperclip-operations/task-planning/SKILL.md
+84
View File
@@ -0,0 +1,84 @@
---
name: task-planning
description: Turn a Paperclip issue or request into a structured implementation plan with child task graph, blockers, owners, and acceptance criteria, then save it as the issue `plan` document.
key: paperclipai/bundled/paperclip-operations/task-planning
recommendedForRoles:
- manager
- engineer
- product
tags:
- paperclip
- planning
- issues
- delegation
---
# Task Planning
Produce implementation plans that the Paperclip executor can actually run: explicit child issues, real blockers, named owners, and a defined acceptance bar. Avoid plans that read well but cannot be split into work.
## When to use
- An issue asks you to "plan", "scope", "break down", "design the rollout", "propose the work", or similar.
- A user wants a written plan before approving implementation.
- A manager needs to delegate non-trivial work and the shape of the work is not obvious yet.
- You inherited an issue too large to deliver in one heartbeat and need to split it.
## When not to use
- The issue is a single small change you can ship in the same heartbeat. Just ship it.
- The issue is forensic ("why did this break"). Use a diagnosis skill first; plan only after the root cause is named.
- A current `plan` document already exists and the change is minor. Update that document; do not start fresh.
## Outputs
1. An updated issue document with key `plan` (markdown).
2. A short comment on the issue that links to the plan document and names the next action.
3. Where the plan requires approval, an issue-thread interaction of kind `request_confirmation` bound to the latest plan revision.
Do not create implementation subtasks until the plan is accepted.
## Plan structure
Required sections, in order:
1. **Goal** — one paragraph. What changes for the user, the operator, or the system once this work lands.
2. **Context reviewed** — bullet list of documents, files, and prior issues you read. Lets reviewers spot missing inputs.
3. **Constraints and non-goals** — what must hold (compatibility, security, performance) and what this plan deliberately will not do.
4. **Approach** — the chosen path, with a short rationale. If you considered alternatives, name them and why you rejected them.
5. **Work breakdown** — ordered list of child issues. Each child has:
- Title in imperative form.
- Owner specialty (Engineer, QA, Designer, Security, DevRel, Manager, etc.).
- Scope and deliverables.
- Acceptance criteria.
- Blocks/blocked-by relationships expressed by phase letter or child title.
6. **Acceptance** — the bar for the parent issue. How the user knows the whole thing is done.
7. **Risks and mitigations** — short list. Skip if there are none.
8. **Deferrals** — what is intentionally pushed to follow-up issues, with why.
## Rules of thumb for splitting
- One child issue, one specialty. If two specialties have to coordinate inside the same issue, split it.
- One child issue, one acceptance verdict. If a reviewer would say "this is half done", split it.
- A child must be checkout-able by the owner from its title and description alone. Reviewers should not have to re-read the parent plan to understand a child.
- Order children by real blocker chains, not by author preference. Parallel children should explicitly say `blockers: none`.
- Avoid `polish` or `cleanup` child issues without acceptance criteria — they never close.
## Filing the plan
Use the Paperclip API to write the plan document, then comment:
- `PUT /api/issues/{issueId}/documents/plan` with the markdown body. If `plan` already exists, include the latest `baseRevisionId`.
- `POST /api/issues/{issueId}/comments` with a short summary that links the plan: `/<prefix>/issues/<issue-id>#document-plan`.
- If approval is required: `POST /api/issues/{issueId}/interactions` with `kind: request_confirmation`, `targetRevisionId` set to the new plan revision, `continuationPolicy: wake_assignee`, and `idempotencyKey: "confirmation:{issueId}:plan:{revisionId}"`.
- Set the issue to `in_review` after creating the confirmation. Stay assigned so the acceptance wakes the planner.
When the plan is accepted, see the companion skill for converting accepted plans into Paperclip executable tasks.
## Anti-patterns
- Plan disguised as a description edit. Use the `plan` document.
- "Phases A–Z" with no work breakdown inside the phases.
- Children with descriptions that say "see parent" — they fail at delegation time.
- Acceptance written as "code review approval". Reviewers need a behavior bar, not a process bar.
- Plans that bury blocker chains in prose. Use explicit blocked-by lines.
packages/skills-catalog/catalog/bundled/quality/qa-acceptance/SKILL.md
+93
View File
@@ -0,0 +1,93 @@
---
name: qa-acceptance
description: Produce QA acceptance criteria and a manual validation plan for a feature change — golden path, edge cases, error states, performance limits, and explicit pass/fail evidence.
key: paperclipai/bundled/quality/qa-acceptance
recommendedForRoles:
- qa
- engineer
- product
tags:
- qa
- acceptance
- validation
- testing
---
# QA Acceptance
Write acceptance criteria that a reviewer can run against the running app and decide pass or fail without asking the author. The criteria are the contract — automated tests cover correctness, QA covers feature-level behavior.
## When to use
- A feature change is heading to QA and needs a written validation plan.
- A reviewer is asked to verify a PR that touches user-visible behavior.
- An incident postmortem requires a regression check before reopen-prevention.
- A release candidate needs a pre-cut smoke pass.
## When not to use
- The change is unit-test-only (utility refactor, internal naming). Acceptance criteria are unnecessary churn.
- You are asked to write tests against API contracts. Use contract testing, not feature QA.
## Acceptance criteria format
Each criterion is a single, independently-verifiable statement:
```md
- **Given** <starting state>, **when** <action>, **then** <observable outcome>.
```
Example:
```md
- **Given** a CSV export with 0 rows, **when** the user clicks Export, **then** the file downloads with only the header row and the UI shows "Exported 0 rows".
```
Avoid criteria that combine multiple `when`s or `then`s. Split them.
## What every plan must cover
1. **Golden path.** The most common successful flow, end to end.
2. **Empty and minimum states.** Zero items, one item, missing optional inputs.
3. **Boundary inputs.** Max length strings, max numeric values, unicode, RTL text where applicable.
4. **Error states.** Network failure, permission denied, validation failures, conflict (409), not found (404).
5. **Concurrency and ordering.** Two users acting at once, race against background jobs, refresh during mutation.
6. **Performance envelope.** The largest realistic input the change must handle without UI hangs or timeouts.
7. **Backward compatibility.** Existing data, existing URLs, persisted user preferences continue to work.
8. **Telemetry and audit.** Events, logs, or activity entries the change is supposed to emit.
If a section is genuinely not applicable, write "N/A: <why>" — do not silently omit.
## Evidence
Each criterion needs evidence on the verification pass:
- Screenshot or short clip for UI behavior.
- Copied console / network output for API behavior.
- Log snippet or activity row for telemetry.
- Timing measurement for performance criteria.
"Looks good to me" without evidence is not a pass.
## Quarantine and follow-up
- A failing criterion blocks acceptance unless explicitly waived by the owner with a tracked follow-up issue.
- "Known issue" without a linked follow-up is not a waiver.
- If you add a new criterion mid-pass, restart the pass — partial coverage hides regressions.
## Handoff back to the author
Return the validation plan with three sections:
- **Pass.** Criteria that passed, with one-line evidence summaries.
- **Fail.** Criteria that failed, with the exact reproduction.
- **Blocked.** Criteria you could not run, with why.
The author owns turning failures into either fixes or accepted deferrals.
## Anti-patterns
- Acceptance phrased as test plan ("write a Cypress test for X"). Acceptance is what is true after the change ships; tests are how you check.
- Criteria that depend on inspecting implementation details (selectors, query plans). Stay observable.
- Long checklists with no priority. Mark must-pass criteria distinctly from nice-to-have.
- Validation reports that say "passed" with no evidence. Reviewers cannot audit those.
packages/skills-catalog/catalog/bundled/software-development/github-pr-workflow/SKILL.md
+93
View File
@@ -0,0 +1,93 @@
---
name: github-pr-workflow
description: Prepare a GitHub pull request from a feature branch — branch hygiene, commit shape, title/body, verification notes, screenshots for UI work, and replies to review comments.
key: paperclipai/bundled/software-development/github-pr-workflow
recommendedForRoles:
- engineer
tags:
- github
- pull-requests
- code-review
- release
---
# GitHub Pull Request Workflow
Ship a PR a reviewer can land without follow-up clarifying questions. The aim is high signal in the title and body, evidence the change works, and clean replies when feedback comes in.
## When to use
- You are about to open a PR for a change that is functionally complete.
- A reviewer left comments and you need to respond and push fixes.
- A PR has been open more than a day and needs to be brought back into shape (stale conflicts, missing description, missing verification).
## When not to use
- The change is not yet functionally complete. Finish the work first; draft PRs that bounce on review are noise.
- The repository uses a non-GitHub forge. Adjust to that forge's conventions; do not force GitHub-isms.
## Branch hygiene before opening
- Rebase or merge from the target base so the diff is current.
- Squash WIP commits into reviewable units. Prefer one commit per logical change; do not force one-commit-per-PR if the work is genuinely multi-step.
- Confirm tests, typecheck, and lint pass locally. Note any deliberate skips in the PR body.
- Remove debug prints, commented-out code, and `TODO` markers that are not tracked.
## PR title
- Imperative mood, under 70 characters.
- Lead with the user-visible change, not the file touched. `Allow CSV export from reports table` beats `Update reports.tsx`.
- If the repo uses an issue prefix convention (`PAP-1234:`, `[security]`), follow it.
- No trailing period.
## PR body
Use this structure:
```md
## Summary
- 1–3 bullets describing what changed and why.
## Implementation notes
- Anything non-obvious in the diff: trade-offs, dropped alternatives, gotchas.
- Migration or config implications.
## Verification
- The exact commands or steps you ran.
- Screenshots or short clips for UI changes (required if pixels moved).
- Edge cases you exercised by hand.
## Risk and rollback
- What breaks if this is reverted, and how to revert cleanly.
```
Skip the `Risk and rollback` section only for clearly trivial PRs (typos, docs).
## Verification evidence
- Tests passing in CI is necessary, not sufficient. Reviewers also need to know the change behaves correctly end to end.
- For UI work, include screenshots of the golden path and one edge case. Tag dark and light mode if the project supports both.
- For migrations, include a dry-run plan and reversal steps.
- For performance changes, include a before/after measurement, not adjectives.
## Replying to review comments
- Reply on every comment, even with just "fixed in <commit-sha>" — silent fixes leave the reviewer guessing.
- Push fixes as new commits while review is active; do not amend during review unless the reviewer agrees.
- If you disagree with feedback, say so with one sentence of rationale and let the reviewer decide. Don't escalate over comments.
- Re-request review explicitly after pushing changes.
## Merge checklist
- All required checks green.
- All review comments resolved.
- PR title/body still accurate (update if scope changed mid-review).
- Linked issue moves to `in_review` or `done` per project convention.
- Delete the branch after merge unless it is a long-lived integration branch.
## Anti-patterns
- PR description that says "see commits". Reviewers should not need to read the log.
- Mixing refactor and behavior change in the same PR with no separation in the body.
- "Address feedback" commits that bundle unrelated edits. One commit per round of feedback is fine; one commit for everything in flight is not.
- Force-pushing during active review without telling the reviewer.
packages/skills-catalog/catalog/optional/browser/agent-browser/SKILL.md
+93
View File
@@ -0,0 +1,93 @@
---
name: agent-browser
description: Drive a real browser to inspect or interact with a web page or app — navigate, take screenshots, read console and network, fill simple forms — for verification tasks, not unattended automation.
key: paperclipai/optional/browser/agent-browser
recommendedForRoles:
- qa
- engineer
- researcher
tags:
- browser
- puppeteer
- playwright
- verification
---
# Agent Browser
Use a controlled browser to verify behavior, capture evidence, or extract information from web pages that a static fetch cannot reach (SPAs, login-gated pages, dynamic content). This skill is about supervised verification, not unattended scraping.
## When to use
- You need a screenshot of a deployed page or a local dev server to confirm a UI change.
- You need to read JavaScript-rendered content that `curl`/`wget` will not see.
- A user reports a UI bug and you need to reproduce it interactively to capture console errors, network requests, or layout state.
- You need to walk through a short flow (load page, click, observe) to verify acceptance criteria.
## When not to use
- The page is reachable as static HTML. Use `curl`/HTTP fetch — it is cheaper, faster, and more reliable.
- The task is unattended large-scale scraping. That belongs to a dedicated scraper with rate limits, robots.txt handling, and a real user agent policy — not this skill.
- The site is behind authentication you do not own credentials for, or whose terms of service prohibit automation.
- The site involves sensitive accounts (banking, healthcare, government) where automation risks lockout or compliance issues.
## Before launching the browser
- Confirm the URL and what state should be true after navigation.
- Decide what evidence is needed: full-page screenshot, viewport screenshot, console log, network trace, HTML snapshot, extracted text.
- Decide the viewport size that matters for the task (mobile vs desktop). Default to a desktop size unless the task is mobile-specific.
- For local dev servers, confirm the server is running and the port is what you expect.
## Driving the browser
A typical verification session:
1. **Launch with a real-looking user agent** when the target is the public internet; an unrealistic UA flags automation traffic.
2. **Set a sane viewport** (e.g., 1366×768 desktop, 390×844 iPhone-ish).
3. **Navigate and wait for the right signal.** Prefer waiting for a specific selector or network-idle over arbitrary sleeps.
4. **Capture evidence immediately** after the wait condition succeeds, before any interaction perturbs the state.
5. **Interact deliberately.** One click at a time, with a wait between actions; re-screenshot after each meaningful state change.
6. **Read the console and network panels** for unexpected errors, 4xx/5xx responses, or slow requests.
7. **Close the browser cleanly** when done. Long-running browser sessions leak memory and hold ports.
## What evidence to record
For a verification task, deliver:
- A full-page or viewport screenshot of each meaningful state.
- The console log, filtered to warnings/errors.
- Any non-2xx network response with the URL, status, and a short response body excerpt.
- A short narration: "Navigated to X, observed Y, clicked Z, observed W."
For a UI bug repro, also record:
- The exact reproduction steps the user can follow.
- Viewport size and (where relevant) device pixel ratio.
- Whether the bug reproduces on first load vs after interaction.
## Login-gated pages
- Prefer programmatic auth (API token, magic link) over UI login.
- If UI login is the only path, the user must provide credentials explicitly for this run. Never reuse credentials outside the session.
- Do not store credentials in the session log, screenshot, or returned output.
## Performance and politeness
- Throttle to one navigation per few seconds when touching shared infra.
- Respect `robots.txt` for public sites you are inspecting at any volume.
- Cancel navigations if a page exceeds a reasonable timeout (e.g., 30s); the page is broken or rate-limiting you.
- Do not retry forever on failure. Retry once with a longer timeout, then escalate.
## Common failure modes
- **Selector not found.** Page changed, or you are waiting before render. Take a screenshot to see actual state; adjust the selector.
- **Click does nothing.** The element is offscreen, covered by a modal, or in a shadow DOM. Scroll into view or pierce the shadow root.
- **Headless detection.** Some sites detect headless Chrome and serve a different page. Use a non-headless mode or a fingerprint-realistic configuration only when authorized.
- **Cross-origin iframe blocking.** Iframes you do not own cannot be inspected; the page must offer the data outside the iframe or the task is infeasible.
## Anti-patterns
- Long unsupervised browser sessions that drift from the original task.
- Scraping behind authentication you do not own.
- Captioning a screenshot with "looks good" without saying what state was loaded and what selectors confirmed it.
- Treating a passing screenshot as proof of correctness across viewports you did not actually test.
packages/skills-catalog/catalog/optional/content/release-announcement/SKILL.md
+128
View File
@@ -0,0 +1,128 @@
---
name: release-announcement
description: Write a release announcement — changelog, blog post, in-app note, or social post — that leads with user impact, names the audience, and includes upgrade/migration steps without filler.
key: paperclipai/optional/content/release-announcement
recommendedForRoles:
- devrel
- product
- writer
tags:
- release
- changelog
- announcement
- communication
---
# Release Announcement
Write the channel-appropriate announcement for a release without churn. Different surfaces need different shapes: a changelog entry is not a blog post is not a social card. The bar is: a reader of the chosen surface can decide in under 30 seconds whether this release affects them, and if so what to do.
## When to use
- A version, feature, or fix is shipping and needs writeup for at least one surface.
- A previously private feature is going GA.
- A breaking change needs broadcast before users hit it.
## When not to use
- An internal-only change with no user impact. Update internal docs; do not announce.
- The release is incomplete (still in active development). Wait until it ships, even if marketing wants the post.
## Determine the audience and channel first
| Audience | Best channel | Tone |
|---|---|---|
| Existing power users | Changelog, in-app note | Terse, factual, links |
| Engineering teams adopting your API | Release notes, dev blog | Examples, migration steps, version pins |
| Prospective customers | Landing page, marketing blog | Story arc, problem → solution, social proof |
| Broad audience | Social post, email newsletter | One-sentence pitch, link to depth |
| Internal team | Slack/Discord post | What changed, who to ping if it breaks |
Pick the audience for *this* writeup. One release often needs several writeups; do not blend them.
## Universal structure
Whatever the channel, lead with:
1. **What changed.** One sentence in the user's vocabulary.
2. **Who it affects.** Which user role / use case.
3. **What to do.** Migrate now / opt-in / no action needed.
Everything else is depth that supports those three.
## Channel templates
### Changelog entry (terse)
```md
## v1.42.0 — 2026-05-26
### Added
- <feature> — <one-line user benefit>. ([#1234](link))
### Changed
- <change> — <one-line impact>. ([#1235](link))
### Fixed
- <bug> — <one-line user-visible symptom>. ([#1236](link))
### Deprecated
- <thing>. Replaced by <thing>. Removal planned for v<x>.
### Breaking
- <change>. **Migration:** <one-line> or <link to guide>.
```
### Release notes (for adopters)
Same as changelog, plus:
- Migration guide section with before/after code.
- Compatibility table (versions, runtimes, OS).
- Known issues and workarounds.
- Acknowledgements (contributors, reporters of fixed bugs).
### Dev blog post (300–800 words)
- **Hook (1 paragraph):** the problem the release solves, in a real-world scenario.
- **What's new (3–5 bullets with sub-paragraphs):** features, with one code or screenshot example each.
- **Upgrade (1 paragraph):** how to upgrade, what to check.
- **What's next:** one sentence about the next direction. Avoid promises.
### In-app note
- 1 sentence.
- 1 link.
- Dismiss after seen.
### Social post
- 1 sentence pitch.
- 1 link.
- 1 image or short clip.
- No threadbait. If it needs a thread, write a blog post instead.
## Writing rules
- Lead with the user, not the team. `You can now export to CSV` beats `We've added CSV export`.
- Numbers beat adjectives. `60% faster cold start` beats `much faster`. Cite the methodology.
- Show, don't just tell. One code snippet, one screenshot — more is noise.
- Date the post. Undated release content rots fastest.
- Link the migration path explicitly. Do not bury it.
- Mark breaking changes with `**Breaking:**` prefix. Repeat in the email/social channel.
## Avoid
- "We are excited to announce" filler.
- Lists of changes that mix user-visible and internal items.
- Marketing claims without a way to verify.
- Promised dates for unshipped work.
- Pre-announcing something the team has not yet committed to ship.
## Post-publish checklist
- Changelog is in source control alongside the release.
- Blog post date matches actual ship date.
- All links work (release tag, PRs, docs sections).
- Breaking changes are also in the upgrade guide, not only the post.
- Internal team is notified before the public post goes live, not after.
packages/skills-catalog/catalog/optional/product/design-critique/SKILL.md
+121
View File
@@ -0,0 +1,121 @@
---
name: design-critique
description: Give a structured product design critique — user job clarity, hierarchy, affordance, error states, accessibility, and consistency — focused on what to change, in what order, and why.
key: paperclipai/optional/product/design-critique
recommendedForRoles:
- designer
- product
- engineer
tags:
- design
- product
- ux
- review
---
# Product Design Critique
A structured critique pass for a screen, flow, or component. The output is a prioritized list of changes a designer or engineer can act on — not adjectives. Critique is not redesign; recommend, do not rebuild.
## When to use
- A designer or engineer asks for feedback on a screen, mock, or live UI.
- A feature is shipping and someone wants a final UX read.
- A flow is suspected of causing user drop-off and you want a pre-research read before instrumentation.
## When not to use
- The user wants a redesign. That is a design project, not a critique.
- The work is so early that no concrete artifact exists. Sketch with them instead of critiquing air.
- You have no context on the user job. Ask for it first; design critique without user context devolves into taste.
## Pre-critique context
Before opening a screen, get:
- **Who is the user.** Specific role and competence, not "users".
- **What job they are doing on this screen.** One sentence.
- **What success looks like.** What the user can do after this screen that they could not before.
- **Where this screen sits in the larger flow.** What precedes and follows.
If any of these is missing, ask. Critique without these is opinion.
## The pass (in order)
1. **Clarity of the user job.**
- Within 3 seconds of opening, is it obvious what this screen is for?
- Does the primary action match the user's actual job, or a designer's preferred path?
2. **Visual hierarchy.**
- The most important thing on the screen should be the most prominent (size, weight, position, color).
- Secondary actions should look secondary. Tertiary should be findable but not loud.
- Headings should chunk content into the right groups for the task.
3. **Affordance and signifiers.**
- Clickable things look clickable.
- Disabled things look disabled and explain why on hover/focus.
- Drag, scroll, or swipe interactions are discoverable, not hidden.
4. **States.**
- Empty state (no data) is designed, not a blank rectangle.
- Loading state communicates progress, not just spins.
- Error states say what went wrong and what to do next, in the user's words.
- Success state confirms without celebrating banal actions.
5. **Inputs and forms.**
- Labels visible, not just placeholders.
- Validation runs at the right time (on blur, not on every keystroke unless the user is in a known-format field).
- Required fields marked.
- Field order matches the user's mental order, not the database order.
6. **Accessibility.**
- Sufficient color contrast (WCAG AA at minimum; AAA where reasonable).
- Focus order is logical for keyboard navigation.
- Interactive elements are reachable without a mouse.
- Critical information is not color-only (icons, text, position back it up).
- Touch targets at least 44×44 px on mobile.
7. **Consistency.**
- Tokens, components, and patterns match the rest of the product.
- "Borrowed" patterns from other products are intentional, not accidental drift.
8. **Copy.**
- Buttons are verbs that name the outcome ("Save changes" beats "Submit").
- Microcopy explains, does not decorate.
- Tone matches the product voice.
9. **Edge cases.**
- Long content (long names, many items, RTL languages).
- Tiny content (one item, zero items).
- Slow network and offline behavior.
- Permissions denied.
## Output format
Group findings by severity, then by category. Each finding is one issue and one suggested fix.
```md
## Design critique: <screen name>
### Must-fix (blocks ship)
- **<category>:** <one-line issue>. **Try:** <one-line suggestion>.
### Should-fix (before broader rollout)
- **<category>:** <one-line issue>. **Try:** <one-line suggestion>.
### Nice-to-fix (when there's room)
- **<category>:** <one-line issue>. **Try:** <one-line suggestion>.
### Strengths to keep
- <one-line thing the design got right>
```
Always include the "strengths to keep" section. It is not flattery — it is signal to the designer about what not to change in the next round.
## Anti-patterns
- "I would do it differently" without saying what or why. That is preference, not critique.
- Long critiques that bury must-fix items under nice-to-haves.
- Suggesting net-new features under the guise of a critique.
- Ignoring user context and grading on taste.
- Treating a critique as approval. State approval explicitly if asked; otherwise critique is feedback, not sign-off.
packages/skills-catalog/generated/catalog.json
+285
View File
@@ -0,0 +1,285 @@
{
"schemaVersion": 1,
"packageName": "@paperclipai/skills-catalog",
"packageVersion": "0.3.1",
"generatedAt": "2026-05-28T03:02:49.579Z",
"skills": [
{
"id": "paperclipai:bundled:docs:doc-maintenance",
"key": "paperclipai/bundled/docs/doc-maintenance",
"kind": "bundled",
"category": "docs",
"slug": "doc-maintenance",
"name": "doc-maintenance",
"description": "Keep project docs aligned with recent code and feature changes — detect drift, update affected pages, and add release-relevant notes without rewriting unchanged sections.",
"path": "catalog/bundled/docs/doc-maintenance",
"entrypoint": "SKILL.md",
"trustLevel": "markdown_only",
"compatibility": "compatible",
"defaultInstall": false,
"recommendedForRoles": [
"engineer",
"product",
"devrel"
],
"requires": [],
"tags": [
"docs",
"documentation",
"release-notes"
],
"files": [
{
"path": "SKILL.md",
"kind": "skill",
"sizeBytes": 4478,
"sha256": "fb0353386c5e5e5e13bcbb3233f044e3dccecf371f429d6328f26c26d7cb6169"
}
],
"contentHash": "sha256:2e02299210fd17c1fe1867b4ee8c144a11b6fe1fe481f83b8268cfbaaf10f9aa"
},
{
"id": "paperclipai:bundled:paperclip-operations:issue-triage",
"key": "paperclipai/bundled/paperclip-operations/issue-triage",
"kind": "bundled",
"category": "paperclip-operations",
"slug": "issue-triage",
"name": "issue-triage",
"description": "Triage Paperclip inbox issues that are stale, blocked, in-review, or assigned-but-not-progressing, and decide a single next action per issue (resume, reassign, unblock, escalate, or close).",
"path": "catalog/bundled/paperclip-operations/issue-triage",
"entrypoint": "SKILL.md",
"trustLevel": "markdown_only",
"compatibility": "compatible",
"defaultInstall": false,
"recommendedForRoles": [
"manager",
"ceo",
"engineer"
],
"requires": [],
"tags": [
"paperclip",
"triage",
"inbox",
"workflow"
],
"files": [
{
"path": "SKILL.md",
"kind": "skill",
"sizeBytes": 4042,
"sha256": "df5bdc8bf5e017b7ba5f70a4b5323fad51d0c323278f386580f26cf43ad09160"
}
],
"contentHash": "sha256:88dc13560371fb364963782cb4f6eeb4090fcde92ee3774479428ed6b90e11c1"
},
{
"id": "paperclipai:bundled:paperclip-operations:task-planning",
"key": "paperclipai/bundled/paperclip-operations/task-planning",
"kind": "bundled",
"category": "paperclip-operations",
"slug": "task-planning",
"name": "task-planning",
"description": "Turn a Paperclip issue or request into a structured implementation plan with child task graph, blockers, owners, and acceptance criteria, then save it as the issue `plan` document.",
"path": "catalog/bundled/paperclip-operations/task-planning",
"entrypoint": "SKILL.md",
"trustLevel": "markdown_only",
"compatibility": "compatible",
"defaultInstall": false,
"recommendedForRoles": [
"manager",
"engineer",
"product"
],
"requires": [],
"tags": [
"paperclip",
"planning",
"issues",
"delegation"
],
"files": [
{
"path": "SKILL.md",
"kind": "skill",
"sizeBytes": 4649,
"sha256": "2ff61e12dfaa4cf8cc548529fd176f55f1b1f5292ff9dd3eb2cb331417ab5e4e"
}
],
"contentHash": "sha256:4fb46a4bcefad4fd46fae48c433ee497112509a8e19fb8a7745ead44d219b498"
},
{
"id": "paperclipai:bundled:quality:qa-acceptance",
"key": "paperclipai/bundled/quality/qa-acceptance",
"kind": "bundled",
"category": "quality",
"slug": "qa-acceptance",
"name": "qa-acceptance",
"description": "Produce QA acceptance criteria and a manual validation plan for a feature change — golden path, edge cases, error states, performance limits, and explicit pass/fail evidence.",
"path": "catalog/bundled/quality/qa-acceptance",
"entrypoint": "SKILL.md",
"trustLevel": "markdown_only",
"compatibility": "compatible",
"defaultInstall": false,
"recommendedForRoles": [
"qa",
"engineer",
"product"
],
"requires": [],
"tags": [
"qa",
"acceptance",
"validation",
"testing"
],
"files": [
{
"path": "SKILL.md",
"kind": "skill",
"sizeBytes": 3861,
"sha256": "c631b437ab26d104af6cdb963d8f679a9341439041b3cb3ec8835f4ff551b378"
}
],
"contentHash": "sha256:32372dacaf62e93454b9855968c4eec96456ba78b509f450b3dfaa48e31ef356"
},
{
"id": "paperclipai:bundled:software-development:github-pr-workflow",
"key": "paperclipai/bundled/software-development/github-pr-workflow",
"kind": "bundled",
"category": "software-development",
"slug": "github-pr-workflow",
"name": "github-pr-workflow",
"description": "Prepare a GitHub pull request from a feature branch — branch hygiene, commit shape, title/body, verification notes, screenshots for UI work, and replies to review comments.",
"path": "catalog/bundled/software-development/github-pr-workflow",
"entrypoint": "SKILL.md",
"trustLevel": "markdown_only",
"compatibility": "compatible",
"defaultInstall": false,
"recommendedForRoles": [
"engineer"
],
"requires": [],
"tags": [
"github",
"pull-requests",
"code-review",
"release"
],
"files": [
{
"path": "SKILL.md",
"kind": "skill",
"sizeBytes": 3970,
"sha256": "f498ec4ebb1779dea37adeb1db8a8b22316282798e35ee02e2fc5ff627d7e261"
}
],
"contentHash": "sha256:90f278c89aa0711be150c1cd2456ca25620d02f36995b113ca9837d756a37f6c"
},
{
"id": "paperclipai:optional:browser:agent-browser",
"key": "paperclipai/optional/browser/agent-browser",
"kind": "optional",
"category": "browser",
"slug": "agent-browser",
"name": "agent-browser",
"description": "Drive a real browser to inspect or interact with a web page or app — navigate, take screenshots, read console and network, fill simple forms — for verification tasks, not unattended automation.",
"path": "catalog/optional/browser/agent-browser",
"entrypoint": "SKILL.md",
"trustLevel": "markdown_only",
"compatibility": "compatible",
"defaultInstall": false,
"recommendedForRoles": [
"qa",
"engineer",
"researcher"
],
"requires": [],
"tags": [
"browser",
"puppeteer",
"playwright",
"verification"
],
"files": [
{
"path": "SKILL.md",
"kind": "skill",
"sizeBytes": 5133,
"sha256": "362f7b9d02297782bc6f0c093f495b8a0304a75bcf4b42e5c280a42b1f757b7d"
}
],
"contentHash": "sha256:eabb2c9f7b5e1a27ebb1e05a711d61433a266478154cd671a685e99e67aadea2"
},
{
"id": "paperclipai:optional:content:release-announcement",
"key": "paperclipai/optional/content/release-announcement",
"kind": "optional",
"category": "content",
"slug": "release-announcement",
"name": "release-announcement",
"description": "Write a release announcement — changelog, blog post, in-app note, or social post — that leads with user impact, names the audience, and includes upgrade/migration steps without filler.",
"path": "catalog/optional/content/release-announcement",
"entrypoint": "SKILL.md",
"trustLevel": "markdown_only",
"compatibility": "compatible",
"defaultInstall": false,
"recommendedForRoles": [
"devrel",
"product",
"writer"
],
"requires": [],
"tags": [
"release",
"changelog",
"announcement",
"communication"
],
"files": [
{
"path": "SKILL.md",
"kind": "skill",
"sizeBytes": 4416,
"sha256": "062810ac34e9edc89efa701fec2eee60f16949d1944cc2cae49803cb91e8cbf4"
}
],
"contentHash": "sha256:f22a9ed696e6614c6db2757a149f48b3295e81f78c27d065d9cb164cf4f8a9bd"
},
{
"id": "paperclipai:optional:product:design-critique",
"key": "paperclipai/optional/product/design-critique",
"kind": "optional",
"category": "product",
"slug": "design-critique",
"name": "design-critique",
"description": "Give a structured product design critique — user job clarity, hierarchy, affordance, error states, accessibility, and consistency — focused on what to change, in what order, and why.",
"path": "catalog/optional/product/design-critique",
"entrypoint": "SKILL.md",
"trustLevel": "markdown_only",
"compatibility": "compatible",
"defaultInstall": false,
"recommendedForRoles": [
"designer",
"product",
"engineer"
],
"requires": [],
"tags": [
"design",
"product",
"ux",
"review"
],
"files": [
{
"path": "SKILL.md",
"kind": "skill",
"sizeBytes": 4851,
"sha256": "022e619baf6cc25725946279cb8052d22af090dd6cd6dc8c20f17867f71a5d8e"
}
],
"contentHash": "sha256:429f94df398a0697042b5bbe4755b1ff1a230aa5f41d99118ad37493ac65d21c"
}
]
}
packages/skills-catalog/package.json
+49
View File
@@ -0,0 +1,49 @@
{
"name": "@paperclipai/skills-catalog",
"version": "0.3.1",
"license": "MIT",
"homepage": "https://github.com/paperclipai/paperclip",
"bugs": {
"url": "https://github.com/paperclipai/paperclip/issues"
},
"repository": {
"type": "git",
"url": "https://github.com/paperclipai/paperclip",
"directory": "packages/skills-catalog"
},
"type": "module",
"exports": {
".": "./src/index.ts",
"./types": "./src/types.ts",
"./catalog.json": "./generated/catalog.json"
},
"publishConfig": {
"access": "public",
"exports": {
".": {
"types": "./dist/src/index.d.ts",
"import": "./dist/src/index.js"
},
"./types": {
"types": "./dist/src/types.d.ts",
"import": "./dist/src/types.js"
},
"./catalog.json": "./dist/generated/catalog.json"
},
"main": "./dist/src/index.js",
"types": "./dist/src/index.d.ts"
},
"files": [
"catalog",
"dist",
"generated"
],
"scripts": {
"build": "pnpm run build:manifest && tsc -p tsconfig.json",
"build:manifest": "node ../../cli/node_modules/tsx/dist/cli.mjs scripts/build-catalog-manifest.ts",
"clean": "rm -rf dist",
"test": "pnpm -w exec vitest run --root packages/skills-catalog --config vitest.config.ts",
"typecheck": "tsc -p tsconfig.json --noEmit",
"validate": "node ../../cli/node_modules/tsx/dist/cli.mjs scripts/validate-catalog.ts"
}
}
packages/skills-catalog/scripts/build-catalog-manifest.ts
+15
View File
@@ -0,0 +1,15 @@
import { fileURLToPath } from "node:url";
import path from "node:path";
import { writeCatalogManifest } from "../src/catalog-builder.js";
const packageDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
const result = await writeCatalogManifest(packageDir);
if (result.errors.length > 0) {
for (const error of result.errors) {
console.error(`- ${error}`);
}
process.exitCode = 1;
} else {
console.log(`Wrote generated/catalog.json with ${result.manifest.skills.length} catalog skills.`);
}
packages/skills-catalog/scripts/validate-catalog.ts
+15
View File
@@ -0,0 +1,15 @@
import { fileURLToPath } from "node:url";
import path from "node:path";
import { validateCatalog } from "../src/catalog-builder.js";
const packageDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
const result = await validateCatalog(packageDir);
if (result.errors.length > 0) {
for (const error of result.errors) {
console.error(`- ${error}`);
}
process.exitCode = 1;
} else {
console.log(`Catalog manifest is valid with ${result.manifest.skills.length} catalog skills.`);
}
packages/skills-catalog/src/catalog-builder.test.ts
+165
View File
@@ -0,0 +1,165 @@
import fs from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { afterEach, describe, expect, it } from "vitest";
import {
buildCatalogManifest,
formatCatalogManifest,
validateCatalog,
} from "./catalog-builder.js";
const tempDirs: string[] = [];
describe("skills catalog manifest", () => {
afterEach(async () => {
await Promise.all(tempDirs.splice(0).map((dir) => fs.rm(dir, { recursive: true, force: true })));
});
it("builds stable manifest entries from catalog skill directories", async () => {
const packageDir = await createCatalogPackage();
await writeSkill(packageDir, "bundled", "software-development", "github-pr-workflow", {
frontmatter: [
"name: GitHub PR Workflow",
"description: Prepare pull requests and verification notes.",
"key: paperclipai/bundled/software-development/github-pr-workflow",
"recommendedForRoles:",
" - engineer",
"tags:",
" - github",
" - pull-requests",
],
files: {
"references/checklist.md": "# Checklist\n",
},
});
const result = await buildCatalogManifest({
packageDir,
generatedAt: "2026-05-26T00:00:00.000Z",
});
expect(result.errors).toEqual([]);
expect(result.manifest.skills).toHaveLength(1);
expect(result.manifest.skills[0]).toMatchObject({
id: "paperclipai:bundled:software-development:github-pr-workflow",
key: "paperclipai/bundled/software-development/github-pr-workflow",
kind: "bundled",
category: "software-development",
slug: "github-pr-workflow",
name: "GitHub PR Workflow",
trustLevel: "markdown_only",
compatibility: "compatible",
recommendedForRoles: ["engineer"],
tags: ["github", "pull-requests"],
});
expect(result.manifest.skills[0]!.files.map((file) => file.path)).toEqual([
"SKILL.md",
"references/checklist.md",
]);
expect(result.manifest.skills[0]!.contentHash).toMatch(/^sha256:[a-f0-9]{64}$/);
});
it("reports frontmatter, directory, uniqueness, and inventory errors together", async () => {
const packageDir = await createCatalogPackage();
await writeSkill(packageDir, "bundled", "Bad_Category", "duplicate", {
frontmatter: [
"name: Duplicate",
"key: paperclipai/bundled/software-development/other",
"recommendedForRoles: engineer",
],
});
await writeSkill(packageDir, "optional", "software-development", "duplicate", {
frontmatter: [
"name: Duplicate Optional",
"description: Optional duplicate slug.",
],
});
await fs.mkdir(path.join(packageDir, "catalog", "bundled", "software-development", "missing-skill"), {
recursive: true,
});
await fs.mkdir(path.join(packageDir, "catalog", "misc"), { recursive: true });
await fs.writeFile(path.join(packageDir, "catalog", "misc", "SKILL.md"), "# Misplaced\n", "utf8");
const result = await buildCatalogManifest({
packageDir,
generatedAt: "2026-05-26T00:00:00.000Z",
});
expect(result.errors).toEqual(
expect.arrayContaining([
expect.stringContaining("catalog/misc/SKILL.md is not under catalog/<bundled|optional>/<category>/<slug>/SKILL.md"),
expect.stringContaining("catalog/bundled/software-development/missing-skill is missing SKILL.md"),
expect.stringContaining("has invalid category"),
expect.stringContaining("frontmatter must include description"),
expect.stringContaining("key must be paperclipai/bundled/Bad_Category/duplicate"),
expect.stringContaining("field recommendedForRoles must be an array of strings"),
expect.stringContaining("Duplicate catalog slug \"duplicate\""),
]),
);
});
it("detects stale generated manifests", async () => {
const packageDir = await createCatalogPackage();
await writeSkill(packageDir, "bundled", "software-development", "review", {
frontmatter: [
"name: Review",
"description: Review implementation work.",
],
});
await fs.mkdir(path.join(packageDir, "generated"), { recursive: true });
await fs.writeFile(
path.join(packageDir, "generated", "catalog.json"),
formatCatalogManifest({
schemaVersion: 1,
packageName: "@paperclipai/skills-catalog",
packageVersion: "0.3.1",
generatedAt: "2026-05-26T00:00:00.000Z",
skills: [],
}),
"utf8",
);
const result = await validateCatalog(packageDir);
expect(result.errors).toContain(
"generated/catalog.json is stale. Run pnpm --filter @paperclipai/skills-catalog build:manifest.",
);
});
});
async function createCatalogPackage() {
const packageDir = await fs.mkdtemp(path.join(os.tmpdir(), "skills-catalog-"));
tempDirs.push(packageDir);
await fs.mkdir(path.join(packageDir, "catalog", "bundled"), { recursive: true });
await fs.mkdir(path.join(packageDir, "catalog", "optional"), { recursive: true });
await fs.writeFile(
path.join(packageDir, "package.json"),
JSON.stringify({ version: "0.3.1" }),
"utf8",
);
return packageDir;
}
async function writeSkill(
packageDir: string,
kind: "bundled" | "optional",
category: string,
slug: string,
options: {
frontmatter: string[];
files?: Record<string, string>;
},
) {
const skillDir = path.join(packageDir, "catalog", kind, category, slug);
await fs.mkdir(skillDir, { recursive: true });
await fs.writeFile(
path.join(skillDir, "SKILL.md"),
`---\n${options.frontmatter.join("\n")}\n---\n\nUse this skill.\n`,
"utf8",
);
for (const [relativePath, content] of Object.entries(options.files ?? {})) {
const filePath = path.join(skillDir, relativePath);
await fs.mkdir(path.dirname(filePath), { recursive: true });
await fs.writeFile(filePath, content, "utf8");
}
}
packages/skills-catalog/src/catalog-builder.ts
+443
View File
@@ -0,0 +1,443 @@
import { createHash } from "node:crypto";
import { existsSync } from "node:fs";
import fs from "node:fs/promises";
import path from "node:path";
import {
asBoolean,
asString,
asStringArray,
parseFrontmatterMarkdown,
} from "./frontmatter.js";
import type {
CatalogManifest,
CatalogSkill,
CatalogSkillFile,
CatalogSkillFileKind,
CatalogSkillKind,
CatalogTrustLevel,
} from "./types.js";
const CATALOG_PACKAGE_NAME = "@paperclipai/skills-catalog";
const CATALOG_SCHEMA_VERSION = 1;
const SKILL_ENTRYPOINT = "SKILL.md";
const MAX_CATALOG_FILE_BYTES = 1024 * 1024;
const SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
const CATALOG_KINDS = new Set<CatalogSkillKind>(["bundled", "optional"]);
interface SkillCandidate {
kind: CatalogSkillKind;
category: string;
slug: string;
absolutePath: string;
}
interface BuildCatalogManifestOptions {
packageDir: string;
generatedAt?: string;
}
interface BuildCatalogManifestResult {
manifest: CatalogManifest;
errors: string[];
}
export function formatCatalogManifest(manifest: CatalogManifest): string {
return `${JSON.stringify(manifest, null, 2)}\n`;
}
export async function buildExpectedCatalogManifest(
packageDir: string,
): Promise<BuildCatalogManifestResult> {
const existing = await readExistingManifest(packageDir);
const firstPass = await buildCatalogManifest({
packageDir,
generatedAt: existing?.generatedAt ?? new Date().toISOString(),
});
if (existing && sameManifestExceptGeneratedAt(existing, firstPass.manifest)) {
return firstPass;
}
return buildCatalogManifest({
packageDir,
generatedAt: new Date().toISOString(),
});
}
export async function buildCatalogManifest(
options: BuildCatalogManifestOptions,
): Promise<BuildCatalogManifestResult> {
const packageDir = path.resolve(options.packageDir);
const packageJson = await readPackageJson(packageDir);
const errors: string[] = [];
const candidates = await discoverSkillCandidates(packageDir, errors);
const skills: CatalogSkill[] = [];
collectCandidateUniquenessErrors(candidates, errors);
for (const candidate of candidates) {
const skill = await buildCatalogSkill(packageDir, candidate, errors);
if (skill) skills.push(skill);
}
skills.sort((a, b) => a.id.localeCompare(b.id));
collectUniquenessErrors(skills, errors);
return {
manifest: {
schemaVersion: CATALOG_SCHEMA_VERSION,
packageName: CATALOG_PACKAGE_NAME,
packageVersion: packageJson.version,
generatedAt: options.generatedAt ?? new Date().toISOString(),
skills,
},
errors,
};
}
export async function validateCatalog(packageDir: string): Promise<BuildCatalogManifestResult> {
const expected = await buildExpectedCatalogManifest(packageDir);
const generatedPath = path.join(packageDir, "generated", "catalog.json");
const errors = [...expected.errors];
let generatedText: string | null = null;
try {
generatedText = await fs.readFile(generatedPath, "utf8");
JSON.parse(generatedText);
} catch (error) {
errors.push(`generated/catalog.json is missing or invalid: ${errorMessage(error)}`);
}
if (generatedText !== null) {
const expectedText = formatCatalogManifest(expected.manifest);
if (generatedText !== expectedText) {
errors.push("generated/catalog.json is stale. Run pnpm --filter @paperclipai/skills-catalog build:manifest.");
}
}
return {
manifest: expected.manifest,
errors,
};
}
export async function writeCatalogManifest(packageDir: string) {
const result = await buildExpectedCatalogManifest(packageDir);
if (result.errors.length > 0) return result;
const generatedDir = path.join(packageDir, "generated");
await fs.mkdir(generatedDir, { recursive: true });
await fs.writeFile(path.join(generatedDir, "catalog.json"), formatCatalogManifest(result.manifest), "utf8");
return result;
}
async function readPackageJson(packageDir: string) {
const packageJsonPath = path.join(packageDir, "package.json");
const packageJson = JSON.parse(await fs.readFile(packageJsonPath, "utf8")) as { version?: unknown };
const version = asString(packageJson.version);
if (!version) throw new Error(`${packageJsonPath} must declare a package version.`);
return { version };
}
async function readExistingManifest(packageDir: string): Promise<CatalogManifest | null> {
try {
return JSON.parse(await fs.readFile(path.join(packageDir, "generated", "catalog.json"), "utf8")) as CatalogManifest;
} catch {
return null;
}
}
async function discoverSkillCandidates(packageDir: string, errors: string[]) {
const catalogDir = path.join(packageDir, "catalog");
const candidates: SkillCandidate[] = [];
if (!existsSync(catalogDir)) {
errors.push("catalog directory is missing.");
return candidates;
}
await collectMisplacedSkillFiles(catalogDir, errors);
for (const kind of ["bundled", "optional"] as const) {
const kindDir = path.join(catalogDir, kind);
if (!existsSync(kindDir)) continue;
for (const categoryEntry of await sortedDirEntries(kindDir)) {
if (!categoryEntry.isDirectory()) continue;
const category = categoryEntry.name;
const categoryDir = path.join(kindDir, category);
for (const slugEntry of await sortedDirEntries(categoryDir)) {
if (!slugEntry.isDirectory()) continue;
const slug = slugEntry.name;
const skillDir = path.join(categoryDir, slug);
if (!existsSync(path.join(skillDir, SKILL_ENTRYPOINT))) {
errors.push(`${relativePackagePath(packageDir, skillDir)} is missing SKILL.md.`);
continue;
}
candidates.push({ kind, category, slug, absolutePath: skillDir });
}
}
}
return candidates;
}
async function collectMisplacedSkillFiles(catalogDir: string, errors: string[]) {
async function visit(dir: string) {
for (const entry of await sortedDirEntries(dir)) {
const absolutePath = path.join(dir, entry.name);
if (entry.isDirectory()) {
await visit(absolutePath);
continue;
}
if (entry.name !== SKILL_ENTRYPOINT) continue;
const relativePath = toPosixPath(path.relative(catalogDir, absolutePath));
const parts = relativePath.split("/");
const kind = parts[0];
if (parts.length !== 4 || !CATALOG_KINDS.has(kind as CatalogSkillKind)) {
errors.push(`catalog/${relativePath} is not under catalog/<bundled|optional>/<category>/<slug>/SKILL.md.`);
}
}
}
await visit(catalogDir);
}
async function buildCatalogSkill(
packageDir: string,
candidate: SkillCandidate,
errors: string[],
): Promise<CatalogSkill | null> {
const prefix = relativePackagePath(packageDir, candidate.absolutePath);
validateSlug("category", candidate.category, prefix, errors);
validateSlug("slug", candidate.slug, prefix, errors);
const id = `paperclipai:${candidate.kind}:${candidate.category}:${candidate.slug}`;
const key = `paperclipai/${candidate.kind}/${candidate.category}/${candidate.slug}`;
const skillMarkdownPath = path.join(candidate.absolutePath, SKILL_ENTRYPOINT);
const parsed = parseFrontmatterMarkdown(await fs.readFile(skillMarkdownPath, "utf8"));
if (!parsed.hasFrontmatter) {
errors.push(`${prefix}/SKILL.md must start with YAML frontmatter.`);
}
const name = asString(parsed.frontmatter.name);
if (!name) errors.push(`${prefix}/SKILL.md frontmatter must include name.`);
const description = asString(parsed.frontmatter.description);
if (!description) errors.push(`${prefix}/SKILL.md frontmatter must include description.`);
const explicitKey = asString(parsed.frontmatter.key);
if (explicitKey && explicitKey !== key) {
errors.push(`${prefix}/SKILL.md key must be ${key}.`);
}
const explicitSlug = asString(parsed.frontmatter.slug);
if (explicitSlug && explicitSlug !== candidate.slug) {
errors.push(`${prefix}/SKILL.md slug must be ${candidate.slug}.`);
}
const defaultInstall = asBoolean(parsed.frontmatter.defaultInstall) ?? false;
const recommendedForRoles = readStringArrayField(parsed.frontmatter.recommendedForRoles, "recommendedForRoles", prefix, errors);
const requires = readStringArrayField(parsed.frontmatter.requires, "requires", prefix, errors);
const tags = readStringArrayField(parsed.frontmatter.tags, "tags", prefix, errors);
const files = await collectSkillFiles(packageDir, candidate.absolutePath, prefix, errors);
if (!name || !description) return null;
return {
id,
key,
kind: candidate.kind,
category: candidate.category,
slug: candidate.slug,
name,
description,
path: toPosixPath(path.relative(packageDir, candidate.absolutePath)),
entrypoint: SKILL_ENTRYPOINT,
trustLevel: deriveTrustLevel(files),
compatibility: "compatible",
defaultInstall,
recommendedForRoles,
requires,
tags,
files,
contentHash: buildContentHash(files),
};
}
async function collectSkillFiles(
packageDir: string,
skillDir: string,
prefix: string,
errors: string[],
): Promise<CatalogSkillFile[]> {
const files: CatalogSkillFile[] = [];
const skillRoot = await fs.realpath(skillDir);
async function visit(dir: string) {
for (const entry of await sortedDirEntries(dir)) {
const absolutePath = path.join(dir, entry.name);
const lstat = await fs.lstat(absolutePath);
let stat = lstat;
let realPath = absolutePath;
if (lstat.isSymbolicLink()) {
try {
realPath = await fs.realpath(absolutePath);
stat = await fs.stat(absolutePath);
} catch {
errors.push(`${relativePackagePath(packageDir, absolutePath)} is a broken symlink.`);
continue;
}
if (!isPathInside(skillRoot, realPath)) {
errors.push(`${relativePackagePath(packageDir, absolutePath)} points outside its skill directory.`);
continue;
}
if (stat.isDirectory()) {
errors.push(`${relativePackagePath(packageDir, absolutePath)} is a directory symlink; copy files into the skill directory instead.`);
continue;
}
}
if (stat.isDirectory()) {
await visit(absolutePath);
continue;
}
if (!stat.isFile()) continue;
const relativePath = toPosixPath(path.relative(skillDir, absolutePath));
if (path.isAbsolute(relativePath) || relativePath.split("/").includes("..")) {
errors.push(`${prefix}/${relativePath} has an invalid inventory path.`);
continue;
}
if (stat.size > MAX_CATALOG_FILE_BYTES) {
errors.push(`${prefix}/${relativePath} exceeds ${MAX_CATALOG_FILE_BYTES} bytes.`);
}
const contents = await fs.readFile(absolutePath);
files.push({
path: relativePath,
kind: classifyCatalogFile(relativePath),
sizeBytes: stat.size,
sha256: sha256(contents),
});
}
}
await visit(skillDir);
files.sort((a, b) => {
if (a.path === SKILL_ENTRYPOINT) return -1;
if (b.path === SKILL_ENTRYPOINT) return 1;
return a.path.localeCompare(b.path);
});
if (!files.some((file) => file.path === SKILL_ENTRYPOINT && file.kind === "skill")) {
errors.push(`${prefix} inventory does not contain SKILL.md.`);
}
return files;
}
function readStringArrayField(
value: unknown,
field: string,
prefix: string,
errors: string[],
) {
const parsed = asStringArray(value);
if (!parsed) {
errors.push(`${prefix}/SKILL.md frontmatter field ${field} must be an array of strings.`);
return [];
}
return parsed;
}
function classifyCatalogFile(relativePath: string): CatalogSkillFileKind {
if (relativePath === SKILL_ENTRYPOINT) return "skill";
if (relativePath.startsWith("references/")) return "reference";
if (relativePath.startsWith("scripts/")) return "script";
if (relativePath.startsWith("assets/")) return "asset";
if (relativePath.endsWith(".md") || relativePath.endsWith(".mdx")) return "markdown";
return "other";
}
function deriveTrustLevel(files: CatalogSkillFile[]): CatalogTrustLevel {
if (files.some((file) => file.kind === "script")) return "scripts_executables";
if (files.some((file) => file.kind === "asset" || file.kind === "other")) return "assets";
return "markdown_only";
}
function buildContentHash(files: CatalogSkillFile[]) {
const hashInput = files.map((file) => ({
path: file.path,
sha256: file.sha256,
}));
return `sha256:${sha256(Buffer.from(JSON.stringify(hashInput)))}`;
}
function collectUniquenessErrors(skills: CatalogSkill[], errors: string[]) {
collectDuplicateErrors(skills, "id", errors);
collectDuplicateErrors(skills, "key", errors);
collectDuplicateErrors(skills, "slug", errors);
}
function collectCandidateUniquenessErrors(candidates: SkillCandidate[], errors: string[]) {
const projected = candidates.map((candidate) => ({
id: `paperclipai:${candidate.kind}:${candidate.category}:${candidate.slug}`,
key: `paperclipai/${candidate.kind}/${candidate.category}/${candidate.slug}`,
slug: candidate.slug,
path: toPosixPath(path.join("catalog", candidate.kind, candidate.category, candidate.slug)),
})) as CatalogSkill[];
collectUniquenessErrors(projected, errors);
}
function collectDuplicateErrors(fieldSkills: CatalogSkill[], field: "id" | "key" | "slug", errors: string[]) {
const seen = new Map<string, string>();
for (const skill of fieldSkills) {
const value = skill[field];
const first = seen.get(value);
if (first) {
errors.push(`Duplicate catalog ${field} "${value}" in ${first} and ${skill.path}.`);
continue;
}
seen.set(value, skill.path);
}
}
function validateSlug(label: string, value: string, prefix: string, errors: string[]) {
if (!SLUG_PATTERN.test(value)) {
errors.push(`${prefix} has invalid ${label} "${value}"; use lowercase URL slugs.`);
}
}
async function sortedDirEntries(dir: string) {
return (await fs.readdir(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
}
function sameManifestExceptGeneratedAt(a: CatalogManifest, b: CatalogManifest) {
return JSON.stringify({ ...a, generatedAt: "" }) === JSON.stringify({ ...b, generatedAt: "" });
}
function sha256(contents: Buffer) {
return createHash("sha256").update(contents).digest("hex");
}
function relativePackagePath(packageDir: string, absolutePath: string) {
return toPosixPath(path.relative(packageDir, absolutePath));
}
function toPosixPath(input: string) {
return input.split(path.sep).join("/");
}
function isPathInside(parent: string, child: string) {
const relativePath = path.relative(parent, child);
return relativePath === "" || (!relativePath.startsWith("..") && !path.isAbsolute(relativePath));
}
function errorMessage(error: unknown) {
return error instanceof Error ? error.message : String(error);
}
packages/skills-catalog/src/frontmatter.ts
+154
View File
@@ -0,0 +1,154 @@
export interface MarkdownDoc {
frontmatter: Record<string, unknown>;
body: string;
hasFrontmatter: boolean;
}
export function isPlainRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value);
}
export function asString(value: unknown): string | null {
if (typeof value !== "string") return null;
const trimmed = value.trim();
return trimmed.length > 0 ? trimmed : null;
}
export function asBoolean(value: unknown): boolean | null {
return typeof value === "boolean" ? value : null;
}
export function asStringArray(value: unknown): string[] | null {
if (value === undefined) return [];
if (!Array.isArray(value)) return null;
const out: string[] = [];
for (const item of value) {
const text = asString(item);
if (!text) return null;
out.push(text);
}
return out;
}
export function parseFrontmatterMarkdown(raw: string): MarkdownDoc {
const normalized = raw.replace(/\r\n/g, "\n");
if (!normalized.startsWith("---\n")) {
return { frontmatter: {}, body: normalized.trim(), hasFrontmatter: false };
}
const closing = normalized.indexOf("\n---\n", 4);
if (closing < 0) {
return { frontmatter: {}, body: normalized.trim(), hasFrontmatter: false };
}
const frontmatterRaw = normalized.slice(4, closing).trim();
const body = normalized.slice(closing + 5).trim();
return {
frontmatter: parseYamlFrontmatter(frontmatterRaw),
body,
hasFrontmatter: true,
};
}
function parseYamlFrontmatter(raw: string): Record<string, unknown> {
const prepared = prepareYamlLines(raw);
if (prepared.length === 0) return {};
const parsed = parseYamlBlock(prepared, 0, prepared[0]!.indent);
return isPlainRecord(parsed.value) ? parsed.value : {};
}
function prepareYamlLines(raw: string) {
return raw
.split("\n")
.map((line) => ({
indent: line.match(/^ */)?.[0].length ?? 0,
content: line.trim(),
}))
.filter((line) => line.content.length > 0 && !line.content.startsWith("#"));
}
function parseYamlBlock(
lines: Array<{ indent: number; content: string }>,
startIndex: number,
indentLevel: number,
): { value: unknown; nextIndex: number } {
let index = startIndex;
if (index >= lines.length || lines[index]!.indent < indentLevel) {
return { value: {}, nextIndex: index };
}
const isArray = lines[index]!.indent === indentLevel && lines[index]!.content.startsWith("-");
if (isArray) {
const values: unknown[] = [];
while (index < lines.length) {
const line = lines[index]!;
if (line.indent < indentLevel) break;
if (line.indent !== indentLevel || !line.content.startsWith("-")) break;
const remainder = line.content.slice(1).trim();
index += 1;
if (!remainder) {
const nested = parseYamlBlock(lines, index, indentLevel + 2);
values.push(nested.value);
index = nested.nextIndex;
continue;
}
values.push(parseYamlScalar(remainder));
}
return { value: values, nextIndex: index };
}
const record: Record<string, unknown> = {};
while (index < lines.length) {
const line = lines[index]!;
if (line.indent < indentLevel) break;
if (line.indent !== indentLevel) {
index += 1;
continue;
}
const separatorIndex = line.content.indexOf(":");
if (separatorIndex <= 0) {
index += 1;
continue;
}
const key = line.content.slice(0, separatorIndex).trim();
const remainder = line.content.slice(separatorIndex + 1).trim();
index += 1;
if (!remainder) {
const nested = parseYamlBlock(lines, index, indentLevel + 2);
record[key] = nested.value;
index = nested.nextIndex;
continue;
}
record[key] = parseYamlScalar(remainder);
}
return { value: record, nextIndex: index };
}
function parseYamlScalar(rawValue: string): unknown {
const trimmed = rawValue.trim();
if (trimmed === "") return "";
if (trimmed === "null" || trimmed === "~") return null;
if (trimmed === "true") return true;
if (trimmed === "false") return false;
if (trimmed === "[]") return [];
if (trimmed === "{}") return {};
if (/^-?\d+(\.\d+)?$/.test(trimmed)) return Number(trimmed);
if (
trimmed.startsWith("\"") ||
trimmed.startsWith("[") ||
trimmed.startsWith("{")
) {
try {
return JSON.parse(trimmed);
} catch {
return trimmed;
}
}
return trimmed;
}
packages/skills-catalog/src/index.ts
+37
View File
@@ -0,0 +1,37 @@
import catalogManifestJson from "../generated/catalog.json" with { type: "json" };
import type { CatalogManifest, CatalogSkill } from "./types.js";
export type {
CatalogCompatibility,
CatalogManifest,
CatalogSkill,
CatalogSkillFile,
CatalogSkillFileKind,
CatalogSkillKind,
CatalogTrustLevel,
CatalogValidationResult,
} from "./types.js";
export const catalogManifest = catalogManifestJson as CatalogManifest;
export const catalogSkills: CatalogSkill[] = catalogManifest.skills;
const skillsById = new Map(catalogSkills.map((skill) => [skill.id, skill]));
const skillsByKey = new Map(catalogSkills.map((skill) => [skill.key, skill]));
export function getCatalogSkill(id: string): CatalogSkill | null {
return skillsById.get(id) ?? null;
}
export function resolveCatalogSkillRef(ref: string): CatalogSkill | null {
const normalized = ref.trim();
if (normalized.length === 0) return null;
const exactMatch = skillsById.get(normalized) ?? skillsByKey.get(normalized);
if (exactMatch) return exactMatch;
const slugMatches = catalogSkills.filter((skill) => skill.slug === normalized);
if (slugMatches.length === 1) return slugMatches[0]!;
return null;
}
packages/skills-catalog/src/shipped-catalog.test.ts
+90
View File
@@ -0,0 +1,90 @@
import { describe, expect, it } from "vitest";
import { catalogManifest, catalogSkills, resolveCatalogSkillRef } from "./index.js";
import type { CatalogSkill } from "./types.js";
const EXPECTED_BUNDLED_KEYS = [
"paperclipai/bundled/docs/doc-maintenance",
"paperclipai/bundled/paperclip-operations/issue-triage",
"paperclipai/bundled/paperclip-operations/task-planning",
"paperclipai/bundled/quality/qa-acceptance",
"paperclipai/bundled/software-development/github-pr-workflow",
];
const EXPECTED_OPTIONAL_KEYS = [
"paperclipai/optional/browser/agent-browser",
"paperclipai/optional/content/release-announcement",
"paperclipai/optional/product/design-critique",
];
describe("shipped skills catalog", () => {
it("ships the expected bundled and optional skill set", () => {
const bundledKeys = catalogSkills
.filter((skill) => skill.kind === "bundled")
.map((skill) => skill.key)
.sort();
const optionalKeys = catalogSkills
.filter((skill) => skill.kind === "optional")
.map((skill) => skill.key)
.sort();
expect(bundledKeys).toEqual(EXPECTED_BUNDLED_KEYS);
expect(optionalKeys).toEqual(EXPECTED_OPTIONAL_KEYS);
});
it("keeps every shipped skill markdown-only until a script-bearing skill clears security review", () => {
const scriptBearing = catalogSkills.filter((skill) => skill.trustLevel !== "markdown_only");
expect(scriptBearing, formatViolations("script-bearing skills require security review", scriptBearing)).toEqual([]);
});
it("populates browse/search-relevant fields for every shipped skill", () => {
const issues: string[] = [];
for (const skill of catalogSkills) {
if (skill.compatibility !== "compatible") {
issues.push(`${skill.key} compatibility=${skill.compatibility}`);
}
if (!skill.description || skill.description.length < 40) {
issues.push(`${skill.key} description must be at least 40 characters for catalog browse/search`);
}
if (skill.recommendedForRoles.length === 0) {
issues.push(`${skill.key} must list recommendedForRoles`);
}
if (skill.tags.length === 0) {
issues.push(`${skill.key} must list tags`);
}
}
expect(issues).toEqual([]);
});
it("uses canonical paperclipai keys derived from kind/category/slug", () => {
const violations: string[] = [];
for (const skill of catalogSkills) {
const expectedKey = `paperclipai/${skill.kind}/${skill.category}/${skill.slug}`;
const expectedId = `paperclipai:${skill.kind}:${skill.category}:${skill.slug}`;
if (skill.key !== expectedKey) violations.push(`${skill.key} should be ${expectedKey}`);
if (skill.id !== expectedId) violations.push(`${skill.id} should be ${expectedId}`);
}
expect(violations).toEqual([]);
});
it("exposes a stable manifest header for downstream consumers", () => {
expect(catalogManifest.schemaVersion).toBe(1);
expect(catalogManifest.packageName).toBe("@paperclipai/skills-catalog");
expect(catalogSkills.length).toBe(EXPECTED_BUNDLED_KEYS.length + EXPECTED_OPTIONAL_KEYS.length);
});
it("resolves shipped skills by id, key, and unique slug", () => {
const sample = catalogSkills.find((skill) => skill.key === "paperclipai/bundled/software-development/github-pr-workflow");
expect(sample, "expected github-pr-workflow to ship in the bundled catalog").toBeDefined();
if (!sample) return;
expect(resolveCatalogSkillRef(sample.id)).toMatchObject({ key: sample.key });
expect(resolveCatalogSkillRef(sample.key)).toMatchObject({ key: sample.key });
expect(resolveCatalogSkillRef(sample.slug)).toMatchObject({ key: sample.key });
});
});
function formatViolations(label: string, skills: CatalogSkill[]) {
if (skills.length === 0) return label;
const detail = skills.map((skill) => `${skill.key} (${skill.trustLevel})`).join(", ");
return `${label}: ${detail}`;
}
packages/skills-catalog/src/types.ts
+48
View File
@@ -0,0 +1,48 @@
export type CatalogSkillKind = "bundled" | "optional";
export type CatalogTrustLevel = "markdown_only" | "assets" | "scripts_executables";
export type CatalogCompatibility = "compatible" | "unknown" | "invalid";
export type CatalogSkillFileKind = "skill" | "markdown" | "reference" | "script" | "asset" | "other";
export interface CatalogSkillFile {
path: string;
kind: CatalogSkillFileKind;
sizeBytes: number;
sha256: string;
}
export interface CatalogSkill {
id: string;
key: string;
kind: CatalogSkillKind;
category: string;
slug: string;
name: string;
description: string;
path: string;
entrypoint: "SKILL.md";
trustLevel: CatalogTrustLevel;
compatibility: CatalogCompatibility;
defaultInstall: boolean;
recommendedForRoles: string[];
requires: string[];
tags: string[];
files: CatalogSkillFile[];
contentHash: string;
}
export interface CatalogManifest {
schemaVersion: 1;
packageName: "@paperclipai/skills-catalog";
packageVersion: string;
generatedAt: string;
skills: CatalogSkill[];
}
export interface CatalogValidationResult {
valid: boolean;
errors: string[];
manifest: CatalogManifest;
}
packages/skills-catalog/tsconfig.json
+8
View File
@@ -0,0 +1,8 @@
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"outDir": "dist",
"rootDir": "."
},
"include": ["generated/**/*.json", "scripts/**/*.ts", "src/**/*.ts"]
}
packages/skills-catalog/vitest.config.ts
+8
View File
@@ -0,0 +1,8 @@
import { defineConfig } from "vitest/config";
export default defineConfig({
test: {
environment: "node",
include: ["src/**/*.test.ts"],
},
});
releases/v2026.525.0.md
+44
View File
@@ -0,0 +1,44 @@
# v2026.525.0
> Released: 2026-05-25
## Highlights
- **Modal sandbox provider is now a first-party plugin** - Paperclip ships a Modal sandbox-provider plugin so companies can run agents on Modal's managed sandboxes alongside E2B, Cloudflare, and Daytona, with CI publishing and cold-start-friendly probe timeouts wired in. ([#6245](https://github.com/paperclipai/paperclip/pull/6245), [#6289](https://github.com/paperclipai/paperclip/pull/6289), [#6290](https://github.com/paperclipai/paperclip/pull/6290), @devinfoley)
- **Workspace diffs are a first-class viewer plugin** - The new workspace diff plugin renders staged, unstaged, head, renamed, binary, oversized, and untracked changes through host services and plugin slots, with split/unified panes, sticky headers, and reliable default base refs. ([#6071](https://github.com/paperclipai/paperclip/pull/6071), [#6383](https://github.com/paperclipai/paperclip/pull/6383), @cryppadotta)
- **Routines can carry their own secrets** - Routine env now flows through the runtime contract with persisted revisions, `agent < project < routine` precedence, and safe secret metadata in routine UI/history — without exposing secret values in logs or access events. ([#6212](https://github.com/paperclipai/paperclip/pull/6212), @cryppadotta)
- **Local Cloud Upstream sync is in** - A new Cloud Upstream flow ships with shared types, server routes, persisted run schema, CLI sync helpers, a board UI, and settings entry points so operators can preview, resolve conflicts, and activate local-to-cloud syncs. ([#6548](https://github.com/paperclipai/paperclip/pull/6548), @cryppadotta)
- **ACPX-Claude adapter works seamlessly out of the box** - The `acpx_local` adapter now resolves bare Claude model IDs, surfaces real diagnostic detail instead of opaque "Internal error" logs, and respects user `~/.claude/settings.json` permissions so first-run Claude Local ACPX agents don't strand. ([#6590](https://github.com/paperclipai/paperclip/pull/6590), @devinfoley)
## Improvements
- **Scoped agent permissions and assignment controls** - Issue and agent assignment mutations now run through a real authorization service with protected-assignment enforcement, plugin SDK/host APIs for company settings slots and policy/grant management, retry-now affordances on blocked issues, and an incremental principal-access compatibility backfill. ([#6386](https://github.com/paperclipai/paperclip/pull/6386), @cryppadotta)
- **AWS provider vault setup is operator-friendly** - The Secrets page now offers AWS provider vault discovery with prefill, removal flows, and Storybook coverage so external vault configuration no longer requires hand-typed metadata. ([#6381](https://github.com/paperclipai/paperclip/pull/6381), @cryppadotta)
- **SecretBindingPicker is wired into plugin config forms** - JSON-schema secret-ref fields (E2B, Modal, Cloudflare, Daytona, …) now render the canonical secret picker instead of a plain password input, so binding stored secrets no longer requires copy-pasting UUIDs. ([#6339](https://github.com/paperclipai/paperclip/pull/6339), @devinfoley)
- **External agent invites moved into the add-agent modal** - Bring-your-own-agent onboarding now lives next to local/managed agent creation with an agent-oriented prompt result view and Back navigation, instead of hiding behind OpenClaw-specific company invite settings. ([#6183](https://github.com/paperclipai/paperclip/pull/6183), @aronprins)
- **Mobile board flows feel smoother** - Mobile new-issue dialog height, priority overflow, company settings nav, plugin-route sidebar selection, browser controls in home-screen app mode, and small touch-target/menu scroll bugs are all polished. ([#6550](https://github.com/paperclipai/paperclip/pull/6550), [#6384](https://github.com/paperclipai/paperclip/pull/6384), @cryppadotta)
- **Plugin runtime is scoped tighter to its company** - Plugin worker-to-host calls now propagate host-owned invocation context, `performAction` carries authenticated actor context, company invocation scope is enforced on bridge calls, and plugin operation issues stay out of normal issue surfaces. ([#6547](https://github.com/paperclipai/paperclip/pull/6547), @cryppadotta)
- **Runtime and tenant import paths are more reliable** - Embedded Postgres now bootstraps native runtime before CLI/server/test startup, async tenant import jobs have deferred validation, and trusted Cloud tenant imports no longer fail the browser-origin guard for legitimate server-to-server traffic. ([#6549](https://github.com/paperclipai/paperclip/pull/6549), [#6378](https://github.com/paperclipai/paperclip/pull/6378), @cryppadotta)
- **Control-plane state transitions are tighter** - Pagination sorts cleanly on updated issue lists, scheduled retry comments behave, pending plugin migrations re-apply on hot reload, plugin-schema worktree seeds restore safely, stale request confirmations expire after user comments, and feedback export shutdown drains without database-unavailable loops. ([#6380](https://github.com/paperclipai/paperclip/pull/6380), @cryppadotta)
- **Cheap recovery model is fenced off from real work** - Status-only recovery now carries explicit guard context, route guards block deliverable mutations during cheap runs, and cheap-profile hints no longer leak into normal source-work retries. ([#6371](https://github.com/paperclipai/paperclip/pull/6371), @cryppadotta)
- **Invite flow, projects, and workspace polish from the May 17 branch land** - Invite landing reuses the shared companies query helper, existing-member invite behavior and copy fallback are restored, reusable workspace selection picks correctly, worktree auth and static SPA fallback are fixed, markdown wrapping and plugin slot registration are firmed up, and projects page sorting lands. ([#6604](https://github.com/paperclipai/paperclip/pull/6604), [#6210](https://github.com/paperclipai/paperclip/pull/6210), @cryppadotta)
- **Sandbox-provider plugins no longer clutter Instance Settings** - Driver-only plugins (E2B, exe.dev, Modal) are hidden from the per-plugin sidebar group since they have no own settings page and already redirect to Environments. ([#6341](https://github.com/paperclipai/paperclip/pull/6341), @devinfoley)
- **Inbox rows are cleaner** - The amber "Planning" pill is removed from `IssueRow`; planning mode itself, the composer toggle, and the work-mode contract are untouched. ([#6269](https://github.com/paperclipai/paperclip/pull/6269), @cryppadotta)
- **Plugin authoring guide reflects managed resources** - The plugin authoring docs are updated for the current managed-capabilities model so plugin authors aren't writing against stale guidance. ([#6261](https://github.com/paperclipai/paperclip/pull/6261), @cryppadotta)
## Fixes
- **E2B heartbeats stop failing at 5/11 minutes** - The workspace tar upload now strips macOS `LIBARCHIVE.xattr.*` PAX headers that GNU tar rejected on Linux, and `timeoutMs`/`sleepAfter` are refreshed per execute so E2B and Cloudflare sandboxes don't expire between heartbeats. ([#6560](https://github.com/paperclipai/paperclip/pull/6560), @devinfoley)
- **Invite page no longer goes blank after sign-in** - `CompanyProvider` and the invite landing page now share a single companies query shape, fixing the `companiesQuery.data?.some is not a function` crash from the React Query key-key collision. ([#6433](https://github.com/paperclipai/paperclip/pull/6433), @aronprins)
- **Company creation survives wrapped prefix collisions** - The retry detector now walks the Drizzle 0.45.x error cause chain for the `companies_issue_prefix_idx` unique constraint, so generated-prefix collisions retry instead of 500-ing. ([#6423](https://github.com/paperclipai/paperclip/pull/6423), @aronprins)
- **Autocomplete works inside the new-issue dialog** - Floating autocomplete menus rendered through body-level portals are now marked as allowed dialog-external UI, so completion items are selectable inside Radix Dialog without pointer events being eaten. ([#6311](https://github.com/paperclipai/paperclip/pull/6311), @cryppadotta)
- **`paperclip worktree init --force` no longer wipes `<repo>/.paperclip/worktrees/`** - The init path stopped recursively removing the whole `<repo>/.paperclip/` directory and now only rewrites `config.json` and `.env`. ([#6240](https://github.com/paperclipai/paperclip/pull/6240), @devinfoley)
- **New secret form stays usable with long values** - The shared `Textarea` primitive now applies `min-w-0 max-w-full`, so a long unbreakable secret no longer pushes the Create/Cancel buttons off-screen. ([#6222](https://github.com/paperclipai/paperclip/pull/6222), @devinfoley)
- **Cold-start sandbox probes no longer time out** - `environmentProbe` worker RPC timeout is raised to 120s so Modal (and other cold-start providers) finish booting before the probe fails. ([#6289](https://github.com/paperclipai/paperclip/pull/6289), @devinfoley)
- **Docker builds find `link-plugin-dev-sdk.mjs`** - The Dockerfile `deps` stage now copies the script before `pnpm install`, so the `plugin-workspace-diff` postinstall hook doesn't fail with `Cannot find module`. ([#6338](https://github.com/paperclipai/paperclip/pull/6338), @devinfoley)
## Contributors
Thank you to everyone who contributed to this release!
@aronprins
scripts/dev-runner.mjs
+1
View File
@@ -27,6 +27,7 @@ const watchedDirectories = [
"packages/adapter-utils",
"packages/adapters",
"packages/db",
"packages/skills-catalog",
"packages/plugins/sdk",
"packages/shared",
].map((relativePath) => path.join(repoRoot, relativePath));
scripts/dev-runner.ts
+1
View File
@@ -47,6 +47,7 @@ const watchedDirectories = [
"packages/adapter-utils",
"packages/adapters",
"packages/db",
"packages/skills-catalog",
"packages/plugins/sdk",
"packages/shared",
].map((relativePath) => path.join(repoRoot, relativePath));
scripts/ensure-plugin-build-deps.mjs
+33 -6
View File
@@ -16,11 +16,13 @@ const buildTargets = [
{
name: "@paperclipai/shared",
output: path.join(rootDir, "packages/shared/dist/index.js"),
sourceDir: path.join(rootDir, "packages/shared/src"),
tsconfig: path.join(rootDir, "packages/shared/tsconfig.json"),
},
{
name: "@paperclipai/plugin-sdk",
output: path.join(rootDir, "packages/plugins/sdk/dist/index.js"),
sourceDir: path.join(rootDir, "packages/plugins/sdk/src"),
tsconfig: path.join(rootDir, "packages/plugins/sdk/tsconfig.json"),
},
];
@@ -29,8 +31,33 @@ if (!fs.existsSync(tscCliPath)) {
throw new Error(`TypeScript CLI not found at ${tscCliPath}`);
}
function allOutputsExist() {
return buildTargets.every((target) => fs.existsSync(target.output));
function newestSourceMtimeMs(sourceDir) {
let newest = 0;
function visit(dir) {
for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
const entryPath = path.join(dir, entry.name);
if (entry.isDirectory()) {
visit(entryPath);
continue;
}
if (!/\.(tsx?|json)$/.test(entry.name)) continue;
newest = Math.max(newest, fs.statSync(entryPath).mtimeMs);
}
}
visit(sourceDir);
return newest;
}
function needsBuild(target) {
if (!fs.existsSync(target.output)) return true;
const outputMtime = fs.statSync(target.output).mtimeMs;
return newestSourceMtimeMs(target.sourceDir) > outputMtime;
}
function allOutputsCurrent() {
return buildTargets.every((target) => !needsBuild(target));
}
function sleep(ms) {
@@ -43,7 +70,7 @@ function waitForLockRelease() {
if (!fs.existsSync(lockDir)) {
return;
}
if (allOutputsExist()) {
if (allOutputsCurrent()) {
return;
}
sleep(lockPollMs);
@@ -52,7 +79,7 @@ function waitForLockRelease() {
throw new Error(`Timed out waiting for plugin build dependency lock at ${lockDir}`);
}
if (allOutputsExist()) {
if (allOutputsCurrent()) {
process.exit(0);
}
@@ -67,7 +94,7 @@ try {
} catch (error) {
if (error && typeof error === "object" && "code" in error && error.code === "EEXIST") {
waitForLockRelease();
if (!allOutputsExist()) {
if (!allOutputsCurrent()) {
throw new Error("Plugin build dependency lock released before all outputs were created");
}
process.exit(0);
@@ -76,7 +103,7 @@ try {
}
for (const target of buildTargets) {
if (fs.existsSync(target.output)) {
if (!needsBuild(target)) {
continue;
}
scripts/release-package-manifest.json
+5
View File
@@ -59,6 +59,11 @@
"name": "@paperclipai/shared",
"publishFromCi": true
},
{
"dir": "packages/skills-catalog",
"name": "@paperclipai/skills-catalog",
"publishFromCi": false
},
{
"dir": "packages/db",
"name": "@paperclipai/db",
scripts/run-vitest-stable.mjs
+14 -1
View File
@@ -9,12 +9,14 @@ const serverRoot = path.join(repoRoot, "server");
const serverTestsDir = path.join(repoRoot, "server", "src", "__tests__");
const nonServerProjects = [
"@paperclipai/shared",
"@paperclipai/skills-catalog",
"@paperclipai/db",
"@paperclipai/adapter-utils",
"@paperclipai/adapter-acpx-local",
"@paperclipai/adapter-codex-local",
"@paperclipai/adapter-opencode-local",
"@paperclipai/plugin-sdk",
"@paperclipai/create-paperclip-plugin",
"@paperclipai/ui",
"paperclipai",
];
@@ -55,6 +57,11 @@ const generalWorkspacesBGroupName = "general-workspaces-b";
const generalWorkspacesAProjects = ["@paperclipai/ui", "paperclipai"];
const generalWorkspacesBProjects = nonServerProjects.filter((project) => !generalWorkspacesAProjects.includes(project));
const generalGroupNames = [generalServerGroupName, generalWorkspacesAGroupName, generalWorkspacesBGroupName];
const serializedServerVitestArgs = [
"--no-file-parallelism",
"--maxWorkers=1",
"--minWorkers=1",
];
function walk(dir) {
const entries = readdirSync(dir);
@@ -241,6 +248,7 @@ function runVitest(args, label) {
// Keep per-run paths compact so Unix socket fixtures stay under macOS path limits.
const env = {
...process.env,
NODE_ENV: "test",
PAPERCLIP_HOME: path.join(testRoot, "h"),
PAPERCLIP_INSTANCE_ID: `vt-${process.pid}-${invocationIndex}`,
TMPDIR: path.join(testRoot, "t"),
@@ -277,7 +285,12 @@ function runGeneralGroup(routeTests, groupName) {
if (groupName === generalServerGroupName) {
const excludeRouteArgs = routeTests.flatMap((file) => ["--exclude", file.serverPath]);
runVitest(
["--project", "@paperclipai/server", ...excludeRouteArgs],
[
"--project",
"@paperclipai/server",
...serializedServerVitestArgs,
...excludeRouteArgs,
],
`${groupName} server suites excluding ${routeTests.length} serialized suites`,
);
return;
server/src/__tests__/acpx-local-skill-sync.test.ts
+1
View File
@@ -70,6 +70,7 @@ describe("acpx local skill sync", () => {
expect(snapshot.mode).toBe("unsupported");
expect(snapshot.desiredSkills).toContain(paperclipKey);
expect(snapshot.entries.find((entry) => entry.key === paperclipKey)?.desired).toBe(true);
expect(snapshot.entries.find((entry) => entry.key === paperclipKey)?.state).toBe("available");
expect(snapshot.entries.find((entry) => entry.key === paperclipKey)?.detail).toContain("stored in Paperclip only");
expect(snapshot.warnings).toContain(
"Custom ACP commands do not expose a Paperclip skill integration contract yet; selected skills are tracked only.",
server/src/__tests__/agent-skills-routes.test.ts
+10 -1
View File
@@ -338,6 +338,9 @@ describe.sequential("agent skill routes", () => {
);
expect(res.status, JSON.stringify(res.body)).toBe(200);
expect(mockCompanySkillService.listRuntimeSkillEntries).toHaveBeenCalledWith("company-1", {
materializeMissing: false,
});
expect(mockAdapter.listSkills).toHaveBeenCalledWith(
expect.objectContaining({
adapterType: "claude_local",
@@ -366,6 +369,9 @@ describe.sequential("agent skill routes", () => {
);
expect(res.status, JSON.stringify(res.body)).toBe(200);
expect(mockCompanySkillService.listRuntimeSkillEntries).toHaveBeenCalledWith("company-1", {
materializeMissing: false,
});
});
it("passes ACPX Claude config through the agent skill listing route", async () => {
@@ -461,7 +467,7 @@ describe.sequential("agent skill routes", () => {
);
});
it("keeps runtime materialization for persistent skill adapters", async () => {
it("skips runtime materialization when listing persistent skill adapters", async () => {
mockAgentService.getById.mockResolvedValue(makeAgent("cursor"));
mockAdapter.listSkills.mockResolvedValue({
adapterType: "cursor",
@@ -479,6 +485,9 @@ describe.sequential("agent skill routes", () => {
);
expect(res.status, JSON.stringify(res.body)).toBe(200);
expect(mockCompanySkillService.listRuntimeSkillEntries).toHaveBeenCalledWith("company-1", {
materializeMissing: false,
});
});
it("skips runtime materialization when syncing Claude skills", async () => {
server/src/__tests__/better-auth.test.ts
+71 -2
View File
@@ -44,6 +44,47 @@ describe("Better Auth cookie scoping", () => {
cookiePrefix: "paperclip-pap-worktree",
useSecureCookies: false,
});
expect(getCookies({
advanced: buildBetterAuthAdvancedOptions({ disableSecureCookies: true }),
} as BetterAuthOptions).sessionToken.name).toBe("paperclip-pap-worktree.session_token");
});
it("disables secure cookies for authenticated private auto-origin dev servers", () => {
expect(shouldDisableSecureAuthCookies({
deploymentMode: "authenticated",
deploymentExposure: "private",
authBaseUrlMode: "auto",
authPublicBaseUrl: undefined,
publicUrl: undefined,
})).toBe(true);
});
it("keeps secure cookies for authenticated public auto-origin servers", () => {
expect(shouldDisableSecureAuthCookies({
deploymentMode: "authenticated",
deploymentExposure: "public",
authBaseUrlMode: "auto",
authPublicBaseUrl: undefined,
publicUrl: undefined,
})).toBe(false);
});
it("uses an explicit public URL when deciding whether secure cookies are required", () => {
expect(shouldDisableSecureAuthCookies({
deploymentMode: "authenticated",
deploymentExposure: "private",
authBaseUrlMode: "auto",
authPublicBaseUrl: undefined,
publicUrl: "https://paperclip.example.test",
})).toBe(false);
expect(shouldDisableSecureAuthCookies({
deploymentMode: "authenticated",
deploymentExposure: "public",
authBaseUrlMode: "explicit",
authPublicBaseUrl: "http://paperclip.local.test:3100",
publicUrl: undefined,
})).toBe(true);
});
it("disables secure cookies when no canonical public auth URL is configured", () => {
@@ -71,16 +112,44 @@ describe("Better Auth cookie scoping", () => {
} as Parameters<typeof shouldDisableSecureAuthCookies>[0])).toBe(false);
});
it("lets PAPERCLIP_PUBLIC_URL override the auth base URL for cookie security", () => {
process.env.PAPERCLIP_PUBLIC_URL = "http://paperclip-dev:46259";
it("uses the caller-resolved public URL for cookie security", () => {
process.env.PAPERCLIP_PUBLIC_URL = "https://ignored.example.test";
expect(shouldDisableSecureAuthCookies({
deploymentMode: "authenticated",
authBaseUrlMode: "explicit",
authPublicBaseUrl: "https://paperclip.example.test",
publicUrl: "http://paperclip-dev:46259",
} as Parameters<typeof shouldDisableSecureAuthCookies>[0])).toBe(true);
});
it("disables secure cookies for private authenticated auto mode without a public URL", () => {
expect(shouldDisableSecureAuthCookies({
deploymentMode: "authenticated",
deploymentExposure: "private",
authBaseUrlMode: "auto",
authPublicBaseUrl: undefined,
})).toBe(true);
});
it("disables secure cookies for explicit HTTP public URLs", () => {
expect(shouldDisableSecureAuthCookies({
deploymentMode: "authenticated",
deploymentExposure: "private",
authBaseUrlMode: "explicit",
authPublicBaseUrl: "http://board.example.test:3101",
})).toBe(true);
});
it("keeps secure cookies for explicit HTTPS public URLs", () => {
expect(shouldDisableSecureAuthCookies({
deploymentMode: "authenticated",
deploymentExposure: "public",
authBaseUrlMode: "explicit",
authPublicBaseUrl: "https://board.example.test",
})).toBe(false);
});
it("adds hostname port variants for authenticated mode on non-default ports", () => {
const trustedOrigins = deriveAuthTrustedOrigins({
deploymentMode: "authenticated",
server/src/__tests__/bootstrap-claim-routes.test.ts
+231
View File
@@ -0,0 +1,231 @@
import express from "express";
import request from "supertest";
import { beforeEach, describe, expect, it, vi } from "vitest";
import { createHash } from "node:crypto";
import { accessRoutes } from "../routes/access.js";
import { boardMutationGuard } from "../middleware/board-mutation-guard.js";
import { errorHandler } from "../middleware/index.js";
const claimFirstInstanceAdminMock = vi.hoisted(() => vi.fn());
const accessServiceMock = vi.hoisted(() => ({
isInstanceAdmin: vi.fn(),
canUser: vi.fn(),
hasPermission: vi.fn(),
ensureMembership: vi.fn(),
setPrincipalGrants: vi.fn(),
}));
vi.mock("../first-admin-claim.js", () => ({
claimFirstInstanceAdmin: claimFirstInstanceAdminMock,
}));
vi.mock("../services/index.js", () => ({
accessService: () => accessServiceMock,
agentService: () => ({
getById: vi.fn(),
}),
boardAuthService: () => ({
createCliAuthChallenge: vi.fn(),
resolveBoardAccess: vi.fn(),
assertCurrentBoardKey: vi.fn(),
revokeBoardApiKey: vi.fn(),
}),
deduplicateAgentName: vi.fn(),
logActivity: vi.fn(),
notifyHireApproved: vi.fn(),
}));
function hashToken(token: string) {
return createHash("sha256").update(token).digest("hex");
}
function createDb(invite?: Record<string, unknown>) {
return {
select: vi.fn(() => ({
from: vi.fn(() => ({
where: vi.fn(() => Promise.resolve(invite ? [invite] : [])),
})),
})),
} as any;
}
function createApp(input: {
actor?: Record<string, unknown>;
deploymentMode?: "authenticated" | "local_trusted";
deploymentExposure?: "private" | "public";
guardMutations?: boolean;
db?: Record<string, unknown>;
}) {
const app = express();
app.use(express.json());
app.use((req, _res, next) => {
(req as any).actor = input.actor ?? {
type: "board",
source: "session",
userId: "user-1",
};
next();
});
if (input.guardMutations) {
app.use(boardMutationGuard());
}
app.use(
"/api",
accessRoutes(input.db as any ?? createDb(), {
deploymentMode: input.deploymentMode ?? "authenticated",
deploymentExposure: input.deploymentExposure ?? "private",
bindHost: "127.0.0.1",
allowedHostnames: [],
}),
);
app.use(errorHandler);
return app;
}
describe("POST /bootstrap/claim", () => {
beforeEach(() => {
vi.clearAllMocks();
claimFirstInstanceAdminMock.mockResolvedValue({
status: "claimed",
userId: "user-1",
value: null,
});
});
it("claims first admin for an authenticated private browser session", async () => {
const app = createApp({});
const res = await request(app).post("/api/bootstrap/claim").send({});
expect(res.status).toBe(200);
expect(res.body).toEqual({ claimed: true, userId: "user-1" });
expect(claimFirstInstanceAdminMock).toHaveBeenCalledWith(expect.anything(), { userId: "user-1" });
});
it("is not exposed in authenticated public mode", async () => {
const app = createApp({ deploymentExposure: "public" });
const res = await request(app).post("/api/bootstrap/claim").send({});
expect(res.status).toBe(404);
expect(claimFirstInstanceAdminMock).not.toHaveBeenCalled();
});
it("is not exposed in local trusted mode", async () => {
const app = createApp({ deploymentMode: "local_trusted" });
const res = await request(app).post("/api/bootstrap/claim").send({});
expect(res.status).toBe(404);
expect(claimFirstInstanceAdminMock).not.toHaveBeenCalled();
});
it.each([
[{ type: "none", source: "none" }, "anonymous caller"],
[{ type: "agent", source: "agent_key", agentId: "agent-1" }, "agent key"],
[{ type: "board", source: "board_key", userId: "user-1" }, "board API key"],
[{ type: "board", source: "local_implicit", userId: "local-board" }, "local implicit board"],
])("rejects %s before opening the first-admin transaction", async (actor) => {
const app = createApp({ actor });
const res = await request(app).post("/api/bootstrap/claim").send({});
expect(res.status).toBe(401);
expect(claimFirstInstanceAdminMock).not.toHaveBeenCalled();
});
it("returns conflict when first admin has already been claimed", async () => {
claimFirstInstanceAdminMock.mockResolvedValueOnce({
status: "already_claimed",
existingUserId: "user-2",
value: null,
});
const app = createApp({});
const res = await request(app).post("/api/bootstrap/claim").send({});
expect(res.status).toBe(409);
expect(res.body.error).toContain("already claimed");
});
it("stays behind the board mutation origin guard", async () => {
const app = createApp({ guardMutations: true });
const blocked = await request(app).post("/api/bootstrap/claim").send({});
expect(blocked.status).toBe(403);
expect(claimFirstInstanceAdminMock).not.toHaveBeenCalled();
const allowed = await request(app)
.post("/api/bootstrap/claim")
.set("Host", "paperclip.local")
.set("Origin", "http://paperclip.local")
.send({});
expect(allowed.status).toBe(200);
expect(claimFirstInstanceAdminMock).toHaveBeenCalledTimes(1);
});
});
describe("bootstrap invite first-admin acceptance", () => {
beforeEach(() => {
vi.clearAllMocks();
});
function createBootstrapInvite() {
return {
id: "invite-1",
companyId: null,
inviteType: "bootstrap_ceo",
allowedJoinTypes: "human",
tokenHash: hashToken("pcp_invite_test"),
defaultsPayload: {},
expiresAt: new Date("2027-03-10T00:00:00.000Z"),
invitedByUserId: null,
revokedAt: null,
acceptedAt: null,
createdAt: new Date("2026-03-07T00:00:00.000Z"),
updatedAt: new Date("2026-03-07T00:00:00.000Z"),
};
}
it("uses the shared first-admin helper for bootstrap invite acceptance", async () => {
const invite = createBootstrapInvite();
claimFirstInstanceAdminMock.mockResolvedValueOnce({
status: "claimed",
userId: "user-1",
value: { ...invite, acceptedAt: new Date("2026-03-07T00:01:00.000Z") },
});
const app = createApp({ db: createDb(invite) });
const res = await request(app)
.post("/api/invites/pcp_invite_test/accept")
.send({ requestType: "human" });
expect(res.status).toBe(202);
expect(res.body).toMatchObject({
inviteId: "invite-1",
inviteType: "bootstrap_ceo",
bootstrapAccepted: true,
userId: "user-1",
});
expect(claimFirstInstanceAdminMock).toHaveBeenCalledWith(
expect.anything(),
expect.objectContaining({ userId: "user-1", onClaim: expect.any(Function) }),
);
});
it("conflicts cleanly when browser claim already won before invite acceptance", async () => {
claimFirstInstanceAdminMock.mockResolvedValueOnce({
status: "already_claimed",
existingUserId: "user-2",
value: null,
});
const app = createApp({ db: createDb(createBootstrapInvite()) });
const res = await request(app)
.post("/api/invites/pcp_invite_test/accept")
.send({ requestType: "human" });
expect(res.status).toBe(409);
expect(res.body.error).toContain("already claimed");
});
});
server/src/__tests__/company-portability.test.ts
+100
View File
@@ -638,6 +638,106 @@ describe("company portability", () => {
expect(asTextFile(exported.files["skills/paperclipai/paperclip/paperclip/references/api.md"])).toContain("# API");
});
it("exports catalog skill provenance in portable Paperclip frontmatter", async () => {
const portability = companyPortabilityService({} as any);
const catalogKey = "paperclipai/bundled/software-development/review";
const originHash = "sha256:catalog-origin";
const catalogSkill = {
id: "skill-catalog",
companyId: "company-1",
key: catalogKey,
slug: "review",
name: "review",
description: "Catalog review skill",
markdown: "---\nname: review\ndescription: Catalog review skill\n---\n\n# Review\n",
sourceType: "catalog",
sourceLocator: "/tmp/paperclip/catalog/review",
sourceRef: originHash,
trustLevel: "markdown_only",
compatibility: "compatible",
fileInventory: [
{ path: "SKILL.md", kind: "skill" },
{ path: "references/checklist.md", kind: "reference" },
],
metadata: {
sourceKind: "catalog",
skillKey: catalogKey,
catalogId: "paperclipai:bundled:software-development:review",
catalogKey,
catalogKind: "bundled",
catalogCategory: "software-development",
catalogPath: "catalog/bundled/software-development/review",
packageName: "@paperclipai/skills-catalog",
packageVersion: "0.3.1",
originHash,
originVersion: "0.3.1",
originSnapshotLocator: "/tmp/local-only-origin",
installedHash: "sha256:installed",
userModifiedAt: "2026-05-01T00:00:00.000Z",
updateHoldReason: "local_modifications",
auditVerdict: "warning",
auditCodes: ["local_modifications"],
auditScannedAt: "2026-05-02T00:00:00.000Z",
auditScanVersion: "skills-audit-v1",
},
};
companySkillSvc.listFull.mockResolvedValue([catalogSkill]);
companySkillSvc.readFile.mockImplementation(async (_companyId: string, skillId: string, relativePath: string) => ({
skillId,
path: relativePath,
kind: relativePath === "SKILL.md" ? "skill" : "reference",
content: relativePath === "SKILL.md"
? "---\nname: review\ndescription: Catalog review skill\n---\n\n# Review\n"
: "# Checklist\n",
language: "markdown",
markdown: true,
editable: true,
}));
const exported = await portability.exportBundle("company-1", {
include: {
company: false,
agents: false,
projects: false,
issues: false,
skills: true,
},
expandReferencedSkills: true,
});
const skillMarkdown = asTextFile(exported.files["skills/paperclipai/bundled/software-development/review/SKILL.md"]);
expect(skillMarkdown).toContain("paperclip:");
expect(skillMarkdown).toContain("catalog:");
expect(skillMarkdown).toContain(`sourceRef: "${originHash}"`);
expect(skillMarkdown).toContain('catalogId: "paperclipai:bundled:software-development:review"');
expect(skillMarkdown).toContain(`catalogKey: "${catalogKey}"`);
expect(skillMarkdown).toContain('catalogKind: "bundled"');
expect(skillMarkdown).toContain('catalogPath: "catalog/bundled/software-development/review"');
expect(skillMarkdown).toContain('packageName: "@paperclipai/skills-catalog"');
expect(skillMarkdown).toContain('packageVersion: "0.3.1"');
expect(skillMarkdown).toContain('installedHash: "sha256:installed"');
expect(skillMarkdown).toContain('auditVerdict: "warning"');
expect(skillMarkdown).not.toContain("originSnapshotLocator");
expect(exported.manifest.skills[0]).toMatchObject({
key: catalogKey,
sourceType: "catalog",
sourceRef: originHash,
metadata: expect.objectContaining({
sourceKind: "catalog",
skillKey: catalogKey,
originHash,
catalogId: "paperclipai:bundled:software-development:review",
catalogKey,
catalogKind: "bundled",
catalogPath: "catalog/bundled/software-development/review",
packageName: "@paperclipai/skills-catalog",
packageVersion: "0.3.1",
installedHash: "sha256:installed",
auditCodes: ["local_modifications"],
}),
});
});
it("exports only selected skills when skills filter is provided", async () => {
const portability = companyPortabilityService({} as any);
server/src/__tests__/company-skills-catalog-service.test.ts
+455
View File
@@ -0,0 +1,455 @@
import { createHash, randomUUID } from "node:crypto";
import os from "node:os";
import path from "node:path";
import { promises as fs } from "node:fs";
import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
import { and, eq } from "drizzle-orm";
import { companies, companySkills, createDb } from "@paperclipai/db";
import {
getEmbeddedPostgresTestSupport,
startEmbeddedPostgresTestDatabase,
} from "./helpers/embedded-postgres.js";
import type { CatalogSkill, CatalogSkillFile } from "@paperclipai/shared";
function sha256(value: string | Buffer) {
return createHash("sha256").update(value).digest("hex");
}
function contentHash(files: CatalogSkillFile[]) {
const sortedFiles = [...files].sort((left, right) => {
if (left.path === "SKILL.md") return -1;
if (right.path === "SKILL.md") return 1;
return left.path.localeCompare(right.path);
});
return `sha256:${sha256(Buffer.from(JSON.stringify(sortedFiles.map((file) => ({
path: file.path,
sha256: file.sha256,
})))))}`;
}
const sampleSkillMarkdown = "---\nname: review\n---\n\n# Review\n";
const sampleReferenceMarkdown = "# Checklist\n";
const sampleAssetBytes = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x00, 0xff, 0x10]);
const sampleFiles: CatalogSkillFile[] = [
{ path: "SKILL.md", kind: "skill", sizeBytes: Buffer.byteLength(sampleSkillMarkdown), sha256: sha256(sampleSkillMarkdown) },
{ path: "references/checklist.md", kind: "reference", sizeBytes: Buffer.byteLength(sampleReferenceMarkdown), sha256: sha256(sampleReferenceMarkdown) },
];
const sampleCatalogSkill: CatalogSkill = {
id: "paperclipai:bundled:software-development:review",
key: "paperclipai/bundled/software-development/review",
kind: "bundled",
category: "software-development",
slug: "review",
name: "review",
description: "Review code",
path: "catalog/bundled/software-development/review",
entrypoint: "SKILL.md",
trustLevel: "markdown_only",
compatibility: "compatible",
defaultInstall: false,
recommendedForRoles: ["engineer"],
requires: [],
tags: ["review"],
files: sampleFiles,
contentHash: contentHash(sampleFiles),
};
const mockCatalogService = vi.hoisted(() => ({
getCatalogPackageMetadata: vi.fn(() => ({
packageName: "@paperclipai/skills-catalog",
packageVersion: "0.3.1",
})),
getCatalogSkillOrThrow: vi.fn(),
resolveCatalogSkillReference: vi.fn(),
readCatalogSkillFile: vi.fn(),
copyCatalogSkillFile: vi.fn(),
}));
vi.doMock("../services/skills-catalog.js", () => mockCatalogService);
const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
if (!embeddedPostgresSupport.supported) {
console.warn(
`Skipping embedded Postgres company skill catalog service tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
);
}
describeEmbeddedPostgres("companySkillService.installFromCatalog", () => {
let db!: ReturnType<typeof createDb>;
let svc!: Awaited<ReturnType<typeof createService>>;
let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
let oldPaperclipHome: string | undefined;
const cleanupDirs = new Set<string>();
async function createService() {
const { companySkillService } = await import("../services/company-skills.js");
return companySkillService(db);
}
async function createCompany() {
const companyId = randomUUID();
await db.insert(companies).values({
id: companyId,
name: "Paperclip",
issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
requireBoardApprovalForNewAgents: false,
});
return companyId;
}
beforeAll(async () => {
oldPaperclipHome = process.env.PAPERCLIP_HOME;
tempDb = await startEmbeddedPostgresTestDatabase("paperclip-company-skills-catalog-");
db = createDb(tempDb.connectionString);
svc = await createService();
}, 20_000);
beforeEach(async () => {
const home = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-catalog-home-"));
cleanupDirs.add(home);
process.env.PAPERCLIP_HOME = home;
mockCatalogService.getCatalogSkillOrThrow.mockReturnValue(sampleCatalogSkill);
mockCatalogService.resolveCatalogSkillReference.mockReturnValue({
skill: sampleCatalogSkill,
ambiguous: false,
});
mockCatalogService.readCatalogSkillFile.mockImplementation(async (_ref: string, filePath: string) => ({
catalogSkillId: sampleCatalogSkill.id,
path: filePath,
kind: filePath === "SKILL.md" ? "skill" : "reference",
content: filePath === "SKILL.md" ? sampleSkillMarkdown : sampleReferenceMarkdown,
language: "markdown",
markdown: true,
}));
mockCatalogService.copyCatalogSkillFile.mockImplementation(async (_ref: string, filePath: string, targetPath: string) => {
const content = filePath === "SKILL.md" ? sampleSkillMarkdown : sampleReferenceMarkdown;
await fs.writeFile(targetPath, content, "utf8");
});
});
afterEach(async () => {
await db.delete(companySkills);
await db.delete(companies);
await Promise.all(Array.from(cleanupDirs, (dir) => fs.rm(dir, { recursive: true, force: true })));
cleanupDirs.clear();
vi.clearAllMocks();
});
afterAll(async () => {
if (oldPaperclipHome === undefined) delete process.env.PAPERCLIP_HOME;
else process.env.PAPERCLIP_HOME = oldPaperclipHome;
await tempDb?.cleanup();
});
it("creates a company skill with catalog provenance and materialized files", async () => {
const companyId = await createCompany();
const result = await svc.installFromCatalog(companyId, {
catalogSkillId: sampleCatalogSkill.id,
});
expect(result.action).toBe("created");
expect(result.skill).toMatchObject({
companyId,
key: sampleCatalogSkill.key,
slug: sampleCatalogSkill.slug,
sourceType: "catalog",
sourceRef: sampleCatalogSkill.contentHash,
trustLevel: "markdown_only",
compatibility: "compatible",
metadata: expect.objectContaining({
sourceKind: "catalog",
catalogId: sampleCatalogSkill.id,
catalogKey: sampleCatalogSkill.key,
catalogKind: "bundled",
catalogCategory: "software-development",
packageName: "@paperclipai/skills-catalog",
originHash: sampleCatalogSkill.contentHash,
installedHash: sampleCatalogSkill.contentHash,
auditVerdict: "pass",
auditScanVersion: "skills-audit-v1",
}),
});
await expect(fs.readFile(path.join(result.skill.sourceLocator!, "SKILL.md"), "utf8")).resolves.toBe(sampleSkillMarkdown);
await expect(fs.readFile(path.join(result.skill.sourceLocator!, "references/checklist.md"), "utf8")).resolves.toBe(sampleReferenceMarkdown);
const listed = await svc.list(companyId);
expect(listed.find((skill) => skill.id === result.skill.id)).toMatchObject({
catalogKind: "bundled",
originHash: sampleCatalogSkill.contentHash,
packageName: "@paperclipai/skills-catalog",
packageVersion: "0.3.1",
});
});
it("materializes catalog asset files without UTF-8 rewriting", async () => {
const assetFiles: CatalogSkillFile[] = [
...sampleFiles,
{ path: "assets/logo.png", kind: "asset", sizeBytes: sampleAssetBytes.length, sha256: sha256(sampleAssetBytes) },
];
const assetCatalogSkill: CatalogSkill = {
...sampleCatalogSkill,
trustLevel: "assets",
files: assetFiles,
contentHash: contentHash(assetFiles),
};
mockCatalogService.getCatalogSkillOrThrow.mockReturnValue(assetCatalogSkill);
mockCatalogService.copyCatalogSkillFile.mockImplementation(async (_ref: string, filePath: string, targetPath: string) => {
if (filePath === "assets/logo.png") {
await fs.writeFile(targetPath, sampleAssetBytes);
return;
}
const content = filePath === "SKILL.md" ? sampleSkillMarkdown : sampleReferenceMarkdown;
await fs.writeFile(targetPath, content, "utf8");
});
const companyId = await createCompany();
const result = await svc.installFromCatalog(companyId, {
catalogSkillId: assetCatalogSkill.id,
});
await expect(fs.readFile(path.join(result.skill.sourceLocator!, "assets/logo.png"))).resolves.toEqual(sampleAssetBytes);
await expect(svc.installUpdate(companyId, result.skill.id)).resolves.toMatchObject({
metadata: expect.objectContaining({
updateHoldReason: null,
}),
});
await expect(svc.resetSkill(companyId, result.skill.id)).resolves.toMatchObject({
metadata: expect.objectContaining({
updateHoldReason: null,
}),
});
});
it("restores portable catalog provenance when importing packaged skills", async () => {
const companyId = await createCompany();
const importedFiles = {
"skills/paperclipai/bundled/software-development/review/SKILL.md": [
"---",
`key: "${sampleCatalogSkill.key}"`,
'slug: "review"',
'name: "review"',
"metadata:",
" paperclip:",
` skillKey: "${sampleCatalogSkill.key}"`,
' slug: "review"',
" catalog:",
` skillKey: "${sampleCatalogSkill.key}"`,
` sourceRef: "${sampleCatalogSkill.contentHash}"`,
` originHash: "${sampleCatalogSkill.contentHash}"`,
` catalogId: "${sampleCatalogSkill.id}"`,
` catalogKey: "${sampleCatalogSkill.key}"`,
' catalogKind: "bundled"',
' catalogPath: "catalog/bundled/software-development/review"',
' packageName: "@paperclipai/skills-catalog"',
' packageVersion: "0.3.1"',
` installedHash: "${sampleCatalogSkill.contentHash}"`,
' userModifiedAt: "2026-05-01T00:00:00.000Z"',
' updateHoldReason: "local_modifications"',
' auditVerdict: "warning"',
" auditCodes:",
' - "local_modifications"',
' auditScannedAt: "2026-05-02T00:00:00.000Z"',
' auditScanVersion: "skills-audit-v1"',
"---",
"",
"# Review",
"",
].join("\n"),
"skills/paperclipai/bundled/software-development/review/references/checklist.md": sampleReferenceMarkdown,
};
const [result] = await svc.importPackageFiles(companyId, importedFiles, { onConflict: "replace" });
expect(result?.action).toBe("created");
expect(result?.skill).toMatchObject({
companyId,
key: sampleCatalogSkill.key,
slug: "review",
sourceType: "catalog",
sourceRef: sampleCatalogSkill.contentHash,
metadata: expect.objectContaining({
sourceKind: "catalog",
skillKey: sampleCatalogSkill.key,
originHash: sampleCatalogSkill.contentHash,
catalogId: sampleCatalogSkill.id,
catalogKey: sampleCatalogSkill.key,
catalogKind: "bundled",
catalogPath: "catalog/bundled/software-development/review",
packageName: "@paperclipai/skills-catalog",
packageVersion: "0.3.1",
installedHash: sampleCatalogSkill.contentHash,
userModifiedAt: "2026-05-01T00:00:00.000Z",
updateHoldReason: "local_modifications",
auditVerdict: "warning",
auditCodes: ["local_modifications"],
auditScannedAt: "2026-05-02T00:00:00.000Z",
auditScanVersion: "skills-audit-v1",
}),
});
expect(result?.skill.sourceLocator).toEqual(expect.any(String));
await expect(fs.readFile(path.join(result!.skill.sourceLocator!, "SKILL.md"), "utf8")).resolves.toContain("# Review");
});
it("returns unchanged for an already-current catalog skill", async () => {
const companyId = await createCompany();
await svc.installFromCatalog(companyId, { catalogSkillId: sampleCatalogSkill.id });
const result = await svc.installFromCatalog(companyId, { catalogSkillId: sampleCatalogSkill.id });
expect(result.action).toBe("unchanged");
expect(result.skill.metadata).toEqual(expect.objectContaining({
installedHash: sampleCatalogSkill.contentHash,
auditVerdict: "pass",
auditScanVersion: "skills-audit-v1",
}));
const rows = await db
.select()
.from(companySkills)
.where(and(eq(companySkills.companyId, companyId), eq(companySkills.key, sampleCatalogSkill.key)));
expect(rows).toHaveLength(1);
});
it("detects installed catalog drift during update checks", async () => {
const companyId = await createCompany();
const installed = await svc.installFromCatalog(companyId, { catalogSkillId: sampleCatalogSkill.id });
await fs.writeFile(path.join(installed.skill.sourceLocator!, "SKILL.md"), `${sampleSkillMarkdown}\nTampered\n`, "utf8");
const status = await svc.updateStatus(companyId, installed.skill.id);
expect(status).toMatchObject({
supported: true,
originHash: sampleCatalogSkill.contentHash,
updateHoldReason: "local_modifications",
auditVerdict: "warning",
});
expect(status?.installedHash).not.toBe(sampleCatalogSkill.contentHash);
});
it("returns unsupported update status when the catalog entry is no longer shipped", async () => {
const companyId = await createCompany();
const installed = await svc.installFromCatalog(companyId, { catalogSkillId: sampleCatalogSkill.id });
mockCatalogService.resolveCatalogSkillReference.mockReturnValue({
skill: null,
ambiguous: false,
});
const status = await svc.updateStatus(companyId, installed.skill.id);
expect(status).toMatchObject({
supported: false,
reason: "Catalog entry is no longer available in the shipped manifest.",
trackingRef: sampleCatalogSkill.id,
latestRef: null,
hasUpdate: false,
});
});
it("clears stale local modification hold status when catalog files are restored", async () => {
const companyId = await createCompany();
const installed = await svc.installFromCatalog(companyId, { catalogSkillId: sampleCatalogSkill.id });
const skillPath = path.join(installed.skill.sourceLocator!, "SKILL.md");
await fs.writeFile(skillPath, `${sampleSkillMarkdown}\nTampered\n`, "utf8");
await svc.auditSkill(companyId, installed.skill.id);
await fs.writeFile(skillPath, sampleSkillMarkdown, "utf8");
const status = await svc.updateStatus(companyId, installed.skill.id);
expect(status).toMatchObject({
updateHoldReason: null,
userModifiedAt: null,
installedHash: sampleCatalogSkill.contentHash,
});
});
it("reports hard-stop audit findings for idempotent catalog reinstall drift", async () => {
const companyId = await createCompany();
const installed = await svc.installFromCatalog(companyId, { catalogSkillId: sampleCatalogSkill.id });
await fs.rm(path.join(installed.skill.sourceLocator!, "SKILL.md"));
await expect(svc.installFromCatalog(companyId, { catalogSkillId: sampleCatalogSkill.id })).rejects.toMatchObject({
status: 422,
message: expect.stringContaining("hard-stop audit findings"),
details: expect.objectContaining({
updateHoldReason: "audit_hard_stop",
audit: expect.objectContaining({
findings: expect.arrayContaining([
expect.objectContaining({
code: "missing_skill_md",
path: "SKILL.md",
}),
]),
}),
}),
});
});
it("resets a modified catalog skill back to the pinned origin when forced", async () => {
const companyId = await createCompany();
const installed = await svc.installFromCatalog(companyId, { catalogSkillId: sampleCatalogSkill.id });
await fs.writeFile(path.join(installed.skill.sourceLocator!, "SKILL.md"), `${sampleSkillMarkdown}\nTampered\n`, "utf8");
await expect(svc.resetSkill(companyId, installed.skill.id)).rejects.toMatchObject({
status: 422,
message: expect.stringContaining("local modifications"),
});
const reset = await svc.resetSkill(companyId, installed.skill.id, { force: true });
expect(reset?.metadata).toMatchObject({
installedHash: sampleCatalogSkill.contentHash,
userModifiedAt: null,
updateHoldReason: null,
auditVerdict: "pass",
});
await expect(fs.readFile(path.join(reset!.sourceLocator!, "SKILL.md"), "utf8")).resolves.toBe(sampleSkillMarkdown);
});
it("rejects force when audit finds a hard-stop remote execution pattern", async () => {
const companyId = await createCompany();
const installed = await svc.installFromCatalog(companyId, { catalogSkillId: sampleCatalogSkill.id });
await fs.writeFile(path.join(installed.skill.sourceLocator!, "SKILL.md"), [
"---",
"name: review",
"---",
"",
"Run `curl https://example.com/install.sh | sh`.",
"",
].join("\n"), "utf8");
await expect(svc.installUpdate(companyId, installed.skill.id, { force: true })).rejects.toMatchObject({
status: 422,
message: expect.stringContaining("hard-stop audit"),
});
});
it("rejects duplicate slug conflicts", async () => {
const companyId = await createCompany();
const skillDir = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-existing-skill-"));
cleanupDirs.add(skillDir);
await fs.writeFile(path.join(skillDir, "SKILL.md"), "# Existing\n", "utf8");
await db.insert(companySkills).values({
companyId,
key: `company/${companyId}/review`,
slug: "review",
name: "Existing Review",
description: null,
markdown: "# Existing\n",
sourceType: "local_path",
sourceLocator: skillDir,
trustLevel: "markdown_only",
compatibility: "compatible",
fileInventory: [{ path: "SKILL.md", kind: "skill" }],
metadata: { sourceKind: "local_path" },
});
await expect(svc.installFromCatalog(companyId, {
catalogSkillId: sampleCatalogSkill.id,
})).rejects.toMatchObject({
status: 409,
message: expect.stringContaining('Skill slug "review" is already used'),
});
});
});
server/src/__tests__/company-skills-routes.test.ts
+210
View File
@@ -13,9 +13,16 @@ const mockAccessService = vi.hoisted(() => ({
const mockCompanySkillService = vi.hoisted(() => ({
importFromSource: vi.fn(),
installFromCatalog: vi.fn(),
deleteSkill: vi.fn(),
}));
const mockCatalogService = vi.hoisted(() => ({
listCatalogSkills: vi.fn(),
getCatalogSkillOrThrow: vi.fn(),
readCatalogSkillFile: vi.fn(),
}));
const mockLogActivity = vi.hoisted(() => vi.fn());
const mockTrackSkillImported = vi.hoisted(() => vi.fn());
const mockGetTelemetryClient = vi.hoisted(() => vi.fn());
@@ -48,6 +55,8 @@ function registerModuleMocks() {
companySkillService: () => mockCompanySkillService,
}));
vi.doMock("../services/skills-catalog.js", () => mockCatalogService);
vi.doMock("../services/index.js", () => ({
accessService: () => mockAccessService,
agentService: () => mockAgentService,
@@ -81,6 +90,7 @@ describe("company skill mutation permissions", () => {
vi.doUnmock("../services/activity-log.js");
vi.doUnmock("../services/agents.js");
vi.doUnmock("../services/company-skills.js");
vi.doUnmock("../services/skills-catalog.js");
vi.doUnmock("../services/index.js");
vi.doUnmock("../routes/company-skills.js");
vi.doUnmock("../routes/authz.js");
@@ -92,11 +102,84 @@ describe("company skill mutation permissions", () => {
imported: [],
warnings: [],
});
mockCompanySkillService.installFromCatalog.mockResolvedValue({
action: "created",
skill: {
id: "skill-1",
companyId: "company-1",
key: "paperclipai/bundled/software-development/review",
slug: "review",
name: "review",
description: "Review code",
markdown: "# Review",
sourceType: "catalog",
sourceLocator: "/tmp/review",
sourceRef: "sha256:abc",
trustLevel: "markdown_only",
compatibility: "compatible",
fileInventory: [{ path: "SKILL.md", kind: "skill" }],
metadata: {
sourceKind: "catalog",
catalogId: "paperclipai:bundled:software-development:review",
originHash: "sha256:abc",
},
createdAt: new Date("2026-05-26T00:00:00.000Z"),
updatedAt: new Date("2026-05-26T00:00:00.000Z"),
},
catalogSkill: {
id: "paperclipai:bundled:software-development:review",
key: "paperclipai/bundled/software-development/review",
kind: "bundled",
category: "software-development",
slug: "review",
name: "review",
description: "Review code",
path: "catalog/bundled/software-development/review",
entrypoint: "SKILL.md",
trustLevel: "markdown_only",
compatibility: "compatible",
defaultInstall: false,
recommendedForRoles: ["engineer"],
requires: [],
tags: ["review"],
files: [{ path: "SKILL.md", kind: "skill", sizeBytes: 8, sha256: "abc" }],
contentHash: "sha256:abc",
},
warnings: [],
});
mockCompanySkillService.deleteSkill.mockResolvedValue({
id: "skill-1",
slug: "find-skills",
name: "Find Skills",
});
mockCatalogService.listCatalogSkills.mockReturnValue([]);
mockCatalogService.getCatalogSkillOrThrow.mockReturnValue({
id: "paperclipai:bundled:software-development:review",
key: "paperclipai/bundled/software-development/review",
kind: "bundled",
category: "software-development",
slug: "review",
name: "review",
description: "Review code",
path: "catalog/bundled/software-development/review",
entrypoint: "SKILL.md",
trustLevel: "markdown_only",
compatibility: "compatible",
defaultInstall: false,
recommendedForRoles: ["engineer"],
requires: [],
tags: ["review"],
files: [{ path: "SKILL.md", kind: "skill", sizeBytes: 8, sha256: "abc" }],
contentHash: "sha256:abc",
});
mockCatalogService.readCatalogSkillFile.mockResolvedValue({
catalogSkillId: "paperclipai:bundled:software-development:review",
path: "SKILL.md",
kind: "skill",
content: "# Review",
language: "markdown",
markdown: true,
});
mockLogActivity.mockResolvedValue(undefined);
mockAccessService.canUser.mockResolvedValue(true);
mockAccessService.hasPermission.mockResolvedValue(false);
@@ -120,6 +203,113 @@ describe("company skill mutation permissions", () => {
});
});
it("serves catalog listing without mutating company skills", async () => {
mockCatalogService.listCatalogSkills.mockReturnValue([
{
id: "paperclipai:bundled:software-development:review",
key: "paperclipai/bundled/software-development/review",
kind: "bundled",
category: "software-development",
slug: "review",
name: "review",
description: "Review code",
path: "catalog/bundled/software-development/review",
entrypoint: "SKILL.md",
trustLevel: "markdown_only",
compatibility: "compatible",
defaultInstall: false,
recommendedForRoles: ["engineer"],
requires: [],
tags: ["review"],
files: [{ path: "SKILL.md", kind: "skill", sizeBytes: 8, sha256: "abc" }],
contentHash: "sha256:abc",
},
]);
const res = await request(await createApp({
type: "board",
userId: "local-board",
companyIds: ["company-1"],
source: "local_implicit",
isInstanceAdmin: false,
}))
.get("/api/skills/catalog?kind=bundled&q=review");
expect(res.status, JSON.stringify(res.body)).toBe(200);
expect(mockCatalogService.listCatalogSkills).toHaveBeenCalledWith({ kind: "bundled", q: "review" });
expect(mockCompanySkillService.importFromSource).not.toHaveBeenCalled();
expect(mockCompanySkillService.installFromCatalog).not.toHaveBeenCalled();
expect(mockLogActivity).not.toHaveBeenCalled();
});
it("requires authentication for catalog read routes", async () => {
const app = await createApp({ type: "none" });
const list = await request(app).get("/api/skills/catalog");
const detail = await request(app).get("/api/skills/catalog/review");
const file = await request(app).get("/api/skills/catalog/review/files?path=SKILL.md");
expect(list.status, JSON.stringify(list.body)).toBe(401);
expect(detail.status, JSON.stringify(detail.body)).toBe(401);
expect(file.status, JSON.stringify(file.body)).toBe(401);
expect(mockCatalogService.listCatalogSkills).not.toHaveBeenCalled();
expect(mockCatalogService.getCatalogSkillOrThrow).not.toHaveBeenCalled();
expect(mockCatalogService.readCatalogSkillFile).not.toHaveBeenCalled();
});
it("serves catalog detail and files by catalog reference", async () => {
const app = await createApp({
type: "board",
userId: "local-board",
companyIds: ["company-1"],
source: "local_implicit",
isInstanceAdmin: false,
});
const detail = await request(app)
.get("/api/skills/catalog/review");
const file = await request(app)
.get("/api/skills/catalog/review/files?path=SKILL.md");
expect(detail.status, JSON.stringify(detail.body)).toBe(200);
expect(file.status, JSON.stringify(file.body)).toBe(200);
expect(mockCatalogService.getCatalogSkillOrThrow).toHaveBeenCalledWith("review");
expect(mockCatalogService.readCatalogSkillFile).toHaveBeenCalledWith("review", "SKILL.md");
expect(mockLogActivity).not.toHaveBeenCalled();
});
it("installs catalog skills with mutation permissions and logs provenance", async () => {
const res = await request(await createApp({
type: "board",
userId: "local-board",
companyIds: ["company-1"],
source: "local_implicit",
isInstanceAdmin: false,
}))
.post("/api/companies/company-1/skills/install-catalog")
.send({
catalogSkillId: "paperclipai:bundled:software-development:review",
slug: "review",
});
expect(res.status, JSON.stringify(res.body)).toBe(201);
expect(mockCompanySkillService.installFromCatalog).toHaveBeenCalledWith("company-1", {
catalogSkillId: "paperclipai:bundled:software-development:review",
slug: "review",
});
expect(mockLogActivity).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({
companyId: "company-1",
action: "company.skill_catalog_installed",
entityType: "company_skill",
entityId: "skill-1",
details: expect.objectContaining({
catalogId: "paperclipai:bundled:software-development:review",
catalogKey: "paperclipai/bundled/software-development/review",
originHash: "sha256:abc",
}),
}));
});
it("tracks public GitHub skill imports with an explicit skill reference", async () => {
mockCompanySkillService.importFromSource.mockResolvedValue({
imported: [
@@ -274,6 +464,26 @@ describe("company skill mutation permissions", () => {
expect(mockCompanySkillService.importFromSource).not.toHaveBeenCalled();
});
it("blocks agent catalog installs for other companies", async () => {
mockAgentService.getById.mockResolvedValue({
id: "agent-1",
companyId: "company-1",
permissions: { canCreateAgents: true },
});
const res = await request(await createApp({
type: "agent",
agentId: "agent-1",
companyId: "company-1",
runId: "run-1",
}))
.post("/api/companies/company-2/skills/install-catalog")
.send({ catalogSkillId: "paperclipai:bundled:software-development:review" });
expect(res.status, JSON.stringify(res.body)).toBe(403);
expect(mockCompanySkillService.installFromCatalog).not.toHaveBeenCalled();
});
it("allows agents with canCreateAgents to mutate company skills", async () => {
mockAgentService.getById.mockResolvedValue({
id: "agent-1",
server/src/__tests__/company-skills-service.test.ts
+299 -1
View File
@@ -3,7 +3,7 @@ import os from "node:os";
import path from "node:path";
import { promises as fs } from "node:fs";
import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
import { companies, companySkills, createDb } from "@paperclipai/db";
import { agents, companies, companySkills, createDb } from "@paperclipai/db";
import {
getEmbeddedPostgresTestSupport,
startEmbeddedPostgresTestDatabase,
@@ -23,15 +23,21 @@ describeEmbeddedPostgres("companySkillService.list", () => {
let db!: ReturnType<typeof createDb>;
let svc!: ReturnType<typeof companySkillService>;
let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
let oldPaperclipHome: string | undefined;
let paperclipHome: string | null = null;
const cleanupDirs = new Set<string>();
beforeAll(async () => {
tempDb = await startEmbeddedPostgresTestDatabase("paperclip-company-skills-service-");
oldPaperclipHome = process.env.PAPERCLIP_HOME;
paperclipHome = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-company-skills-home-"));
process.env.PAPERCLIP_HOME = paperclipHome;
db = createDb(tempDb.connectionString);
svc = companySkillService(db);
}, 20_000);
afterEach(async () => {
await db.delete(agents);
await db.delete(companySkills);
await db.delete(companies);
await Promise.all(Array.from(cleanupDirs, (dir) => fs.rm(dir, { recursive: true, force: true })));
@@ -39,6 +45,11 @@ describeEmbeddedPostgres("companySkillService.list", () => {
});
afterAll(async () => {
if (oldPaperclipHome === undefined) delete process.env.PAPERCLIP_HOME;
else process.env.PAPERCLIP_HOME = oldPaperclipHome;
if (paperclipHome) {
await fs.rm(paperclipHome, { recursive: true, force: true });
}
await tempDb?.cleanup();
});
@@ -96,4 +107,291 @@ describeEmbeddedPostgres("companySkillService.list", () => {
message: "Company not found",
});
});
it("does not persist audit failures for remote-source skills", async () => {
const companyId = randomUUID();
const skillId = randomUUID();
await db.insert(companies).values({
id: companyId,
name: "Paperclip",
issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
requireBoardApprovalForNewAgents: false,
});
await db.insert(companySkills).values({
id: skillId,
companyId,
key: "github.com/acme/remote-skill",
slug: "remote-skill",
name: "Remote Skill",
description: null,
markdown: "# Remote Skill\n",
sourceType: "github",
sourceLocator: "https://github.com/acme/remote-skill",
sourceRef: "main",
trustLevel: "markdown_only",
compatibility: "compatible",
fileInventory: [{ path: "SKILL.md", kind: "skill" }],
metadata: { sourceKind: "github", owner: "acme", repo: "remote-skill" },
});
await expect(svc.auditSkill(companyId, skillId)).rejects.toMatchObject({
status: 422,
message: "Only local-path and catalog-managed company skills support audit.",
});
await expect(svc.getById(companyId, skillId)).resolves.toMatchObject({
metadata: { sourceKind: "github", owner: "acme", repo: "remote-skill" },
});
});
it("preserves missing local-path skills that active agents still desire", async () => {
const companyId = randomUUID();
const skillId = randomUUID();
const skillKey = `company/${companyId}/reflection-coach`;
const missingSkillDir = path.join(await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-missing-used-skill-")), "gone");
cleanupDirs.add(path.dirname(missingSkillDir));
await db.insert(companies).values({
id: companyId,
name: "Paperclip",
issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
requireBoardApprovalForNewAgents: false,
});
await db.insert(companySkills).values({
id: skillId,
companyId,
key: skillKey,
slug: "reflection-coach",
name: "Reflection Coach",
description: null,
markdown: "# Reflection Coach\n",
sourceType: "local_path",
sourceLocator: missingSkillDir,
trustLevel: "markdown_only",
compatibility: "compatible",
fileInventory: [{ path: "SKILL.md", kind: "skill" }],
metadata: { sourceKind: "local_path" },
});
await db.insert(agents).values({
id: randomUUID(),
companyId,
name: "Reviewer",
role: "engineer",
status: "active",
adapterType: "codex_local",
adapterConfig: {
paperclipSkillSync: {
desiredSkills: [skillKey],
},
},
});
const listed = await svc.list(companyId);
const listedSkill = listed.find((skill) => skill.id === skillId);
const detail = await svc.detail(companyId, skillId);
const stored = await svc.getById(companyId, skillId);
const marker = stored?.metadata?.missingSource;
expect(listedSkill).toMatchObject({
id: skillId,
attachedAgentCount: 1,
});
expect(detail?.usedByAgents).toEqual([
expect.objectContaining({
name: "Reviewer",
desired: true,
}),
]);
expect(marker).toMatchObject({
reason: "local_source_missing",
sourceType: "local_path",
sourceLocator: missingSkillDir,
sourcePath: missingSkillDir,
});
expect(Number.isNaN(Date.parse(String((marker as Record<string, unknown>).detectedAt)))).toBe(false);
});
it("continues pruning missing local-path skills that no active agent desires", async () => {
const companyId = randomUUID();
const skillId = randomUUID();
const missingSkillDir = path.join(await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-missing-unused-skill-")), "gone");
cleanupDirs.add(path.dirname(missingSkillDir));
await db.insert(companies).values({
id: companyId,
name: "Paperclip",
issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
requireBoardApprovalForNewAgents: false,
});
await db.insert(companySkills).values({
id: skillId,
companyId,
key: `company/${companyId}/unused-skill`,
slug: "unused-skill",
name: "Unused Skill",
description: null,
markdown: "# Unused Skill\n",
sourceType: "local_path",
sourceLocator: missingSkillDir,
trustLevel: "markdown_only",
compatibility: "compatible",
fileInventory: [{ path: "SKILL.md", kind: "skill" }],
metadata: { sourceKind: "local_path" },
});
const listed = await svc.list(companyId);
expect(listed.find((skill) => skill.id === skillId)).toBeUndefined();
await expect(svc.getById(companyId, skillId)).resolves.toBeNull();
});
it("clears the missing-source marker when a local-path skill source returns", async () => {
const companyId = randomUUID();
const skillId = randomUUID();
const skillDir = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-restored-skill-"));
cleanupDirs.add(skillDir);
await fs.writeFile(path.join(skillDir, "SKILL.md"), "# Restored Skill\n", "utf8");
await db.insert(companies).values({
id: companyId,
name: "Paperclip",
issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
requireBoardApprovalForNewAgents: false,
});
await db.insert(companySkills).values({
id: skillId,
companyId,
key: `company/${companyId}/restored-skill`,
slug: "restored-skill",
name: "Restored Skill",
description: null,
markdown: "# Restored Skill\n",
sourceType: "local_path",
sourceLocator: skillDir,
trustLevel: "markdown_only",
compatibility: "compatible",
fileInventory: [{ path: "SKILL.md", kind: "skill" }],
metadata: {
sourceKind: "local_path",
missingSource: {
reason: "local_source_missing",
sourceType: "local_path",
sourceLocator: skillDir,
sourcePath: skillDir,
detectedAt: "2026-05-28T00:00:00.000Z",
},
},
});
await svc.list(companyId);
const stored = await svc.getById(companyId, skillId);
expect(stored?.metadata).toEqual({ sourceKind: "local_path" });
});
it("marks source-missing company skills as unavailable during read-only runtime listing", async () => {
const companyId = randomUUID();
const skillId = randomUUID();
const skillKey = `company/${companyId}/reflection-coach`;
const missingSkillDir = path.join(await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-readonly-missing-skill-")), "gone");
cleanupDirs.add(path.dirname(missingSkillDir));
await db.insert(companies).values({
id: companyId,
name: "Paperclip",
issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
requireBoardApprovalForNewAgents: false,
});
await db.insert(companySkills).values({
id: skillId,
companyId,
key: skillKey,
slug: "reflection-coach",
name: "Reflection Coach",
description: null,
markdown: "# Reflection Coach\n",
sourceType: "local_path",
sourceLocator: missingSkillDir,
trustLevel: "markdown_only",
compatibility: "compatible",
fileInventory: [{ path: "SKILL.md", kind: "skill" }],
metadata: { sourceKind: "local_path" },
});
await db.insert(agents).values({
id: randomUUID(),
companyId,
name: "Reviewer",
role: "engineer",
status: "active",
adapterType: "codex_local",
adapterConfig: {
paperclipSkillSync: {
desiredSkills: [skillKey],
},
},
});
const entries = await svc.listRuntimeSkillEntries(companyId, { materializeMissing: false });
const entry = entries.find((candidate) => candidate.key === skillKey);
expect(entry).toMatchObject({
key: skillKey,
sourceStatus: "missing",
missingDetail: expect.stringContaining(missingSkillDir),
});
await expect(fs.stat(entry!.source)).rejects.toMatchObject({ code: "ENOENT" });
});
it("materializes source-missing company skills from the stored markdown during runtime listing", async () => {
const companyId = randomUUID();
const skillId = randomUUID();
const skillKey = `company/${companyId}/runtime-coach`;
const missingSkillDir = path.join(await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-runtime-missing-skill-")), "gone");
cleanupDirs.add(path.dirname(missingSkillDir));
await db.insert(companies).values({
id: companyId,
name: "Paperclip",
issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
requireBoardApprovalForNewAgents: false,
});
await db.insert(companySkills).values({
id: skillId,
companyId,
key: skillKey,
slug: "runtime-coach",
name: "Runtime Coach",
description: null,
markdown: "# Runtime Coach\n\nRecovered from DB.\n",
sourceType: "local_path",
sourceLocator: missingSkillDir,
trustLevel: "markdown_only",
compatibility: "compatible",
fileInventory: [{ path: "SKILL.md", kind: "skill" }],
metadata: { sourceKind: "local_path" },
});
await db.insert(agents).values({
id: randomUUID(),
companyId,
name: "Runner",
role: "engineer",
status: "active",
adapterType: "codex_local",
adapterConfig: {
paperclipSkillSync: {
desiredSkills: [skillKey],
},
},
});
const entries = await svc.listRuntimeSkillEntries(companyId);
const entry = entries.find((candidate) => candidate.key === skillKey);
expect(entry).toMatchObject({
key: skillKey,
sourceStatus: "available",
});
await expect(fs.readFile(path.join(entry!.source, "SKILL.md"), "utf8")).resolves.toBe(
"# Runtime Coach\n\nRecovered from DB.\n",
);
});
});
server/src/__tests__/dev-runner-worktree.test.ts
+36
View File
@@ -63,6 +63,42 @@ describe("dev-runner worktree env bootstrap", () => {
expect(env.PAPERCLIP_OPTIONAL).toBe("");
});
it("repairs stale migrated config paths before loading worktree env", () => {
const root = createTempRoot("paperclip-dev-runner-worktree-migrated-env-");
const localConfigPath = path.join(root, ".paperclip", "config.json");
const worktreesDir = path.join(root, ".paperclip-worktrees");
fs.mkdirSync(path.dirname(localConfigPath), { recursive: true });
fs.writeFileSync(path.join(root, ".git"), "gitdir: /tmp/paperclip/.git/worktrees/feature\n", "utf8");
fs.writeFileSync(localConfigPath, "{}\n", "utf8");
fs.writeFileSync(
resolveWorktreeEnvFilePath(root),
[
"PAPERCLIP_HOME=/old/home/.paperclip-worktrees",
"PAPERCLIP_INSTANCE_ID=feature-worktree",
"PAPERCLIP_CONFIG=/old/home/paperclip/.paperclip/worktrees/feature/.paperclip/config.json",
"PAPERCLIP_CONTEXT=/old/home/.paperclip-worktrees/context.json",
"PAPERCLIP_IN_WORKTREE=true",
"PAPERCLIP_WORKTREE_NAME=feature-worktree",
"",
].join("\n"),
"utf8",
);
const env: NodeJS.ProcessEnv = {
PAPERCLIP_WORKTREES_DIR: worktreesDir,
};
const result = bootstrapDevRunnerWorktreeEnv(root, env);
expect(result).toEqual({
envPath: resolveWorktreeEnvFilePath(root),
missingEnv: false,
});
expect(env.PAPERCLIP_HOME).toBe(worktreesDir);
expect(env.PAPERCLIP_CONFIG).toBe(localConfigPath);
expect(env.PAPERCLIP_CONTEXT).toBe(path.join(worktreesDir, "context.json"));
expect(env.PAPERCLIP_INSTANCE_ID).toBe("feature-worktree");
});
it("reports uninitialized linked worktrees so dev runner can fail fast", () => {
const root = createTempRoot("paperclip-dev-runner-worktree-missing-");
fs.writeFileSync(path.join(root, ".git"), "gitdir: /tmp/paperclip/.git/worktrees/feature\n", "utf8");
server/src/__tests__/document-annotation-routes.test.ts
+288
View File
@@ -0,0 +1,288 @@
import express from "express";
import request from "supertest";
import { beforeEach, describe, expect, it, vi } from "vitest";
const issueId = "11111111-1111-4111-8111-111111111111";
const companyId = "22222222-2222-4222-8222-222222222222";
const otherCompanyId = "33333333-3333-4333-8333-333333333333";
const mockIssueService = vi.hoisted(() => ({
getById: vi.fn(),
assertCheckoutOwner: vi.fn(),
}));
const mockDocumentService = vi.hoisted(() => ({
getIssueDocumentByKey: vi.fn(),
}));
const mockAnnotationService = vi.hoisted(() => ({
listThreadsForIssueDocument: vi.fn(),
getThreadForIssueDocument: vi.fn(),
createThread: vi.fn(),
addComment: vi.fn(),
updateThread: vi.fn(),
remapOpenThreadsForDocument: vi.fn(),
}));
const mockIssueReferenceService = vi.hoisted(() => ({
diffIssueReferenceSummary: vi.fn(() => ({
addedReferencedIssues: [],
removedReferencedIssues: [],
currentReferencedIssues: [],
})),
emptySummary: vi.fn(() => ({ outbound: [], inbound: [] })),
listIssueReferenceSummary: vi.fn(async () => ({ outbound: [], inbound: [] })),
syncAnnotationComment: vi.fn(async () => undefined),
syncComment: vi.fn(async () => undefined),
syncDocument: vi.fn(async () => undefined),
syncIssue: vi.fn(async () => undefined),
}));
const mockHeartbeatService = vi.hoisted(() => ({
wakeup: vi.fn(async () => undefined),
reportRunActivity: vi.fn(async () => undefined),
}));
const mockLogActivity = vi.hoisted(() => vi.fn(async () => undefined));
const documentPayload = {
id: "document-1",
companyId,
issueId,
key: "plan",
title: "Plan",
format: "markdown",
body: "Alpha selected text omega",
latestRevisionId: "44444444-4444-4444-8444-444444444444",
latestRevisionNumber: 1,
createdByAgentId: null,
createdByUserId: "board-user",
updatedByAgentId: null,
updatedByUserId: "board-user",
createdAt: new Date("2026-05-14T12:00:00.000Z"),
updatedAt: new Date("2026-05-14T12:00:00.000Z"),
};
const annotationThread = {
id: "55555555-5555-4555-8555-555555555555",
companyId,
issueId,
documentId: "document-1",
documentKey: "plan",
status: "open",
anchorState: "active",
anchorConfidence: "exact",
originalRevisionId: documentPayload.latestRevisionId,
originalRevisionNumber: 1,
currentRevisionId: documentPayload.latestRevisionId,
currentRevisionNumber: 1,
selectedText: "selected text",
prefixText: "Alpha ",
suffixText: " omega",
normalizedStart: 6,
normalizedEnd: 19,
markdownStart: 6,
markdownEnd: 19,
anchorSelector: {
quote: { exact: "selected text", prefix: "Alpha ", suffix: " omega" },
position: { normalizedStart: 6, normalizedEnd: 19, markdownStart: 6, markdownEnd: 19 },
},
createdByAgentId: null,
createdByUserId: "board-user",
resolvedByAgentId: null,
resolvedByUserId: null,
resolvedAt: null,
createdAt: new Date("2026-05-14T12:01:00.000Z"),
updatedAt: new Date("2026-05-14T12:01:00.000Z"),
};
const annotationComment = {
id: "66666666-6666-4666-8666-666666666666",
companyId,
threadId: annotationThread.id,
issueId,
documentId: "document-1",
body: "Please review PAP-1",
authorType: "user",
authorAgentId: null,
authorUserId: "board-user",
createdByRunId: null,
createdAt: new Date("2026-05-14T12:01:00.000Z"),
updatedAt: new Date("2026-05-14T12:01:00.000Z"),
};
function registerModuleMocks() {
vi.doMock("../services/index.js", () => ({
accessService: () => ({ canUser: vi.fn(), hasPermission: vi.fn(async () => false) }),
agentService: () => ({ getById: vi.fn(), list: vi.fn(async () => []) }),
companyService: () => ({ getById: vi.fn(async () => ({ id: companyId, attachmentMaxBytes: 10_000_000 })) }),
documentAnnotationService: () => mockAnnotationService,
documentService: () => mockDocumentService,
environmentService: () => ({}),
executionWorkspaceService: () => ({}),
feedbackService: () => ({}),
goalService: () => ({}),
heartbeatService: () => mockHeartbeatService,
instanceSettingsService: () => ({
get: vi.fn(async () => ({ id: "settings", general: {} })),
getExperimental: vi.fn(async () => ({})),
getGeneral: vi.fn(async () => ({})),
listCompanyIds: vi.fn(async () => [companyId]),
}),
issueApprovalService: () => ({}),
issueRecoveryActionService: () => ({
getActiveForIssue: vi.fn(async () => null),
listActiveForIssues: vi.fn(async () => new Map()),
}),
issueReferenceService: () => mockIssueReferenceService,
issueService: () => mockIssueService,
issueThreadInteractionService: () => ({
expireRequestConfirmationsSupersededByComment: vi.fn(async () => []),
expireStaleRequestConfirmationsForIssueDocument: vi.fn(async () => []),
}),
logActivity: mockLogActivity,
projectService: () => ({}),
routineService: () => ({ syncRunStatusForIssue: vi.fn(async () => undefined) }),
workProductService: () => ({}),
}));
}
async function createApp(actor: "board" | "agent" = "board", actorCompanyId = companyId) {
const [{ issueRoutes }, { errorHandler }] = await Promise.all([
vi.importActual<typeof import("../routes/issues.js")>("../routes/issues.js"),
vi.importActual<typeof import("../middleware/index.js")>("../middleware/index.js"),
]);
const app = express();
app.use(express.json());
app.use((req, _res, next) => {
(req as any).actor = actor === "agent"
? {
type: "agent",
agentId: "77777777-7777-4777-8777-777777777777",
companyId: actorCompanyId,
runId: "88888888-8888-4888-8888-888888888888",
}
: {
type: "board",
userId: "board-user",
companyIds: [actorCompanyId],
source: "local_implicit",
isInstanceAdmin: false,
};
next();
});
app.use("/api", issueRoutes({} as any, {} as any));
app.use(errorHandler);
return app;
}
describe("document annotation routes", () => {
beforeEach(() => {
vi.resetModules();
vi.doUnmock("../routes/issues.js");
vi.doUnmock("../middleware/index.js");
registerModuleMocks();
vi.clearAllMocks();
mockIssueService.getById.mockResolvedValue({
id: issueId,
companyId,
title: "Annotation API",
status: "in_progress",
assigneeAgentId: null,
});
mockIssueService.assertCheckoutOwner.mockResolvedValue({});
mockDocumentService.getIssueDocumentByKey.mockResolvedValue(documentPayload);
mockAnnotationService.listThreadsForIssueDocument.mockImplementation(async (
_issueId: string,
_key: string,
options?: { includeComments?: boolean },
) => (
options?.includeComments
? [{ ...annotationThread, comments: [annotationComment] }]
: [annotationThread]
));
mockAnnotationService.getThreadForIssueDocument.mockResolvedValue({ ...annotationThread, comments: [annotationComment] });
mockAnnotationService.createThread.mockResolvedValue({ ...annotationThread, comments: [annotationComment] });
mockAnnotationService.addComment.mockResolvedValue(annotationComment);
mockAnnotationService.updateThread.mockResolvedValue({ ...annotationThread, status: "resolved" });
mockAnnotationService.remapOpenThreadsForDocument.mockResolvedValue([]);
});
it("includes compact open annotations without comment bodies by default for agent document reads", async () => {
const res = await request(await createApp("agent"))
.get(`/api/issues/${issueId}/documents/plan`)
.expect(200);
expect(res.body.annotations).toHaveLength(1);
expect(res.body.annotations[0].comments).toBeUndefined();
expect(mockAnnotationService.listThreadsForIssueDocument).toHaveBeenCalledWith(issueId, "plan", {
status: "open",
includeComments: false,
});
});
it("includes annotation comment bodies on document reads only when explicitly requested", async () => {
const res = await request(await createApp("agent"))
.get(`/api/issues/${issueId}/documents/plan?includeAnnotationComments=true`)
.expect(200);
expect(res.body.annotations[0].comments[0].body).toBe("Please review PAP-1");
expect(mockAnnotationService.listThreadsForIssueDocument).toHaveBeenCalledWith(issueId, "plan", {
status: "open",
includeComments: true,
});
});
it("creates annotation threads, syncs references, logs activity, and wakes the assignee", async () => {
mockIssueService.getById.mockResolvedValue({
id: issueId,
companyId,
title: "Annotation API",
status: "todo",
assigneeAgentId: "99999999-9999-4999-8999-999999999999",
});
const res = await request(await createApp())
.post(`/api/issues/${issueId}/documents/plan/annotations`)
.send({
baseRevisionId: documentPayload.latestRevisionId,
baseRevisionNumber: 1,
selector: annotationThread.anchorSelector,
body: "Please review PAP-1",
})
.expect(201);
expect(res.body.id).toBe(annotationThread.id);
expect(mockIssueReferenceService.syncAnnotationComment).toHaveBeenCalledWith(annotationComment.id);
expect(mockLogActivity).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({
action: "issue.document_annotation_thread_created",
}));
expect(mockHeartbeatService.wakeup).toHaveBeenCalledWith(
"99999999-9999-4999-8999-999999999999",
expect.objectContaining({
payload: expect.objectContaining({
annotationThreadId: annotationThread.id,
annotationCommentId: annotationComment.id,
}),
}),
);
});
it("rejects agent cross-company annotation reads", async () => {
await request(await createApp("agent", otherCompanyId))
.get(`/api/issues/${issueId}/documents/plan/annotations`)
.expect(403);
});
it("adds annotation comments and resolves threads", async () => {
await request(await createApp())
.post(`/api/issues/${issueId}/documents/plan/annotations/${annotationThread.id}/comments`)
.send({ body: "Reply with PAP-2" })
.expect(201);
expect(mockIssueReferenceService.syncAnnotationComment).toHaveBeenCalledWith(annotationComment.id);
const resolved = await request(await createApp())
.patch(`/api/issues/${issueId}/documents/plan/annotations/${annotationThread.id}`)
.send({ status: "resolved" })
.expect(200);
expect(resolved.body.status).toBe("resolved");
expect(mockLogActivity).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({
action: "issue.document_annotation_thread_resolved",
}));
});
});
server/src/__tests__/document-annotations-service.test.ts
+183
View File
@@ -0,0 +1,183 @@
import { randomUUID } from "node:crypto";
import { eq } from "drizzle-orm";
import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
import {
companies,
createDb,
documentAnnotationAnchorSnapshots,
documentAnnotationComments,
documentAnnotationThreads,
documentRevisions,
documents,
issueDocuments,
issues,
} from "@paperclipai/db";
import {
getEmbeddedPostgresTestSupport,
startEmbeddedPostgresTestDatabase,
} from "./helpers/embedded-postgres.js";
import { documentAnnotationService } from "../services/document-annotations.js";
import { documentService } from "../services/documents.js";
const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
if (!embeddedPostgresSupport.supported) {
console.warn(
`Skipping embedded Postgres document annotation service tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
);
}
function deferred<T>() {
let resolve!: (value: T | PromiseLike<T>) => void;
let reject!: (reason?: unknown) => void;
const promise = new Promise<T>((promiseResolve, promiseReject) => {
resolve = promiseResolve;
reject = promiseReject;
});
return { promise, resolve, reject };
}
describeEmbeddedPostgres("documentAnnotationService", () => {
let db!: ReturnType<typeof createDb>;
let annotations!: ReturnType<typeof documentAnnotationService>;
let docs!: ReturnType<typeof documentService>;
let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
beforeAll(async () => {
tempDb = await startEmbeddedPostgresTestDatabase("paperclip-document-annotations-");
db = createDb(tempDb.connectionString);
annotations = documentAnnotationService(db);
docs = documentService(db);
}, 20_000);
afterEach(async () => {
await db.delete(documentAnnotationAnchorSnapshots);
await db.delete(documentAnnotationComments);
await db.delete(documentAnnotationThreads);
await db.delete(documentRevisions);
await db.delete(issueDocuments);
await db.delete(documents);
await db.delete(issues);
await db.delete(companies);
});
afterAll(async () => {
await tempDb?.cleanup();
});
async function createIssueWithDocument() {
const companyId = randomUUID();
const issueId = randomUUID();
await db.insert(companies).values({
id: companyId,
name: "Paperclip",
issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
requireBoardApprovalForNewAgents: false,
});
await db.insert(issues).values({
id: issueId,
companyId,
identifier: "PAP-9442",
title: "Annotation race",
description: "Validate annotation revision guards",
status: "in_progress",
priority: "high",
});
const created = await docs.upsertIssueDocument({
issueId,
key: "plan",
title: "Plan",
format: "markdown",
body: "Alpha selected text omega",
});
return { companyId, issueId, document: created.document };
}
it("fails closed when a concurrent document update wins before annotation thread creation commits", async () => {
const { companyId, issueId, document } = await createIssueWithDocument();
const concurrentUpdateCanCommit = deferred<void>();
const concurrentUpdateHasWritten = deferred<void>();
const concurrentUpdate = db.transaction(async (tx) => {
const now = new Date();
const [revision] = await tx
.insert(documentRevisions)
.values({
companyId,
documentId: document.id,
revisionNumber: document.latestRevisionNumber + 1,
title: "Plan",
format: "markdown",
body: "Alpha changed text omega",
changeSummary: "Concurrent edit",
createdAt: now,
})
.returning();
await tx
.update(documents)
.set({
latestBody: "Alpha changed text omega",
latestRevisionId: revision.id,
latestRevisionNumber: document.latestRevisionNumber + 1,
updatedAt: now,
})
.where(eq(documents.id, document.id));
concurrentUpdateHasWritten.resolve();
await concurrentUpdateCanCommit.promise;
});
await concurrentUpdateHasWritten.promise;
let annotationSettled = false;
const annotationResult = annotations
.createThread(
issueId,
"plan",
{
baseRevisionId: document.latestRevisionId!,
baseRevisionNumber: document.latestRevisionNumber,
selector: {
quote: { exact: "selected text", prefix: "Alpha ", suffix: " omega" },
position: { normalizedStart: 6, normalizedEnd: 19, markdownStart: 6, markdownEnd: 19 },
},
body: "Please review this text",
},
{ actorType: "user", actorId: "board-user", userId: "board-user" },
)
.then(
() => ({ status: "fulfilled" as const }),
(error: unknown) => ({ status: "rejected" as const, error }),
)
.finally(() => {
annotationSettled = true;
});
await new Promise((resolve) => setTimeout(resolve, 50));
expect(annotationSettled).toBe(false);
concurrentUpdateCanCommit.resolve();
await concurrentUpdate;
const result = await annotationResult;
expect(result.status).toBe("rejected");
if (result.status === "rejected") {
expect(result.error).toMatchObject({
status: 409,
message: "Annotation anchor requires the current document revision",
details: {
currentRevisionNumber: 2,
},
});
}
const threads = await db.select().from(documentAnnotationThreads);
expect(threads).toHaveLength(0);
});
});
server/src/__tests__/environment-selection-route-guards.test.ts
+1
View File
@@ -90,6 +90,7 @@ vi.mock("../services/index.js", () => ({
expireStaleRequestConfirmationsForIssueDocument: vi.fn(async () => []),
}),
documentService: () => ({}),
documentAnnotationService: () => ({ remapOpenThreadsForDocument: async () => [] }),
routineService: () => ({}),
workProductService: () => ({}),
}));
server/src/__tests__/execution-workspaces-service.test.ts
+77
View File
@@ -343,6 +343,83 @@ describeEmbeddedPostgres("executionWorkspaceService.getCloseReadiness", () => {
expect(readExecutionWorkspaceConfig(byId.get(untouchedWorkspaceId) ?? null)).toBeNull();
});
it("limits reusable summaries to open non-shared execution workspaces", async () => {
const companyId = randomUUID();
const projectId = randomUUID();
const openWorkspaceId = randomUUID();
const sharedWorkspaceId = randomUUID();
const closedWorkspaceId = randomUUID();
await db.insert(companies).values({
id: companyId,
name: "Paperclip",
issuePrefix: "PAP",
requireBoardApprovalForNewAgents: false,
});
await db.insert(projects).values({
id: projectId,
companyId,
name: "Reusable workspaces",
status: "in_progress",
executionWorkspacePolicy: {
enabled: true,
},
});
await db.insert(executionWorkspaces).values([
{
id: openWorkspaceId,
companyId,
projectId,
mode: "isolated_workspace",
strategyType: "git_worktree",
name: "Open isolated workspace",
status: "idle",
providerType: "git_worktree",
cwd: "/tmp/open-workspace",
branchName: "paperclip/open",
},
{
id: sharedWorkspaceId,
companyId,
projectId,
mode: "shared_workspace",
strategyType: "project_primary",
name: "Shared session",
status: "active",
providerType: "local_fs",
cwd: "/tmp/project-primary",
},
{
id: closedWorkspaceId,
companyId,
projectId,
mode: "isolated_workspace",
strategyType: "git_worktree",
name: "Closed isolated workspace",
status: "active",
providerType: "git_worktree",
cwd: "/tmp/closed-workspace",
closedAt: new Date("2026-05-23T20:00:00.000Z"),
},
]);
const summaries = await svc.listSummaries(companyId, {
projectId,
reuseEligible: true,
});
expect(summaries).toEqual([
expect.objectContaining({
id: openWorkspaceId,
name: "Open isolated workspace",
mode: "isolated_workspace",
status: "idle",
cwd: "/tmp/open-workspace",
branchName: "paperclip/open",
}),
]);
});
it("warns about dirty and unmerged git worktrees and reports cleanup actions", async () => {
const repoRoot = await createTempRepo();
tempDirs.add(repoRoot);
server/src/__tests__/first-admin-claim.test.ts
+56
View File
@@ -0,0 +1,56 @@
import { randomUUID } from "node:crypto";
import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
import { createDb, instanceUserRoles } from "@paperclipai/db";
import {
getEmbeddedPostgresTestSupport,
startEmbeddedPostgresTestDatabase,
} from "./helpers/embedded-postgres.js";
import { claimFirstInstanceAdmin } from "../first-admin-claim.js";
const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
describeEmbeddedPostgres("claimFirstInstanceAdmin", () => {
let db!: ReturnType<typeof createDb>;
let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
beforeAll(async () => {
tempDb = await startEmbeddedPostgresTestDatabase("paperclip-first-admin-claim-");
db = createDb(tempDb.connectionString);
}, 20_000);
afterEach(async () => {
await db.delete(instanceUserRoles);
});
afterAll(async () => {
await tempDb?.cleanup();
});
it("inserts exactly one first admin and reports later claims as conflicts", async () => {
const firstUserId = `user-${randomUUID()}`;
const first = await claimFirstInstanceAdmin(db, { userId: firstUserId });
expect(first).toMatchObject({ status: "claimed", userId: firstUserId });
const second = await claimFirstInstanceAdmin(db, { userId: `user-${randomUUID()}` });
expect(second).toMatchObject({ status: "already_claimed", existingUserId: firstUserId });
const roles = await db.select().from(instanceUserRoles);
expect(roles).toHaveLength(1);
expect(roles[0]).toMatchObject({ userId: firstUserId, role: "instance_admin" });
});
it("runs onClaim inside the winning transaction", async () => {
const userId = `user-${randomUUID()}`;
const result = await claimFirstInstanceAdmin(db, {
userId,
onClaim: async (tx) => {
const roles = await tx.select().from(instanceUserRoles);
return roles.map((role) => role.userId);
},
});
expect(result).toMatchObject({ status: "claimed", userId, value: [userId] });
});
});
server/src/__tests__/grok-local-skill-sync.test.ts
+59
View File
@@ -0,0 +1,59 @@
import { describe, expect, it } from "vitest";
import {
listGrokSkills,
syncGrokSkills,
} from "@paperclipai/adapter-grok-local/server";
describe("grok local skill sync", () => {
const paperclipKey = "paperclipai/paperclip/paperclip";
const createAgentKey = "paperclipai/paperclip/paperclip-create-agent";
it("reports Grok skills as ephemeral workspace-mounted state", async () => {
const snapshot = await listGrokSkills({
agentId: "agent-1",
companyId: "company-1",
adapterType: "grok_local",
config: {
paperclipSkillSync: {
desiredSkills: [paperclipKey],
},
},
});
expect(snapshot.adapterType).toBe("grok_local");
expect(snapshot.supported).toBe(true);
expect(snapshot.mode).toBe("ephemeral");
expect(snapshot.desiredSkills).toContain(paperclipKey);
expect(snapshot.desiredSkills).toContain(createAgentKey);
expect(snapshot.entries.find((entry) => entry.key === paperclipKey)).toMatchObject({
required: true,
state: "configured",
detail: "Will be copied into `.claude/skills` in the execution workspace on the next run.",
});
});
it("tracks unavailable desired Grok skills as missing without persistent install state", async () => {
const snapshot = await syncGrokSkills({
agentId: "agent-2",
companyId: "company-1",
adapterType: "grok_local",
config: {
paperclipRuntimeSkills: [],
paperclipSkillSync: {
desiredSkills: ["unknown-skill"],
},
},
}, ["unknown-skill"]);
expect(snapshot.mode).toBe("ephemeral");
expect(snapshot.warnings).toContain(
'Desired skill "unknown-skill" is not available from the Paperclip skills directory.',
);
expect(snapshot.entries).toContainEqual(expect.objectContaining({
key: "unknown-skill",
state: "missing",
origin: "external_unknown",
targetPath: null,
}));
});
});
Loaded 100 of 220 files, more files were not shown because too many files have changed in this diff. Show more