mirror of
https://github.com/alkimake/paperclip.git
synced 2026-06-17 11:20:37 +09:00
[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
GitHub
parent
8da50dbcf8
commit
9eac727cf1
77 changed files with 9704 additions and 530 deletions
|
|
@ -1217,9 +1217,13 @@ export function agentRoutes(
|
|||
companyId: string,
|
||||
adapterType: string,
|
||||
config: Record<string, unknown>,
|
||||
options: {
|
||||
materializeMissing?: boolean;
|
||||
} = {},
|
||||
) {
|
||||
const runtimeSkillEntries = await companySkills.listRuntimeSkillEntries(companyId, {
|
||||
materializeMissing: shouldMaterializeRuntimeSkillsForAdapter(adapterType),
|
||||
materializeMissing: options.materializeMissing
|
||||
?? shouldMaterializeRuntimeSkillsForAdapter(adapterType),
|
||||
});
|
||||
return {
|
||||
...config,
|
||||
|
|
@ -1486,6 +1490,7 @@ export function agentRoutes(
|
|||
agent.companyId,
|
||||
agent.adapterType,
|
||||
runtimeConfig,
|
||||
{ materializeMissing: false },
|
||||
);
|
||||
const snapshot = await adapter.listSkills({
|
||||
agentId: agent.id,
|
||||
|
|
|
|||
|
|
@ -1,16 +1,21 @@
|
|||
import { Router, type Request } from "express";
|
||||
import type { Db } from "@paperclipai/db";
|
||||
import {
|
||||
catalogSkillListQuerySchema,
|
||||
companySkillCreateSchema,
|
||||
companySkillFileUpdateSchema,
|
||||
companySkillImportSchema,
|
||||
companySkillInstallCatalogSchema,
|
||||
companySkillInstallUpdateSchema,
|
||||
companySkillProjectScanRequestSchema,
|
||||
companySkillResetSchema,
|
||||
} from "@paperclipai/shared";
|
||||
import { trackSkillImported } from "@paperclipai/shared/telemetry";
|
||||
import { validate } from "../middleware/validate.js";
|
||||
import { accessService, agentService, companySkillService, logActivity } from "../services/index.js";
|
||||
import { getCatalogSkillOrThrow, listCatalogSkills, readCatalogSkillFile } from "../services/skills-catalog.js";
|
||||
import { forbidden } from "../errors.js";
|
||||
import { assertCompanyAccess, getActorInfo } from "./authz.js";
|
||||
import { assertAuthenticated, assertCompanyAccess, getActorInfo } from "./authz.js";
|
||||
import { getTelemetryClient } from "../telemetry.js";
|
||||
|
||||
type SkillTelemetryInput = {
|
||||
|
|
@ -52,6 +57,12 @@ export function companySkillRoutes(db: Db) {
|
|||
return skill.key;
|
||||
}
|
||||
|
||||
function firstQueryString(value: unknown): string | undefined {
|
||||
if (typeof value === "string") return value;
|
||||
if (Array.isArray(value) && typeof value[0] === "string") return value[0];
|
||||
return undefined;
|
||||
}
|
||||
|
||||
async function assertCanMutateCompanySkills(req: Request, companyId: string) {
|
||||
assertCompanyAccess(req, companyId);
|
||||
|
||||
|
|
@ -81,6 +92,29 @@ export function companySkillRoutes(db: Db) {
|
|||
throw forbidden("Missing permission: can create agents");
|
||||
}
|
||||
|
||||
router.get("/skills/catalog", async (req, res) => {
|
||||
assertAuthenticated(req);
|
||||
const query = catalogSkillListQuerySchema.parse({
|
||||
kind: firstQueryString(req.query.kind),
|
||||
category: firstQueryString(req.query.category),
|
||||
q: firstQueryString(req.query.q),
|
||||
});
|
||||
res.json(listCatalogSkills(query));
|
||||
});
|
||||
|
||||
router.get("/skills/catalog/:catalogId/files", async (req, res) => {
|
||||
assertAuthenticated(req);
|
||||
const catalogRef = firstQueryString(req.query.ref) ?? (req.params.catalogId as string);
|
||||
const relativePath = firstQueryString(req.query.path) ?? "SKILL.md";
|
||||
res.json(await readCatalogSkillFile(catalogRef, relativePath));
|
||||
});
|
||||
|
||||
router.get("/skills/catalog/:catalogId", async (req, res) => {
|
||||
assertAuthenticated(req);
|
||||
const catalogRef = firstQueryString(req.query.ref) ?? (req.params.catalogId as string);
|
||||
res.json(getCatalogSkillOrThrow(catalogRef));
|
||||
});
|
||||
|
||||
router.get("/companies/:companyId/skills", async (req, res) => {
|
||||
const companyId = req.params.companyId as string;
|
||||
assertCompanyAccess(req, companyId);
|
||||
|
|
@ -227,6 +261,38 @@ export function companySkillRoutes(db: Db) {
|
|||
},
|
||||
);
|
||||
|
||||
router.post(
|
||||
"/companies/:companyId/skills/install-catalog",
|
||||
validate(companySkillInstallCatalogSchema),
|
||||
async (req, res) => {
|
||||
const companyId = req.params.companyId as string;
|
||||
await assertCanMutateCompanySkills(req, companyId);
|
||||
const result = await svc.installFromCatalog(companyId, req.body);
|
||||
|
||||
const actor = getActorInfo(req);
|
||||
await logActivity(db, {
|
||||
companyId,
|
||||
actorType: actor.actorType,
|
||||
actorId: actor.actorId,
|
||||
agentId: actor.agentId,
|
||||
runId: actor.runId,
|
||||
action: result.action === "created" ? "company.skill_catalog_installed" : "company.skill_catalog_updated",
|
||||
entityType: "company_skill",
|
||||
entityId: result.skill.id,
|
||||
details: {
|
||||
action: result.action,
|
||||
catalogId: result.catalogSkill.id,
|
||||
catalogKey: result.catalogSkill.key,
|
||||
slug: result.skill.slug,
|
||||
originHash: result.catalogSkill.contentHash,
|
||||
warningCount: result.warnings.length,
|
||||
},
|
||||
});
|
||||
|
||||
res.status(result.action === "created" ? 201 : 200).json(result);
|
||||
},
|
||||
);
|
||||
|
||||
router.post(
|
||||
"/companies/:companyId/skills/scan-projects",
|
||||
validate(companySkillProjectScanRequestSchema),
|
||||
|
|
@ -289,34 +355,120 @@ export function companySkillRoutes(db: Db) {
|
|||
res.json(result);
|
||||
});
|
||||
|
||||
router.post("/companies/:companyId/skills/:skillId/install-update", async (req, res) => {
|
||||
const companyId = req.params.companyId as string;
|
||||
const skillId = req.params.skillId as string;
|
||||
await assertCanMutateCompanySkills(req, companyId);
|
||||
const result = await svc.installUpdate(companyId, skillId);
|
||||
if (!result) {
|
||||
res.status(404).json({ error: "Skill not found" });
|
||||
return;
|
||||
}
|
||||
router.post(
|
||||
"/companies/:companyId/skills/:skillId/audit",
|
||||
async (req, res) => {
|
||||
const companyId = req.params.companyId as string;
|
||||
const skillId = req.params.skillId as string;
|
||||
await assertCanMutateCompanySkills(req, companyId);
|
||||
const result = await svc.auditSkill(companyId, skillId);
|
||||
if (!result) {
|
||||
res.status(404).json({ error: "Skill not found" });
|
||||
return;
|
||||
}
|
||||
|
||||
const actor = getActorInfo(req);
|
||||
await logActivity(db, {
|
||||
companyId,
|
||||
actorType: actor.actorType,
|
||||
actorId: actor.actorId,
|
||||
agentId: actor.agentId,
|
||||
runId: actor.runId,
|
||||
action: "company.skill_update_installed",
|
||||
entityType: "company_skill",
|
||||
entityId: result.id,
|
||||
details: {
|
||||
slug: result.slug,
|
||||
sourceRef: result.sourceRef,
|
||||
},
|
||||
});
|
||||
const actor = getActorInfo(req);
|
||||
await logActivity(db, {
|
||||
companyId,
|
||||
actorType: actor.actorType,
|
||||
actorId: actor.actorId,
|
||||
agentId: actor.agentId,
|
||||
runId: actor.runId,
|
||||
action: "company.skill_audited",
|
||||
entityType: "company_skill",
|
||||
entityId: skillId,
|
||||
details: {
|
||||
verdict: result.verdict,
|
||||
codes: result.codes,
|
||||
installedHash: result.installedHash,
|
||||
originHash: result.originHash,
|
||||
scanVersion: result.scanVersion,
|
||||
},
|
||||
});
|
||||
|
||||
res.json(result);
|
||||
});
|
||||
res.json(result);
|
||||
},
|
||||
);
|
||||
|
||||
router.post(
|
||||
"/companies/:companyId/skills/:skillId/install-update",
|
||||
validate(companySkillInstallUpdateSchema),
|
||||
async (req, res) => {
|
||||
const companyId = req.params.companyId as string;
|
||||
const skillId = req.params.skillId as string;
|
||||
await assertCanMutateCompanySkills(req, companyId);
|
||||
const before = await svc.getById(companyId, skillId);
|
||||
const result = await svc.installUpdate(companyId, skillId, req.body);
|
||||
if (!result) {
|
||||
res.status(404).json({ error: "Skill not found" });
|
||||
return;
|
||||
}
|
||||
|
||||
const actor = getActorInfo(req);
|
||||
await logActivity(db, {
|
||||
companyId,
|
||||
actorType: actor.actorType,
|
||||
actorId: actor.actorId,
|
||||
agentId: actor.agentId,
|
||||
runId: actor.runId,
|
||||
action: "company.skill_update_installed",
|
||||
entityType: "company_skill",
|
||||
entityId: result.id,
|
||||
details: {
|
||||
slug: result.slug,
|
||||
previousOriginHash: before?.metadata?.originHash ?? before?.sourceRef ?? null,
|
||||
previousOriginVersion: before?.metadata?.originVersion ?? null,
|
||||
newOriginHash: result.metadata?.originHash ?? result.sourceRef,
|
||||
newOriginVersion: result.metadata?.originVersion ?? null,
|
||||
driftDetected: Boolean(before?.metadata?.userModifiedAt),
|
||||
force: Boolean(req.body.force),
|
||||
auditVerdict: result.metadata?.auditVerdict ?? null,
|
||||
},
|
||||
});
|
||||
|
||||
res.json(result);
|
||||
},
|
||||
);
|
||||
|
||||
router.post(
|
||||
"/companies/:companyId/skills/:skillId/reset",
|
||||
validate(companySkillResetSchema),
|
||||
async (req, res) => {
|
||||
const companyId = req.params.companyId as string;
|
||||
const skillId = req.params.skillId as string;
|
||||
await assertCanMutateCompanySkills(req, companyId);
|
||||
const before = await svc.getById(companyId, skillId);
|
||||
const result = await svc.resetSkill(companyId, skillId, req.body);
|
||||
if (!result) {
|
||||
res.status(404).json({ error: "Skill not found" });
|
||||
return;
|
||||
}
|
||||
|
||||
const actor = getActorInfo(req);
|
||||
await logActivity(db, {
|
||||
companyId,
|
||||
actorType: actor.actorType,
|
||||
actorId: actor.actorId,
|
||||
agentId: actor.agentId,
|
||||
runId: actor.runId,
|
||||
action: "company.skill_reset",
|
||||
entityType: "company_skill",
|
||||
entityId: result.id,
|
||||
details: {
|
||||
slug: result.slug,
|
||||
previousOriginHash: before?.metadata?.originHash ?? before?.sourceRef ?? null,
|
||||
previousOriginVersion: before?.metadata?.originVersion ?? null,
|
||||
newOriginHash: result.metadata?.originHash ?? result.sourceRef,
|
||||
newOriginVersion: result.metadata?.originVersion ?? null,
|
||||
driftDetected: Boolean(before?.metadata?.userModifiedAt),
|
||||
force: Boolean(req.body.force),
|
||||
auditVerdict: result.metadata?.auditVerdict ?? null,
|
||||
},
|
||||
});
|
||||
|
||||
res.json(result);
|
||||
},
|
||||
);
|
||||
|
||||
return router;
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue