pm-presets 2026.10.30 → 2026.11.5
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/CHANGELOG.md +30 -0
- package/README.md +194 -19
- package/dist/application-history.d.ts +12 -0
- package/dist/application-history.d.ts.map +1 -0
- package/dist/application-history.js +59 -0
- package/dist/application-history.js.map +1 -0
- package/dist/apply-admission.d.ts +21 -0
- package/dist/apply-admission.d.ts.map +1 -0
- package/dist/apply-admission.js +115 -0
- package/dist/apply-admission.js.map +1 -0
- package/dist/apply-command.d.ts +44 -0
- package/dist/apply-command.d.ts.map +1 -0
- package/dist/apply-command.js +47 -0
- package/dist/apply-command.js.map +1 -0
- package/dist/artifact-ownership.d.ts +17 -0
- package/dist/artifact-ownership.d.ts.map +1 -0
- package/dist/artifact-ownership.js +123 -0
- package/dist/artifact-ownership.js.map +1 -0
- package/dist/artifact-reader.d.ts +7 -0
- package/dist/artifact-reader.d.ts.map +1 -0
- package/dist/artifact-reader.js +48 -0
- package/dist/artifact-reader.js.map +1 -0
- package/dist/catalog.d.ts +52 -2
- package/dist/catalog.d.ts.map +1 -1
- package/dist/catalog.js +120 -45
- package/dist/catalog.js.map +1 -1
- package/dist/command-errors.d.ts +7 -0
- package/dist/command-errors.d.ts.map +1 -0
- package/dist/command-errors.js +72 -0
- package/dist/command-errors.js.map +1 -0
- package/dist/desired-state.d.ts +61 -0
- package/dist/desired-state.d.ts.map +1 -0
- package/dist/desired-state.js +157 -0
- package/dist/desired-state.js.map +1 -0
- package/dist/diff.d.ts +54 -19
- package/dist/diff.d.ts.map +1 -1
- package/dist/diff.js +228 -32
- package/dist/diff.js.map +1 -1
- package/dist/export.d.ts +1 -1
- package/dist/export.d.ts.map +1 -1
- package/dist/export.js +10 -2
- package/dist/export.js.map +1 -1
- package/dist/index.d.ts +13 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +69 -29
- package/dist/index.js.map +1 -1
- package/dist/input-file.d.ts +3 -0
- package/dist/input-file.d.ts.map +1 -0
- package/dist/input-file.js +25 -0
- package/dist/input-file.js.map +1 -0
- package/dist/json-object.d.ts +4 -0
- package/dist/json-object.d.ts.map +1 -0
- package/dist/json-object.js +6 -0
- package/dist/json-object.js.map +1 -0
- package/dist/params.d.ts +263 -0
- package/dist/params.d.ts.map +1 -0
- package/dist/params.js +762 -0
- package/dist/params.js.map +1 -0
- package/dist/plan.d.ts.map +1 -1
- package/dist/plan.js +3 -2
- package/dist/plan.js.map +1 -1
- package/dist/presets/agent-workflow/index.d.ts.map +1 -1
- package/dist/presets/agent-workflow/index.js +1 -0
- package/dist/presets/agent-workflow/index.js.map +1 -1
- package/dist/presets/bug-triage/index.d.ts.map +1 -1
- package/dist/presets/bug-triage/index.js +1 -0
- package/dist/presets/bug-triage/index.js.map +1 -1
- package/dist/presets/indie-dev/index.d.ts.map +1 -1
- package/dist/presets/indie-dev/index.js +1 -0
- package/dist/presets/indie-dev/index.js.map +1 -1
- package/dist/presets/kanban/index.d.ts.map +1 -1
- package/dist/presets/kanban/index.js +1 -0
- package/dist/presets/kanban/index.js.map +1 -1
- package/dist/presets/open-source/index.d.ts.map +1 -1
- package/dist/presets/open-source/index.js +1 -0
- package/dist/presets/open-source/index.js.map +1 -1
- package/dist/presets/shared.d.ts +8 -1
- package/dist/presets/shared.d.ts.map +1 -1
- package/dist/presets/shared.js +456 -62
- package/dist/presets/shared.js.map +1 -1
- package/dist/presets/software-sprint/index.d.ts.map +1 -1
- package/dist/presets/software-sprint/index.js +1 -0
- package/dist/presets/software-sprint/index.js.map +1 -1
- package/dist/presets/startup-roadmap/index.d.ts +11 -0
- package/dist/presets/startup-roadmap/index.d.ts.map +1 -1
- package/dist/presets/startup-roadmap/index.js +25 -3
- package/dist/presets/startup-roadmap/index.js.map +1 -1
- package/dist/registry.d.ts +10 -1
- package/dist/registry.d.ts.map +1 -1
- package/dist/registry.js +18 -1
- package/dist/registry.js.map +1 -1
- package/dist/sdk-loader.js +1 -1
- package/dist/sdk-loader.js.map +1 -1
- package/dist/seeds.d.ts +17 -2
- package/dist/seeds.d.ts.map +1 -1
- package/dist/seeds.js +51 -12
- package/dist/seeds.js.map +1 -1
- package/dist/settings-replacement.d.ts +4 -0
- package/dist/settings-replacement.d.ts.map +1 -0
- package/dist/settings-replacement.js +50 -0
- package/dist/settings-replacement.js.map +1 -0
- package/dist/simulation.d.ts.map +1 -1
- package/dist/simulation.js +4 -3
- package/dist/simulation.js.map +1 -1
- package/dist/stack.d.ts.map +1 -1
- package/dist/stack.js +15 -7
- package/dist/stack.js.map +1 -1
- package/dist/upgrade-command.d.ts.map +1 -1
- package/dist/upgrade-command.js +3 -21
- package/dist/upgrade-command.js.map +1 -1
- package/docs/params-example.md +150 -0
- package/manifest.json +2 -2
- package/package.json +10 -8
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,25 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 2026.11.5 - 2026-11-05
|
|
4
|
+
|
|
5
|
+
### Fixed
|
|
6
|
+
|
|
7
|
+
- Ignore managed extension files so the scheduled issue sync can commit ([pm-11xf](https://github.com/unbraind/pm-presets/blob/main/.agents/pm/issues/pm-11xf.toon))
|
|
8
|
+
|
|
9
|
+
### Security
|
|
10
|
+
|
|
11
|
+
- Salvage sensitive legacy setting refusals and snapshot capture from the unmerged typed-binding review ([pm-yaji](https://github.com/unbraind/pm-presets/blob/main/.agents/pm/issues/pm-yaji.toon))
|
|
12
|
+
|
|
13
|
+
## 2026.11.1 - 2026-11-01
|
|
14
|
+
|
|
15
|
+
### Added
|
|
16
|
+
|
|
17
|
+
- Typed parameter binding manifests: declare preset parameters once, resolve across settings, templates and seeds ([pm-qz1k](https://github.com/unbraind/pm-presets/blob/main/.agents/pm/features/pm-qz1k.toon))
|
|
18
|
+
|
|
19
|
+
### Fixed
|
|
20
|
+
|
|
21
|
+
- Upstream template SDK loses own keys and inherits phantom builtin names ([pm-7km8](https://github.com/unbraind/pm-presets/blob/main/.agents/pm/issues/pm-7km8.toon))
|
|
22
|
+
|
|
3
23
|
## 2026.10.30 - 2026-10-30
|
|
4
24
|
|
|
5
25
|
### Fixed
|
|
@@ -18,6 +38,16 @@
|
|
|
18
38
|
|
|
19
39
|
- Use the pm SDK for preset seed creation ([pm-1j8u](https://github.com/unbraind/pm-presets/blob/main/.agents/pm/chores/pm-1j8u.toon))
|
|
20
40
|
|
|
41
|
+
## 2026.10.26 - 2026-10-26
|
|
42
|
+
|
|
43
|
+
### Added
|
|
44
|
+
|
|
45
|
+
- Preview preset stacks through host profile composition ([pm-1eww](https://github.com/unbraind/pm-presets/blob/main/.agents/pm/features/pm-1eww.toon))
|
|
46
|
+
|
|
47
|
+
### Other
|
|
48
|
+
|
|
49
|
+
- Point the npm homepage at the package catalog and link the author ([pm-39f2](https://github.com/unbraind/pm-presets/blob/main/.agents/pm/chores/pm-39f2.toon))
|
|
50
|
+
|
|
21
51
|
## 2026.10.25 - 2026-10-25
|
|
22
52
|
|
|
23
53
|
### Added
|
package/README.md
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# pm-presets
|
|
2
2
|
|
|
3
|
+
Requires pm CLI **2026.10.25 or newer** for complete artifact reconciliation and owned settings replacement.
|
|
4
|
+
|
|
3
5
|
All 7 official [pm-cli](https://github.com/unbraind/pm-cli) workspace presets in one package.
|
|
4
6
|
|
|
5
7
|
Install once, get all preset setup commands:
|
|
@@ -46,9 +48,11 @@ All setup commands share the same flags:
|
|
|
46
48
|
|
|
47
49
|
| Flag | Short | Description |
|
|
48
50
|
|---|---|---|
|
|
49
|
-
| `--force` | `-f` |
|
|
50
|
-
| `--dry-run` | `-n` | Preview
|
|
51
|
+
| `--force` | `-f` | Reconcile changed preset templates and managed seed contents |
|
|
52
|
+
| `--dry-run` | `-n` | Preview artifacts; the host audit may create a lock file |
|
|
51
53
|
| `--prefix` | `-p` | Override the id_prefix in settings.json |
|
|
54
|
+
| `--param <name>=<value>` | | Supply a declared preset parameter (repeatable; see [Preset parameters](#preset-parameters)) |
|
|
55
|
+
| `--params-file <file>` | | Read parameter values from a JSON object file |
|
|
52
56
|
|
|
53
57
|
Each setup command installs valid `pm create` templates and registers the
|
|
54
58
|
`templates show` runtime handler required by the current pm CLI, so
|
|
@@ -63,7 +67,7 @@ management surface plus a generic `apply`:
|
|
|
63
67
|
|---|---|
|
|
64
68
|
| `pm presets list` | Enumerate every bundled preset and what it configures (governance, built-in + custom item types, templates). |
|
|
65
69
|
| `pm presets show <id>` | Print the full definition of one preset: the settings patch it merges, every template (with its `pm create` option keys), and any custom item types it registers. |
|
|
66
|
-
| `pm presets diff <id>` | Compare the current workspace (`settings.json` + installed templates) against a preset and report what `apply` would add / change,
|
|
70
|
+
| `pm presets diff <id>` | Compare the current workspace (`settings.json` + installed templates) against a preset and report what `apply` would add / change, including missing or changed complete templates and managed seed contents. Add `--strict` to exit non-zero on drift (CI/compliance). |
|
|
67
71
|
| `pm presets plan <id>` | Negotiate operational prerequisites before mutation; use `--composition` and `--target` for composed/provider plans. Missing required contracts exit 2. |
|
|
68
72
|
| `pm presets stack --input stack.json` | Preview a canonical preset stack; conflicting settings, templates and seed identities require explicit owner choices. |
|
|
69
73
|
| `pm presets validate` | Validate that all bundled presets parse and load coherently (governance enums, template names/options, registry↔export agreement). |
|
|
@@ -112,7 +116,7 @@ plus:
|
|
|
112
116
|
|
|
113
117
|
| Flag | Short | Description |
|
|
114
118
|
|---|---|---|
|
|
115
|
-
| `--with-seeds` | `-s` |
|
|
119
|
+
| `--with-seeds` | `-s` | Enroll the preset's starter items as managed artifacts, creating missing items and reconciling them with later bindings. |
|
|
116
120
|
| `--replace` | | Full-replace the `governance` / `validation` / `testing` trees with the preset's instead of deep-merging them. |
|
|
117
121
|
|
|
118
122
|
**Idempotency & safety.** `apply` is safe to re-run:
|
|
@@ -127,21 +131,32 @@ plus:
|
|
|
127
131
|
- `--replace` instead **swaps the `governance` / `validation` / `testing` trees
|
|
128
132
|
wholesale** with the preset's trees — resetting omitted keys to host defaults
|
|
129
133
|
and deriving named governance policies, for a clean reset. The host serializer
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
+
preserves unrelated top-level settings. Omitted raw keys inside the three
|
|
135
|
+
replaced trees are removed. Unowned top-level settings (`telemetry`, `locks`,
|
|
136
|
+
…) remain preserved in both modes; the preset still sets `id_prefix`.
|
|
137
|
+
- Existing templates are skipped only when their complete JSON documents already
|
|
138
|
+
match. A non-force apply that would leave changed templates or managed seeds
|
|
139
|
+
returns `stale_artifacts` (exit 2), naming their relative paths, before changing
|
|
140
|
+
settings or history. Inspect the changes and use `--force` to reconcile them.
|
|
141
|
+
- Apply and diff share one desired-state planner for settings keys, complete
|
|
142
|
+
template documents, managed seed content and seed ownership. A successful real
|
|
143
|
+
apply verifies that complete postcondition before reporting success.
|
|
134
144
|
- `--dry-run` previews every settings merge/replace, template write, and seed
|
|
135
|
-
item without
|
|
145
|
+
item without writing workspace settings, templates, items or history. The host
|
|
146
|
+
may acquire an audit lock; replacement normalization uses isolated public settings.
|
|
136
147
|
|
|
137
148
|
### Drift detection: `presets diff --strict`
|
|
138
149
|
|
|
139
150
|
`presets diff <id> --strict` reuses the diff logic but **exits non-zero (code
|
|
140
|
-
`4`)** when
|
|
141
|
-
|
|
151
|
+
`4`)** when any managed artifact differs: settings keys, full template JSON
|
|
152
|
+
documents (including options and metadata), or managed seed contents. It prints what drifted (human summary, or the
|
|
142
153
|
full diff with `--json`) before exiting, so CI logs explain the failure. When
|
|
143
154
|
the workspace already matches the preset it exits `0`. Plain `presets diff`
|
|
144
|
-
(without `--strict`)
|
|
155
|
+
(without `--strict`) reports structured drift with `templates.changed`, seed
|
|
156
|
+
missing/changed entries and an `artifacts` list of relative paths. Both diff forms
|
|
157
|
+
accept `--prefix`, `--replace` and `--with-seeds` to mirror application choices.
|
|
158
|
+
Invalid inputs still refuse with a typed error. Unreadable artifacts remain
|
|
159
|
+
named drift and can never produce a synchronized result.
|
|
145
160
|
|
|
146
161
|
```bash
|
|
147
162
|
# Fail a compliance/CI job if the workspace drifts from the locked preset:
|
|
@@ -162,16 +177,31 @@ pm presets export our-config --output our-config.preset.json --display-name "Our
|
|
|
162
177
|
```
|
|
163
178
|
|
|
164
179
|
The exported document is `$schema: "pm-presets/exported-preset@1"` and records
|
|
165
|
-
`settings` + `templates`.
|
|
180
|
+
`settings` + `templates`. Workspace-local `preset_artifacts` ownership is excluded;
|
|
181
|
+
a portable preset cannot adopt another tracker's item ids. **Custom item-field _values_ are not captured**:
|
|
166
182
|
custom scalar fields have no `pm create --<field>` setter today (pm-cli #97),
|
|
167
183
|
so the snapshot reconstructs the preset from settings + templates only.
|
|
168
184
|
|
|
169
|
-
**
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
185
|
+
**Managed seeds.** `--with-seeds` uses the host SDK client and active schema;
|
|
186
|
+
it needs neither a `pm` executable on PATH nor git. Stable preset/slot item ids
|
|
187
|
+
are recorded in `settings.preset_artifacts` and recovered from the host's verified
|
|
188
|
+
append-only workspace audit. Removing the settings record cannot hide stale or
|
|
189
|
+
missing seeds from diff. Older unmanaged starter items are not adopted implicitly. Once enrolled, later applies and
|
|
190
|
+
diffs include those seeds even without repeating `--with-seeds`; prefix changes
|
|
191
|
+
keep their established ids and update the controlled type/title/priority/tags/body
|
|
192
|
+
and explicit no-parent state. Existing item lifecycle and unrelated user metadata
|
|
193
|
+
remain host-owned. Reapplying matching content creates no duplicate seeds.
|
|
194
|
+
Seed plans use the native writer's type aliases, trimmed titles, named priorities,
|
|
195
|
+
canonical tag lists and body normalization. Equivalent authored values therefore
|
|
196
|
+
agree across apply, strict diff, stack previews and prerequisite plans.
|
|
197
|
+
|
|
198
|
+
Settings, template and seed writes share one apply admission. A preflight checks
|
|
199
|
+
overwrite conflicts before settings/history mutation. Native write failures exit
|
|
200
|
+
nonzero; completed audited writes remain recorded, and retrying reconciles artifacts
|
|
201
|
+
that were never written. Template ownership is recorded after the whole template
|
|
202
|
+
write succeeds, so a template written before a later failure in the same run is
|
|
203
|
+
unowned: a retry refuses it with `artifact_conflict` until you preserve, rename or
|
|
204
|
+
remove it. Seed reads use the SDK locator/parser and emit no usage/cache writes.
|
|
175
205
|
|
|
176
206
|
**Seeds and custom fields.** Starter items created by `--with-seeds` set only
|
|
177
207
|
**built-in** fields (`type`, `title`, `priority`, `tags`, `body`). Custom scalar
|
|
@@ -182,6 +212,139 @@ agent-workflow templates persist `phase`, `mode`, and `model` this way while
|
|
|
182
212
|
leaving the core pm `status` field untouched. The kanban `Card` and
|
|
183
213
|
agent-workflow `AgentRun` seeds are created with their registered item types.
|
|
184
214
|
|
|
215
|
+
## Preset parameters
|
|
216
|
+
|
|
217
|
+
A preset can declare **typed parameters** once in a manifest and reference them
|
|
218
|
+
with `${param:<name>}` binding occurrences in its settings patch, template
|
|
219
|
+
options and seed items. One supplied value then reaches **every** declared
|
|
220
|
+
occurrence — the `startup-roadmap` preset, for example, uses its `projectKey`
|
|
221
|
+
parameter for the `id_prefix`, the roadmap template prose, and its starter
|
|
222
|
+
initiative seed:
|
|
223
|
+
|
|
224
|
+
```bash
|
|
225
|
+
# Default resolution (projectKey defaults to "road"):
|
|
226
|
+
pm presets apply startup-roadmap
|
|
227
|
+
|
|
228
|
+
# Inspect the changed templates before reconciling owned artifacts:
|
|
229
|
+
pm presets diff startup-roadmap --param projectKey=acme
|
|
230
|
+
# One supplied value reaches every occurrence (prefix becomes "acme-",
|
|
231
|
+
# templates record "acme" under "## Project", the seed title names the acme project):
|
|
232
|
+
pm presets apply startup-roadmap --param projectKey=acme --with-seeds --force
|
|
233
|
+
|
|
234
|
+
# Values can also come from a JSON file:
|
|
235
|
+
pm presets diff startup-roadmap --params-file params.json
|
|
236
|
+
pm presets apply startup-roadmap --params-file params.json --force
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
`pm presets show <id>` lists every declared parameter (type, constraints,
|
|
240
|
+
default, and whether it is still **unanswered**), and `presets diff <id>`
|
|
241
|
+
accepts the same `--param` flags so the drift preview resolves exactly like a
|
|
242
|
+
parameterized apply.
|
|
243
|
+
|
|
244
|
+
**Refusal contract.** All parameter input is validated once, before anything is
|
|
245
|
+
read or written, with typed exit-2 refusals:
|
|
246
|
+
|
|
247
|
+
- an unknown supplied name (`--param ghost=1`) is refused (`unknown_parameter`);
|
|
248
|
+
- a required parameter with neither a value nor a default is refused and every
|
|
249
|
+
unanswered choice is listed (`unanswered_parameter`) — by `apply` and by a
|
|
250
|
+
parameterized `diff`, while `show` keeps displaying the declaration;
|
|
251
|
+
- values that violate the declared pattern, enum or length bound are refused
|
|
252
|
+
(`invalid_value`); control characters and line breaks never enter prose;
|
|
253
|
+
- joining values or surrounding text must not assemble new `${param:...}`
|
|
254
|
+
syntax (`invalid_value`); parameter substitution never evaluates generated bindings;
|
|
255
|
+
- a binding that references a name the preset never declared is an authoring
|
|
256
|
+
error and refuses (`unknown_binding`), as does a malformed `${param:...}`
|
|
257
|
+
fragment (`malformed_binding`);
|
|
258
|
+
- all manifests validate bindings, including an explicit empty `parameters: []`;
|
|
259
|
+
unresolved or malformed occurrences refuse before settings or template writes.
|
|
260
|
+
|
|
261
|
+
**Secrets.** A `secret` parameter accepts only an external environment reference,
|
|
262
|
+
for example `--param token=@DEPLOY_TOKEN`. Literal credentials are refused with
|
|
263
|
+
`invalid_secret_reference` (exit 2); keep values in the environment, never in a
|
|
264
|
+
params file or tracker. Secret defaults are forbidden.
|
|
265
|
+
|
|
266
|
+
Secret-reference bindings must occupy an entire value in the explicit
|
|
267
|
+
`settings.secret_references.<name>` map, for example
|
|
268
|
+
`secret_references: { deploy: "${param:token}" }`. That map stores pointers only;
|
|
269
|
+
it cannot receive credential values. Identifiers (`id_prefix`, seed
|
|
270
|
+
IDs), titles, tags, filenames, templates and other settings are public tracked
|
|
271
|
+
data; secret bindings there refuse at manifest projection, even without a
|
|
272
|
+
supplied value. References cannot be interpolated into a larger string.
|
|
273
|
+
|
|
274
|
+
Reference maps preserve accepted JSON names, including `__proto__` and
|
|
275
|
+
`constructor`, through resolution, previews and audited storage.
|
|
276
|
+
Once a reference map exists, the host audit protocol cannot add or change its
|
|
277
|
+
`__proto__` entry. Such updates refuse before writes; keep a stable reference
|
|
278
|
+
and rotate the external environment value.
|
|
279
|
+
Public templates and seeds require nonempty trimmed field names and refuse
|
|
280
|
+
`__proto__` before writes because supported host readers lose that field.
|
|
281
|
+
Existing templates that would lose option names refuse reads/exports with a
|
|
282
|
+
typed remedy instead of returning partial data.
|
|
283
|
+
|
|
284
|
+
Apply stores **only `@DEPLOY_TOKEN`**, including in audited append-only history.
|
|
285
|
+
Dry-run, diff and parameter summaries display references, never credentials.
|
|
286
|
+
Static references such as `secret_references: { deploy: "@DEPLOY_TOKEN" }`
|
|
287
|
+
receive the same protection: diffs hide legacy credentials at those destinations.
|
|
288
|
+
SDK callers retain known legacy sensitivity in `WorkspaceSnapshot.secretSettingPaths`.
|
|
289
|
+
Diff combines those stored paths with incoming provenance before comparing: sensitive
|
|
290
|
+
prefixes refuse managed seed comparisons, and sensitive governance, validation or
|
|
291
|
+
testing paths refuse `--replace` with `invalid_secret_reference`. Ordinary comparisons
|
|
292
|
+
redact both sides of those locations, including when their JSON shapes differ.
|
|
293
|
+
Show may retain the authored occurrence for an unanswered declaration. Commands
|
|
294
|
+
do not read credential environment variables. A consuming integration calls
|
|
295
|
+
`resolveSecretReference("@DEPLOY_TOKEN")` only when the credential is needed;
|
|
296
|
+
that API returns the current environment value in memory without logging or
|
|
297
|
+
writing it. Missing or empty variables produce a privacy-safe typed refusal.
|
|
298
|
+
Rotating the external value requires no tracker change. There is no automatic
|
|
299
|
+
migration or rewrite of credentials already stored by older versions: revoke
|
|
300
|
+
those credentials and review affected tracker history separately.
|
|
301
|
+
|
|
302
|
+
Defaults and supplied public values share trimming and constraint checks; seed
|
|
303
|
+
previews resolve defaults before computing identities and ownership.
|
|
304
|
+
|
|
305
|
+
**One resolution, one read.** The unified apply reads your flags and params
|
|
306
|
+
file exactly once, resolves every parameter at that boundary, pre-validates the
|
|
307
|
+
preset's seed bindings, and threads the same effective values through the
|
|
308
|
+
settings merge, the template writes and the seed creation — editing the params
|
|
309
|
+
file mid-apply cannot split your workspace across two values.
|
|
310
|
+
|
|
311
|
+
**Ownership and recovery.** Existing item ids, template names and customized
|
|
312
|
+
settings are preserved unless recorded preset provenance proves ownership.
|
|
313
|
+
**Upgrading:** workspaces configured by earlier pm-presets versions carry no
|
|
314
|
+
provenance. Their templates and customized settings are unowned, so the first
|
|
315
|
+
re-apply with this version refuses them with `artifact_conflict`, even when the
|
|
316
|
+
contents match. Move or remove those templates and reset customized leaves before
|
|
317
|
+
that apply, or keep the current configuration and only run `pm presets diff`.
|
|
318
|
+
`--force` reconciles owned drift; an unowned collision returns `artifact_conflict`
|
|
319
|
+
with its exact id or path. A missing managed seed with retained history returns
|
|
320
|
+
`artifact_recovery_required` with a native `pm restore <id> <timestamp>` command
|
|
321
|
+
for its latest verified materialized state. Run that
|
|
322
|
+
command, inspect the restored item and retry; keep the history. Ownership metadata
|
|
323
|
+
stays workspace-local and is omitted from exported presets.
|
|
324
|
+
|
|
325
|
+
**Concurrent applies.** A real apply holds a workspace-scoped lock
|
|
326
|
+
(`.agents/pm/locks/`) across the audited settings mutation *and* the template
|
|
327
|
+
writes, so two concurrent parameterized applies can never leave the id prefix
|
|
328
|
+
of one invocation next to the template prose of another. Dry-runs skip the
|
|
329
|
+
preset apply lock. The host audit may create its own lock file and may refuse
|
|
330
|
+
on a read-only tracker. Dry-runs do not change preset artifacts.
|
|
331
|
+
|
|
332
|
+
Publication, stale recovery and release also hold an admission claim with a
|
|
333
|
+
unique per-process pathname. Cleanup targets that exact claim, so a delayed
|
|
334
|
+
reaper cannot unlink a replacement owner's claim. Live owners are never evicted
|
|
335
|
+
because of age. Automatic recovery requires a verified kernel/PID namespace and
|
|
336
|
+
a PID proven absent; unverifiable claims stay locked. Inspect abandoned claims
|
|
337
|
+
only after confirming their writers have stopped.
|
|
338
|
+
|
|
339
|
+
`--params-file` reads one regular JSON file, bounded to 64 KiB even if it grows
|
|
340
|
+
while being read. Missing, unreadable, nonregular and oversized files return
|
|
341
|
+
`invalid_params_file` with exit 2, without raw filesystem diagnostics.
|
|
342
|
+
|
|
343
|
+
The same engine backs every read path (`show`, `diff`, `plan`, `stack`,
|
|
344
|
+
`validate`): answered bindings resolve in every preview, while a declaration-mode
|
|
345
|
+
projection may keep the authored `${param:...}` occurrence for an unanswered parameter. See
|
|
346
|
+
[docs/params-example.md](docs/params-example.md) for the full authoring walkthrough.
|
|
347
|
+
|
|
185
348
|
## Presets in Detail
|
|
186
349
|
|
|
187
350
|
### bug-triage
|
|
@@ -483,3 +646,15 @@ Seed rows describe prospective catalog contributions, without claiming existing
|
|
|
483
646
|
items by title. Plans are observations, not transactions or replayable authority;
|
|
484
647
|
replan after peer changes. Target classifications always read current settings
|
|
485
648
|
and templates. See [the stack example](docs/stack-example.md).
|
|
649
|
+
|
|
650
|
+
SDK callers can await `computeDesiredPresetState`, `computePresetDiff`,
|
|
651
|
+
`computeParameterizedDiff` and `readWorkspaceSnapshot`; `requirePresetDefinition`
|
|
652
|
+
provides resolved bundled template/seed payloads. JSON and TOON commands use
|
|
653
|
+
these same APIs. SDK diff requires complete `templateDocuments` for every
|
|
654
|
+
declared template and an explicit `seedItems` inventory for seed comparisons;
|
|
655
|
+
summary-only definitions refuse. Final overrides and payloads must be resolved.
|
|
656
|
+
Legacy SDK settings projections remain redacted and cannot report synchronization
|
|
657
|
+
when application would reject their settings.
|
|
658
|
+
|
|
659
|
+
Development checks use `npm run check` for typechecking and `npm run lint` for
|
|
660
|
+
compiler-backed unused-local/parameter checks with the pinned TypeScript version.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import type { ArtifactOwnership } from "./artifact-ownership.ts";
|
|
2
|
+
import { type PresetArtifactRecord } from "./desired-state.ts";
|
|
3
|
+
/** Verified last application ownership, or named uncertainty without exposing audit values. */
|
|
4
|
+
export interface PresetApplicationHistory {
|
|
5
|
+
records: Record<string, PresetArtifactRecord | null>;
|
|
6
|
+
errors: string[];
|
|
7
|
+
}
|
|
8
|
+
/** Read/replay through public SDK contracts; no history, usage or cache mutation. */
|
|
9
|
+
export declare function readPresetApplicationHistory(pmRoot: string): Promise<PresetApplicationHistory>;
|
|
10
|
+
/** Verify cumulative template/settings ownership against a recorded preset settings mutation. */
|
|
11
|
+
export declare function readPresetOwnership(pmRoot: string): Promise<ArtifactOwnership>;
|
|
12
|
+
//# sourceMappingURL=application-history.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"application-history.d.ts","sourceRoot":"","sources":["../src/application-history.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAMjE,OAAO,EAAqC,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAElG,+FAA+F;AAC/F,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI,CAAC,CAAC;IACrD,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAID,qFAAqF;AACrF,wBAAsB,4BAA4B,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAyBpG;AAED,iGAAiG;AACjG,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAapF"}
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
import { existsSync } from "node:fs";
|
|
2
|
+
import { join } from "node:path";
|
|
3
|
+
import { createRequire } from "node:module";
|
|
4
|
+
import { createHash } from "node:crypto";
|
|
5
|
+
import { resolveSimulationSdk } from "./sdk-loader.js";
|
|
6
|
+
import { ownArtifact, presetArtifactRecord } from "./desired-state.js";
|
|
7
|
+
const verified = new Map();
|
|
8
|
+
/** Read/replay through public SDK contracts; no history, usage or cache mutation. */
|
|
9
|
+
export async function readPresetApplicationHistory(pmRoot) {
|
|
10
|
+
const file = join(pmRoot, "history", "_workspace.jsonl");
|
|
11
|
+
if (!existsSync(file))
|
|
12
|
+
return { records: {}, errors: [] };
|
|
13
|
+
try {
|
|
14
|
+
const sdk = createRequire(import.meta.url)(resolveSimulationSdk([import.meta.url, process.argv[1]]));
|
|
15
|
+
const { entries, raw } = await sdk.readHistorySnapshot(file, "_workspace");
|
|
16
|
+
const digest = createHash("sha256").update(raw).digest("hex");
|
|
17
|
+
const cached = verified.get(pmRoot);
|
|
18
|
+
if (cached?.digest === digest)
|
|
19
|
+
return structuredClone(cached.value);
|
|
20
|
+
const latest = entries.length > 0 ? sdk.replayHistoryToTarget(entries, entries.length - 1) : undefined;
|
|
21
|
+
const records = new Map();
|
|
22
|
+
for (let index = entries.length - 1; index >= 0; index--) {
|
|
23
|
+
const match = /^extension:(?:[^:]+:)*settings:(?:[^:]+:)*pm-presets-([a-z][a-z0-9-]*)-[a-f0-9-]{36}$/.exec(entries[index].op);
|
|
24
|
+
if (!match || records.has(match[1]))
|
|
25
|
+
continue;
|
|
26
|
+
const replayed = index === entries.length - 1 ? latest : sdk.replayHistoryToTarget(entries, index);
|
|
27
|
+
const documents = ownArtifact(replayed.metadata, "documents");
|
|
28
|
+
const settings = ownArtifact(documents, "settings.json");
|
|
29
|
+
records.set(match[1], structuredClone(presetArtifactRecord(settings, match[1]) ?? null));
|
|
30
|
+
}
|
|
31
|
+
const value = { records: Object.fromEntries(records), errors: [] };
|
|
32
|
+
verified.delete(pmRoot);
|
|
33
|
+
if (verified.size >= 16)
|
|
34
|
+
verified.delete(verified.keys().next().value);
|
|
35
|
+
verified.set(pmRoot, { digest, value });
|
|
36
|
+
return structuredClone(value);
|
|
37
|
+
}
|
|
38
|
+
catch {
|
|
39
|
+
return { records: {}, errors: ["history/_workspace.jsonl"] };
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
/** Verify cumulative template/settings ownership against a recorded preset settings mutation. */
|
|
43
|
+
export async function readPresetOwnership(pmRoot) {
|
|
44
|
+
const file = join(pmRoot, "history", "_workspace.jsonl");
|
|
45
|
+
if (!existsSync(file))
|
|
46
|
+
return {};
|
|
47
|
+
const sdk = createRequire(import.meta.url)(resolveSimulationSdk([import.meta.url, process.argv[1]]));
|
|
48
|
+
const { entries } = await sdk.readHistorySnapshot(file, "_workspace");
|
|
49
|
+
for (let index = entries.length - 1; index >= 0; index--) {
|
|
50
|
+
if (!/^extension:(?:[^:]+:)*settings:(?:[^:]+:)*pm-presets-[a-z][a-z0-9-]*-[a-f0-9-]{36}$/.test(entries[index].op))
|
|
51
|
+
continue;
|
|
52
|
+
const replayed = sdk.replayHistoryToTarget(entries, index);
|
|
53
|
+
const documents = ownArtifact(replayed.metadata, "documents");
|
|
54
|
+
const settings = ownArtifact(documents, "settings.json");
|
|
55
|
+
return (ownArtifact(settings, "preset_ownership") ?? {});
|
|
56
|
+
}
|
|
57
|
+
return {};
|
|
58
|
+
}
|
|
59
|
+
//# sourceMappingURL=application-history.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"application-history.js","sourceRoot":"","sources":["../src/application-history.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
/** Identify a kernel/PID namespace; unverifiable realms deliberately cannot reap one another. */
|
|
2
|
+
export declare function captureAdmissionRealm(): string;
|
|
3
|
+
/** A public failure excludes local paths, process identities and filesystem diagnostics. */
|
|
4
|
+
export declare class ApplyAdmissionRefusal extends Error {
|
|
5
|
+
/** Host-recognized failure status prevents an unhandled-command retry. */
|
|
6
|
+
readonly exitCode = 1;
|
|
7
|
+
/** Construct the same refusal for acquisition, cleanup and release faults. */
|
|
8
|
+
constructor();
|
|
9
|
+
}
|
|
10
|
+
/**
|
|
11
|
+
* Publish a unique claim and enter only when it is the sole surviving claim.
|
|
12
|
+
*
|
|
13
|
+
* Active owners keep their claim throughout publication, stale-lock recovery,
|
|
14
|
+
* the settings/template writes and release. Contenders withdraw before waiting.
|
|
15
|
+
* A reaper can unlink only the exact dead claim it observed: a replacement owner
|
|
16
|
+
* has a fresh pathname, never the old one. The containing directory is retained,
|
|
17
|
+
* so directory removal/recreation cannot turn cleanup into an ABA race.
|
|
18
|
+
* Live or unverifiable processes are never evicted merely because time passed.
|
|
19
|
+
*/
|
|
20
|
+
export declare function acquireApplyAdmission(pmDir: string): Promise<() => void>;
|
|
21
|
+
//# sourceMappingURL=apply-admission.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"apply-admission.d.ts","sourceRoot":"","sources":["../src/apply-admission.ts"],"names":[],"mappings":"AAMA,iGAAiG;AACjG,wBAAgB,qBAAqB,IAAI,MAAM,CAY9C;AAKD,4FAA4F;AAC5F,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,KAAK;IACtB,8EAA8E;IAC9E,cAGC;CACF;AAuBD;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CA+B9E"}
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
/** Cross-process admission with immutable claim paths, including recovery and release. */
|
|
2
|
+
import * as fs from "node:fs";
|
|
3
|
+
import * as path from "node:path";
|
|
4
|
+
import { createHash, randomUUID } from "node:crypto";
|
|
5
|
+
import { hostname } from "node:os";
|
|
6
|
+
/** Identify a kernel/PID namespace; unverifiable realms deliberately cannot reap one another. */
|
|
7
|
+
export function captureAdmissionRealm() {
|
|
8
|
+
let realm;
|
|
9
|
+
try {
|
|
10
|
+
// These platforms share the host PID domain. Reused/live PIDs still block;
|
|
11
|
+
// only ESRCH allows recovery, even across boots, without a rounded clock key.
|
|
12
|
+
if (process.platform !== "linux")
|
|
13
|
+
return createHash("sha256").update(`host:${hostname()}`).digest("hex");
|
|
14
|
+
realm = fs.readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim()
|
|
15
|
+
+ ":" + fs.readlinkSync("/proc/self/ns/pid");
|
|
16
|
+
}
|
|
17
|
+
catch {
|
|
18
|
+
realm = randomUUID();
|
|
19
|
+
}
|
|
20
|
+
return createHash("sha256").update(realm).digest("hex");
|
|
21
|
+
}
|
|
22
|
+
const HOST = captureAdmissionRealm();
|
|
23
|
+
const WAIT_MS = 15_000;
|
|
24
|
+
/** A public failure excludes local paths, process identities and filesystem diagnostics. */
|
|
25
|
+
export class ApplyAdmissionRefusal extends Error {
|
|
26
|
+
/** Host-recognized failure status prevents an unhandled-command retry. */
|
|
27
|
+
exitCode = 1;
|
|
28
|
+
/** Construct the same refusal for acquisition, cleanup and release faults. */
|
|
29
|
+
constructor() {
|
|
30
|
+
super("Preset application ownership is unavailable; wait for other applies. Claims live in the tracker's locks/pm-presets-apply-claims directory; a claim left by another boot or PID namespace is never recovered automatically, so remove it only after confirming its writer has stopped. Verify lock-directory permissions and retry.");
|
|
31
|
+
this.name = "ApplyAdmissionRefusal";
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
/** Remove only this immutable claim pathname; another owner always has a different name. */
|
|
35
|
+
function removeClaim(file) {
|
|
36
|
+
try {
|
|
37
|
+
fs.unlinkSync(file);
|
|
38
|
+
}
|
|
39
|
+
catch (error) {
|
|
40
|
+
if (error.code !== "ENOENT")
|
|
41
|
+
throw error;
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
/** Only a same-namespace PID proven absent permits automatic claim recovery; uncertainty stays locked. */
|
|
45
|
+
function deadClaim(name) {
|
|
46
|
+
const match = /^([a-f0-9]{64})-([1-9][0-9]*)-([a-f0-9-]{36})\.claim$/.exec(name);
|
|
47
|
+
if (!match || match[1] !== HOST)
|
|
48
|
+
return false;
|
|
49
|
+
const pid = Number(match[2]);
|
|
50
|
+
if (!Number.isSafeInteger(pid) || pid > 2147483647)
|
|
51
|
+
return false;
|
|
52
|
+
try {
|
|
53
|
+
process.kill(pid, 0);
|
|
54
|
+
return false;
|
|
55
|
+
}
|
|
56
|
+
catch (error) {
|
|
57
|
+
return error.code === "ESRCH";
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
/** Only claim files take part in admission; stray files such as `.DS_Store` or editor backups never block an apply. */
|
|
61
|
+
function claims(directory) {
|
|
62
|
+
return fs.readdirSync(directory).filter((entry) => entry.endsWith(".claim"));
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* Publish a unique claim and enter only when it is the sole surviving claim.
|
|
66
|
+
*
|
|
67
|
+
* Active owners keep their claim throughout publication, stale-lock recovery,
|
|
68
|
+
* the settings/template writes and release. Contenders withdraw before waiting.
|
|
69
|
+
* A reaper can unlink only the exact dead claim it observed: a replacement owner
|
|
70
|
+
* has a fresh pathname, never the old one. The containing directory is retained,
|
|
71
|
+
* so directory removal/recreation cannot turn cleanup into an ABA race.
|
|
72
|
+
* Live or unverifiable processes are never evicted merely because time passed.
|
|
73
|
+
*/
|
|
74
|
+
export async function acquireApplyAdmission(pmDir) {
|
|
75
|
+
const directory = path.join(pmDir, "locks", "pm-presets-apply-claims");
|
|
76
|
+
const deadline = Date.now() + WAIT_MS;
|
|
77
|
+
try {
|
|
78
|
+
fs.mkdirSync(directory, { recursive: true });
|
|
79
|
+
for (;;) {
|
|
80
|
+
const name = `${HOST}-${process.pid}-${randomUUID()}.claim`;
|
|
81
|
+
const file = path.join(directory, name);
|
|
82
|
+
fs.writeFileSync(file, "", { flag: "wx", mode: 0o600 });
|
|
83
|
+
let admitted = false;
|
|
84
|
+
try {
|
|
85
|
+
for (const observed of claims(directory)) {
|
|
86
|
+
if (observed !== name && deadClaim(observed))
|
|
87
|
+
removeClaim(path.join(directory, observed));
|
|
88
|
+
}
|
|
89
|
+
const current = claims(directory);
|
|
90
|
+
if (current.length === 1 && current[0] === name) {
|
|
91
|
+
admitted = true;
|
|
92
|
+
return () => {
|
|
93
|
+
try {
|
|
94
|
+
removeClaim(file);
|
|
95
|
+
}
|
|
96
|
+
catch {
|
|
97
|
+
throw new ApplyAdmissionRefusal();
|
|
98
|
+
}
|
|
99
|
+
};
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
finally {
|
|
103
|
+
if (!admitted)
|
|
104
|
+
removeClaim(file);
|
|
105
|
+
}
|
|
106
|
+
if (Date.now() >= deadline)
|
|
107
|
+
throw new ApplyAdmissionRefusal();
|
|
108
|
+
await new Promise((resolve) => setTimeout(resolve, 25 + Math.floor(Math.random() * 75)));
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
catch {
|
|
112
|
+
throw new ApplyAdmissionRefusal();
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
//# sourceMappingURL=apply-admission.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"apply-admission.js","sourceRoot":"","sources":["../src/apply-admission.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* apply-command.ts — the unified `presets apply` bridge.
|
|
3
|
+
*
|
|
4
|
+
* One boundary for one apply invocation: the caller's parameter input is read
|
|
5
|
+
* exactly once (flags plus at most one params file), every declared parameter
|
|
6
|
+
* is answered strictly, and the SEED bindings are validated here — all before
|
|
7
|
+
* the setup handler writes a single settings leaf or template file. The
|
|
8
|
+
* resolved values are then threaded through the handler (and on to seed
|
|
9
|
+
* creation) so no later step re-reads the caller's input.
|
|
10
|
+
*/
|
|
11
|
+
import type { CommandHandlerContext } from "@unbrained/pm-cli/sdk/authoring";
|
|
12
|
+
import { type PresetDefinition } from "./catalog.ts";
|
|
13
|
+
import { type ResolvedParameterValues } from "./params.ts";
|
|
14
|
+
import { type SeedItem } from "./seeds.ts";
|
|
15
|
+
/** Everything one apply invocation needs, resolved at a single boundary. */
|
|
16
|
+
export interface ResolvedPresetApplication {
|
|
17
|
+
/** The preset the caller named (already validated against the registry). */
|
|
18
|
+
readonly definition: PresetDefinition;
|
|
19
|
+
/** Effective parameter values plus their sources; strict resolution refused before any write. */
|
|
20
|
+
readonly parameters: ResolvedParameterValues;
|
|
21
|
+
/** Whether the caller asked for the preset's starter items. */
|
|
22
|
+
readonly withSeeds: boolean;
|
|
23
|
+
/** Whether the whole apply is a preview. */
|
|
24
|
+
readonly dryRun: boolean;
|
|
25
|
+
/** Resolved, validated seed items (only when requested); never re-read from input. */
|
|
26
|
+
readonly seeds: readonly SeedItem[] | undefined;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Resolve one apply invocation completely, before any write.
|
|
30
|
+
*
|
|
31
|
+
* Strict order: unknown or invalid parameter input refuses first, unanswered
|
|
32
|
+
* required parameters refuse next (listing every unanswered choice), and a
|
|
33
|
+
* malformed or secret binding in the preset's SEEDS refuses here — all before
|
|
34
|
+
* the setup handler runs, so a bad seed can never leave a half-applied preset.
|
|
35
|
+
* The returned values are the single resolution the settings, templates and
|
|
36
|
+
* seed steps all use; nothing downstream reads flags or the params file again.
|
|
37
|
+
*/
|
|
38
|
+
export declare function resolvePresetApplication(context: CommandHandlerContext): ResolvedPresetApplication;
|
|
39
|
+
/**
|
|
40
|
+
* Clone the command context so the setup handler receives the invocation's
|
|
41
|
+
* resolved values (never a file path to re-read).
|
|
42
|
+
*/
|
|
43
|
+
export declare function contextWithResolvedParameters(context: CommandHandlerContext, application: ResolvedPresetApplication): CommandHandlerContext;
|
|
44
|
+
//# sourceMappingURL=apply-command.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"apply-command.d.ts","sourceRoot":"","sources":["../src/apply-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AAE7E,OAAO,EAA2B,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAE9E,OAAO,EAAuD,KAAK,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAChH,OAAO,EAA0B,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEnE,4EAA4E;AAC5E,MAAM,WAAW,yBAAyB;IACxC,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IACtC,iGAAiG;IACjG,QAAQ,CAAC,UAAU,EAAE,uBAAuB,CAAC;IAC7C,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,sFAAsF;IACtF,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,SAAS,CAAC;CACjD;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,qBAAqB,GAAG,yBAAyB,CAUlG;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,qBAAqB,EAC9B,WAAW,EAAE,yBAAyB,GACrC,qBAAqB,CAKvB"}
|