@dxos/deus 0.0.0-stage → 0.0.0

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 (201) hide show
  1. package/LICENSE +105 -0
  2. package/README.md +24 -2
  3. package/bin/deus.ts +42 -0
  4. package/dist/lib/chunk-blocks.mjs +151 -0
  5. package/dist/lib/chunk-blocks.mjs.map +1 -0
  6. package/dist/lib/chunk-check.mjs +452 -0
  7. package/dist/lib/chunk-check.mjs.map +1 -0
  8. package/dist/lib/chunk-completion.mjs +112 -0
  9. package/dist/lib/chunk-completion.mjs.map +1 -0
  10. package/dist/lib/chunk-extension.mjs +396 -0
  11. package/dist/lib/chunk-extension.mjs.map +1 -0
  12. package/dist/lib/chunk-parse.mjs +21 -0
  13. package/dist/lib/chunk-parse.mjs.map +1 -0
  14. package/dist/lib/cli.mjs +946 -0
  15. package/dist/lib/cli.mjs.map +1 -0
  16. package/dist/lib/extension.mjs +4 -0
  17. package/dist/lib/index.mjs +6 -0
  18. package/dist/lib/parse.mjs +4 -0
  19. package/dist/lib/review.mjs +260 -0
  20. package/dist/lib/review.mjs.map +1 -0
  21. package/dist/lib/spec-index.mjs +28 -0
  22. package/dist/lib/spec-index.mjs.map +1 -0
  23. package/dist/types/bin/deus.d.ts +3 -0
  24. package/dist/types/bin/deus.d.ts.map +1 -0
  25. package/dist/types/src/cli/__fixtures__/review/plugin-deps/dx.config.d.ts +8 -0
  26. package/dist/types/src/cli/__fixtures__/review/plugin-deps/dx.config.d.ts.map +1 -0
  27. package/dist/types/src/cli/__fixtures__/review/plugin-deps-diverged/dx.config.d.ts +8 -0
  28. package/dist/types/src/cli/__fixtures__/review/plugin-deps-diverged/dx.config.d.ts.map +1 -0
  29. package/dist/types/src/cli/__fixtures__/review/plugin-deps-empty/dx.config.d.ts +7 -0
  30. package/dist/types/src/cli/__fixtures__/review/plugin-deps-empty/dx.config.d.ts.map +1 -0
  31. package/dist/types/src/cli/__fixtures__/review/plugin-deps-mismatch/dx.config.d.ts +8 -0
  32. package/dist/types/src/cli/__fixtures__/review/plugin-deps-mismatch/dx.config.d.ts.map +1 -0
  33. package/dist/types/src/cli/__fixtures__/review/plugin-deps-noplugin/dx.config.d.ts +5 -0
  34. package/dist/types/src/cli/__fixtures__/review/plugin-deps-noplugin/dx.config.d.ts.map +1 -0
  35. package/dist/types/src/cli/changelog.d.ts +25 -0
  36. package/dist/types/src/cli/changelog.d.ts.map +1 -0
  37. package/dist/types/src/cli/cli.test.d.ts +2 -0
  38. package/dist/types/src/cli/cli.test.d.ts.map +1 -0
  39. package/dist/types/src/cli/errors.d.ts +183 -0
  40. package/dist/types/src/cli/errors.d.ts.map +1 -0
  41. package/dist/types/src/cli/features.d.ts +58 -0
  42. package/dist/types/src/cli/features.d.ts.map +1 -0
  43. package/dist/types/src/cli/git.d.ts +8 -0
  44. package/dist/types/src/cli/git.d.ts.map +1 -0
  45. package/dist/types/src/cli/index.d.ts +12 -0
  46. package/dist/types/src/cli/index.d.ts.map +1 -0
  47. package/dist/types/src/cli/lint.d.ts +17 -0
  48. package/dist/types/src/cli/lint.d.ts.map +1 -0
  49. package/dist/types/src/cli/qa-lint.d.ts +40 -0
  50. package/dist/types/src/cli/qa-lint.d.ts.map +1 -0
  51. package/dist/types/src/cli/qa.d.ts +86 -0
  52. package/dist/types/src/cli/qa.d.ts.map +1 -0
  53. package/dist/types/src/cli/review.d.ts +38 -0
  54. package/dist/types/src/cli/review.d.ts.map +1 -0
  55. package/dist/types/src/cli/spec-index.d.ts +17 -0
  56. package/dist/types/src/cli/spec-index.d.ts.map +1 -0
  57. package/dist/types/src/extension/blocks.d.ts +65 -0
  58. package/dist/types/src/extension/blocks.d.ts.map +1 -0
  59. package/dist/types/src/extension/check.d.ts +99 -0
  60. package/dist/types/src/extension/check.d.ts.map +1 -0
  61. package/dist/types/src/extension/check.test.d.ts +2 -0
  62. package/dist/types/src/extension/check.test.d.ts.map +1 -0
  63. package/dist/types/src/extension/code.d.ts +7 -0
  64. package/dist/types/src/extension/code.d.ts.map +1 -0
  65. package/dist/types/src/extension/complete.d.ts +6 -0
  66. package/dist/types/src/extension/complete.d.ts.map +1 -0
  67. package/dist/types/src/extension/completion.d.ts +10 -0
  68. package/dist/types/src/extension/completion.d.ts.map +1 -0
  69. package/dist/types/src/extension/constants.d.ts +6 -0
  70. package/dist/types/src/extension/constants.d.ts.map +1 -0
  71. package/dist/types/src/extension/fences.d.ts +10 -0
  72. package/dist/types/src/extension/fences.d.ts.map +1 -0
  73. package/dist/types/src/extension/gen/mdl.d.ts +3 -0
  74. package/dist/types/src/extension/gen/mdl.d.ts.map +1 -0
  75. package/dist/types/src/extension/gen/mdl.terms.d.ts +2 -0
  76. package/dist/types/src/extension/gen/mdl.terms.d.ts.map +1 -0
  77. package/dist/types/src/extension/index.d.ts +8 -0
  78. package/dist/types/src/extension/index.d.ts.map +1 -0
  79. package/dist/types/src/extension/language.d.ts +20 -0
  80. package/dist/types/src/extension/language.d.ts.map +1 -0
  81. package/dist/types/src/extension/lint.d.ts +8 -0
  82. package/dist/types/src/extension/lint.d.ts.map +1 -0
  83. package/dist/types/src/extension/parse.d.ts +6 -0
  84. package/dist/types/src/extension/parse.d.ts.map +1 -0
  85. package/dist/types/src/extension/parser.test.d.ts +2 -0
  86. package/dist/types/src/extension/parser.test.d.ts.map +1 -0
  87. package/dist/types/src/extension/refs.d.ts +32 -0
  88. package/dist/types/src/extension/refs.d.ts.map +1 -0
  89. package/dist/types/src/extension/refs.test.d.ts +2 -0
  90. package/dist/types/src/extension/refs.test.d.ts.map +1 -0
  91. package/dist/types/src/extension/syntax.d.ts +12 -0
  92. package/dist/types/src/extension/syntax.d.ts.map +1 -0
  93. package/dist/types/src/index.d.ts +3 -0
  94. package/dist/types/src/index.d.ts.map +1 -0
  95. package/dist/types/src/review/fields.d.ts +9 -0
  96. package/dist/types/src/review/fields.d.ts.map +1 -0
  97. package/dist/types/src/review/index.d.ts +5 -0
  98. package/dist/types/src/review/index.d.ts.map +1 -0
  99. package/dist/types/src/review/review.d.ts +70 -0
  100. package/dist/types/src/review/review.d.ts.map +1 -0
  101. package/dist/types/src/review/review.test.d.ts +2 -0
  102. package/dist/types/src/review/review.test.d.ts.map +1 -0
  103. package/dist/types/src/review/source-key.d.ts +35 -0
  104. package/dist/types/src/review/source-key.d.ts.map +1 -0
  105. package/dist/types/src/review/symbol.d.ts +17 -0
  106. package/dist/types/src/review/symbol.d.ts.map +1 -0
  107. package/dist/types/src/review/symbol.test.d.ts +2 -0
  108. package/dist/types/src/review/symbol.test.d.ts.map +1 -0
  109. package/dist/types/src/spec-index/index.d.ts +3 -0
  110. package/dist/types/src/spec-index/index.d.ts.map +1 -0
  111. package/dist/types/src/spec-index/parse.d.ts +11 -0
  112. package/dist/types/src/spec-index/parse.d.ts.map +1 -0
  113. package/dist/types/src/spec-index/spec-index.d.ts +21 -0
  114. package/dist/types/src/spec-index/spec-index.d.ts.map +1 -0
  115. package/dist/types/src/spec-index/spec-index.test.d.ts +2 -0
  116. package/dist/types/src/spec-index/spec-index.test.d.ts.map +1 -0
  117. package/dist/types/tsconfig.tsbuildinfo +1 -0
  118. package/docs/DESIGN.md +561 -0
  119. package/docs/IDIOMS.md +265 -0
  120. package/lang/PLUGIN-.template.mdl +115 -0
  121. package/lang/app.mdl +200 -0
  122. package/lang/changelog.mdl +184 -0
  123. package/lang/core.mdl +203 -0
  124. package/lang/examples/chess-1.mdl +149 -0
  125. package/lang/examples/chess-2.mdl +203 -0
  126. package/lang/examples/chess-3.mdl +231 -0
  127. package/lang/features.mdl +92 -0
  128. package/lang/plugin.mdl +59 -0
  129. package/lang/qa.mdl +383 -0
  130. package/lang/review.mdl +103 -0
  131. package/lang/sql.mdl +72 -0
  132. package/package.json +74 -3
  133. package/src/cli/__fixtures__/bad-decision.mdl +13 -0
  134. package/src/cli/__fixtures__/features/CYCLE.mdl +25 -0
  135. package/src/cli/__fixtures__/features/FEATURES.mdl +47 -0
  136. package/src/cli/__fixtures__/features/SPEC.mdl +22 -0
  137. package/src/cli/__fixtures__/features/SPEC.review.mdl +32 -0
  138. package/src/cli/__fixtures__/features/TASKS.md +5 -0
  139. package/src/cli/__fixtures__/lint-refs/SPEC.mdl +7 -0
  140. package/src/cli/__fixtures__/lint-refs/SPEC.review.mdl +7 -0
  141. package/src/cli/__fixtures__/qa-lint/packages/plugins/plugin-risky/PLUGIN.mdl +29 -0
  142. package/src/cli/__fixtures__/qa-list/plugin-sample/spec/PLUGIN.mdl +51 -0
  143. package/src/cli/__fixtures__/review/SPEC.mdl +23 -0
  144. package/src/cli/__fixtures__/review/SPEC.review.mdl +26 -0
  145. package/src/cli/__fixtures__/review/plugin-deps/PLUGIN.mdl +9 -0
  146. package/src/cli/__fixtures__/review/plugin-deps/PLUGIN.review.mdl +13 -0
  147. package/src/cli/__fixtures__/review/plugin-deps/dx.config.ts +10 -0
  148. package/src/cli/__fixtures__/review/plugin-deps-diverged/PLUGIN.mdl +9 -0
  149. package/src/cli/__fixtures__/review/plugin-deps-diverged/PLUGIN.review.mdl +14 -0
  150. package/src/cli/__fixtures__/review/plugin-deps-diverged/dx.config.ts +10 -0
  151. package/src/cli/__fixtures__/review/plugin-deps-empty/PLUGIN.mdl +9 -0
  152. package/src/cli/__fixtures__/review/plugin-deps-empty/PLUGIN.review.mdl +13 -0
  153. package/src/cli/__fixtures__/review/plugin-deps-empty/dx.config.ts +9 -0
  154. package/src/cli/__fixtures__/review/plugin-deps-mismatch/PLUGIN.mdl +9 -0
  155. package/src/cli/__fixtures__/review/plugin-deps-mismatch/PLUGIN.review.mdl +13 -0
  156. package/src/cli/__fixtures__/review/plugin-deps-mismatch/dx.config.ts +10 -0
  157. package/src/cli/__fixtures__/review/plugin-deps-noplugin/PLUGIN.mdl +9 -0
  158. package/src/cli/__fixtures__/review/plugin-deps-noplugin/PLUGIN.review.mdl +13 -0
  159. package/src/cli/__fixtures__/review/plugin-deps-noplugin/dx.config.ts +7 -0
  160. package/src/cli/changelog.ts +122 -0
  161. package/src/cli/cli.test.ts +359 -0
  162. package/src/cli/errors.ts +23 -0
  163. package/src/cli/features.ts +320 -0
  164. package/src/cli/git.ts +35 -0
  165. package/src/cli/index.ts +27 -0
  166. package/src/cli/lint.ts +75 -0
  167. package/src/cli/qa-lint.ts +206 -0
  168. package/src/cli/qa.ts +300 -0
  169. package/src/cli/review.ts +359 -0
  170. package/src/cli/spec-index.ts +54 -0
  171. package/src/extension/blocks.ts +169 -0
  172. package/src/extension/check.test.ts +629 -0
  173. package/src/extension/check.ts +552 -0
  174. package/src/extension/code.ts +99 -0
  175. package/src/extension/complete.ts +34 -0
  176. package/src/extension/completion.ts +64 -0
  177. package/src/extension/constants.ts +28 -0
  178. package/src/extension/fences.ts +270 -0
  179. package/src/extension/gen/mdl.terms.ts +16 -0
  180. package/src/extension/gen/mdl.ts +16 -0
  181. package/src/extension/index.ts +25 -0
  182. package/src/extension/language.ts +33 -0
  183. package/src/extension/lint.ts +19 -0
  184. package/src/extension/mdl.grammar +60 -0
  185. package/src/extension/parse.ts +31 -0
  186. package/src/extension/parser.test.ts +248 -0
  187. package/src/extension/refs.test.ts +95 -0
  188. package/src/extension/refs.ts +94 -0
  189. package/src/extension/syntax.ts +25 -0
  190. package/src/index.ts +6 -0
  191. package/src/review/fields.ts +31 -0
  192. package/src/review/index.ts +8 -0
  193. package/src/review/review.test.ts +111 -0
  194. package/src/review/review.ts +184 -0
  195. package/src/review/source-key.ts +63 -0
  196. package/src/review/symbol.test.ts +47 -0
  197. package/src/review/symbol.ts +96 -0
  198. package/src/spec-index/index.ts +6 -0
  199. package/src/spec-index/parse.ts +22 -0
  200. package/src/spec-index/spec-index.test.ts +56 -0
  201. package/src/spec-index/spec-index.ts +49 -0
