proteum 2.1.3-1 → 2.1.7

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.
Files changed (95) hide show
  1. package/AGENTS.md +22 -14
  2. package/README.md +109 -17
  3. package/agents/project/AGENTS.md +188 -25
  4. package/agents/project/CODING_STYLE.md +1 -0
  5. package/agents/project/client/AGENTS.md +13 -8
  6. package/agents/project/client/pages/AGENTS.md +17 -9
  7. package/agents/project/diagnostics.md +52 -0
  8. package/agents/project/optimizations.md +48 -0
  9. package/agents/project/server/routes/AGENTS.md +9 -6
  10. package/agents/project/server/services/AGENTS.md +10 -6
  11. package/agents/project/tests/AGENTS.md +11 -5
  12. package/cli/app/config.ts +13 -14
  13. package/cli/app/index.ts +58 -0
  14. package/cli/commands/connect.ts +45 -0
  15. package/cli/commands/dev.ts +37 -13
  16. package/cli/commands/diagnose.ts +286 -0
  17. package/cli/commands/doctor.ts +18 -5
  18. package/cli/commands/explain.ts +25 -0
  19. package/cli/commands/perf.ts +243 -0
  20. package/cli/commands/trace.ts +9 -1
  21. package/cli/commands/verify.ts +281 -0
  22. package/cli/compiler/artifacts/connectedProjects.ts +453 -0
  23. package/cli/compiler/artifacts/controllers.ts +198 -49
  24. package/cli/compiler/artifacts/discovery.ts +0 -34
  25. package/cli/compiler/artifacts/manifest.ts +95 -6
  26. package/cli/compiler/artifacts/routing.ts +2 -2
  27. package/cli/compiler/artifacts/services.ts +277 -130
  28. package/cli/compiler/client/index.ts +3 -0
  29. package/cli/compiler/common/files/style.ts +52 -0
  30. package/cli/compiler/common/generatedRouteModules.ts +34 -5
  31. package/cli/compiler/common/scripts.ts +11 -5
  32. package/cli/compiler/index.ts +2 -1
  33. package/cli/compiler/server/index.ts +3 -0
  34. package/cli/presentation/commands.ts +110 -7
  35. package/cli/presentation/devSession.ts +32 -7
  36. package/cli/runtime/commands.ts +165 -6
  37. package/cli/scaffold/index.ts +18 -27
  38. package/cli/scaffold/templates.ts +48 -28
  39. package/cli/utils/agents.ts +106 -13
  40. package/cli/utils/keyboard.ts +8 -0
  41. package/client/dev/profiler/ApexChart.tsx +66 -0
  42. package/client/dev/profiler/index.tsx +2508 -302
  43. package/client/dev/profiler/runtime.noop.ts +12 -0
  44. package/client/dev/profiler/runtime.ts +195 -4
  45. package/client/services/router/request/api.ts +6 -1
  46. package/common/applicationConfig.ts +173 -0
  47. package/common/applicationConfigLoader.ts +102 -0
  48. package/common/connectedProjects.ts +113 -0
  49. package/common/dev/connect.ts +267 -0
  50. package/common/dev/console.ts +31 -0
  51. package/common/dev/contractsDoctor.ts +128 -0
  52. package/common/dev/diagnostics.ts +59 -15
  53. package/common/dev/inspection.ts +491 -0
  54. package/common/dev/performance.ts +809 -0
  55. package/common/dev/profiler.ts +3 -0
  56. package/common/dev/proteumManifest.ts +31 -6
  57. package/common/dev/requestTrace.ts +52 -1
  58. package/common/env/proteumEnv.ts +176 -50
  59. package/common/router/index.ts +1 -0
  60. package/common/router/request/api.ts +2 -0
  61. package/config.ts +5 -0
  62. package/docs/dev-commands.md +5 -1
  63. package/docs/dev-sessions.md +90 -0
  64. package/docs/diagnostics.md +74 -11
  65. package/docs/request-tracing.md +50 -3
  66. package/package.json +1 -1
  67. package/server/app/container/config.ts +16 -87
  68. package/server/app/container/console/index.ts +42 -8
  69. package/server/app/container/index.ts +10 -2
  70. package/server/app/container/trace/index.ts +105 -0
  71. package/server/app/devDiagnostics.ts +138 -0
  72. package/server/app/index.ts +18 -8
  73. package/server/app/service/container.ts +0 -12
  74. package/server/app/service/index.ts +0 -2
  75. package/server/services/prisma/index.ts +121 -4
  76. package/server/services/router/http/index.ts +305 -11
  77. package/server/services/router/index.ts +116 -57
  78. package/server/services/router/request/api.ts +160 -19
  79. package/server/services/router/request/index.ts +8 -0
  80. package/server/services/router/response/index.ts +23 -1
  81. package/server/services/router/response/page/document.tsx +31 -14
  82. package/server/services/router/response/page/index.tsx +10 -0
  83. package/agents/framework/AGENTS.md +0 -177
  84. package/server/services/auth/router/service.json +0 -6
  85. package/server/services/auth/service.json +0 -6
  86. package/server/services/cron/service.json +0 -6
  87. package/server/services/disks/drivers/local/service.json +0 -6
  88. package/server/services/disks/drivers/s3/service.json +0 -6
  89. package/server/services/disks/service.json +0 -6
  90. package/server/services/fetch/service.json +0 -7
  91. package/server/services/prisma/service.json +0 -6
  92. package/server/services/router/service.json +0 -6
  93. package/server/services/schema/router/service.json +0 -6
  94. package/server/services/schema/service.json +0 -6
  95. package/server/services/security/encrypt/aes/service.json +0 -6
