forked from farhoodlabs/paperclip
[codex] Add skills CLI and catalog management (#6782)
## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies through company-scoped control-plane workflows. > - Agents need reusable, inspectable skills that can be installed, reset, audited, exported, and assigned without bespoke local setup. > - The existing skill truth model needed cleanup so bundled skills, optional catalog skills, runtime skills, and adapter-provided skills have clear provenance. > - Operators also need a practical CLI and board UI for discovering and managing company skills. > - This pull request adds the skills CLI, packaged skills catalog, company skills APIs, and catalog-aware board UI. > - The benefit is a more reusable Paperclip company setup where skills are portable, auditable, and easier for operators and agents to manage. ## What Changed - Added `paperclipai skills` CLI commands and coverage for catalog listing, installing, resetting, and inspecting company skills. - Added a packaged `@paperclipai/skills-catalog` workspace with bundled and optional skill content plus validation/build tests. - Added shared company-skill types and validators used across CLI, server, and UI contracts. - Added server catalog APIs/services for company skill catalog operations, reset semantics, audit behavior, and portability provenance. - Updated adapter skill handling so runtime/catalog provenance remains explicit across local adapters. - Added board UI support for browsing and managing catalog-backed company skills. - Updated docs for the skills CLI/catalog flow and the company skills Paperclip skill reference. - Rebased the branch onto current `paperclipai/paperclip:master`; no `pnpm-lock.yaml`, `.github/workflows`, or migration files are included in the final PR diff. ## Verification - Passed: `pnpm run preflight:workspace-links && pnpm exec vitest run cli/src/__tests__/skills.test.ts packages/skills-catalog/src/catalog-builder.test.ts packages/skills-catalog/src/shipped-catalog.test.ts packages/shared/src/validators/company-skill.test.ts packages/adapter-utils/src/server-utils.test.ts packages/plugins/create-paperclip-plugin/src/entrypoints.test.ts server/src/__tests__/company-skills-catalog-service.test.ts server/src/__tests__/company-skills-routes.test.ts server/src/__tests__/company-portability.test.ts`. - Passed: `pnpm exec vitest run server/src/__tests__/workspace-runtime.test.ts -t "default branch|origin/master|symbolic-ref"`. - Attempted: full `server/src/__tests__/workspace-runtime.test.ts`. Four provisioning tests failed while seeding an isolated worktree database from the local Paperclip instance because the local plugin schema dump contains a duplicate-column foreign key (`plugin_content_machine_18a7bc327b.content_case_signals`). The default-branch tests touched by the rebase conflict passed in the focused run above. - Checked final diff: no `pnpm-lock.yaml`, no `.github/workflows`, and no migration-file changes relative to `master`. ## Risks - Medium: this is a broad skills/catalog change touching CLI, server APIs, shared contracts, adapter skill sync, and UI. - Catalog validation and reset semantics need careful reviewer attention because they affect reusable company setup and portability. - No database migrations are included in this PR, so there is no migration ordering/idempotency risk in the final diff. - No lockfile is included by design; dependency resolution will be handled by the repository lockfile workflow. ## Model Used - OpenAI Codex coding agent based on GPT-5, running in Paperclip via the `codex_local` adapter with shell, git, GitHub CLI, and code-editing tool access. Exact hosted model build/context-window metadata is not exposed in this runtime. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have run targeted tests locally and documented the local workspace-runtime seed failure above - [x] I have added or updated tests where applicable - [x] If this change affects the UI, screenshots were intentionally omitted per PAP-10124 instructions; UI behavior is covered by tests and reviewer inspection - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Dotta
@@ -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",
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user