package/docs/IDIOMS.md ADDED
@@ -0,0 +1,265 @@
1
+ # Idioms
2
+
3
+ > A named, canonical way of doing one thing in DXOS, demonstrated by real code
4
+ > that the build system compiles and tests.
5
+
6
+ ## What an idiom is
7
+
8
+ An **idiom** is a recurring solution to a problem in the DXOS codebase, given a
9
+ short slug and pinned to a single concrete artifact — a storybook story, a
10
+ test, a hook, a function, or a type. The artifact _is_ the canonical example;
11
+ the idiom is just metadata that names it, explains when to use it, and links it
12
+ to related symbols.
13
+
14
+ Idioms exist because:
15
+
16
+ - Agents need to find the right pattern by name before reading code.
17
+ - Humans need a single place to point to when reviewing a PR ("use the
18
+ `org.dxos.react-ui-menu.toolbarMenu` idiom").
19
+ - The codebase needs guard rails against drift — when the canonical artifact
20
+ breaks, the idiom breaks, and CI surfaces it.
21
+
22
+ ### Principles
23
+
24
+ **Code is ground truth.** An idiom cannot exist without a compiling, exported
25
+ artifact that demonstrates it. No prose-only idioms, no aspirational idioms.
26
+
27
+ **Nothing is an idiom by default.** A storybook story is just a story; a test
28
+ is just a test. Only an explicit `@idiom <slug>` tag promotes it.
29
+
30
+ **JSDoc carries the metadata.** Idioms travel with the code they describe.
31
+ No sidecar files, no central registry to keep in sync.
32
+
33
+ **Distributed authoring, central discovery.** Any package can declare idioms.
34
+ A build-time scanner (`moon run introspect:idioms`) harvests them into a single
35
+ catalog.
36
+
37
+ **Slugs are NSIDs.** Every idiom slug must be a well-formed AT Protocol NSID
38
+ (see [`@dxos/util.id`](../../../common/util/src/id.ts) and
39
+ <https://atproto.com/specs/nsid>). Authority segments are reverse-domain dotted
40
+ (`org.dxos.<package>`), the name segment is camelCase. One namespace across
41
+ the monorepo.
42
+
43
+ Examples:
44
+ `org.dxos.react-ui-menu.toolbarMenu`,
45
+ `org.dxos.echo-react.reactiveQuery`,
46
+ `org.dxos.app-framework.capabilityProvider`.
47
+
48
+ ## Tagging
49
+
50
+ An idiom is declared by adding an `@idiom` JSDoc tag to an exported symbol or a
51
+ top-level `test(...)` call.
52
+
53
+ ### Tag shape
54
+
55
+ ```ts
56
+ /**
57
+ * <Leading prose — becomes the idiom summary.>
58
+ *
59
+ * @idiom <slug>
60
+ * applies: <when this pattern fits>
61
+ * instead-of: <what this replaces> [{@link AntiSymbol}]
62
+ * uses: {@link SymbolA}, {@link SymbolB}
63
+ * related: <slug>, <slug>
64
+ */
65
+ ```
66
+
67
+ | Field | Required | Meaning |
68
+ | ------------ | -------- | ---------------------------------------------------------- |
69
+ | `<slug>` | yes | Globally unique [NSID](https://atproto.com/specs/nsid). |
70
+ | `applies` | yes | One-line applicability — when to reach for this. |
71
+ | `instead-of` | no | Anti-pattern this replaces. Prose plus optional `{@link}`. |
72
+ | `uses` | no | Comma-separated `{@link}` references to the key symbols. |
73
+ | `related` | no | NSID slugs of related idioms. |
74
+
75
+ The leading JSDoc paragraph (above the `@idiom` line) is the **summary**: a
76
+ two-to-four sentence rationale. If the host symbol's own JSDoc already explains
77
+ the pattern well, the leading prose may be empty — the agent will read the
78
+ source.
79
+
80
+ `{@link}` references are standard JSDoc and resolve against the introspect
81
+ symbol graph.
82
+
83
+ ### Hosts
84
+
85
+ The `@idiom` tag is recognized on:
86
+
87
+ - **Storybook story exports** — `export const X: Story = { … }` in any
88
+ `*.stories.tsx` file. Best for UI patterns.
89
+ - **Tests** — top-level `test('…', …)` calls in any `*.test.ts`. Best for
90
+ behavioral patterns (ECHO queries, effect flows, capability wiring). The tag
91
+ goes on a JSDoc immediately preceding the `test(...)` call.
92
+ - **Exported symbols** — any `export` declaration: function, class, hook, type,
93
+ schema, constant.
94
+
95
+ A test or story is _not_ an idiom by default — only the `@idiom` tag makes it
96
+ one. There is no implicit promotion based on naming, location, or other
97
+ heuristics.
98
+
99
+ If multiple artifacts demonstrate the same pattern, only one carries the tag —
100
+ the most representative. Others should link back via `related:` if useful.
101
+
102
+ ## Examples
103
+
104
+ ### UI pattern (story host)
105
+
106
+ ```tsx
107
+ // packages/ui/react-ui-menu/src/Menu.stories.tsx
108
+
109
+ /**
110
+ * Reactive toolbar driven by an atom-backed actions hook.
111
+ *
112
+ * Defining actions inside a hook lets them subscribe to reactive state
113
+ * (echo, atoms, settings) without re-rendering the toolbar shell. The
114
+ * menu structure is data, not JSX.
115
+ *
116
+ * @idiom org.dxos.react-ui-menu.toolbarMenu
117
+ * applies: Toolbars whose entries depend on reactive state
118
+ * instead-of: {@link Toolbar.Root} with hand-wired children
119
+ * uses: {@link useMenuActions}, {@link Menu.Root}
120
+ * related: org.dxos.react-ui-menu.menuActions, org.dxos.app-framework.actionGraph
121
+ */
122
+ export const ReactiveToolbar: Story = {
123
+ render: () => {
124
+ const actions = useMenuActions(/* ... */);
125
+ return <Menu.Root actions={actions} />;
126
+ },
127
+ };
128
+ ```
129
+
130
+ ### Behavioral pattern (test host)
131
+
132
+ ```ts
133
+ // packages/sdk/echo-react/src/use-query.test.tsx
134
+
135
+ /**
136
+ * Live ECHO query that re-renders the component on insert/update/delete.
137
+ *
138
+ * @idiom org.dxos.echo-react.reactiveQuery
139
+ * applies: Subscribing to a live ECHO collection from a React component
140
+ * instead-of: imperatively re-reading the space inside an effect
141
+ * uses: {@link Query}, {@link useQuery}
142
+ */
143
+ test('reactive query updates on insert', ({ expect }) => {
144
+ const tasks = useQuery(space, Query.type(Task));
145
+ // ...assertions that the query reacts...
146
+ });
147
+ ```
148
+
149
+ ### Pure-API pattern (symbol host)
150
+
151
+ ```ts
152
+ // packages/sdk/app-framework/src/define-capability.ts
153
+
154
+ /**
155
+ * @idiom org.dxos.app-framework.capabilityProvider
156
+ * applies: Exposing a service resolvable by id from elsewhere in the app
157
+ * uses: {@link contributes}, {@link Capability}
158
+ * related: org.dxos.app-framework.operationHandler, org.dxos.app-framework.pluginScaffold
159
+ */
160
+ export const defineCapability = /* ... */;
161
+ ```
162
+
163
+ ## Discovery
164
+
165
+ Idioms are harvested by a scanner exposed as `scanIdioms()` from
166
+ `@dxos/introspect/idioms`, and invoked by the `dx reflect idiom list` CLI command.
167
+
168
+ ### POC behavior (this PR)
169
+
170
+ The current POC is regex-based — it does **not** use the ts-morph indexer:
171
+
172
+ 1. Walks `packages/**/src/**/*.{ts,tsx}` via `glob`.
173
+ 2. Locates JSDoc blocks containing `@idiom <nsid>` on stories, tests, and
174
+ exported symbols.
175
+ 3. Parses the indented key:value body.
176
+ 4. Captures source location, a best-effort symbol/test name, and a host kind
177
+ (`story` / `test` / `symbol`).
178
+ 5. Throws if the slug fails NSID validation or if `applies:` is missing.
179
+
180
+ `{@link}` and `uses:` references are captured verbatim — they are not yet
181
+ resolved against the symbol graph.
182
+
183
+ ### Planned (not yet implemented)
184
+
185
+ The follow-on, ts-morph-based implementation will additionally:
186
+
187
+ - Resolve `{@link}` / `uses:` / `instead-of:` refs against the introspect
188
+ symbol graph.
189
+ - Emit `packages/reflect/introspect/dist/idioms.json` for downstream
190
+ consumers and the MCP server.
191
+ - Add a CI gate that fails on duplicate slugs, unresolved refs, or host
192
+ artifacts that do not compile.
193
+ - Emit warnings for idioms with no `uses:` / `instead-of:` references, or
194
+ whose summary is empty _and_ whose host has no JSDoc body.
195
+
196
+ ## MCP surface
197
+
198
+ The `@dxos/introspect-mcp` server exposes:
199
+
200
+ ```ts
201
+ list_idioms(filter?: { tag?: string })
202
+ → { slug, summary, host: 'story' | 'test' | 'symbol', canonicalSource }[]
203
+
204
+ get_idiom(slug)
205
+ → {
206
+ slug,
207
+ summary,
208
+ applies,
209
+ insteadOf?,
210
+ uses: SymbolRef[],
211
+ related: string[],
212
+ canonicalSource: {
213
+ kind: 'story' | 'test' | 'symbol',
214
+ file: string,
215
+ line: number,
216
+ excerpt: string,
217
+ storybookUrl?: string, // when host is a story
218
+ },
219
+ }
220
+
221
+ find_idioms_by_symbol(ref: SymbolRef)
222
+ → IdiomSummary[] // idioms that `uses:` this symbol
223
+ ```
224
+
225
+ `storybookUrl` is derived from the host file path + export name when the host
226
+ is a story; for tests and symbols it is omitted.
227
+
228
+ ## Deus integration
229
+
230
+ Deus does not own idioms. The language only needs a one-line ext in `Deus.DXOS`
231
+ so a `.mdl` document can _reference_ an idiom by slug:
232
+
233
+ ```mdl
234
+ ext idiom-ref
235
+ uri: org.dxos.mdl.idiom-ref@1.0
236
+ desc: Reference to an idiom by slug. Resolved via introspect.
237
+ fields:
238
+ slug: Identifier
239
+ ```
240
+
241
+ A `PLUGIN.mdl` may then list
242
+ `uses-idioms: [org.dxos.react-ui-menu.toolbarMenu, org.dxos.app-framework.capabilityProvider]`
243
+ to declare which patterns the plugin builds on. The introspect linter resolves
244
+ the slug against the idiom catalog.
245
+
246
+ ## Non-goals
247
+
248
+ - **Prose-only idioms.** Every idiom binds to a compiling artifact.
249
+ - **Idiom versioning.** Idioms move with their host code; semver is not
250
+ introduced. A breaking change to a host is a breaking change to the idiom.
251
+ - **Cross-repo idioms.** Idioms only describe patterns in this monorepo.
252
+ - **Auto-generation.** No tool will write `@idiom` tags for you. Tagging is an
253
+ explicit editorial act.
254
+
255
+ ## Open questions
256
+
257
+ - **Idiom deprecation.** When a pattern is superseded, do we keep the old
258
+ `@idiom` and add `@deprecated <reason> {@link new-slug}`, or remove it
259
+ entirely? Leaning: keep + deprecate, so agents reading old code can still
260
+ find the modern replacement.
261
+ - **Anti-idiom artifacts.** Should we support a `@anti-idiom <slug>` tag on a
262
+ story or test that demonstrates the broken version side-by-side? Useful for
263
+ rich storybook pages, but adds a second concept. Deferred to v2.
264
+ - **Authoring lint rules.** Should we enforce that every public package
265
+ exposes at least one idiom? Probably not — discovery should be organic.
@@ -0,0 +1,115 @@
1
+ ---
2
+ id: org.dxos.plugin.<name>
3
+ name: <Name>Plugin
4
+ version: 0.1.0
5
+ ---
6
+
7
+ <description>
8
+
9
+ ## Extensions
10
+
11
+ The following extension dialects are used in this document.
12
+ Each extension is defined in the Appendix or resolved via its URI.
13
+
14
+ | Term | URI |
15
+ |-------------|--------------------------------|
16
+ | `type` | `org.dxos.mdl.type@1.0` |
17
+ | `feat` | `org.dxos.mdl.feat@1.0` |
18
+ | `scenario` | `org.dxos.mdl.scenario@1.0` |
19
+ | `component` | `org.dxos.mdl.component@1.0` |
20
+ | `decision` | `org.dxos.mdl.decision@1.0` |
21
+
22
+ ## Types
23
+
24
+ ```mdl
25
+ type <name>
26
+ ```
27
+
28
+ ## Components
29
+
30
+ ```mdl
31
+ component <name>
32
+ desc: <description>
33
+ ```
34
+
35
+ ## Features
36
+
37
+ ```mdl
38
+ feat F-1: <feature>
39
+
40
+ req F-1.1: <requirement>
41
+ ```
42
+
43
+ ## Acceptance
44
+
45
+ ```mdl
46
+ scenario T-1:
47
+ given:
48
+ then:
49
+ ```
50
+
51
+ ## Changelog
52
+
53
+ Every change to this spec adds a decision, newest last. See `lang/changelog.mdl` for the attribution rules.
54
+
55
+ ```mdl
56
+ decision D-1: <what is now true>
57
+ date: <YYYY-MM-DD>
58
+ by: user:<handle>
59
+ why: <the constraint that forced it>
60
+ ```
61
+
62
+ ---
63
+
64
+ ## Appendix: Extension Definitions
65
+
66
+ Extension block types used in this document are defined below using
67
+ the core `ext` primitive — the only construct the base language provides.
68
+
69
+ ```mdl
70
+ ext type
71
+ uri: org.dxos.mdl.type@1.0
72
+ desc: A named data structure with typed fields and optional literals.
73
+ fields:
74
+ desc?: Prose
75
+ fields?: FieldMap # name[?]: TypeExpr (# inline comment)
76
+ literals?: UnionList # a | b | c
77
+ extends?: TypeRef[]
78
+ ```
79
+
80
+ ```mdl
81
+ ext feat
82
+ uri: org.dxos.mdl.feat@1.0
83
+ desc: A named feature grouping one or more requirements.
84
+ fields:
85
+ desc?: Prose
86
+ req: RequirementList
87
+ nesting: self # feat blocks may contain feat blocks
88
+ ```
89
+
90
+ ```mdl
91
+ ext scenario
92
+ uri: org.dxos.mdl.scenario@1.0
93
+ desc: An acceptance scenario expressed as given / when / then steps.
94
+ fields:
95
+ given?: Step | Step[]
96
+ when?: Step | Step[]
97
+ then: Step | Step[]
98
+ tags?: TagList
99
+ ```
100
+
101
+ ```mdl
102
+ ext component
103
+ uri: org.dxos.mdl.component@1.0
104
+ desc: A UI component with props, internal state, slots, actions, and events.
105
+ fields:
106
+ desc?: Prose
107
+ props?: FieldMap # external inputs (immutable inside component)
108
+ state?: FieldMap # internal reactive state
109
+ slots?: FieldMap # named ReactNode injection points
110
+ actions?: ActionMap # methods the component exposes or handles
111
+ emits?: EventMap # events the component raises to its parent
112
+ layout?: CodeBlock # ASCII sketch of visual structure (non-normative)
113
+ ```
114
+
115
+ `decision` is defined in [`changelog.mdl`](./changelog.mdl).
package/lang/app.mdl ADDED
@@ -0,0 +1,200 @@
1
+ ---
2
+ id: org.dxos.spec.app
3
+ name: DSL.App
4
+ version: 1.0
5
+ extends:
6
+ - org.dxos.spec.core
7
+ ---
8
+
9
+ The app dialect: vocabulary for describing a Composer application's
10
+ **navigation and presentation structure** — app-graph nodes, deck level
11
+ chains, planks, companions, surface contributions, and menus. It complements
12
+ the standard dialect (`type`, `op`, `component`, `service`, `feat`, `test`),
13
+ which describes data and behavior; this dialect describes *where things
14
+ appear and how the user reaches them*.
15
+
16
+ Consumers list the terms they use in their Extensions table (each resolves to
17
+ a URI defined here), or extend this document wholesale via frontmatter
18
+ `extends`. See `packages/plugins/plugin-inbox/PLUGIN.mdl` for a full
19
+ real-world usage.
20
+
21
+ ## Model
22
+
23
+ The vocabulary mirrors the runtime exactly:
24
+
25
+ - The **app-graph** is a reactive graph of nodes contributed by plugins.
26
+ A `node` block declares a node (or family of nodes) — its subject, its
27
+ children (e.g. folders), and the actions that hang off it.
28
+ - The **deck** renders planks; a plank is *just a graph-node id* whose content
29
+ resolves through an `article` Surface dispatch. A `deck` block declares a
30
+ **level chain** (`Mailbox > Message > Attachment`): opening at a level
31
+ reuses that level's plank and closes levels below.
32
+ - A **companion** is a child node (`~variant` linked segment) rendered as a
33
+ plank attached to its context plank.
34
+ - A **surface** contribution maps `(role, subject type)` to a component — the
35
+ single dispatch mechanism by which anything renders anywhere.
36
+ - A **menu** declares toolbar/context-menu content as references to
37
+ operations (`op:` blocks) and graph-node actions — never inline behavior.
38
+
39
+ ### Reference forms
40
+
41
+ Cross-references follow the core rules (`[id]`, `op:Name`, `component:Name`)
42
+ with these additional prefixes: `node:Name`, `surface:Name`, `type:Name`.
43
+ Subjects reference ECHO types declared in `type` blocks (or external types
44
+ listed in prose).
45
+
46
+ ## Extensions
47
+
48
+ | Term | URI |
49
+ | ----------- | ----------------------------- |
50
+ | `node` | `org.dxos.mdl.node@1.0` |
51
+ | `deck` | `org.dxos.mdl.deck@1.0` |
52
+ | `plank` | `org.dxos.mdl.plank@1.0` |
53
+ | `companion` | `org.dxos.mdl.companion@1.0` |
54
+ | `surface` | `org.dxos.mdl.surface@1.0` |
55
+ | `menu` | `org.dxos.mdl.menu@1.0` |
56
+
57
+ ## Definitions
58
+
59
+ ```mdl
60
+ ext node
61
+ uri: org.dxos.mdl.node@1.0
62
+ desc: |
63
+ An app-graph node contribution: a node (or per-object family of nodes)
64
+ the plugin adds to the graph. `source` names the parent — a well-known
65
+ node id (e.g. the space root) or a type whose instances the connector
66
+ expands. Children declared inline become child nodes (e.g. folders).
67
+ Actions reference `op:` blocks and surface as menu/toolbar items wherever
68
+ the node appears.
69
+ fields:
70
+ desc?: Prose
71
+ source?: NodeRef | TypeRef # parent node or the type this connector expands
72
+ subject?: TypeRef | Literal # the node's data (an ECHO object or a constant)
73
+ properties?: FieldMap # label, icon, disposition, position, ...
74
+ children?: NodeList # inline child node declarations (folders etc.)
75
+ actions?: OpRefList # operations contributed to this node
76
+ article?: SurfaceRef | ComponentRef # what an article surface renders for it
77
+ nesting: self
78
+ ```
79
+
80
+ ```mdl
81
+ ext deck
82
+ uri: org.dxos.mdl.deck@1.0
83
+ desc: |
84
+ A declared level chain: how reading down a hierarchy maps onto planks.
85
+ Each level names the plank that opens at that depth; opening at a level
86
+ reuses that level's plank and closes deeper ones. Modifier gestures
87
+ (meta/ctrl) opt out and open a free plank instead.
88
+ fields:
89
+ desc?: Prose
90
+ chain: PlankRefList # ordered, e.g. Mailbox > Message > Attachment
91
+ ```
92
+
93
+ ```mdl
94
+ ext plank
95
+ uri: org.dxos.mdl.plank@1.0
96
+ desc: |
97
+ One deck plank kind: which subject it presents and through which article.
98
+ `parent` places it in a level chain (equivalently declared via `deck`);
99
+ `companions` lists the companion variants available on it.
100
+ fields:
101
+ desc?: Prose
102
+ subject: TypeRef # the graph node data this plank presents
103
+ article: SurfaceRef | ComponentRef
104
+ parent?: PlankRef # the level above in the chain
105
+ companions?: CompanionRefList
106
+ ```
107
+
108
+ ```mdl
109
+ ext companion
110
+ uri: org.dxos.mdl.companion@1.0
111
+ desc: |
112
+ A plank companion: a child node (`~variant` linked segment) rendered as a
113
+ plank attached to its context plank, sharing its attention context.
114
+ fields:
115
+ desc?: Prose
116
+ of: TypeRef | NodeRef # the context plank's subject
117
+ variant: Identifier # the `~variant` segment / tab id
118
+ component?: ComponentRef | SurfaceRef
119
+ properties?: FieldMap # label, icon, position, ...
120
+ ```
121
+
122
+ ```mdl
123
+ ext surface
124
+ uri: org.dxos.mdl.surface@1.0
125
+ desc: |
126
+ A Surface contribution: maps a role token plus a subject-type filter to a
127
+ component. This is the app's single presentation dispatch — articles,
128
+ sections, cards, dialogs, and companions all resolve through it.
129
+
130
+ Resolution is not most-specific-wins: every contribution whose role and
131
+ filter match is a candidate, and `position` orders them (`first` /
132
+ `last` are the sentinels; equal positions keep registration order). A
133
+ role-only contribution therefore competes with a subject-specific one,
134
+ and the subject-specific one must claim an earlier position to win.
135
+ fields:
136
+ desc?: Prose
137
+ role: Identifier # role token (article | section | card | dialog | ...)
138
+ subject?: TypeRef # type filter; omitted = role-only match
139
+ component: ComponentRef
140
+ variant?: Identifier
141
+ position?: number | first | last # tie-break among all matching contributions
142
+ ```
143
+
144
+ ```mdl
145
+ ext menu
146
+ uri: org.dxos.mdl.menu@1.0
147
+ desc: |
148
+ Toolbar / context-menu content for a node or type: ordered references to
149
+ operations and action groups. Menus carry no behavior of their own —
150
+ every item resolves to an `op:` (directly or through a graph-node
151
+ action).
152
+ fields:
153
+ desc?: Prose
154
+ of: TypeRef | NodeRef # what the menu attaches to
155
+ disposition?: toolbar | context | list-item
156
+ items: OpRefList # ordered; groups as nested lists
157
+ ```
158
+
159
+ ## Example
160
+
161
+ A mailbox with system folders, a two-level reading chain, and a companion:
162
+
163
+ ```mdl
164
+ node MailboxNode
165
+ source: type:Mailbox
166
+ subject: type:Mailbox
167
+ properties:
168
+ icon: ph--tray--regular
169
+ children:
170
+ - Inbox # folder: system-tag filtered view of the mailbox
171
+ - Sent
172
+ - Drafts
173
+ actions: [op:SyncMailbox, op:DraftEmail]
174
+ ```
175
+
176
+ ```mdl
177
+ plank MailboxPlank
178
+ subject: type:Mailbox
179
+ article: component:MailboxArticle
180
+ ```
181
+
182
+ ```mdl
183
+ plank MessagePlank
184
+ subject: type:Message
185
+ article: component:MessageArticle
186
+ parent: MailboxPlank
187
+ ```
188
+
189
+ ```mdl
190
+ deck MailboxDeck
191
+ desc: Reading down the mailbox reuses one plank per level (two levels shown; the attachment level is elided).
192
+ chain: MailboxPlank > MessagePlank
193
+ ```
194
+
195
+ ```mdl
196
+ companion RelatedContacts
197
+ of: type:Message
198
+ variant: contacts
199
+ component: component:RelatedContacts
200
+ ```