mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-21 02:43:25 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - A responsibility shows the skills of the agents doing its work. People cannot say which skills a responsibility needs. > - The maintainer chose to file skills under responsibilities like projects, tasks and routines. > - Agents also need to set a skill's catalog details without rewriting its SKILL.md. > - This pull request lets people and agents file, move and remove company skills under a responsibility, and adds `update_skill_details`. > - The benefit is that a responsibility lists the skills it needs, beside the skills its agents already hold. ## Linked Issues or Issue Description Refs #22253, #22261 and #22274; this pull request is stacked on them. **Subsystem affected** Database (`responsibility_links`), shared types and validators, server responsibility service and routes, Dashboard versions, native runner tools, and the responsibility page UI. **Problem or motivation** Skills under a responsibility are only computed from the agents doing its work. A person cannot record that "Hiring needs interviewing", and an agent cannot file a skill when it maps work for a person. **Proposed solution** Add a nullable `skill_id` to `responsibility_links` and allow it as the one target of a link. Show filed and computed skills together. Let the file, unfile, lookup and link routes and tools take skills. Keep filed skills in Dashboard versions so undo covers them. Add a small live tool for a skill's tagline and categories. **Alternatives considered** Keeping skills computed only, and giving the skill to the agent that runs the responsibility, was the other option. It was not chosen. Extending `update_skill` would change its scenario contract, whose mock needs `markdown`, so the details tool is separate. ## What Changed - Review fixes: the default responsibility view's Skills "+" adds an existing skill, removes a filed one, or opens an agent's skills page. A newest Dashboard version without a skill list is upgraded in place, so the first skill filed after it is undone. Undo files again, or removes, only skills the restoring person can see. A read scope without a skill condition sees no filed skill. `update_skill_details` with only `skillId` is a no-op, as its schema allows. - Migration `0499`: add `responsibility_links.skill_id` (FK to `company_skills`, on delete cascade). Widen the single-target check to four targets. Add a unique `(responsibility_id, skill_id)` index and a `skill_id` index. The migration is idempotent and online-compatible (NOT VALID then VALIDATE, and the indexes are built CONCURRENTLY). It is listed in `MIGRATIONS_WITH_TOP_LEVEL_STATEMENTS`. - Shared: `ResponsibilityLink.skillId`; `ResponsibilitySkillSummary.linkId` and `computed`; `skillId` in the link and lookup schemas; `skill` in `RESPONSIBILITY_FILE_ITEM_KINDS`; optional `skillIds` in Dashboard snapshot links. - Server: filing checks the reader's skill visibility (`skillAccessService`). The detail merges filed and computed skills into one card each. Lookup accepts `skillId`. Dashboard capture, restore and summary include filed skills. A version without `skillIds` leaves filed skills as they are when it is restored. - Tools: `file_under_responsibility`, `remove_from_responsibility` and `find_responsibilities_for` accept `kind: "skill"`. `get_responsibility` returns `linkId` and `computed` for each skill. Add `update_skill_details` (tagline and categories). - UI: the responsibility page has "Add existing skill". A filed skill shows "Filed here" and a remove button. Computed skills keep their holders. ## Verification - Server: the `responsibilit*` tests (new: file, find, move and unfile a skill; one card for a skill that is both filed and computed; undo of a filed skill from the Dashboard history), `skill-tools.test.ts` (new `update_skill_details` cases), `responsibility-tools`, `routine-tools`, `routines-routes`, `paperclip-runner-tool-authority`, `runner-api` and `openapi-routes`: 24 files, 2723 tests passed. - UI: responsibility page and component tests (16 files, 158 tests, including a new filed-skill test) pass. `pnpm --filter @paperclipai/ui typecheck` passed. - `@paperclipai/db` `check:migrations` passes and reports the override. The snapshot drift test passes. `tsc` passes for `db`, `shared` and the server layers. - Runner: catalog and semantic-tool tests (317) pass. All generator checks pass. ## Risks - The migration changes a check constraint on `responsibility_links`. The replacement accepts every row that the old check accepted. It is swapped as NOT VALID and then validated. The previous release never sets `skill_id`. - Deleting a company skill removes its links (cascade). - Filed skills follow the reader's skill visibility. A skill the reader may not see is not listed. ## Model Used Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use and code execution. ## 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 searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: Paperclip <noreply@paperclip.ing>
710 lines
37 KiB
TypeScript
710 lines
37 KiB
TypeScript
import { createHash } from "node:crypto";
|
|
import { and, desc, eq, inArray, ne, notInArray, or, sql } from "drizzle-orm";
|
|
import type { Db } from "@paperclipai/db";
|
|
import { agents, companySkills, issues, projects, responsibilities, responsibilityAreas, responsibilityDashboardVersions, responsibilityLinks, routines } from "@paperclipai/db";
|
|
import {
|
|
RESPONSIBILITY_DASHBOARD_UNDO_HOURS,
|
|
RESPONSIBILITY_DASHBOARD_VERSION_LIMIT,
|
|
responsibilityDashboardChangeSummary,
|
|
responsibilityDashboardSnapshotSchema,
|
|
type ResponsibilityDashboardSnapshot,
|
|
type ResponsibilityDashboardSnapshotArea,
|
|
type ResponsibilityDashboardSnapshotLinks,
|
|
type ResponsibilityDashboardVersionCause,
|
|
type ResponsibilityDashboardVersionList,
|
|
type ResponsibilityDashboardVersionSummary,
|
|
} from "@paperclipai/shared";
|
|
import { notFound } from "../errors.js";
|
|
import { skillAccessService } from "./skill-access.js";
|
|
|
|
/**
|
|
* Versions of a person's Dashboard (experimental `enableResponsibilities`).
|
|
* This module owns what a snapshot holds, when one is saved, the bounded
|
|
* history and what restoring one does. The change sets that cause most
|
|
* versions belong to responsibility-dashboard.ts, which calls in here inside
|
|
* its own transaction.
|
|
*
|
|
* Every write for one person runs under the same transaction-scoped advisory
|
|
* lock, so a restore, an applied change set and a checkpoint never interleave.
|
|
*/
|
|
|
|
export type DashboardTransaction = Parameters<Parameters<Db["transaction"]>[0]>[0];
|
|
type DbOrTx = Db | DashboardTransaction;
|
|
type VersionRow = typeof responsibilityDashboardVersions.$inferSelect;
|
|
type AreaRow = typeof responsibilityAreas.$inferSelect;
|
|
type ResponsibilityRow = typeof responsibilities.$inferSelect;
|
|
|
|
const LIVE = ["proposed", "active"] as const;
|
|
|
|
/** One activity entry a restore or an applied change set writes after commit. */
|
|
export interface DashboardActivityEvent {
|
|
action: string;
|
|
entityType: "responsibility" | "responsibility_area";
|
|
entityId: string;
|
|
details: Record<string, unknown>;
|
|
}
|
|
|
|
export function toDashboardVersionSummary(row: VersionRow): ResponsibilityDashboardVersionSummary {
|
|
return {
|
|
id: row.id,
|
|
cause: row.cause as ResponsibilityDashboardVersionCause,
|
|
summary: row.summary,
|
|
actorUserId: row.actorUserId,
|
|
actorAgentId: row.actorAgentId,
|
|
interactionId: row.interactionId,
|
|
previousVersionId: row.previousVersionId,
|
|
restoredFromVersionId: row.restoredFromVersionId,
|
|
createdAt: row.createdAt,
|
|
};
|
|
}
|
|
|
|
export function parseDashboardSnapshot(value: unknown): ResponsibilityDashboardSnapshot {
|
|
return responsibilityDashboardSnapshotSchema.parse(value) as ResponsibilityDashboardSnapshot;
|
|
}
|
|
|
|
/**
|
|
* Identity of a snapshot's contents: the areas and responsibilities, never
|
|
* which areas a change created. A snapshot whose responsibilities hold what is
|
|
* filed under them hashes those too; `legacy` leaves them out, to compare with
|
|
* a version saved before snapshots held them.
|
|
*/
|
|
export function dashboardSnapshotHash(snapshot: ResponsibilityDashboardSnapshot, opts: { legacy?: boolean } = {}): string {
|
|
const areas = [...snapshot.areas].sort((a, b) => a.id.localeCompare(b.id))
|
|
.map((area) => opts.legacy || area.description === undefined
|
|
? [area.id, area.title, area.status, area.sortOrder]
|
|
: [area.id, area.title, area.status, area.sortOrder, area.description]);
|
|
const items = [...snapshot.responsibilities].sort((a, b) => a.id.localeCompare(b.id))
|
|
.map((item) => {
|
|
const base: unknown[] = [item.id, item.title, item.standard, item.areaId, item.status, item.sortOrder];
|
|
if (opts.legacy || !item.links) return base;
|
|
// No filed skills hashes like a version saved before skills could be filed.
|
|
const links = { ...item.links, skillIds: item.links.skillIds?.length ? item.links.skillIds : undefined };
|
|
return [...base, links, item.description ?? null, item.runByAgentId ?? null,
|
|
item.evidence ?? null, item.healthOverride ?? null, item.healthNote ?? null];
|
|
});
|
|
return createHash("sha256").update(JSON.stringify({ areas, items })).digest("hex");
|
|
}
|
|
|
|
/** True for a version saved before snapshots held filed items. */
|
|
function isLegacySnapshot(snapshot: ResponsibilityDashboardSnapshot) {
|
|
return snapshot.responsibilities.some((item) => item.links === undefined);
|
|
}
|
|
|
|
/** True for a version saved before snapshots held filed skills: restoring it would leave filed skills alone. */
|
|
function lacksFiledSkills(snapshot: ResponsibilityDashboardSnapshot) {
|
|
return snapshot.responsibilities.some((item) => item.links !== undefined && item.links.skillIds === undefined);
|
|
}
|
|
|
|
/** Serialize all dashboard writes for one person inside `tx`. */
|
|
export async function lockDashboard(tx: DashboardTransaction, companyId: string, ownerUserId: string) {
|
|
await tx.execute(sql`select pg_advisory_xact_lock(hashtextextended(${`responsibility-dashboard:${companyId}:${ownerUserId}`}, 0))`);
|
|
}
|
|
|
|
function lower(value: string) {
|
|
return value.trim().toLowerCase();
|
|
}
|
|
|
|
export function responsibilityDashboardVersionService(db: Db) {
|
|
/**
|
|
* The person's dashboard as it is: every responsibility they own that is
|
|
* active, every area one of them is in, and every area a change on this
|
|
* dashboard created that is not archived (an empty one still shows, so it
|
|
* must be undoable), plus any area in `touched` that is not archived: an
|
|
* existing area a change is about to rename or remove, even when it holds
|
|
* nothing of this person's. Three queries at most.
|
|
*/
|
|
async function captureSnapshot(
|
|
database: DbOrTx,
|
|
companyId: string,
|
|
ownerUserId: string,
|
|
/** Areas the change being saved created, which no stored version names yet. */
|
|
createdNow: readonly string[] = [],
|
|
touched: readonly string[] = [],
|
|
): Promise<ResponsibilityDashboardSnapshot> {
|
|
const [rows, linkRows, created] = await Promise.all([
|
|
database.select({
|
|
id: responsibilities.id,
|
|
title: responsibilities.title,
|
|
standard: responsibilities.standard,
|
|
areaId: responsibilities.areaId,
|
|
status: responsibilities.status,
|
|
sortOrder: responsibilities.sortOrder,
|
|
description: responsibilities.description,
|
|
runByAgentId: responsibilities.runByAgentId,
|
|
evidence: responsibilities.evidence,
|
|
healthOverride: responsibilities.healthOverride,
|
|
healthNote: responsibilities.healthNote,
|
|
}).from(responsibilities).where(and(
|
|
eq(responsibilities.companyId, companyId),
|
|
eq(responsibilities.ownerUserId, ownerUserId),
|
|
eq(responsibilities.status, "active"),
|
|
)),
|
|
database.select({
|
|
responsibilityId: responsibilityLinks.responsibilityId,
|
|
projectId: responsibilityLinks.projectId,
|
|
issueId: responsibilityLinks.issueId,
|
|
routineId: responsibilityLinks.routineId,
|
|
skillId: responsibilityLinks.skillId,
|
|
}).from(responsibilityLinks)
|
|
.innerJoin(responsibilities, eq(responsibilities.id, responsibilityLinks.responsibilityId))
|
|
.where(and(
|
|
eq(responsibilities.companyId, companyId),
|
|
eq(responsibilities.ownerUserId, ownerUserId),
|
|
eq(responsibilities.status, "active"),
|
|
)),
|
|
database.selectDistinct({ id: sql<string>`jsonb_array_elements_text(${responsibilityDashboardVersions.snapshot} -> 'createdAreaIds')` })
|
|
.from(responsibilityDashboardVersions)
|
|
.where(and(
|
|
eq(responsibilityDashboardVersions.companyId, companyId),
|
|
eq(responsibilityDashboardVersions.ownerUserId, ownerUserId),
|
|
)),
|
|
]);
|
|
const linksBy = new Map<string, ResponsibilityDashboardSnapshotLinks>();
|
|
for (const link of linkRows) {
|
|
const entry = linksBy.get(link.responsibilityId) ?? { projectIds: [], issueIds: [], routineIds: [], skillIds: [] };
|
|
if (link.projectId) entry.projectIds.push(link.projectId);
|
|
if (link.issueId) entry.issueIds.push(link.issueId);
|
|
if (link.routineId) entry.routineIds.push(link.routineId);
|
|
if (link.skillId) entry.skillIds!.push(link.skillId);
|
|
linksBy.set(link.responsibilityId, entry);
|
|
}
|
|
const sortedLinks = (id: string): ResponsibilityDashboardSnapshotLinks => {
|
|
const entry = linksBy.get(id) ?? { projectIds: [], issueIds: [], routineIds: [], skillIds: [] };
|
|
return {
|
|
projectIds: [...entry.projectIds].sort(), issueIds: [...entry.issueIds].sort(),
|
|
routineIds: [...entry.routineIds].sort(), skillIds: [...(entry.skillIds ?? [])].sort(),
|
|
};
|
|
};
|
|
const items = rows.map(({ description, runByAgentId, evidence, healthOverride, healthNote, ...item }) => ({
|
|
...item, links: sortedLinks(item.id), description, runByAgentId, evidence, healthOverride, healthNote,
|
|
}));
|
|
const referenced = [...new Set(items.map((item) => item.areaId).filter((value): value is string => value !== null))];
|
|
const createdIds = [...new Set([...created.map((row) => row.id), ...createdNow])].filter((value) => !referenced.includes(value));
|
|
// An area a change is about to touch is held whatever its status, so undoing a restore archives it again.
|
|
const touchedIds = touched.filter((value) => !referenced.includes(value));
|
|
const areas = referenced.length + createdIds.length + touchedIds.length === 0 ? [] : await database.select({
|
|
id: responsibilityAreas.id,
|
|
title: responsibilityAreas.title,
|
|
status: responsibilityAreas.status,
|
|
sortOrder: responsibilityAreas.sortOrder,
|
|
description: responsibilityAreas.description,
|
|
}).from(responsibilityAreas).where(and(
|
|
eq(responsibilityAreas.companyId, companyId),
|
|
or(
|
|
referenced.length > 0 ? inArray(responsibilityAreas.id, referenced) : undefined,
|
|
createdIds.length > 0 ? and(inArray(responsibilityAreas.id, createdIds), ne(responsibilityAreas.status, "archived")) : undefined,
|
|
touchedIds.length > 0 ? inArray(responsibilityAreas.id, touchedIds) : undefined,
|
|
),
|
|
));
|
|
return {
|
|
version: 1,
|
|
areas: areas.sort((a, b) => a.id.localeCompare(b.id)),
|
|
responsibilities: items.sort((a, b) => a.id.localeCompare(b.id)),
|
|
createdAreaIds: [...createdNow],
|
|
};
|
|
}
|
|
|
|
async function latestRow(database: DbOrTx, companyId: string, ownerUserId: string): Promise<VersionRow | null> {
|
|
const [row] = await database.select().from(responsibilityDashboardVersions).where(and(
|
|
eq(responsibilityDashboardVersions.companyId, companyId),
|
|
eq(responsibilityDashboardVersions.ownerUserId, ownerUserId),
|
|
)).orderBy(desc(responsibilityDashboardVersions.createdAt), desc(responsibilityDashboardVersions.id)).limit(1);
|
|
return row ?? null;
|
|
}
|
|
|
|
async function prune(tx: DashboardTransaction, companyId: string, ownerUserId: string) {
|
|
const keep = tx.select({ id: responsibilityDashboardVersions.id }).from(responsibilityDashboardVersions).where(and(
|
|
eq(responsibilityDashboardVersions.companyId, companyId),
|
|
eq(responsibilityDashboardVersions.ownerUserId, ownerUserId),
|
|
)).orderBy(desc(responsibilityDashboardVersions.createdAt), desc(responsibilityDashboardVersions.id))
|
|
.limit(RESPONSIBILITY_DASHBOARD_VERSION_LIMIT);
|
|
await tx.delete(responsibilityDashboardVersions).where(and(
|
|
eq(responsibilityDashboardVersions.companyId, companyId),
|
|
eq(responsibilityDashboardVersions.ownerUserId, ownerUserId),
|
|
notInArray(responsibilityDashboardVersions.id, keep),
|
|
));
|
|
}
|
|
|
|
/**
|
|
* Save `snapshot` as the newest version, unless it is identical to the
|
|
* newest one (then that one is returned). The summary says what changed
|
|
* since the newest one. Prunes past the limit.
|
|
*/
|
|
async function save(tx: DashboardTransaction, input: {
|
|
companyId: string;
|
|
ownerUserId: string;
|
|
cause: ResponsibilityDashboardVersionCause;
|
|
snapshot: ResponsibilityDashboardSnapshot;
|
|
actorUserId?: string | null;
|
|
actorAgentId?: string | null;
|
|
issueId?: string | null;
|
|
interactionId?: string | null;
|
|
restoredFromVersionId?: string | null;
|
|
}): Promise<{ row: VersionRow; created: boolean }> {
|
|
const previous = await latestRow(tx, input.companyId, input.ownerUserId);
|
|
const previousSnapshot = previous ? parseDashboardSnapshot(previous.snapshot) : null;
|
|
const hash = dashboardSnapshotHash(input.snapshot);
|
|
// A version saved before snapshots held filed items is compared on what it holds.
|
|
const legacy = previousSnapshot ? isLegacySnapshot(previousSnapshot) : false;
|
|
const comparable = legacy ? dashboardSnapshotHash(input.snapshot, { legacy: true }) : hash;
|
|
if (previous && previous.snapshotHash === comparable) {
|
|
// One saved before skills could be filed hashes the same (no filed skills) but must hold the empty list too.
|
|
if (!legacy && !lacksFiledSkills(previousSnapshot!)) return { row: previous, created: false };
|
|
// The same dashboard as an older version that held no filed items,
|
|
// details or skills: it now holds them, so the next change compares, and undoes, in full.
|
|
const [upgraded] = await tx.update(responsibilityDashboardVersions)
|
|
.set({ snapshot: input.snapshot as unknown as Record<string, unknown>, snapshotHash: hash })
|
|
.where(eq(responsibilityDashboardVersions.id, previous.id))
|
|
.returning();
|
|
return { row: upgraded ?? previous, created: false };
|
|
}
|
|
const summary = responsibilityDashboardChangeSummary(previous ? parseDashboardSnapshot(previous.snapshot) : null, input.snapshot);
|
|
// Strictly after the previous version, so "newest" never ties within one transaction.
|
|
const createdAt = new Date(Math.max(Date.now(), (previous?.createdAt.getTime() ?? 0) + 1));
|
|
const [row] = await tx.insert(responsibilityDashboardVersions).values({
|
|
companyId: input.companyId,
|
|
ownerUserId: input.ownerUserId,
|
|
cause: input.cause,
|
|
summary,
|
|
snapshot: input.snapshot as unknown as Record<string, unknown>,
|
|
snapshotHash: hash,
|
|
actorUserId: input.actorUserId ?? null,
|
|
actorAgentId: input.actorAgentId ?? null,
|
|
issueId: input.issueId ?? null,
|
|
interactionId: input.interactionId ?? null,
|
|
previousVersionId: previous?.id ?? null,
|
|
restoredFromVersionId: input.restoredFromVersionId ?? null,
|
|
createdAt,
|
|
}).returning();
|
|
await prune(tx, input.companyId, input.ownerUserId);
|
|
return { row: row!, created: true };
|
|
}
|
|
|
|
/**
|
|
* Inside `tx`, holding the person's lock: save the dashboard as it is now
|
|
* as a `person` version when it differs from the newest one (changes made by
|
|
* hand since), so the version before the next change is what they last saw.
|
|
*/
|
|
async function checkpoint(
|
|
tx: DashboardTransaction,
|
|
companyId: string,
|
|
ownerUserId: string,
|
|
actorUserId: string | null,
|
|
touched: readonly string[] = [],
|
|
) {
|
|
const snapshot = await captureSnapshot(tx, companyId, ownerUserId, [], touched);
|
|
const saved = await save(tx, { companyId, ownerUserId, cause: "person", snapshot, actorUserId });
|
|
return { ...saved, snapshot };
|
|
}
|
|
|
|
/**
|
|
* Inside `tx`: put the person's dashboard back to `target`. For every area
|
|
* and responsibility in it, its name or sentence, area, order and status
|
|
* are put back; whatever the person owns now that is not in it is let go,
|
|
* and an area it leaves holding nothing of anyone's is archived. Nothing is
|
|
* deleted, and bars, metrics and readings are never touched. A version that
|
|
* holds what is filed under each responsibility, its description and the
|
|
* agent that runs it puts those back too (see restoreDetailsInTx); an older
|
|
* version leaves them as they are.
|
|
*
|
|
* Areas other people have responsibilities in keep their name and order
|
|
* (they see them too); a responsibility deleted since is created again with
|
|
* its sentence; an area deleted since is created again (or the live area now
|
|
* holding its name is used); when an area's old name is now another area's,
|
|
* that area is used instead.
|
|
*/
|
|
async function applySnapshotInTx(
|
|
tx: DashboardTransaction,
|
|
companyId: string,
|
|
ownerUserId: string,
|
|
target: ResponsibilityDashboardSnapshot,
|
|
current: ResponsibilityDashboardSnapshot,
|
|
source: Record<string, unknown>,
|
|
): Promise<{ events: DashboardActivityEvent[]; createdAreaIds: string[] }> {
|
|
const events: DashboardActivityEvent[] = [];
|
|
const createdAreaIds: string[] = [];
|
|
const now = new Date();
|
|
const areaIds = [...new Set([...target.areas.map((area) => area.id), ...current.areas.map((area) => area.id)])];
|
|
const targetItemIds = target.responsibilities.map((item) => item.id);
|
|
const [areaRows, liveAreas, othersByArea, ownRows] = await Promise.all([
|
|
areaIds.length === 0 ? Promise.resolve([] as AreaRow[]) : tx.select().from(responsibilityAreas)
|
|
.where(and(eq(responsibilityAreas.companyId, companyId), inArray(responsibilityAreas.id, areaIds))),
|
|
tx.select({ id: responsibilityAreas.id, title: responsibilityAreas.title }).from(responsibilityAreas)
|
|
.where(and(eq(responsibilityAreas.companyId, companyId), ne(responsibilityAreas.status, "archived"))),
|
|
areaIds.length === 0 ? Promise.resolve([] as Array<{ areaId: string | null; count: number }>) : tx.select({
|
|
areaId: responsibilities.areaId,
|
|
count: sql<number>`count(*)::int`,
|
|
}).from(responsibilities).where(and(
|
|
eq(responsibilities.companyId, companyId),
|
|
inArray(responsibilities.areaId, areaIds),
|
|
ne(responsibilities.ownerUserId, ownerUserId),
|
|
inArray(responsibilities.status, [...LIVE]),
|
|
)).groupBy(responsibilities.areaId),
|
|
targetItemIds.length === 0 ? Promise.resolve([] as ResponsibilityRow[]) : tx.select().from(responsibilities).where(and(
|
|
eq(responsibilities.companyId, companyId),
|
|
eq(responsibilities.ownerUserId, ownerUserId),
|
|
inArray(responsibilities.id, targetItemIds),
|
|
)),
|
|
]);
|
|
const areasById = new Map(areaRows.map((row) => [row.id, row]));
|
|
const shared = new Set(othersByArea.filter((row) => row.areaId && row.count > 0).map((row) => row.areaId!));
|
|
// Live titles, kept current as this restore renames and archives, for the one-live-name-per-area rule.
|
|
const liveTitle = new Map(liveAreas.map((row) => [lower(row.title), row.id]));
|
|
const setLive = (row: { id: string; title: string; status: string }) => {
|
|
for (const [title, id] of liveTitle) if (id === row.id) liveTitle.delete(title);
|
|
if (row.status !== "archived") liveTitle.set(lower(row.title), row.id);
|
|
};
|
|
|
|
// Areas: which area each of the snapshot's areas is now.
|
|
const areaFor = new Map<string, string>();
|
|
const pending: ResponsibilityDashboardSnapshotArea[] = [];
|
|
const placeArea = async (want: ResponsibilityDashboardSnapshotArea, final: boolean): Promise<boolean> => {
|
|
const row = areasById.get(want.id);
|
|
if (!row) {
|
|
// Deleted since: use the live area that has its name, else create it again.
|
|
const holder = liveTitle.get(lower(want.title));
|
|
if (holder) {
|
|
areaFor.set(want.id, holder);
|
|
return true;
|
|
}
|
|
const [created] = await tx.insert(responsibilityAreas).values({
|
|
companyId,
|
|
title: want.title,
|
|
description: want.description ?? null,
|
|
status: want.status === "archived" ? "archived" : "active",
|
|
sortOrder: want.sortOrder,
|
|
}).returning();
|
|
areaFor.set(want.id, created!.id);
|
|
createdAreaIds.push(created!.id);
|
|
setLive(created!);
|
|
events.push({ action: "responsibility_area.created", entityType: "responsibility_area", entityId: created!.id, details: { title: created!.title, status: created!.status, ...source } });
|
|
return true;
|
|
}
|
|
const isShared = shared.has(row.id);
|
|
// Other people see a shared area: only bring it back if it was archived, never rename or reorder it.
|
|
const nextTitle = isShared ? row.title : want.title;
|
|
const nextStatus = isShared ? (row.status === "archived" && want.status !== "archived" ? "active" : row.status) : want.status;
|
|
const nextOrder = isShared ? row.sortOrder : want.sortOrder;
|
|
// A version that holds the description puts it back, except on an area others share.
|
|
const nextDescription = isShared || want.description === undefined ? row.description : want.description;
|
|
if (nextTitle === row.title && nextStatus === row.status && nextOrder === row.sortOrder && nextDescription === row.description) {
|
|
areaFor.set(want.id, row.id);
|
|
return true;
|
|
}
|
|
if (nextStatus !== "archived") {
|
|
const holder = liveTitle.get(lower(nextTitle));
|
|
if (holder && holder !== row.id) {
|
|
if (!final) return false;
|
|
// Its old name now belongs to another area: file the person's responsibilities there.
|
|
areaFor.set(want.id, holder);
|
|
return true;
|
|
}
|
|
}
|
|
const [updated] = await tx.update(responsibilityAreas)
|
|
.set({ title: nextTitle, status: nextStatus, sortOrder: nextOrder, description: nextDescription, updatedAt: now })
|
|
.where(and(eq(responsibilityAreas.id, row.id), eq(responsibilityAreas.companyId, companyId)))
|
|
.returning();
|
|
areasById.set(row.id, updated!);
|
|
setLive(updated!);
|
|
areaFor.set(want.id, row.id);
|
|
events.push({
|
|
action: "responsibility_area.updated",
|
|
entityType: "responsibility_area",
|
|
entityId: row.id,
|
|
details: {
|
|
fields: [
|
|
nextTitle !== row.title ? "title" : null, nextStatus !== row.status ? "status" : null,
|
|
nextOrder !== row.sortOrder ? "sortOrder" : null, nextDescription !== row.description ? "description" : null,
|
|
].filter(Boolean),
|
|
...(nextTitle !== row.title ? { fromTitle: row.title, toTitle: nextTitle } : {}),
|
|
...(nextStatus !== row.status ? { fromStatus: row.status, toStatus: nextStatus } : {}),
|
|
...source,
|
|
},
|
|
});
|
|
return true;
|
|
};
|
|
for (const want of target.areas) if (!(await placeArea(want, false))) pending.push(want);
|
|
// A second pass: a name another area held may have been freed by the first.
|
|
for (const want of pending) await placeArea(want, true);
|
|
|
|
// Responsibilities in the snapshot: put each back.
|
|
const ownById = new Map(ownRows.map((row) => [row.id, row]));
|
|
// A deleted one comes back under its saved id, so restoring the same version again finds it
|
|
// instead of making another copy. Its id is reused only while no other row holds it.
|
|
const missingIds = targetItemIds.filter((id) => !ownById.has(id));
|
|
const takenIds = new Set(missingIds.length === 0 ? [] : (await tx.select({ id: responsibilities.id }).from(responsibilities)
|
|
.where(inArray(responsibilities.id, missingIds))).map((row) => row.id));
|
|
const touchedAreas = new Set<string>();
|
|
for (const want of target.responsibilities) {
|
|
const areaId = want.areaId ? areaFor.get(want.areaId) ?? null : null;
|
|
const row = ownById.get(want.id);
|
|
if (!row) {
|
|
// Deleted since: it comes back with its sentence (what was filed under it went with it).
|
|
const [created] = await tx.insert(responsibilities).values({
|
|
...(takenIds.has(want.id) ? {} : { id: want.id }),
|
|
companyId,
|
|
ownerUserId,
|
|
areaId,
|
|
title: want.title,
|
|
standard: want.standard,
|
|
status: "active",
|
|
source: "manual",
|
|
sortOrder: want.sortOrder,
|
|
metricDirection: null,
|
|
confirmedAt: now,
|
|
}).returning();
|
|
events.push({ action: "responsibility.created", entityType: "responsibility", entityId: created!.id, details: { title: created!.title, ownerUserId, status: "active", source: "manual", areaId, ...source } });
|
|
events.push(...await restoreDetailsInTx(tx, companyId, created!, want, source));
|
|
continue;
|
|
}
|
|
// A bar keeps its sentence: an empty one would leave its metric without the words it measures.
|
|
const standard = want.standard === null && row.metricName ? row.standard : want.standard;
|
|
const set: Partial<typeof responsibilities.$inferInsert> = {};
|
|
if (row.title !== want.title) set.title = want.title;
|
|
if ((row.standard ?? null) !== (standard ?? null)) set.standard = standard;
|
|
if (row.areaId !== areaId) set.areaId = areaId;
|
|
if (row.sortOrder !== want.sortOrder) set.sortOrder = want.sortOrder;
|
|
if (row.status !== "active") {
|
|
set.status = "active";
|
|
if (!row.confirmedAt) set.confirmedAt = now;
|
|
}
|
|
events.push(...await restoreDetailsInTx(tx, companyId, row, want, source));
|
|
if (Object.keys(set).length === 0) continue;
|
|
await tx.update(responsibilities).set({ ...set, updatedAt: now })
|
|
.where(and(eq(responsibilities.id, row.id), eq(responsibilities.companyId, companyId)));
|
|
if (row.areaId) touchedAreas.add(row.areaId);
|
|
events.push({
|
|
action: "responsibility.updated",
|
|
entityType: "responsibility",
|
|
entityId: row.id,
|
|
details: {
|
|
fields: Object.keys(set).filter((key) => key !== "confirmedAt"),
|
|
...(set.status ? { fromStatus: row.status, toStatus: "active" } : {}),
|
|
...(set.areaId !== undefined ? { fromAreaId: row.areaId, toAreaId: areaId } : {}),
|
|
...source,
|
|
},
|
|
});
|
|
}
|
|
|
|
// What the person owns now that the snapshot does not hold: let go.
|
|
const keep = new Set(target.responsibilities.map((item) => item.id));
|
|
for (const item of current.responsibilities) {
|
|
if (keep.has(item.id)) continue;
|
|
const [updated] = await tx.update(responsibilities).set({ status: "let_go", updatedAt: now })
|
|
.where(and(
|
|
eq(responsibilities.id, item.id),
|
|
eq(responsibilities.companyId, companyId),
|
|
eq(responsibilities.ownerUserId, ownerUserId),
|
|
eq(responsibilities.status, "active"),
|
|
)).returning({ id: responsibilities.id });
|
|
if (!updated) continue;
|
|
if (item.areaId) touchedAreas.add(item.areaId);
|
|
events.push({ action: "responsibility.updated", entityType: "responsibility", entityId: item.id, details: { fields: ["status"], fromStatus: "active", toStatus: "let_go", ...source } });
|
|
}
|
|
|
|
// Areas the snapshot does not hold that are now empty of anyone's live responsibilities: archived.
|
|
const kept = new Set(areaFor.values());
|
|
const candidates = [...new Set([...current.areas.map((area) => area.id), ...touchedAreas])].filter((areaId) => !kept.has(areaId));
|
|
events.push(...await archiveIfEmpty(tx, companyId, candidates, source));
|
|
return { events, createdAreaIds };
|
|
}
|
|
|
|
/**
|
|
* Inside `tx`: put back what a version holds beyond the sentence fields,
|
|
* when it holds them: the description, the agent that runs it (while that
|
|
* agent still exists) and exactly the projects, tasks and routines filed
|
|
* directly under it (those deleted since stay gone).
|
|
*/
|
|
async function restoreDetailsInTx(
|
|
tx: DashboardTransaction,
|
|
companyId: string,
|
|
row: Pick<ResponsibilityRow, "id" | "description" | "runByAgentId" | "evidence" | "healthOverride" | "healthNote">,
|
|
want: ResponsibilityDashboardSnapshot["responsibilities"][number],
|
|
source: Record<string, unknown>,
|
|
): Promise<DashboardActivityEvent[]> {
|
|
const events: DashboardActivityEvent[] = [];
|
|
const set: Partial<typeof responsibilities.$inferInsert> = {};
|
|
if (want.description !== undefined && (row.description ?? null) !== want.description) set.description = want.description;
|
|
if (want.evidence !== undefined && (row.evidence ?? null) !== want.evidence) set.evidence = want.evidence;
|
|
if (want.healthOverride !== undefined && (row.healthOverride ?? null) !== want.healthOverride) set.healthOverride = want.healthOverride;
|
|
if (want.healthNote !== undefined && (row.healthNote ?? null) !== want.healthNote) set.healthNote = want.healthNote;
|
|
if (want.runByAgentId !== undefined && row.runByAgentId !== want.runByAgentId) {
|
|
const agentExists = want.runByAgentId === null || (await tx.select({ id: agents.id }).from(agents)
|
|
.where(and(eq(agents.id, want.runByAgentId), eq(agents.companyId, companyId)))).length > 0;
|
|
if (agentExists) set.runByAgentId = want.runByAgentId;
|
|
}
|
|
if (Object.keys(set).length > 0) {
|
|
await tx.update(responsibilities).set({ ...set, updatedAt: new Date() })
|
|
.where(and(eq(responsibilities.id, row.id), eq(responsibilities.companyId, companyId)));
|
|
events.push({
|
|
action: "responsibility.updated",
|
|
entityType: "responsibility",
|
|
entityId: row.id,
|
|
details: {
|
|
fields: Object.keys(set),
|
|
...(set.runByAgentId !== undefined ? { fromRunByAgentId: row.runByAgentId, toRunByAgentId: set.runByAgentId } : {}),
|
|
...source,
|
|
},
|
|
});
|
|
}
|
|
if (!want.links) return events;
|
|
// A version saved before skills could be filed leaves filed skills as they are.
|
|
const withSkills = want.links.skillIds !== undefined;
|
|
const linked = await tx.select().from(responsibilityLinks).where(eq(responsibilityLinks.responsibilityId, row.id));
|
|
// Skills the person restoring cannot see (the request's actor) are left as they are: not filed again, not removed.
|
|
const skillIds = [...new Set([...linked.flatMap((link) => (link.skillId ? [link.skillId] : [])), ...(want.links.skillIds ?? [])])];
|
|
const visibleSkills = !withSkills || skillIds.length === 0 ? new Set<string>() : new Set(
|
|
(await tx.select({ id: companySkills.id }).from(companySkills).where(and(
|
|
eq(companySkills.companyId, companyId), inArray(companySkills.id, skillIds),
|
|
await skillAccessService(tx as unknown as Db).condition(companyId),
|
|
))).map((skill) => skill.id),
|
|
);
|
|
const current = linked.filter((link) => !link.skillId || visibleSkills.has(link.skillId));
|
|
const wanted = new Set([
|
|
...want.links.projectIds.map((id) => `project:${id}`),
|
|
...want.links.issueIds.map((id) => `issue:${id}`),
|
|
...want.links.routineIds.map((id) => `routine:${id}`),
|
|
...(want.links.skillIds ?? []).filter((id) => visibleSkills.has(id)).map((id) => `skill:${id}`),
|
|
]);
|
|
const keyOf = (link: typeof responsibilityLinks.$inferSelect) =>
|
|
link.projectId ? `project:${link.projectId}` : link.issueId ? `issue:${link.issueId}`
|
|
: link.routineId ? `routine:${link.routineId}` : `skill:${link.skillId}`;
|
|
const have = new Set(current.map(keyOf));
|
|
for (const link of current) {
|
|
if (wanted.has(keyOf(link))) continue;
|
|
await tx.delete(responsibilityLinks).where(eq(responsibilityLinks.id, link.id));
|
|
const [targetType, targetId] = keyOf(link).split(":");
|
|
events.push({ action: "responsibility.unlinked", entityType: "responsibility", entityId: row.id, details: { linkId: link.id, targetType, targetId, ...source } });
|
|
}
|
|
const missing = [...wanted].filter((key) => !have.has(key)).map((key) => key.split(":") as [string, string]);
|
|
const idsOf = (kind: string) => missing.filter(([type]) => type === kind).map(([, id]) => id);
|
|
// Only items that still exist in the company can be filed again.
|
|
const [liveProjects, liveIssues, liveRoutines, liveSkills] = await Promise.all([
|
|
idsOf("project").length === 0 ? [] : tx.select({ id: projects.id }).from(projects)
|
|
.where(and(eq(projects.companyId, companyId), inArray(projects.id, idsOf("project")))),
|
|
idsOf("issue").length === 0 ? [] : tx.select({ id: issues.id }).from(issues)
|
|
.where(and(eq(issues.companyId, companyId), inArray(issues.id, idsOf("issue")))),
|
|
idsOf("routine").length === 0 ? [] : tx.select({ id: routines.id }).from(routines)
|
|
.where(and(eq(routines.companyId, companyId), inArray(routines.id, idsOf("routine")))),
|
|
idsOf("skill").length === 0 ? [] : tx.select({ id: companySkills.id }).from(companySkills)
|
|
.where(and(eq(companySkills.companyId, companyId), inArray(companySkills.id, idsOf("skill")))),
|
|
]);
|
|
const live = new Set([
|
|
...liveProjects.map((item) => `project:${item.id}`),
|
|
...liveIssues.map((item) => `issue:${item.id}`),
|
|
...liveRoutines.map((item) => `routine:${item.id}`),
|
|
...liveSkills.map((item) => `skill:${item.id}`),
|
|
]);
|
|
for (const [kind, id] of missing) {
|
|
if (!live.has(`${kind}:${id}`)) continue;
|
|
const [inserted] = await tx.insert(responsibilityLinks).values({
|
|
companyId,
|
|
responsibilityId: row.id,
|
|
projectId: kind === "project" ? id : null,
|
|
issueId: kind === "issue" ? id : null,
|
|
routineId: kind === "routine" ? id : null,
|
|
skillId: kind === "skill" ? id : null,
|
|
}).onConflictDoNothing().returning();
|
|
if (inserted) events.push({ action: "responsibility.linked", entityType: "responsibility", entityId: row.id, details: { linkId: inserted.id, targetType: kind, targetId: id, ...source } });
|
|
}
|
|
return events;
|
|
}
|
|
|
|
/** Inside `tx`: archive each listed area that is not archived and holds no proposed or active responsibility of anyone. */
|
|
async function archiveIfEmpty(tx: DashboardTransaction, companyId: string, areaIds: readonly string[], source: Record<string, unknown>) {
|
|
if (areaIds.length === 0) return [];
|
|
const archived = await tx.update(responsibilityAreas).set({ status: "archived", updatedAt: new Date() }).where(and(
|
|
eq(responsibilityAreas.companyId, companyId),
|
|
inArray(responsibilityAreas.id, [...areaIds]),
|
|
ne(responsibilityAreas.status, "archived"),
|
|
sql`not exists (select 1 from ${responsibilities} r where r.area_id = ${responsibilityAreas.id} and r.status in ('proposed', 'active'))`,
|
|
)).returning({ id: responsibilityAreas.id, title: responsibilityAreas.title, status: responsibilityAreas.status });
|
|
return archived.map((row): DashboardActivityEvent => ({
|
|
action: "responsibility_area.updated",
|
|
entityType: "responsibility_area",
|
|
entityId: row.id,
|
|
details: { fields: ["status"], toStatus: "archived", title: row.title, ...source },
|
|
}));
|
|
}
|
|
|
|
async function getInCompany(database: DbOrTx, companyId: string, versionId: string) {
|
|
const [row] = await database.select().from(responsibilityDashboardVersions)
|
|
.where(and(eq(responsibilityDashboardVersions.id, versionId), eq(responsibilityDashboardVersions.companyId, companyId)));
|
|
return row ?? null;
|
|
}
|
|
|
|
return {
|
|
captureSnapshot,
|
|
save,
|
|
checkpoint,
|
|
applySnapshotInTx,
|
|
archiveIfEmpty,
|
|
|
|
getById: (versionId: string) =>
|
|
db.select().from(responsibilityDashboardVersions).where(eq(responsibilityDashboardVersions.id, versionId))
|
|
.then((rows) => rows[0] ?? null),
|
|
|
|
/**
|
|
* The newest version when it is an applied change set or a restore saved
|
|
* within the Undo window, for the Dashboard's Undo line. One query.
|
|
*/
|
|
async latestChange(companyId: string, ownerUserId: string, now: Date = new Date()): Promise<ResponsibilityDashboardVersionSummary | null> {
|
|
const row = await latestRow(db, companyId, ownerUserId);
|
|
if (!row || row.cause === "person" || !row.previousVersionId) return null;
|
|
if (now.getTime() - row.createdAt.getTime() > RESPONSIBILITY_DASHBOARD_UNDO_HOURS * 3_600_000) return null;
|
|
return toDashboardVersionSummary(row);
|
|
},
|
|
|
|
/**
|
|
* The version list, newest first. With `checkpointBy` (someone who may
|
|
* change this dashboard) the dashboard as it is now is saved first when
|
|
* it changed by hand, so the list starts with what they see.
|
|
*/
|
|
async list(companyId: string, ownerUserId: string, opts: { checkpointBy?: string | null } = {}): Promise<{ list: ResponsibilityDashboardVersionList; saved: VersionRow | null }> {
|
|
let saved: VersionRow | null = null;
|
|
if (opts.checkpointBy !== undefined) {
|
|
saved = await db.transaction(async (tx) => {
|
|
await lockDashboard(tx, companyId, ownerUserId);
|
|
const result = await checkpoint(tx, companyId, ownerUserId, opts.checkpointBy ?? null);
|
|
return result.created ? result.row : null;
|
|
});
|
|
}
|
|
const rows = await db.select().from(responsibilityDashboardVersions).where(and(
|
|
eq(responsibilityDashboardVersions.companyId, companyId),
|
|
eq(responsibilityDashboardVersions.ownerUserId, ownerUserId),
|
|
)).orderBy(desc(responsibilityDashboardVersions.createdAt), desc(responsibilityDashboardVersions.id))
|
|
.limit(RESPONSIBILITY_DASHBOARD_VERSION_LIMIT);
|
|
return { list: { ownerUserId, versions: rows.map(toDashboardVersionSummary) }, saved };
|
|
},
|
|
|
|
/**
|
|
* Restore a version: the dashboard as it is now is saved first (when it
|
|
* changed by hand), the version is applied, and the result is saved as a
|
|
* new `restore` version whose previous version is the one before, so the
|
|
* restore itself can be undone. Restoring the version that already
|
|
* matches changes nothing and saves nothing.
|
|
*/
|
|
async restore(version: VersionRow, actor: { userId: string | null }) {
|
|
const target = parseDashboardSnapshot(version.snapshot);
|
|
return db.transaction(async (tx) => {
|
|
await lockDashboard(tx, version.companyId, version.ownerUserId);
|
|
// Pruned between reading it and taking the lock: it is gone.
|
|
if (!(await getInCompany(tx, version.companyId, version.id))) throw notFound("Version not found");
|
|
const before = await checkpoint(tx, version.companyId, version.ownerUserId, actor.userId);
|
|
const source = { source: "dashboard_restore", restoredVersionId: version.id };
|
|
const { events, createdAreaIds } = await applySnapshotInTx(tx, version.companyId, version.ownerUserId, target, before.snapshot, source);
|
|
const after = await captureSnapshot(tx, version.companyId, version.ownerUserId, createdAreaIds);
|
|
const saved = await save(tx, {
|
|
companyId: version.companyId,
|
|
ownerUserId: version.ownerUserId,
|
|
cause: "restore",
|
|
snapshot: after,
|
|
actorUserId: actor.userId,
|
|
restoredFromVersionId: version.id,
|
|
});
|
|
return { version: saved.row, changed: saved.created, events };
|
|
});
|
|
},
|
|
};
|
|
}
|