@lensmcp/protocol-types 1.25.32 → 1.25.34

package/lib/team-design.d.ts

@@ -0,0 +1,228 @@
+import type { DashTeamKind } from './team.js';
+/**
+ * Team design (planning/team/01-team-design.md): LensMCP reads a project — a dossier it builds itself, then Claude's
+ * own research with the code tools — and proposes the team that should work on it: the project as understood, its
+ * goals with evidence, whether it splits at all, the roles cut along its seams with their rules, the defaults it does
+ * not need, the flow, and the first goals. The person accepts on the Team page; only then are `.lensmcp/team/` files
+ * written. These are the shapes the run, the dashboard and MCP share; the model's answer is checked into them.
+ */
+export declare const TEAM_DESIGN_VERSION = 1;
+/** A part of the project that can move on its own — or cannot: `coupling` says how much it depends on the others. */
+export interface TeamDesignDomain {
+    /** Stable, kebab-case. */
+    id: string;
+    name: string;
+    /** What it is and does, in a sentence or two. */
+    what: string;
+    /** Repository paths it lives in. */
+    paths: string[];
+    /** Ids of the domains it depends on. */
+    dependsOn: string[];
+    coupling: 'low' | 'medium' | 'high';
+}
+/** A check the project already has — a command a role runs before it says done. */
+export interface TeamDesignGate {
+    command: string;
+    what: string;
+    /** When it applies: "every change", "a change under apps/web", "before a release"… */
+    when: string;
+    /** LensMCP found the script or target it names (package.json scripts, a project's targets, CI). */
+    checked?: boolean;
+}
+/** What the project is working towards, from what it shows: docs, plans, recent commits, open issues, the lens. */
+export interface TeamDesignGoal {
+    id: string;
+    title: string;
+    why: string;
+    /** `file:<path>[:line]`, `commit:<sha or subject>`, `lens:<what>` — where it was read. */
+    evidence: string[];
+    horizon: 'now' | 'next' | 'later';
+}
+/** One proposed role — a brief an agent can work from — in the shape of a `.lensmcp/team/roles/<id>.md` file. */
+export interface TeamDesignRole {
+    id: string;
+    title: string;
+    summary: string;
+    /** Why this project needs it. */
+    why: string;
+    /** The default role it refines (builder, reviewer, …), when it does. */
+    basedOn?: string;
+    /** Paths it owns — where it works and others do not. */
+    owns: string[];
+    takes: DashTeamKind[];
+    creates: DashTeamKind[] | 'any';
+    wip: number;
+    worktree: 'own' | 'shared' | 'any';
+    /** How many agents to run in it, and whether to start them now or once the work is there. */
+    agents: number;
+    start: 'now' | 'later';
+    /** Its rules, as tagged sections (`<rules id note>…</rules>`). */
+    rules: string;
+    /** The LensMCP tools and resources it should reach for first. */
+    uses: string[];
+    /** Against the repository's current team: a new role, one that changes a role it has, or one it already has as is. */
+    status?: 'new' | 'changes' | 'same';
+}
+/** A default role this project does not need — accepted, it is written with `off: true`. */
+export interface TeamDesignOff {
+    id: string;
+    why: string;
+}
+/**
+ * A hand-off, in the shape of `.lensmcp/team/flow.json`'s entries (libs/storage coordination/flow.ts). The work a chain
+ * is about is its nearest build or bug: `after` holds the hand-off for one of them, `paths` for work on those paths
+ * (prefixes or globs); `to: owner` sends it back to whoever did the work (`builder`: its older name); `join` makes it
+ * once, when every task of the completed one's kind under the same parent completed with this outcome.
+ */
+export interface TeamDesignHandOff {
+    on: {
+        kind: DashTeamKind;
+        outcome: string;
+        after?: 'build' | 'bug';
+        paths?: string[];
+    };
+    create: {
+        kind: DashTeamKind;
+        role?: string;
+        to?: 'owner' | 'builder';
+        join?: boolean;
+        title: string;
+        description: string;
+    };
+}
+/** Keep the flow the repository has, or replace it. */
+export type TeamDesignFlow = {
+    keep: true;
+    why?: string;
+} | {
+    keep: false;
+    handOffs: TeamDesignHandOff[];
+    why: string;
+};
+/** A goal to put on the board when the design is accepted, with the tasks it breaks into. */
+export interface TeamDesignFirstGoal {
+    title: string;
+    description: string;
+    priority: number;
+    tasks: Array<{
+        kind: DashTeamKind;
+        role?: string;
+        title: string;
+        description: string;
+        priority: number;
+        paths: string[];
+    }>;
+}
+/** What LensMCP's checks did to the model's answer before anyone saw it — never silent. */
+export interface TeamDesignCheck {
+    level: 'dropped' | 'changed' | 'warning';
+    what: string;
+    why: string;
+}
+/** The project as the design read it: when the project has moved on far enough, the page offers to design again. */
+export interface TeamDesignBasis {
+    head: string | null;
+    branch: string | null;
+    /** The projects (Nx / workspace packages) it saw, by root. */
+    projects: string[];
+    trackedFiles: number;
+    at: number;
+}
+export interface TeamDesign {
+    version: typeof TEAM_DESIGN_VERSION;
+    project: {
+        name: string;
+        summary: string;
+        /** Who it serves. */
+        users: string;
+        stack: string[];
+        domains: TeamDesignDomain[];
+        qualityGates: TeamDesignGate[];
+        risks: string[];
+    };
+    goals: TeamDesignGoal[];
+    /** Does the project split into parallel work at all: a team, a small team (one builder and a checker), or one agent. */
+    fit: {
+        verdict: 'team' | 'small-team' | 'single-agent';
+        why: string;
+        parallel: string[];
+    };
+    roles: TeamDesignRole[];
+    off: TeamDesignOff[];
+    flow: TeamDesignFlow;
+    firstGoals: TeamDesignFirstGoal[];
+    /** What it could not assess, and why. */
+    limits: string[];
+    /** 0–1. */
+    confidence: number;
+    checks: TeamDesignCheck[];
+    basis: TeamDesignBasis;
+}
+/** A design run as the Team page shows it: the run (status, steps, cost — a DashAiRun's) and, once done, its design. */
+export interface DashTeamDesignRun {
+    id: string;
+    status: 'queued' | 'running' | 'done' | 'failed';
+    startedAt: number;
+    finishedAt?: number;
+    costUsd?: number;
+    model?: string;
+    steps: string[];
+    error?: string;
+    refused?: 'no-key' | 'over-daily-cap' | 'no-room';
+    design?: TeamDesign;
+    /** The design was accepted (when, and what it wrote). */
+    accepted?: {
+        at: number;
+        files: string[];
+        goals: string[];
+    };
+}
+/** What the person keeps of a design. Roles they edited carry their own rules. */
+export interface DashTeamDesignAccept {
+    runId: string;
+    roles: Array<{
+        id: string;
+        rules?: string;
+    }>;
+    /** Default roles to switch off. */
+    off: string[];
+    flow: boolean;
+    /** Write `.lensmcp/team/project.md`. */
+    brief: boolean;
+    /** Indexes into `firstGoals` to create on the board. */
+    goals: number[];
+    /** Overwrite files the repository already has (they are listed to the person first). */
+    force: boolean;
+}
+/** What accepting wrote, and what it kept because a file was already there and `force` was not given. */
+export interface DashTeamDesignAccepted {
+    written: string[];
+    kept: string[];
+    goals: string[];
+    problems: string[];
+    /** Whether the agents on the team were told to agent_join again (a team file that changed). */
+    notified?: boolean;
+}
+/** Whether a design still fits the project: what changed since it was made, and whether that is enough to design again. */
+export interface DashTeamDesignFit {
+    fits: boolean;
+    /** What moved since, in words: commits since its HEAD, projects added or gone, tracked files. */
+    changed: string[];
+    /** The project as it is now. */
+    now: TeamDesignBasis;
+}
+/**
+ * `GET /api/team/design` — and `team_design` over MCP: the newest run whole (its design once done), the newest design
+ * when that is another run, every run (without their designs), whether a key can pay for one, and — when asked
+ * (`?fits=1`) — whether the newest design still fits the project.
+ */
+export interface DashTeamDesignState {
+    /** A working key can pay for a design: an Anthropic key, or one of the provider of the model Settings chose for it. */
+    ready: boolean;
+    latest?: DashTeamDesignRun;
+    /** The newest finished design, when the newest run is another (one running now, one that failed). */
+    done?: DashTeamDesignRun;
+    /** Newest first, at most 20, without their designs. */
+    runs: DashTeamDesignRun[];
+    fits?: DashTeamDesignFit;
+}

