@nocobase/app-plugin-projects 0.0.0-stage → 0.1.0-beta.2

package/dist/shared/workflows.js

@@ -0,0 +1,149 @@
+export const STATUS_CATEGORIES = [
+    'unstarted',
+    'started',
+    'done',
+    'closed',
+];
+export const STATUS_RULE_TYPES = [
+    'checklist',
+    'notifyOwner',
+    'subtasksDone',
+    'blockersDone',
+    'startOption',
+];
+/** The longest `startOption` label, as text or as a key's default. */
+export const START_LABEL_MAX = 64;
+/** A contributed rule type's key: not a built-in one. */
+export const STATUS_RULE_TYPE_PATTERN = /^[a-z][A-Za-z0-9]{1,63}$/u;
+export function isBuiltInRule(rule) {
+    return STATUS_RULE_TYPES.includes(rule.type);
+}
+export const WORKFLOW_EVENTS = [
+    'subtasks.done',
+];
+/** A contributed event's key: dotted, its plugin's prefix first, such as `acme.merged`. */
+export const WORKFLOW_EVENT_PATTERN = /^[a-z][a-zA-Z0-9]{0,31}(\.[a-z][a-zA-Z0-9]{0,63}){1,3}$/u;
+export function isBuiltInEvent(event) {
+    return WORKFLOW_EVENTS.includes(event);
+}
+export const APPROVER_ROLES = [
+    'owner',
+    'projectLead',
+    'admin',
+];
+/** `*` stands for any status. */
+export const ANY_STATUS = '*';
+export const WORKFLOW_NAME_MAX = 100;
+export const CHECKLIST_ITEMS_MAX = 20;
+export const CHECKLIST_LABEL_MAX = 200;
+export const CHECKLIST_ITEM_KEY_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/u;
+export const NOTIFY_MESSAGE_MAX = 500;
+export const MESSAGE_KEY_MAX = 200;
+export const MESSAGE_NAMESPACE_PATTERN = /^[@a-z0-9][@a-z0-9._/-]{0,99}$/u;
+export function isLocalizedMessage(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        typeof value.key === 'string');
+}
+/**
+ * A message in words: plain text as it is, a key through `t` (with its namespace and default). Blank text and
+ * anything else read as no message.
+ */
+export function messageText(message, t) {
+    if (typeof message === 'string')
+        return message.trim() || null;
+    if (!isLocalizedMessage(message))
+        return null;
+    const text = t(message.key, {
+        ...(message.ns ? { ns: message.ns } : {}),
+        defaultValue: message.defaultValue ?? message.key,
+    });
+    return text.trim() || null;
+}
+export const STATUS_NAME_MAX = 64;
+export const STATUS_KEY_PATTERN = /^[a-z][a-z0-9_]{1,31}$/u;
+/** Where a new issue starts, in every workflow. */
+export const INITIAL_STATUS = 'todo';
+/**
+ * Where issues wait before anyone plans them, in every workflow. Work does not start there: an executor given an issue
+ * in backlog starts when the issue leaves it.
+ */
+export const BACKLOG_STATUS = 'backlog';
+/**
+ * The nine statuses every workflow has, in the order of the old NocoProject's default workflow; notifications and
+ * reports rely on their keys.
+ */
+export const BUILTIN_STATUSES = [
+    {
+        key: BACKLOG_STATUS,
+        name: 'Backlog',
+        category: 'unstarted',
+        color: 'gray',
+        builtIn: true,
+    },
+    {
+        key: 'todo',
+        name: 'Todo',
+        category: 'unstarted',
+        color: 'blue',
+        builtIn: true,
+    },
+    {
+        key: 'analysis',
+        name: 'Analysis',
+        category: 'started',
+        color: 'orange',
+        builtIn: true,
+    },
+    {
+        key: 'proposal_review',
+        name: 'Proposal review',
+        category: 'started',
+        color: 'purple',
+        builtIn: true,
+    },
+    {
+        key: 'in_progress',
+        name: 'In progress',
+        category: 'started',
+        color: 'yellow',
+        builtIn: true,
+    },
+    {
+        key: 'in_review',
+        name: 'In review',
+        category: 'started',
+        color: 'purple',
+        builtIn: true,
+    },
+    {
+        key: 'blocked',
+        name: 'Blocked',
+        category: 'started',
+        color: 'red',
+        builtIn: true,
+    },
+    {
+        key: 'done',
+        name: 'Done',
+        category: 'done',
+        color: 'green',
+        builtIn: true,
+    },
+    {
+        key: 'cancelled',
+        name: 'Cancelled',
+        category: 'closed',
+        color: 'gray',
+        builtIn: true,
+    },
+];
+/** Whether a built-in status still has its default name, so the interface shows the translation instead. */
+export function hasDefaultName(status) {
+    return BUILTIN_STATUSES.some((builtIn) => builtIn.key === status.key && builtIn.name === status.name);
+}
+export function isTerminalCategory(category) {
+    return category === 'done' || category === 'closed';
+}
+//# sourceMappingURL=workflows.js.map

