@crossworks/client-types 0.300.48 → 0.300.49

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crossworks/client-types",
3
- "version": "0.300.48",
3
+ "version": "0.300.49",
4
4
  "type": "module",
5
5
  "main": "./src/index.ts",
6
6
  "types": "./src/index.ts",
@@ -11,6 +11,7 @@
11
11
  * (`@crossworks/client-types/dto/access-keys`); the brain pins it to its
12
12
  * own list in a test.
13
13
  */
14
+ import type { LoginRole } from '../role-names';
14
15
 
15
16
  /** The parts of the brain a key can be limited to. */
16
17
  export const ACCESS_KEY_AREAS = [
@@ -31,7 +32,8 @@ export type AccessKeyArea = (typeof ACCESS_KEY_AREAS)[number];
31
32
 
32
33
  export type AccessKeyAccess = 'read' | 'read_write';
33
34
 
34
- export type AccessKeyRole = 'admin' | 'member';
35
+ /** The role of the login a key acts as (LOGIN_ROLES, ../role-names). */
36
+ export type AccessKeyRole = LoginRole;
35
37
 
36
38
  export type AccessKeyStatus = 'active' | 'expired' | 'revoked';
37
39
 
package/src/dto/logins.ts CHANGED
@@ -6,8 +6,11 @@
6
6
  * one of the reasons below.
7
7
  */
8
8
 
9
- /** Who a login is. The brain reads it from the login row on every request. */
10
- export type LoginKind = 'admin' | 'member';
9
+ import type { LoginRole } from '../role-names';
10
+
11
+ /** Who a login is. The brain reads it from the login row on every request.
12
+ * The login roles (LOGIN_ROLES, ../role-names). */
13
+ export type LoginKind = LoginRole;
11
14
 
12
15
  /** The `reason` of a 403 a gate answers a login of the wrong kind with:
13
16
  * `member-login` from an admin route, `admin-login` from a member route. */
package/src/dto/rows.ts CHANGED
@@ -11,6 +11,7 @@
11
11
  */
12
12
 
13
13
  import type { AppNav, AppOpenStat, AppTint } from '../app-nav';
14
+ import type { HistoryActor } from '../role-names';
14
15
  import type { ListChips, ListWorkspace } from './grants';
15
16
 
16
17
  // ── Row/DTO shapes moved from the server packages (jackdaw split P0) ─────────
@@ -273,7 +274,7 @@ export type AppSnapshot = {
273
274
  | 'pre_mcp_write';
274
275
  kind: 'version' | 'snapshot';
275
276
  note: string | null;
276
- actor: 'owner' | 'agent' | 'mcp' | 'system' | 'member';
277
+ actor: HistoryActor;
277
278
  createdAt: string;
278
279
  /** The seq this one's content was restored from, when it was. */
279
280
  restoredFrom: number | null;
@@ -301,7 +302,7 @@ export type TableSnapshot = {
301
302
  seq: number;
302
303
  trigger: 'commit' | 'manual';
303
304
  note: string | null;
304
- actor: 'owner' | 'agent' | 'mcp' | 'system' | 'member';
305
+ actor: HistoryActor;
305
306
  createdAt: string;
306
307
  /** The table's version the copy holds (it counts commits). */
307
308
  tableVersion: number | null;
package/src/dto/shell.ts CHANGED
@@ -7,10 +7,11 @@
7
7
  * both now answer 410 code gone.
8
8
  */
9
9
  import type { TreeKind } from '../tree';
10
+ import type { LoginRole } from '../role-names';
10
11
  import type { ShellWorkspace, WorkspaceArea } from './workspaces';
11
12
 
12
- /** Who is signed in, by role. */
13
- export type ShellRole = 'admin' | 'member';
13
+ /** Who is signed in, by role (LOGIN_ROLES, ../role-names). */
14
+ export type ShellRole = LoginRole;
14
15
 
15
16
  /** What this brain can do, so a client branches on capability, not version. */
16
17
  export type ShellFeatures = { recallV2: boolean };
@@ -8,18 +8,20 @@
8
8
  * or login the caller may not see answers 404, never 403.
9
9
  */
10
10
  import type { AppTint } from '../app-nav';
11
+ import type { LoginRole } from '../role-names';
11
12
 
12
- /** The Admin areas (plan 1.4). An Admin workspace user has all of them
13
- * unless a per-user switch turns one off (none can be switched off yet). */
14
- export type WorkspaceArea = 'settings' | 'users' | 'assistants' | 'connectors' | 'keys';
13
+ /** The Admin areas (plan 1.4), the one list of them (A10 #13: the brain's
14
+ * SCOPE_AREAS, adminUserSql and the route classes read it). An Admin
15
+ * workspace user has all of them unless a per-user switch turns one off
16
+ * (none can be switched off yet). In this order on the wire (the shell's
17
+ * `areas`). */
18
+ export const WORKSPACE_AREAS = ['settings', 'users', 'assistants', 'connectors', 'keys'] as const;
19
+ export type WorkspaceArea = (typeof WORKSPACE_AREAS)[number];
15
20
 
16
- export const WORKSPACE_AREAS: readonly WorkspaceArea[] = [
17
- 'settings',
18
- 'users',
19
- 'assistants',
20
- 'connectors',
21
- 'keys',
22
- ];
21
+ /** Whether `v` names an Admin area. */
22
+ export function isWorkspaceArea(v: unknown): v is WorkspaceArea {
23
+ return typeof v === 'string' && (WORKSPACE_AREAS as readonly string[]).includes(v);
24
+ }
23
25
 
24
26
  /** What a workspace is, for its default icon: the Admin workspace, a
25
27
  * login's private workspace, or any other. 'team' (the built-in Team
@@ -216,7 +218,7 @@ export type ShellWorkspaces = { workspaces: ShellWorkspace[]; areas: WorkspaceAr
216
218
  * `brainId` is left out only while the database is behind the code.
217
219
  */
218
220
  export type AuthWhoami = {
219
- role: 'admin' | 'member';
221
+ role: LoginRole;
220
222
  loginId: string;
221
223
  email: string;
222
224
  displayName: string | null;
package/src/index.ts CHANGED
@@ -180,6 +180,10 @@ export type {
180
180
  TreeVisibilityRefusal,
181
181
  TreeWorkspaceChange,
182
182
  } from './tree';
183
+ // Role and actor names (A10 #13). Types only; the lists (LOGIN_ROLES,
184
+ // HISTORY_ACTORS, RECALL_ACTOR_KINDS) are the `@mantle/client-types/role-names`
185
+ // subpath. RecallActorKind comes through ./dto/recall.
186
+ export type { HistoryActor, LoginRole } from './role-names';
183
187
  // Types only; WORKSPACE_AREAS (runtime) is the `@mantle/client-types/dto/workspaces` subpath.
184
188
  export type {
185
189
  AuthWhoami,
@@ -0,0 +1,257 @@
1
+ /**
2
+ * The role, area and actor names (arch plan A10 #13), RECORDED as every
3
+ * copy stood on main v0.300.47, before each was read from one source.
4
+ *
5
+ * Record, move, compare: the first commit of A10 #13 proved RECORDED
6
+ * against the literals in the source files (the commit before this one), and that
7
+ * every copy of a concept already held its source's values (no difference
8
+ * on main). Now each copy reads its source (./role-names and the dto lists),
9
+ * and this proves each source holds exactly the values main recorded, in
10
+ * main's order. A list the code only asks membership of is compared as a
11
+ * set; a list whose order means something is compared in order (ORDERED).
12
+ *
13
+ * These are also the contract's VALUES (jackdaw holds hand copies of some):
14
+ * a change here is a contract change, made on purpose.
15
+ */
16
+ import { readFileSync, readdirSync } from 'node:fs';
17
+ import { describe, expect, it } from 'vitest';
18
+ import { ACCESS_LEVELS } from './dto/access';
19
+ import { ACCESS_KEY_AREAS } from './dto/access-keys';
20
+ import { WORKSPACE_AREAS, isWorkspaceArea } from './dto/workspaces';
21
+ import { HISTORY_ACTORS, LOGIN_ROLES, RECALL_ACTOR_KINDS, isLoginRole } from './role-names';
22
+
23
+ /** Every concept: its source (file, then the list) and each copy on main. */
24
+ export const RECORDED = {
25
+ loginRole: {
26
+ // packages/db/src/schema/auth-users.ts LOGIN_ROLES (and the role CHECK
27
+ // users_role_ck, migration 0272).
28
+ source: ['admin', 'member'],
29
+ copies: {
30
+ 'packages/client-types/src/dto/logins.ts LoginKind': ['admin', 'member'],
31
+ 'packages/client-types/src/dto/shell.ts ShellRole': ['admin', 'member'],
32
+ 'packages/client-types/src/dto/access-keys.ts AccessKeyRole': ['admin', 'member'],
33
+ 'packages/client-types/src/dto/workspaces.ts AuthWhoami.role': ['admin', 'member'],
34
+ 'packages/content/src/contacts.ts loginEmails inArray': ['admin', 'member'],
35
+ 'packages/content/src/mcp-app-data.ts McpDataRole': ['admin', 'member'],
36
+ 'packages/mcp-core/src/login-surface.ts McpLoginRole': ['admin', 'member'],
37
+ 'packages/tools/src/types.ts LoginMcpChannel.role': ['admin', 'member'],
38
+ 'packages/runtime/src/assistant/run-team-turn.ts hasUnknownRole': ['admin', 'member'],
39
+ 'packages/db/src/test-support.ts setLoginRoleUnguarded': ['admin', 'member'],
40
+ 'server/web/app/api/auth/token/refresh/route.ts BEARER_ROLES': ['admin', 'member'],
41
+ 'server/web/app/api/users/route.ts CreateBody.role': ['admin', 'member'],
42
+ 'server/web/app/api/users/[id]/route.ts PatchBody.role': ['admin', 'member'],
43
+ 'server/web/app/api/users/[id]/password/route.ts named roles': ['admin', 'member'],
44
+ 'server/web/app/api/oauth/authorize/route.ts Consenter.role': ['admin', 'member'],
45
+ 'server/web/lib/access-keys.ts AccessKeyRole': ['admin', 'member'],
46
+ 'server/web/lib/access-keys.ts isRole': ['admin', 'member'],
47
+ 'server/web/lib/mcp-auth.ts isRole': ['admin', 'member'],
48
+ 'server/web/lib/auth/session.ts HttpLogin.role': ['admin', 'member'],
49
+ 'server/web/lib/auth/session.ts ChatLogin.kind': ['admin', 'member'],
50
+ 'server/web/lib/auth/session.ts getCookieUpgradeLoginOr401 role': ['admin', 'member'],
51
+ 'server/web/lib/auth/session.ts passwordRole': ['admin', 'member'],
52
+ 'server/web/lib/login-update.ts LoginChange.role': ['admin', 'member'],
53
+ 'server/web/lib/login-update.ts role-fixed refusal': ['admin', 'member'],
54
+ 'server/web/lib/workspaces.ts WsCaller.kind': ['admin', 'member'],
55
+ 'server/web/lib/workspaces.ts adminRoleChange role': ['admin', 'member'],
56
+ 'server/web/server/a4-guard-sweep.keys.ts row role': ['admin', 'member'],
57
+ 'server/web/server/a4-guard-sweep.keys.ts grant role': ['admin', 'member'],
58
+ },
59
+ },
60
+ workspaceArea: {
61
+ // packages/client-types/src/dto/workspaces.ts WORKSPACE_AREAS.
62
+ source: ['settings', 'users', 'assistants', 'connectors', 'keys'],
63
+ copies: {
64
+ 'packages/client-types/src/dto/workspaces.ts WorkspaceArea': [
65
+ 'settings',
66
+ 'users',
67
+ 'assistants',
68
+ 'connectors',
69
+ 'keys',
70
+ ],
71
+ 'packages/db/src/admin-user.ts Area': [
72
+ 'settings',
73
+ 'users',
74
+ 'assistants',
75
+ 'connectors',
76
+ 'keys',
77
+ ],
78
+ 'packages/db/src/viewer.ts SCOPE_AREAS': [
79
+ 'settings',
80
+ 'users',
81
+ 'assistants',
82
+ 'connectors',
83
+ 'keys',
84
+ ],
85
+ 'server/web/lib/auth/route-scope.ts AREAS': [
86
+ 'settings',
87
+ 'users',
88
+ 'assistants',
89
+ 'connectors',
90
+ 'keys',
91
+ ],
92
+ },
93
+ },
94
+ historyActor: {
95
+ // No source on main: three equal unions and the column's comment.
96
+ source: ['owner', 'agent', 'mcp', 'system', 'member'],
97
+ copies: {
98
+ 'packages/client-types/src/dto/rows.ts AppSnapshot.actor': [
99
+ 'owner',
100
+ 'agent',
101
+ 'mcp',
102
+ 'system',
103
+ 'member',
104
+ ],
105
+ 'packages/client-types/src/dto/rows.ts TableSnapshot.actor': [
106
+ 'owner',
107
+ 'agent',
108
+ 'mcp',
109
+ 'system',
110
+ 'member',
111
+ ],
112
+ 'packages/content/src/apps.ts AppHistoryActor': ['owner', 'agent', 'mcp', 'system', 'member'],
113
+ 'packages/db/src/schema/node-snapshots.ts actor comment': [
114
+ 'owner',
115
+ 'agent',
116
+ 'mcp',
117
+ 'system',
118
+ 'member',
119
+ ],
120
+ },
121
+ },
122
+ recallActor: {
123
+ // packages/db/src/schema/recall.ts RECALL_ACTOR_KINDS (and the CHECK
124
+ // recall_revisions_actor_kind_ck, migration 0203).
125
+ source: ['owner', 'agent'],
126
+ copies: {
127
+ 'packages/client-types/src/types/recall.ts RecallActorKind': ['owner', 'agent'],
128
+ 'packages/content/src/recall-native.ts RecallActor.kind': ['owner', 'agent'],
129
+ 'packages/content/src/recall-native.ts listRevisions actorKind': ['owner', 'agent'],
130
+ 'packages/content/src/recall-native.ts listRevisions cast': ['owner', 'agent'],
131
+ },
132
+ },
133
+ accessLevel: {
134
+ // packages/client-types/src/dto/access.ts ACCESS_LEVELS, highest first.
135
+ source: ['admin', 'team', 'client', 'public'],
136
+ copies: {
137
+ // Lowest first, on purpose (levelCovers reads it so): asked for
138
+ // membership only.
139
+ 'packages/db/src/viewer.ts VIEWER_LEVELS': ['public', 'client', 'team', 'admin'],
140
+ },
141
+ },
142
+ keyArea: {
143
+ // packages/client-types/src/dto/access-keys.ts ACCESS_KEY_AREAS.
144
+ source: [
145
+ 'search',
146
+ 'pages',
147
+ 'notes',
148
+ 'tasks',
149
+ 'tables',
150
+ 'files',
151
+ 'calendar',
152
+ 'contacts',
153
+ 'journal',
154
+ 'apps',
155
+ 'app_data',
156
+ ],
157
+ copies: {
158
+ 'packages/mcp-core/src/key-scope.ts KEY_AREAS': [
159
+ 'search',
160
+ 'pages',
161
+ 'notes',
162
+ 'tasks',
163
+ 'tables',
164
+ 'files',
165
+ 'calendar',
166
+ 'contacts',
167
+ 'journal',
168
+ 'apps',
169
+ 'app_data',
170
+ ],
171
+ },
172
+ },
173
+ } as const;
174
+
175
+ /** The copies whose order the code reads (iterates or shows), compared in
176
+ * order with their source. Every other copy is asked for membership. */
177
+ export const ORDERED: ReadonlySet<string> = new Set([
178
+ 'packages/db/src/viewer.ts SCOPE_AREAS',
179
+ 'packages/mcp-core/src/key-scope.ts KEY_AREAS',
180
+ ]);
181
+
182
+ /** The source of each concept, as the code reads it now. */
183
+ const SOURCES = {
184
+ loginRole: LOGIN_ROLES,
185
+ workspaceArea: WORKSPACE_AREAS,
186
+ historyActor: HISTORY_ACTORS,
187
+ recallActor: RECALL_ACTOR_KINDS,
188
+ accessLevel: ACCESS_LEVELS,
189
+ keyArea: ACCESS_KEY_AREAS,
190
+ } as const satisfies Record<keyof typeof RECORDED, readonly string[]>;
191
+
192
+ const MIGRATIONS = new URL('../../db/migrations/', import.meta.url);
193
+
194
+ /** The text of the newest migration that adds `constraint`. */
195
+ function newestCheck(constraint: string): string {
196
+ const files = readdirSync(MIGRATIONS)
197
+ .filter((f) => f.endsWith('.sql'))
198
+ .sort();
199
+ let found = '';
200
+ for (const f of files) {
201
+ const text = readFileSync(new URL(f, MIGRATIONS), 'utf8');
202
+ const at = text.indexOf(`ADD CONSTRAINT "${constraint}"`);
203
+ const inline = text.indexOf(`CONSTRAINT "${constraint}" CHECK`);
204
+ const from = at >= 0 ? at : inline;
205
+ if (from >= 0) found = text.slice(from, text.indexOf(';', from));
206
+ }
207
+ if (!found) throw new Error(`no migration adds ${constraint}`);
208
+ return found;
209
+ }
210
+
211
+ const quoted = (values: readonly string[]) => values.map((v) => `'${v}'`).join(', ');
212
+
213
+ /** Each copy that differs from its source (as a set, or in order for
214
+ * ORDERED): none on main. */
215
+ function differences(): string[] {
216
+ const out: string[] = [];
217
+ for (const [concept, { source: src, copies }] of Object.entries(RECORDED)) {
218
+ for (const [site, values] of Object.entries(copies)) {
219
+ const a: readonly string[] = values;
220
+ const b: readonly string[] = src;
221
+ const same = ORDERED.has(site)
222
+ ? a.join() === b.join()
223
+ : a.length === b.length && a.every((v) => b.includes(v));
224
+ if (!same) out.push(`${concept}: ${site} = ${a.join('|')}, source = ${b.join('|')}`);
225
+ }
226
+ }
227
+ return out;
228
+ }
229
+
230
+ describe('the role, area and actor names, recorded on main v0.300.47', () => {
231
+ it('each source holds the values main recorded, in main order', () => {
232
+ for (const [concept, values] of Object.entries(SOURCES)) {
233
+ expect([...values], concept).toEqual([...RECORDED[concept as keyof typeof RECORDED].source]);
234
+ }
235
+ });
236
+
237
+ it('every copy on main already held its source values', () => {
238
+ expect(differences()).toEqual([]);
239
+ });
240
+
241
+ it('the guards accept exactly the source values', () => {
242
+ for (const r of LOGIN_ROLES) expect(isLoginRole(r)).toBe(true);
243
+ for (const v of ['client', 'owner', 'Admin', '', null, undefined, 1]) {
244
+ expect(isLoginRole(v)).toBe(false);
245
+ }
246
+ for (const a of WORKSPACE_AREAS) expect(isWorkspaceArea(a)).toBe(true);
247
+ for (const v of ['content', 'self', 'Settings', '', null])
248
+ expect(isWorkspaceArea(v)).toBe(false);
249
+ });
250
+
251
+ it('the role and recall actor CHECKs admit the source values', () => {
252
+ expect(newestCheck('users_role_ck')).toContain(`CHECK ("role" IN (${quoted(LOGIN_ROLES)})`);
253
+ expect(newestCheck('recall_revisions_actor_kind_ck')).toContain(
254
+ `CHECK ("actor_kind" IN (${quoted(RECALL_ACTOR_KINDS)}))`,
255
+ );
256
+ });
257
+ });
@@ -0,0 +1,41 @@
1
+ /**
2
+ * Role and actor names (arch plan A10 #13): each list is written here once,
3
+ * and every type, zod enum, Set and membership test elsewhere reads it.
4
+ * Before A10 #13 the login roles alone were written by hand about thirty
5
+ * times; a role added to one copy would have been missing from the rest.
6
+ *
7
+ * The other name lists already had a source in this package and stay there
8
+ * (one source each, read the same way): the Admin areas WORKSPACE_AREAS
9
+ * (./dto/workspaces), the access levels ACCESS_LEVELS (./dto/access) and the
10
+ * key areas ACCESS_KEY_AREAS (./dto/access-keys). docs/actors.md, "Role and
11
+ * area names", lists them all with what reads each.
12
+ *
13
+ * Each list is a non-empty `as const` tuple, so it is its own zod enum:
14
+ * `z.enum(LOGIN_ROLES)`. Zero dependency and browser safe, as every
15
+ * subpath of this package is.
16
+ */
17
+
18
+ /** Every role a login can hold (workspaces W8a, migration 0272: the client
19
+ * role is gone). A role grants nothing: what a login reads and may do comes
20
+ * from its workspaces. The SQL CHECK users_role_ck admits the same values
21
+ * (role-names.test.ts pins it). A row whose role is not one of these is no
22
+ * login (fail closed). */
23
+ export const LOGIN_ROLES = ['admin', 'member'] as const;
24
+ export type LoginRole = (typeof LOGIN_ROLES)[number];
25
+
26
+ /** Whether `v` is a role this code knows: anything else is no login. */
27
+ export function isLoginRole(v: unknown): v is LoginRole {
28
+ return typeof v === 'string' && (LOGIN_ROLES as readonly string[]).includes(v);
29
+ }
30
+
31
+ /** Who a version or snapshot row of an app or a table names
32
+ * (node_snapshots.actor): 'member' is a member author's own act (team apps
33
+ * Phase 3), and the row then names the login too. */
34
+ export const HISTORY_ACTORS = ['owner', 'agent', 'mcp', 'system', 'member'] as const;
35
+ export type HistoryActor = (typeof HISTORY_ACTORS)[number];
36
+
37
+ /** Who wrote a recall revision (recall v2): the owner's UI or an agent's
38
+ * recall-write tool. The SQL CHECK recall_revisions_actor_kind_ck admits
39
+ * the same values (role-names.test.ts pins it). */
40
+ export const RECALL_ACTOR_KINDS = ['owner', 'agent'] as const;
41
+ export type RecallActorKind = (typeof RECALL_ACTOR_KINDS)[number];
@@ -13,6 +13,7 @@
13
13
  * `GET /api/shell`, absent on a brain older than v2. Branch the SCREEN on
14
14
  * that, not on the shapes below.
15
15
  */
16
+ import type { RecallActorKind } from '../role-names';
16
17
 
17
18
  /** One map in the catalog (`GET /api/recall/maps`). Unlike the agent-facing
18
19
  * `recall_index`, the owner catalog includes unpublished maps and maps with
@@ -109,9 +110,10 @@ export interface RecallMapDetailDTO extends RecallMapSummaryDTO {
109
110
  // `version` it was made against; a stale one is refused rather than silently
110
111
  // overwriting another editor's (or an agent's) change.
111
112
 
112
- /** Who made a change. An `agent` row is why the revision log exists: v2 serves
113
- * an agent's card edit immediately, with no compile step to hold it back. */
114
- export type RecallActorKind = 'owner' | 'agent';
113
+ /** Who made a change (RECALL_ACTOR_KINDS, ../role-names). An `agent` row is
114
+ * why the revision log exists: v2 serves an agent's card edit immediately,
115
+ * with no compile step to hold it back. */
116
+ export type { RecallActorKind };
115
117
 
116
118
  /** `POST /api/recall/maps` — a new map, with its entry card. Created
117
119
  * unpublished when an agent asks; the owner publishes it. */