package/lib/team-design.js

@@ -0,0 +1 @@
+"use strict";export const TEAM_DESIGN_VERSION=1;

package/lib/team-library.d.ts

@@ -0,0 +1,283 @@
+import type { DashTeamKind, DashTeamOutcome } from './team.js';
+/**
+ * The role library and the team as the person shapes it on the Team page (planning/team/02-role-library.md, RL1): the
+ * base roles LensMCP ships and its team templates, the repository's members built on them (`.lensmcp/team/roles/`),
+ * and the person's writes — a member added, edited or removed, a template previewed and applied. Served by
+ * servers/lensmcp-mcp/src/dashboard/team-library.ts; the data comes from `@lensmcp/storage` (library.ts,
+ * team-files.ts, templates.ts).
+ */
+export type DashTeamRoleFamily = 'lead' | 'build' | 'check' | 'support' | 'market';
+export type DashTeamWorktreePolicy = 'own' | 'shared' | 'any';
+/** A LensMCP tool a role works with, and when to reach for it. */
+export interface DashTeamRoleTool {
+    name: string;
+    when: string;
+}
+/** One tagged section of a role's craft: `<instructions id="…" note="…">`. */
+export interface DashTeamRoleSection {
+    tag: string;
+    id: string;
+    note?: string;
+}
+/** A library role in brief — a card. Its tools by name; `GET /api/team/library/role` has each one's when. */
+export interface DashTeamLibraryRole {
+    id: string;
+    title: string;
+    family: DashTeamRoleFamily;
+    /** Moves when what the role tells an agent changes. */
+    version: number;
+    /** Other names that resolve to it — the default it stands behind. */
+    aliases: string[];
+    summary: string;
+    takes: DashTeamKind[];
+    creates: DashTeamKind[] | 'any';
+    wip: number;
+    worktree: DashTeamWorktreePolicy;
+    /** Stack words it fits. */
+    fits: string[];
+    skills: string[];
+    tools: string[];
+    /** The id a member built on it gets in a repository: the default's it stands behind (`reviewer`), else its own. */
+    member: string;
+    /** The default role it stands behind, when it does. */
+    default?: string;
+    sections: DashTeamRoleSection[];
+    /** How long its craft is, in characters. */
+    chars: number;
+    /** `team://library/<id>` — where an agent reads it whole. */
+    uri: string;
+}
+/** `GET /api/team/library/role?id=` — one library role whole (by its id or an alias). */
+export interface DashTeamLibraryRoleWhole extends Omit<DashTeamLibraryRole, 'tools'> {
+    tools: DashTeamRoleTool[];
+    sha: string;
+    /** Its craft, as tagged sections — read-only beside a member's own rules. */
+    instructions: string;
+}
+/** A member a template staffs. */
+export interface DashTeamTemplateMember {
+    /** The library role it builds on. */
+    role: string;
+    /** Its id in the repository: `.lensmcp/team/roles/<member>.md`. */
+    member: string;
+    title: string;
+    agents: number;
+    start?: 'now' | 'later';
+}
+/**
+ * A hand-off of a template's own flow (TeamDesignHandOff without the text it may leave out: its title and description
+ * are its own, else the default flow's for the same step). `role` names a library role.
+ */
+export interface DashTeamTemplateHandOff {
+    on: {
+        kind: DashTeamKind;
+        outcome: DashTeamOutcome;
+        after?: 'build' | 'bug';
+        paths?: string[];
+    };
+    create: {
+        kind: DashTeamKind;
+        role?: string;
+        to?: 'owner';
+        join?: boolean;
+        title?: string;
+        description?: string;
+    };
+}
+export interface DashTeamTemplate {
+    id: string;
+    title: string;
+    summary: string;
+    fits: string[];
+    roles: DashTeamTemplateMember[];
+    flow: 'default' | DashTeamTemplateHandOff[];
+    /** When it fits, and how to adjust it. */
+    about: string;
+}
+/** `GET /api/team/library` — the base roles by family, in brief, and the team templates. */
+export interface DashTeamLibrary {
+    /** Moves when any role or template does. */
+    sha: string;
+    families: Array<{
+        family: DashTeamRoleFamily;
+        title: string;
+        roles: DashTeamLibraryRole[];
+    }>;
+    templates: DashTeamTemplate[];
+}
+/** Where a member's field came from: its file, its library base, the default role's text — tools and skills from both. */
+export type DashTeamFieldSource = 'file' | 'base' | 'default' | 'base+file';
+/** One member of the repository's team, as its files make it. */
+export interface DashTeamMember {
+    id: string;
+    title: string;
+    summary: string;
+    takes: DashTeamKind[];
+    creates: DashTeamKind[] | 'any';
+    wip: number;
+    worktree: DashTeamWorktreePolicy;
+    /** The library role it builds on — or, while the library has no entry behind a default, that default's id. */
+    base?: string;
+    /** The base's title and version, when it is a library role. */
+    baseTitle?: string;
+    baseVersion?: number;
+    /** The paths it changes and others do not. */
+    owns: string[];
+    /** The LensMCP tools it works with — from its base, or added by its file. */
+    tools: Array<DashTeamRoleTool & {
+        from: 'base' | 'file';
+    }>;
+    skills: Array<{
+        name: string;
+        from: 'base' | 'file';
+    }>;
+    /** Wants `wants` agents (none said: no number), has `has` active ones now — `listening` of them waiting for work. */
+    staffing: {
+        wants?: number;
+        start?: 'now' | 'later';
+        has: number;
+        listening: number;
+    };
+    /** The repository's own rules for it, as tagged sections — empty when it has none. */
+    rules: string;
+    /** `default`: no file — LensMCP's default (built on its library role); `file`: the repository's file; `design`: a file an accepted team design wrote. */
+    source: 'default' | 'file' | 'design';
+    /** Its file, when it has one: `.lensmcp/team/roles/<id>.md`. */
+    file?: string;
+    /** One of the seven defaults (removing it switches it off; deleting its file brings the default back). */
+    isDefault: boolean;
+    fields: Record<string, DashTeamFieldSource>;
+    /** Why its file was not read (the default stood in) — empty when it was. */
+    problems: string[];
+}
+/** `GET /api/team/roles` — the team as the checkout's files make it. */
+export interface DashTeamMembers {
+    members: DashTeamMember[];
+    /** Defaults switched off (`off: true`), each with its file. */
+    off: Array<{
+        id: string;
+        file: string;
+    }>;
+    flow: {
+        from: string;
+    };
+    /** Every file that was skipped, and why. */
+    problems: Array<{
+        file: string;
+        problem: string;
+    }>;
+    files: {
+        roles: string;
+        flow: string;
+        project: string;
+    };
+}
+/** One file a write would make: `write` (new — or already exactly so: `same`), `overwrite` (forced), `keep` (left as it is). */
+export interface DashTeamFilePlan {
+    path: string;
+    exists: boolean;
+    action: 'write' | 'overwrite' | 'keep';
+    same?: true;
+}
+/**
+ * `POST /api/team/roles` — a member created or changed: its file written as an overlay on its base (only what differs
+ * from it). Fields left out come from the base; `force` writes over a file that is there.
+ */
+export interface DashTeamMemberEdit {
+    /** One per submit. */
+    requestId: string;
+    /** Its id — when absent, the id a member built on `base` gets (`reviewer` for code-reviewer). */
+    id?: string;
+    /** A library role (id or alias); none for a role of the repository's own (it then needs title, summary and rules). */
+    base?: string;
+    title?: string;
+    summary?: string;
+    owns?: string[];
+    takes?: DashTeamKind[];
+    creates?: DashTeamKind[] | 'any';
+    wip?: number;
+    worktree?: DashTeamWorktreePolicy;
+    agents?: number;
+    start?: 'now' | 'later';
+    /** Tools added to the base's (one the base has, named again, takes this when). */
+    tools?: DashTeamRoleTool[];
+    /** Skills added to the base's. */
+    skills?: string[];
+    /** The repository's own rules for it — tagged sections, or plain lines (wrapped in `<rules id="role.<id>">`). */
+    rules?: string;
+    force?: boolean;
+}
+/** `POST /api/team/roles`'s answer: what happened to the file, and the member as it is now. */
+export interface DashTeamMemberWritten {
+    file: DashTeamFilePlan;
+    written: boolean;
+    problems: string[];
+    member?: DashTeamMember;
+    /** Whether the agents on the team were told to agent_join again (a file that changed, a requestId). */
+    notified?: boolean;
+    /** On a refusal (409): why, in words — the dashboard's fetch reads only this from an error answer. */
+    error?: string;
+}
+/** `POST /api/team/roles/remove` — `{ requestId, id, why? }`: a default switched off, a role of the repository's own deleted. */
+export interface DashTeamMemberRemoved {
+    path: string;
+    action: 'off' | 'deleted';
+    /** Whether the agents on the team were told to agent_join again. */
+    notified?: boolean;
+    /** Why they were not, when they were not. */
+    problems?: string[];
+}
+/** `POST /api/team/roles/on` — `{ requestId, id }`: a switched-off default back on the team. */
+export interface DashTeamMemberOn {
+    path: string;
+    /** Its file deleted (it only switched the role off), or its `off: true` line taken out (the file holds more). */
+    action: 'deleted' | 'changed';
+    /** Whether the agents on the team were told to agent_join again. */
+    notified?: boolean;
+    /** Why they were not, when they were not. */
+    problems?: string[];
+}
+/** `GET /api/team/paths?under=` — the tracked folders (with their file counts) and files directly under a path. */
+export interface DashTeamPaths {
+    under: string;
+    dirs: Array<{
+        path: string;
+        files: number;
+    }>;
+    files: string[];
+    /** More files than the answer carries, or the tracked-file list was cut. */
+    cut?: string;
+    /** Why nothing could be listed (not a Git checkout, git failed). */
+    why?: string;
+}
+/** `POST /api/team/templates/preview` — `{ requestId?, template, force? }`. */
+export interface DashTeamTemplatePreview {
+    template: {
+        id: string;
+        title: string;
+        summary: string;
+    };
+    members: DashTeamTemplateMember[];
+    /** The defaults it switches off. */
+    off: string[];
+    /** What it leaves as it is, and why. */
+    notes: string[];
+    files: DashTeamFilePlan[];
+    problems: string[];
+}
+/** `POST /api/team/templates/apply` — `{ requestId, template, force? }`. */
+export interface DashTeamTemplateApplied {
+    template: {
+        id: string;
+        title: string;
+        summary: string;
+    };
+    members: DashTeamTemplateMember[];
+    off: string[];
+    notes: string[];
+    written: string[];
+    kept: string[];
+    problems: string[];
+    /** The team was told (one broadcast note) — something changed. */
+    notified: boolean;
+}

package/lib/team-library.js

@@ -0,0 +1 @@
+"use strict";export{};