package/dist/shared/workflows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflows.js","sourceRoot":"","sources":["../../shared/workflows.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,207 @@
 {
   "name": "@nocobase/app-plugin-projects",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "displayName": "Projects",
+  "description": "Projects, issues, workflows and collaboration for a NocoBase application.",
+  "version": "0.1.0-beta.2",
+  "type": "module",
+  "prettier": "@nocobase/dev-config/prettier",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "sideEffects": false,
+  "exports": {
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
+    },
+    "./server/tokens": {
+      "types": "./dist/server/tokens.d.ts",
+      "import": "./dist/server/tokens.js"
+    },
+    "./server/composition": {
+      "types": "./dist/server/composition.d.ts",
+      "import": "./dist/server/composition.js"
+    },
+    "./shared/access": {
+      "types": "./dist/shared/access.d.ts",
+      "import": "./dist/shared/access.js"
+    },
+    "./shared/approvals": {
+      "types": "./dist/shared/approvals.d.ts",
+      "import": "./dist/shared/approvals.js"
+    },
+    "./shared/attachments": {
+      "types": "./dist/shared/attachments.d.ts",
+      "import": "./dist/shared/attachments.js"
+    },
+    "./shared/checklists": {
+      "types": "./dist/shared/checklists.d.ts",
+      "import": "./dist/shared/checklists.js"
+    },
+    "./shared/common": {
+      "types": "./dist/shared/common.d.ts",
+      "import": "./dist/shared/common.js"
+    },
+    "./shared/issues": {
+      "types": "./dist/shared/issues.d.ts",
+      "import": "./dist/shared/issues.js"
+    },
+    "./shared/intake": {
+      "types": "./dist/shared/intake.d.ts",
+      "import": "./dist/shared/intake.js"
+    },
+    "./shared/intake-ai": {
+      "types": "./dist/shared/intake-ai.d.ts",
+      "import": "./dist/shared/intake-ai.js"
+    },
+    "./shared/labels": {
+      "types": "./dist/shared/labels.d.ts",
+      "import": "./dist/shared/labels.js"
+    },
+    "./shared/members": {
+      "types": "./dist/shared/members.d.ts",
+      "import": "./dist/shared/members.js"
+    },
+    "./shared/plans": {
+      "types": "./dist/shared/plans.d.ts",
+      "import": "./dist/shared/plans.js"
+    },
+    "./shared/projects": {
+      "types": "./dist/shared/projects.d.ts",
+      "import": "./dist/shared/projects.js"
+    },
+    "./shared/realtime": {
+      "types": "./dist/shared/realtime.d.ts",
+      "import": "./dist/shared/realtime.js"
+    },
+    "./shared/settings": {
+      "types": "./dist/shared/settings.d.ts",
+      "import": "./dist/shared/settings.js"
+    },
+    "./shared/workflows": {
+      "types": "./dist/shared/workflows.d.ts",
+      "import": "./dist/shared/workflows.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js"
+    },
+    "./client/plugin": {
+      "types": "./dist/client/plugin.d.ts",
+      "import": "./dist/client/plugin.js"
+    },
+    "./client/config": {
+      "types": "./dist/client/config.d.ts",
+      "import": "./dist/client/config.js"
+    },
+    "./client/kit": {
+      "types": "./dist/client/kit.d.ts",
+      "import": "./dist/client/kit.js"
+    },
+    "./client/issues": {
+      "types": "./dist/client/issues.d.ts",
+      "import": "./dist/client/issues.js"
+    },
+    "./client/projects": {
+      "types": "./dist/client/projects.d.ts",
+      "import": "./dist/client/projects.js"
+    },
+    "./client/routes": {
+      "types": "./dist/client/routes.d.ts",
+      "import": "./dist/client/routes.js"
+    },
+    "./client/pages": {
+      "types": "./dist/client/pages.d.ts",
+      "import": "./dist/client/pages.js"
+    },
+    "./client/plan-model": {
+      "types": "./dist/client/plan-model.d.ts",
+      "import": "./dist/client/plan-model.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "skills"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "hono": "^4.13.2",
+    "officeparser": "^6.0.4",
+    "zod": "^4.6.5"
+  },
+  "peerDependencies": {
+    "@base-ui/react": "^1.6.0",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "@tanstack/react-query": "^5.81.5",
+    "@tanstack/react-table": "^8.2.6",
+    "@tiptap/core": "3.30.2",
+    "@tiptap/extension-link": "3.30.2",
+    "@tiptap/extension-list": "3.30.2",
+    "@tiptap/extension-placeholder": "3.30.2",
+    "@tiptap/extension-table": "3.30.2",
+    "@tiptap/markdown": "3.30.2",
+    "@tiptap/pm": "3.30.2",
+    "@tiptap/react": "3.30.2",
+    "@tiptap/starter-kit": "3.30.2",
+    "class-variance-authority": "^0.7.1",
+    "cmdk": "^1.1.1",
+    "cn": "^0.4.0",
+    "date-fns": "^4.1.0",
+    "lucide-react": "^0.487.0",
+    "react": "^19.0.0",
+    "react-day-picker": "10.0.1",
+    "react-markdown": "^10.1.0",
+    "react-router": "^7.0.2",
+    "react-virtuoso": "^4.18.15",
+    "remark-gfm": "^4.0.1",
+    "@nocobase/app-client": "^2.0.0-beta.2",
+    "@nocobase/app-plugin-authentication": "^2.0.0-beta.2",
+    "@nocobase/app-plugin-authorization": "^1.0.0-beta.25",
+    "@nocobase/app-plugin-file": "^1.0.0-beta.21",
+    "@nocobase/app-plugin-users": "^2.0.0-beta.1",
+    "@nocobase/app-server": "^2.0.0-beta.2",
+    "@nocobase/authorization": "^1.0.0-beta.12",
+    "@nocobase/db": "^1.0.0-beta.18",
+    "@nocobase/i18n": "^1.0.0-beta.5",
+    "@nocobase/markdown-mermaid": "^0.1.0-beta.1",
+    "@nocobase/app-plugin-notification": "^1.0.0-beta.24",
+    "@nocobase/repository-input": "^0.1.0-beta.2",
+    "@nocobase/service-provider": "^0.0.2-beta.1"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.3",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.2.0",
+    "eslint": "^10.0.0",
+    "jsdom": "^30.0.1",
+    "prettier": "^3.9.6",
+    "react-dom": "^19.2.8",
+    "shadcn": "^4.13.1",
+    "tailwindcss": "^4.1.4",
+    "tw-animate-css": "^1.2.5",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10",
+    "@nocobase/app-testing": "0.1.0-beta.1",
+    "@nocobase/db-sqlite": "0.1.0-beta.4",
+    "@nocobase/dev-config": "0.1.0-beta.20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && nocobase-db-manifests",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "lint": "eslint . --max-warnings 0",
+    "lint:fix": "eslint . --fix --max-warnings 0",
+    "format": "prettier . --write",
+    "format:check": "prettier . --check",
+    "check": "pnpm lint && pnpm format:check && pnpm typecheck && pnpm test && pnpm build",
+    "fix": "pnpm lint:fix && pnpm format"
+  }
 }