@@ -34,12 +34,10 @@ export default class DocumentRenderer<TRouter extends TServerRouter> {
34
34
  <head>
35
35
  {/* Format */}
36
36
  <meta charSet="utf-8" />
37
- <meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1" />
37
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
38
38
 
39
39
  {/* CSS */}
40
40
  {this.clientStyles()}
41
- <link rel="preload" as="font" href={'/public/icons.woff2?v=' + BUILD_ID} type="font/woff2" />
42
- <link rel="stylesheet" type="text/css" href="/public/icons.css" />
43
41
 
44
42
  {/* JS */}
45
43
  <script
@@ -69,7 +67,7 @@ export default class DocumentRenderer<TRouter extends TServerRouter> {
69
67
  {/* Format */}
70
68
  <meta charSet="utf-8" />
71
69
  <meta content="IE=edge" httpEquiv="X-UA-Compatible" />
72
- <meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1" />
70
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
73
71
 
74
72
  {/* Mobile */}
75
73
  <meta name="application-name" content={this.app.identity.web.title} />
@@ -80,18 +78,28 @@ export default class DocumentRenderer<TRouter extends TServerRouter> {
80
78
  <meta name="msapplication-TileColor" content={this.app.identity.maincolor} />
81
79
  <meta name="apple-mobile-web-app-capable" content="yes" />
82
80
  <meta name="mobile-web-app-capable" content="yes" />
83
- <meta
84
- name="viewport"
85
- content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0"
86
- />
87
81
 
88
82
  {/* https://stackoverflow.com/questions/48956465/favicon-standard-2019-svg-ico-png-and-dimensions */}
89
83
  {/*<link rel="manifest" href={RES['manifest.json']} />*/}
90
- <link rel="shortcut icon" href="/public/app/favicon.ico" />
91
- <link rel="icon" type="image/png" sizes="16x16" href="/public/app/favicon-16x16.png" />
92
- <link rel="icon" type="image/png" sizes="32x32" href="/public/app/favicon-32x32.png" />
93
- <link rel="apple-touch-icon" sizes="180x180" href="/public/app/apple-touch-icon-180x180.png" />
94
- <meta name="msapplication-config" content="/public/app/browserconfig.xml" />
84
+ <link rel="shortcut icon" href={this.publicAssetUrl('app/favicon.ico', true)} />
85
+ <link
86
+ rel="icon"
87
+ type="image/png"
88
+ sizes="16x16"
89
+ href={this.publicAssetUrl('app/favicon-16x16.png', true)}
90
+ />
91
+ <link
92
+ rel="icon"
93
+ type="image/png"
94
+ sizes="32x32"
95
+ href={this.publicAssetUrl('app/favicon-32x32.png', true)}
96
+ />
97
+ <link
98
+ rel="apple-touch-icon"
99
+ sizes="180x180"
100
+ href={this.publicAssetUrl('app/apple-touch-icon-180x180.png', true)}
101
+ />
102
+ <meta name="msapplication-config" content={this.publicAssetUrl('app/browserconfig.xml', true)} />
95
103
 
96
104
  {/* Page */}
97
105
  <title>{page.title}</title>
@@ -165,7 +173,7 @@ export default class DocumentRenderer<TRouter extends TServerRouter> {
165
173
  return (
166
174
  <>
167
175
  {scripts.map((script) => {
168
- const src = this.clientAssetUrl(script, true);
176
+ const src = this.clientAssetUrl(script);
169
177
 
170
178
  return (
171
179
  <React.Fragment key={script}>
@@ -195,6 +203,11 @@ export default class DocumentRenderer<TRouter extends TServerRouter> {
195
203
  customContextKeys,
196
204
  serializedBytes: Buffer.byteLength(context, 'utf8'),
197
205
  routeCount: this.router.ssrRoutes.length,
206
+ source: {
207
+ filepath: page.route.options.filepath || '',
208
+ line: page.route.options.sourceLocation?.line || 0,
209
+ column: page.route.options.sourceLocation?.column || 0,
210
+ },
198
211
  },
199
212
  'resolve',
200
213
  );
@@ -243,6 +256,10 @@ export default class DocumentRenderer<TRouter extends TServerRouter> {
243
256
  }
244
257
 
245
258
  private clientAssetUrl(asset: string, withBuildId = false) {
259
+ return this.publicAssetUrl(asset, withBuildId);
260
+ }
261
+
262
+ private publicAssetUrl(asset: string, withBuildId = false) {
246
263
  return `/public/${asset}${withBuildId ? `?v=${BUILD_ID}` : ''}`;
247
264
  }
248
265
  }
@@ -70,6 +70,11 @@ export default class ServerPage<TRouter extends TServerRouter = TServerRouter> e
70
70
  chunkId: this.chunkId || '',
71
71
  title: this.title || '',
72
72
  routeId: this.route.options['id'] || '',
73
+ source: {
74
+ filepath: this.route.options.filepath || '',
75
+ line: this.route.options.sourceLocation?.line || 0,
76
+ column: this.route.options.sourceLocation?.column || 0,
77
+ },
73
78
  },
74
79
  'summary',
75
80
  );
@@ -103,6 +108,11 @@ export default class ServerPage<TRouter extends TServerRouter = TServerRouter> e
103
108
  documentLength: document.length,
104
109
  styleCount: this.style.length,
105
110
  scriptCount: this.scripts.length,
111
+ source: {
112
+ filepath: this.route.options.filepath || '',
113
+ line: this.route.options.sourceLocation?.line || 0,
114
+ column: this.route.options.sourceLocation?.column || 0,
115
+ },
106
116
  },
107
117
  'summary',
108
118
  );
@@ -1,177 +0,0 @@
1
- # Proteum App Contract
2
-
3
- This is the canonical contract for Proteum-based projects. Local project `AGENTS.md` files should add deltas only, not restate these rules.
4
-
5
- ## First Pass
6
-
7
- Inspect apps in this order:
8
-
9
- 1. Run `npx proteum explain --json` or read `./.proteum/manifest.json`.
10
- 2. Inspect `./server/index.ts`, `./server/config/*.ts`, and the touched files under `./commands`, `./server/controllers`, `./server/services`, `./server/routes`, and `./client/pages`.
11
- 3. Run `npx proteum doctor` if routing or generation looks suspicious.
12
- 4. For request-time issues in dev, read the default port from `PORT` or `./.proteum/manifest.json`; if a server is already running there, inspect `npx proteum trace` output before reproducing the issue or adding logs.
13
- 5. If existing traces are insufficient, run `npx proteum trace arm --capture deep`, reproduce once, then inspect the captured request.
14
-
15
- ## Non-Negotiable Rules
16
-
17
- - Client pages live in `client/pages/**` and register routes with top-level `Router.page(...)` or `Router.error(...)`.
18
- - Page URLs come from the explicit `Router.page('/path', ...)` call, not from the file path.
19
- - Callable app APIs live only in `server/controllers/**/*.ts` files that extend `Controller`.
20
- - Dev-only internal execution lives only in `commands/**/*.ts` files that extend `Commands`.
21
- - Manual HTTP endpoints live only in `server/routes/**`.
22
- - Controllers call `this.input(schema)` inside the method body, at most once per method.
23
- - Request-scoped state lives only on `this.request` and manual-route/router context objects.
24
- - SSR page data belongs in page `setup`, not in `api.fetch(...)`.
25
- - Normal service methods do not read request state directly.
26
- - Do not import runtime values from `@models`.
27
- - Do not use `@request` runtime globals.
28
- - Do not use `@app` on the client.
29
- - Do not edit generated files under `.proteum` by hand.
30
- - Prefer type inference rooted in the explicit application graph in `server/index.ts`.
31
-
32
- ## Source Of Truth
33
-
34
- Proteum reads:
35
-
36
- - `package.json`
37
- - `identity.yaml`
38
- - `process.env` via `PORT`, `ENV_*`, `URL`, and `TRACE_*`
39
- - `server/config/*.ts`
40
- - `server/index.ts`
41
- - `server/services/**/service.json`
42
- - `commands/**/*.ts`
43
- - `server/controllers/**/*.ts`
44
- - `server/routes/**/*.ts`
45
- - `client/pages/**/*.ts(x)`
46
- - `client/pages/**/_layout/index.tsx`
47
- - `public/**`
48
-
49
- Proteum owns:
50
-
51
- - `.proteum/manifest.json`
52
- - `.proteum/client/*`
53
- - `.proteum/common/*`
54
- - `.proteum/server/*`
55
-
56
- Project code should consume:
57
-
58
- - `@generated/client/*`
59
- - `@generated/common/*`
60
- - `@generated/server/*`
61
- - `@/client/context` as the generated client context entrypoint
62
-
63
- Prefer structured CLI surfaces over re-deriving framework facts from source:
64
-
65
- - `npx proteum explain --json`
66
- - `npx proteum doctor --json`
67
- - `npx proteum trace ...`
68
- - `npx proteum command ...`
69
- - `npx proteum create ... --dry-run --json`
70
-
71
- Prefer scaffold commands before hand-writing boilerplate:
72
-
73
- - Use `npx proteum init <directory> --name <name>` for new apps.
74
- - Use `npx proteum init ... --dry-run --json` when an agent needs a machine-readable app plan before writing files.
75
- - Use `npx proteum create page|controller|command|route|service <target>` for new app artifacts before creating the files manually.
76
- - Use `npx proteum create ... --dry-run --json` when an agent needs a machine-readable artifact plan before writing files.
77
-
78
- ## File Contracts
79
-
80
- ### App Bootstrap And Services
81
-
82
- - `server/index.ts` default-exports the app `Application` subclass and is the canonical type root.
83
- - Root services are public class fields instantiated with `new ServiceClass(this, config, this)`.
84
- - Typed root-service config lives in `server/config/*.ts` via `Services.config(ServiceClass, { ... })`.
85
- - Router plugins are instantiated explicitly inside the `Router` config `plugins` object.
86
- - `server/services/**/service.json` plus `server/index.ts` drive generated service typings and manifest entries.
87
- - Business logic lives in classes that extend `Service` and use `this.services`, `this.models`, and `this.app`.
88
- - Keep auth, input parsing, locale, cookies, and request-derived values in controllers, then pass explicit typed arguments into services.
89
- - Split growing features into explicit subservices.
90
- - `proteum create service ...` scaffolds the service file, its `service.json`, a typed config export under `server/config/*.ts`, and the root registration in `server/index.ts`; review and adapt the generated names before committing.
91
-
92
- ### Controllers
93
-
94
- - Files live under `server/controllers/**/*.ts` and default-export a class extending `Controller`.
95
- - Methods with bodies become generated client-callable endpoints.
96
- - Route path comes from the controller file path plus the method name.
97
- - `export const controllerPath = 'Custom/path'` can override the base path.
98
- - Generated client calls use `POST`.
99
- - Prefer `proteum create controller ...` for new controller boilerplate, then adapt the generated method to real service calls.
100
-
101
- ### Commands
102
-
103
- - Files live under `commands/**/*.ts` and default-export a class extending `Commands` from `@server/app/commands`.
104
- - Methods with bodies become generated dev commands.
105
- - Command path comes from the file path plus the method name.
106
- - `export const commandPath = 'Custom/path'` can override the base path.
107
- - Commands are for dev-only internal execution through `proteum command ...` or the profiler `Commands` tab.
108
- - Keep command logic internal; do not turn it into a normal controller unless it is a real app API.
109
- - Prefer `proteum create command ...` for new command boilerplate.
110
-
111
- ### Client Pages
112
-
113
- - Proteum scans page files for top-level `Router.page(...)` and `Router.error(...)` calls.
114
- - File path controls chunk identity and layout discovery; route path comes from the explicit `Router.page(...)` string.
115
- - Supported page signatures are `Router.page(path, render)`, `Router.page(path, setup, render)`, `Router.page(path, options, render)`, and `Router.page(path, options, setup, render)`.
116
- - For new work, prefer `Router.page(path, setup, render)` or `Router.page(path, options, setup, render)`.
117
- - `setup` returns one flat object. Reserved keys like `_auth`, `_layout`, `_static`, and `_redirectLogged` are route options; all other keys are SSR data.
118
- - Controller fetchers and promises returned from `setup` resolve before render.
119
- - `render` consumes resolved setup data and uses generated controller methods from render args or `@/client/context`.
120
- - Use `api.reload(...)` or `api.set(...)` only when intentionally mutating active page setup state.
121
- - Error pages use `Router.error(code, options, render)` in `client/pages/_messages/**`.
122
- - Prefer `proteum create page ...` for new page boilerplate, then review the explicit route path and setup payload.
123
-
124
- ### Manual Routes
125
-
126
- - Use `server/routes/**` only for explicit HTTP behavior that should not be a generated controller action.
127
- - Good fits include redirects, sitemap or RSS output, OAuth callbacks, webhooks, and public resources with custom semantics.
128
- - Import server-side app services from `@app` and use route handler context for `request`, `response`, router plugins, and custom router context.
129
- - If the route is a normal app API, prefer a controller.
130
- - Prefer `proteum create route ...` for new manual-route boilerplate.
131
-
132
- ### Models And Aliases
133
-
134
- - Use Prisma typings from `@models/types`.
135
- - Use runtime models through `this.models` or `this.app.Models.client`.
136
- - Keep Prisma runtime access inside services when possible and prefer explicit `select` or narrow `include`.
137
- - Do not import runtime values from `@models` or edit generated Prisma client files.
138
- - Aliases:
139
- - `@/client/...`, `@/server/...`, `@/common/...`: app code
140
- - `@client/...`, `@server/...`, `@common/...`: Proteum core modules
141
- - `@app`: server-side application services for manual routes only
142
- - `@generated/*`: generated app surfaces
143
-
144
- ## Design Rules
145
-
146
- - Prefer explicit `server/index.ts` bootstrap over hidden registration.
147
- - Prefer controller-backed app APIs over ad hoc manual `/api/...` routes.
148
- - Prefer service classes over server helpers with hidden dependencies.
149
- - Keep one canonical source of truth for catalogs, registries, and shared types.
150
- - Reuse project-local Shadcn-based UI primitives when the app already provides them.
151
- - Before inventing a helper, primitive, parser, formatter, SDK wrapper, or build-time tool, first check whether the repo already depends on a suitable package.
152
- - If it does not, search npm before writing a custom implementation.
153
- - Prefer widely adopted, actively maintained, flexible, well-typed packages.
154
- - Only build custom infrastructure when packages would clearly hurt bundle size, SSR behavior, performance, explicit contracts, or long-term maintainability.
155
- - If you choose custom over a package, state briefly why.
156
-
157
- ## Discouraged Patterns
158
-
159
- - `api.fetch(...)` inside page files for SSR loading
160
- - client-side `@app` imports
161
- - runtime `@models` imports
162
- - request-scoped state inside normal service methods
163
- - hiding route registration behind abstractions that remove the top-level `Router.page(...)` call
164
- - editing `.proteum` directly
165
-
166
- ## Verification
167
-
168
- Verify at the correct layer:
169
-
170
- - route additions: boot the app and hit the real URL
171
- - controller changes: exercise the generated client call or generated `/api/...` endpoint
172
- - SSR changes: load the real page and inspect rendered HTML plus browser console
173
- - router or plugin changes: verify request context, auth, redirects, metrics, and validation on a running app
174
-
175
- When an app may already be running, check the default port from `PORT` or `./.proteum/manifest.json` and inspect `proteum trace requests`, `proteum trace latest`, and `proteum trace show <requestId>` before reproducing the issue. If those traces are not enough, arm `npx proteum trace arm --capture deep`, reproduce once, then inspect the new request.
176
-
177
- Useful commands: `npx proteum init <dir> --name <name>`, `npx proteum create <kind> <target>`, `proteum dev`, `npx proteum refresh`, `npx proteum typecheck`, `npx proteum lint`, `npx proteum check`, `npx proteum build prod`, `npx proteum command <path>`.
@@ -1,6 +0,0 @@
1
- {
2
- "id": "Core/Users/Router",
3
- "name": "RouteUser",
4
- "parent": "router",
5
- "dependences": []
6
- }
@@ -1,6 +0,0 @@
1
- {
2
- "id": "Core/Users",
3
- "name": "Users",
4
- "parent": "app",
5
- "dependences": []
6
- }
@@ -1,6 +0,0 @@
1
- {
2
- "id": "Core/Cron",
3
- "name": "Cron",
4
- "parent": "app",
5
- "dependences": []
6
- }
@@ -1,6 +0,0 @@
1
- {
2
- "id": "Core/Disks/Local",
3
- "name": "LocalDiskDriver",
4
- "parent": "disks",
5
- "dependences": []
6
- }
@@ -1,6 +0,0 @@
1
- {
2
- "id": "Core/Disks/S3",
3
- "name": "S3DiskDriver",
4
- "parent": "disks",
5
- "dependences": []
6
- }
@@ -1,6 +0,0 @@
1
- {
2
- "id": "Core/Disks",
3
- "name": "Disks",
4
- "parent": "app",
5
- "dependences": []
6
- }
@@ -1,7 +0,0 @@
1
- {
2
- "id": "Core/Fetch",
3
- "name": "Fetch",
4
- "parent": "app",
5
- "dependences": [],
6
- "priority": 0
7
- }
@@ -1,6 +0,0 @@
1
- {
2
- "id": "Core/Models",
3
- "name": "Models",
4
- "parent": "app",
5
- "dependences": []
6
- }
@@ -1,6 +0,0 @@
1
- {
2
- "id": "Core/Router",
3
- "name": "Router",
4
- "parent": "app",
5
- "dependences": []
6
- }
@@ -1,6 +0,0 @@
1
- {
2
- "id": "Core/Schema/Router",
3
- "name": "RouteSchema",
4
- "parent": "router",
5
- "dependences": []
6
- }
@@ -1,6 +0,0 @@
1
- {
2
- "id": "Core/Schema",
3
- "name": "Schema",
4
- "parent": "app",
5
- "dependences": []
6
- }
@@ -1,6 +0,0 @@
1
- {
2
- "id": "Core/Encryption/AES",
3
- "name": "AES",
4
- "parent": "app",
5
- "dependences": []
6
- }