package/skills/nocobase-app-plugin-projects/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: nocobase-app-plugin-projects
+description: Register the Projects plugin in a NocoBase App, call its /api/projects API for projects, issues, workflows, labels and members, grant its permissions, or work out why a projects request is rejected.
+metadata:
+  short-description: Projects, issues, workflows, labels and members
+---
+
+# Projects App Plugin
+
+Use this Skill when an App needs project and issue tracking, or when a request under `/api/projects` fails. Do not use it
+for generic collection CRUD; the plugin's tables are only written through its API.
+
+## Public surfaces
+
+- Server plugin: default export of `@nocobase/app-plugin-projects/server`; `projectsToken` from
+  `@nocobase/app-plugin-projects/server/tokens` resolves the services. The App must bind `projectsAccessToken`
+  (`ProjectsAccess`: `permissionsOf`, `admit`, `changed`, `administrators`, and optionally `permissionsOfUser` so
+  notices reach only those who may see the issue): the plugin keeps no roles of its own. It may bind
+  `projectsNoticesToken` (`ProjectsNotices`: `send`, `resolve`) to receive the plugin's notices (owner notified,
+  approval requested as a `decision`, approval decided, commented, mentioned, status changed, owner or executor
+  assigned; information carries a `group` to merge by) and keep its own inbox; otherwise they go to the in-app
+  channel `projects.inboxChannel`. Another plugin binds `projectsTriggersToken` (`IssueTriggers`) to start work when
+  a person comments, and adds notice rules through `projectsNoticeRulesToken`. Operation plans (`shared/plans.ts`)
+  are proposed through `projects.plans` (`PlanService`: rehearse, create, propose to someone else, execute, preview an undo and undo in one step), and
+  a plugin binds `projectsPlanHooksToken` (`PlanHooks.onPlanDecided`) to hear their decisions.
+- Shared types: `@nocobase/app-plugin-projects/shared/<name>` (`access`, `attachments`, `comments`, `common`, `issues`,
+  `labels`, `members`, `plans`, `projects`, `settings`, `subscriptions`, `subtasks`, `workflows`).
+- Server routes: everything under `/api/projects`; see the package README for the list. Failures are the standard error body with domain `projects`: branch on `reason`, read details from `metadata`.
+- Client: the default export of `@nocobase/app-plugin-projects/client` adds `/projects` (the list and "New project").
+  The App owns a project's page (`/projects/:projectId`, routed as that route's child) and composes it from the
+  headless `@nocobase/app-plugin-projects/client/projects` (`useProjectDetail`, `useProjectUpdate`,
+  `useProjectMembership`, `useProjectResources`, `useResourceValidation`, `useDeleteProject`, `useProjectWorkflow`).
+  The App also owns `/issues` and
+  `/my-issues`: it composes them from the headless `@nocobase/app-plugin-projects/client/issues` (list and board queries,
+  board moves, filters in the query string, executor options) and routes the plugin's pages under `/issues` (the New
+  issue dialog with its AI draft and manual tabs, a plan) from `client/pages` (`issueChildRoutes`). It also owns an
+  issue's page (`/issues/:issueId`), presented over the same headless entry (`useIssueDetail`, `useIssuePageActions`,
+  `useIssueTimeline`, `useIssueCommentActions` and the rest), and hosts the plugin's "New sub-issue" dialog under it
+  (`issueDetailChildRoutes`).
+  The settings pages (issue prefix, labels, workflows) are exported from
+  `@nocobase/app-plugin-projects/client/config` for the App to route under its own settings page, and shared page
+  components from `@nocobase/app-plugin-projects/client/kit`. Changes are announced on the realtime topic `pm:changes`.
+
+The NocoBase UI Library presents these headless entries; install an item rather than building the page from scratch, and read its example (`pnpm exec shadcn view @nocobase/<item>-demo`) first. `project-detail` is a block for a project's page, `issue-detail` a block for an issue's page, and `issue-table`, `kanban` and `comment-thread` the components for the issue list, the board and an issue's activity. For agents working on issues, `agent-queue` (a block) and `agent-run-history` (a component) take the runs of `@nocobase/app-plugin-agents`. Each is installed with `yes n | pnpm exec shadcn add @nocobase/<item>` and is presentational: map the hooks' data to its props and its callbacks to the hooks' mutations.
+
+## Prerequisites
+
+The App must register `@nocobase/app-plugin-authentication`, `@nocobase/app-plugin-authorization` and
+`@nocobase/app-plugin-users` (whose invitations the member settings use) before this plugin, and bind
+`projectsAccessToken` from one of its own providers. The roles seed still creates `pm-*` permission sets with composite
+grants from before roles moved to the App; the App converts them (for example, `database/roles-conversion.ts`).
+
+## Permissions and constraints
+
+- Anonymous requests are 401. Every signed-in caller becomes a member on their first request, and the App's
+  `admit` gives them its default role.
+- Business actions (`pm.projects`: view, create, manage, delete; `pm.issues`: view, create, edit, comment,
+  moderate-comments, close, change-owner, delete; `pm.attachments`: upload) reach none, related or all records. The
+  plugin registers them as the `pm` resource type, one action per level (`edit.related`, `edit.all`; `create` and
+  `delete` without levels; `shared/access.ts`: `levelActionsOf`), and a role grants the level's action; the App's
+  `permissionsOf` says which for each request. Settings items (`pm.general`, `pm.labels`, `pm.workflows`: read,
+  update; `pm.members`: read, invite, assign, define-roles) are registered by the plugin. Creating an issue needs `pm.issues` `create`, not `edit`. `GET /api/projects/me` returns what the caller
+  holds.
+- Issue updates need the `revision` the caller read; a stale revision is 409 `REVISION_CONFLICT` (`ABORTED`).
+- An issue cannot be created in a terminal status, and moving it to another project needs a status that project's
+  workflow has. A status change the workflow does not allow for the caller is 400 `TRANSITION_NOT_ALLOWED`.
+- Workflows (`/api/projects/workflows`) are read by every member and changed with `pm.workflows` `update`. A definition is
+  `{ states: [{ key, name, category, color, builtIn? }], transitions: [{ from, to, actors }] }` (`*` for any
+  status, actors: registered kind keys, `user` and `system` built in); the seven built-in statuses stay, each
+  transition stays within what its kinds allow (`mayEnter`, `mayTargetAny`), and people can leave every status. Problems are 400 `INVALID_WORKFLOW` with `metadata.issues`; dropping a
+  status issues are in is 400 `WORKFLOW_STATUS_CONFLICT` (`FAILED_PRECONDITION`). A project's `workflowId` (null: the default) switches only
+  when every issue keeps its status.
+- A status may carry `rules`: `{ type: 'checklist', config: { items: [{ key, label, required }] } }` and
+  `{ type: 'notifyOwner', config: { message? } }`, each at most once. Entering the status copies the checklist to the
+  issue (`GET /api/projects/issues/{issueId}/checklists`, `PATCH …/checklists/{statusKey}/items/{itemKey} { checked }` by anyone who may
+  edit the issue); leaving it for anything but a closed status is 400 `CHECKLIST_INCOMPLETE` until the required items
+  are checked. `notifyOwner` records `owner_notified` and sends an `owner_notified` notice (see `projectsNoticesToken`
+  above); nothing is sent when the owner moved the issue.
+- Another plugin adds status rule types through `projectsStatusRulesToken` (`StatusRuleTypes.add({ type, categories?,
+validate?, describe?, canEnter?, entered? })`; `entered` runs in the move's transaction with the issue after the move
+  and may `setExecutor`; `canEnter` runs before every move into the status, the system's event moves included, and
+  answers null or `{ code, message, details? }`, which refuses the move with 400 `code`) and workflows that use them through `projectsWorkflowTemplatesToken` (installed once each, marked by
+  `builtInKey`, titled by the template's `title`). What such a rule did is recorded as `stage_action_applied` or
+  `stage_action_skipped { reason }`. A rule whose type is gone stays in the definition: saving keeps it unchanged,
+  entering skips it as `unavailable`. `POST /api/projects/workflows/{workflowId}/preview { definition }` (with `pm.workflows`
+  `update`) lists the rules a save would add or remove and those that wake someone without confirmation. In the
+  browser, `StatusRuleTypesContext` from `client/kit` gives each type its title, editor and summary.
+- Another plugin registers workflow events through `projectsWorkflowEventsToken` (`WorkflowEventTypes.add({ key, from?,
+to? })`, a dotted key such as `acme.merged`; `from`/`to` are the status categories a transition on it may leave and
+  enter) and fires one with `projects.workflowEvents.fire({ event, issueIds, actor?, note?, details? }, tx?)`. Each
+  issue with a `{ from, to, actors: ['system'], on: event }` transition from its status moves as the system, inside
+  `tx` when given; the activity `status_changed { event, note, cause }` names `actor`. The answer lists one outcome
+  per issue: `moved`, `ignored { reason: 'notFound' | 'noTransition' }` or `refused { code }` (an entry condition held
+  it back, recorded as `auto_move_skipped`). Only registered, contributed events may be fired. A transition on an
+  event whose plugin is gone is kept while unchanged. In the browser, `WorkflowEventsContext` (`client/kit`) gives
+  each event its title and hint for the workflow editor and the timeline.
+- A transition may carry `approval: { approvers: ['owner' | 'projectLead' | 'admin', …] }`. A status change through
+  it answers `PATCH /api/projects/issues/{issueId}` with 202 `{ data: { issue, pendingApproval } }` (the issue unchanged) unless the
+  mover is an approver or none resolves. `GET /api/projects/approvals` lists the caller's; `POST /api/projects/approvals/{approvalId}/
+approve|reject` (403 `NOT_APPROVER`) and `/withdraw` (403 `NOT_REQUESTER`) decide; a decided request is 400
+  `APPROVAL_DECIDED`, a second pending one 400 `APPROVAL_PENDING`. Approving moves the issue, or leaves the request
+  `stale` when the move no longer passes; the issue leaving the status also makes its request stale.
+- A sub-issue may have a `stage` (0–1000, 400 `INVALID_STAGE`). `POST /api/projects/issues/{issueId}/dependencies
+{ dependsOnIssueId, type: 'blockedBy' | 'relatedTo' }` links issues (201); `DELETE …/dependencies/{dependencyId}`
+  removes a link (204). A cycle is 400 `DEPENDENCY_CYCLE`, a duplicate 409 `DEPENDENCY_EXISTS`. Issue detail carries
+  `subtasks`, `blockedBy`, `blocks`, `relatedTo`, `blockers` and `hiddenBlockerCount`; list items `subtaskCount` and
+  `blockedCount`. Finishing an issue releases the issues waiting on it (`dependency_released` notice) and tells the
+  parent's owner when a stage or all sub-issues finish (`batch_done`). A workflow transition `{ from, to, actors:
+['system'], on: 'subtasks.done' }` moves the parent then; status rules `{ type: 'subtasksDone' }` (400
+  `SUBTASKS_OPEN`) and `{ type: 'blockersDone' }` (400 `ISSUE_BLOCKED`) refuse entering a status too early.
+- Comments (`/api/projects/issues/{issueId}/comments`, `/api/projects/comments/{commentId}…`): posting, replying and resolving need
+  `pm.issues` `comment`; only the author edits a comment (403 otherwise); deleting another's needs
+  `moderate-comments`. Content is 1 to 200,000 characters (400 `INVALID_COMMENT`); a reply's parent must be a comment of the
+  same issue (400 `INVALID_PARENT`); resolving a reply is 400 `NOT_THREAD_ROOT`; mentioning what a kind refuses is 403 `MENTION_FORBIDDEN`.
+  Reactions (`POST …/react` and `…/unreact` with `{ emoji }`) take one of the fixed emoji (400 `INVALID_INPUT`).
+- Files (`shared/attachments.ts`): stored through `@nocobase/app-plugin-file` on the App's default Drive disk (400
+  `FILES_UNAVAILABLE` without it), any type, at most 20 MiB each (413 `FILE_TOO_LARGE`). Uploading needs
+  `pm.attachments` `upload`: onto an issue (`POST /api/projects/issues/{issueId}/attachments`, with `edit`) or attached to nothing
+  (`POST /api/projects/attachments`) and then sent with a comment by `attachmentIds` (at most 10 of the caller's own; 400
+  `INVALID_ATTACHMENT` otherwise). Whoever sees the issue reads its files (`GET /api/projects/attachments/{attachmentId}/content`: safe
+  images inline, everything else as a download); the uploader or a comment moderator removes an issue's file, and a
+  comment's files go with the comment. Uploads attached to nothing are purged after 24 hours.
+- Roles, members' roles and the default role for new members are the App's (for example, `/api/acme/roles`,
+  `/api/acme/members`, `/api/acme/access/settings`).
+
+## Verification
+
+`GET /api/projects/me` as a signed-in user returns 200 with `permissions`; `POST /api/projects/issues` with a `title` returns 201
+with an identifier such as `PM-1`.