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.
Files changed (113) hide show
  1. package/CHANGELOG.md +30 -0
  2. package/README.md +194 -19
  3. package/dist/application-history.d.ts +12 -0
  4. package/dist/application-history.d.ts.map +1 -0
  5. package/dist/application-history.js +59 -0
  6. package/dist/application-history.js.map +1 -0
  7. package/dist/apply-admission.d.ts +21 -0
  8. package/dist/apply-admission.d.ts.map +1 -0
  9. package/dist/apply-admission.js +115 -0
  10. package/dist/apply-admission.js.map +1 -0
  11. package/dist/apply-command.d.ts +44 -0
  12. package/dist/apply-command.d.ts.map +1 -0
  13. package/dist/apply-command.js +47 -0
  14. package/dist/apply-command.js.map +1 -0
  15. package/dist/artifact-ownership.d.ts +17 -0
  16. package/dist/artifact-ownership.d.ts.map +1 -0
  17. package/dist/artifact-ownership.js +123 -0
  18. package/dist/artifact-ownership.js.map +1 -0
  19. package/dist/artifact-reader.d.ts +7 -0
  20. package/dist/artifact-reader.d.ts.map +1 -0
  21. package/dist/artifact-reader.js +48 -0
  22. package/dist/artifact-reader.js.map +1 -0
  23. package/dist/catalog.d.ts +52 -2
  24. package/dist/catalog.d.ts.map +1 -1
  25. package/dist/catalog.js +120 -45
  26. package/dist/catalog.js.map +1 -1
  27. package/dist/command-errors.d.ts +7 -0
  28. package/dist/command-errors.d.ts.map +1 -0
  29. package/dist/command-errors.js +72 -0
  30. package/dist/command-errors.js.map +1 -0
  31. package/dist/desired-state.d.ts +61 -0
  32. package/dist/desired-state.d.ts.map +1 -0
  33. package/dist/desired-state.js +157 -0
  34. package/dist/desired-state.js.map +1 -0
  35. package/dist/diff.d.ts +54 -19
  36. package/dist/diff.d.ts.map +1 -1
  37. package/dist/diff.js +228 -32
  38. package/dist/diff.js.map +1 -1
  39. package/dist/export.d.ts +1 -1
  40. package/dist/export.d.ts.map +1 -1
  41. package/dist/export.js +10 -2
  42. package/dist/export.js.map +1 -1
  43. package/dist/index.d.ts +13 -0
  44. package/dist/index.d.ts.map +1 -1
  45. package/dist/index.js +69 -29
  46. package/dist/index.js.map +1 -1
  47. package/dist/input-file.d.ts +3 -0
  48. package/dist/input-file.d.ts.map +1 -0
  49. package/dist/input-file.js +25 -0
  50. package/dist/input-file.js.map +1 -0
  51. package/dist/json-object.d.ts +4 -0
  52. package/dist/json-object.d.ts.map +1 -0
  53. package/dist/json-object.js +6 -0
  54. package/dist/json-object.js.map +1 -0
  55. package/dist/params.d.ts +263 -0
  56. package/dist/params.d.ts.map +1 -0
  57. package/dist/params.js +762 -0
  58. package/dist/params.js.map +1 -0
  59. package/dist/plan.d.ts.map +1 -1
  60. package/dist/plan.js +3 -2
  61. package/dist/plan.js.map +1 -1
  62. package/dist/presets/agent-workflow/index.d.ts.map +1 -1
  63. package/dist/presets/agent-workflow/index.js +1 -0
  64. package/dist/presets/agent-workflow/index.js.map +1 -1
  65. package/dist/presets/bug-triage/index.d.ts.map +1 -1
  66. package/dist/presets/bug-triage/index.js +1 -0
  67. package/dist/presets/bug-triage/index.js.map +1 -1
  68. package/dist/presets/indie-dev/index.d.ts.map +1 -1
  69. package/dist/presets/indie-dev/index.js +1 -0
  70. package/dist/presets/indie-dev/index.js.map +1 -1
  71. package/dist/presets/kanban/index.d.ts.map +1 -1
  72. package/dist/presets/kanban/index.js +1 -0
  73. package/dist/presets/kanban/index.js.map +1 -1
  74. package/dist/presets/open-source/index.d.ts.map +1 -1
  75. package/dist/presets/open-source/index.js +1 -0
  76. package/dist/presets/open-source/index.js.map +1 -1
  77. package/dist/presets/shared.d.ts +8 -1
  78. package/dist/presets/shared.d.ts.map +1 -1
  79. package/dist/presets/shared.js +456 -62
  80. package/dist/presets/shared.js.map +1 -1
  81. package/dist/presets/software-sprint/index.d.ts.map +1 -1
  82. package/dist/presets/software-sprint/index.js +1 -0
  83. package/dist/presets/software-sprint/index.js.map +1 -1
  84. package/dist/presets/startup-roadmap/index.d.ts +11 -0
  85. package/dist/presets/startup-roadmap/index.d.ts.map +1 -1
  86. package/dist/presets/startup-roadmap/index.js +25 -3
  87. package/dist/presets/startup-roadmap/index.js.map +1 -1
  88. package/dist/registry.d.ts +10 -1
  89. package/dist/registry.d.ts.map +1 -1
  90. package/dist/registry.js +18 -1
  91. package/dist/registry.js.map +1 -1
  92. package/dist/sdk-loader.js +1 -1
  93. package/dist/sdk-loader.js.map +1 -1
  94. package/dist/seeds.d.ts +17 -2
  95. package/dist/seeds.d.ts.map +1 -1
  96. package/dist/seeds.js +51 -12
  97. package/dist/seeds.js.map +1 -1
  98. package/dist/settings-replacement.d.ts +4 -0
  99. package/dist/settings-replacement.d.ts.map +1 -0
  100. package/dist/settings-replacement.js +50 -0
  101. package/dist/settings-replacement.js.map +1 -0
  102. package/dist/simulation.d.ts.map +1 -1
  103. package/dist/simulation.js +4 -3
  104. package/dist/simulation.js.map +1 -1
  105. package/dist/stack.d.ts.map +1 -1
  106. package/dist/stack.js +15 -7
  107. package/dist/stack.js.map +1 -1
  108. package/dist/upgrade-command.d.ts.map +1 -1
  109. package/dist/upgrade-command.js +3 -21
  110. package/dist/upgrade-command.js.map +1 -1
  111. package/docs/params-example.md +150 -0
  112. package/manifest.json +2 -2
  113. 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` | Overwrite existing preset template files |
50
- | `--dry-run` | `-n` | Preview changes without writing any files |
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, plus which templates are missing. Add `--strict` to exit non-zero on drift (CI/compliance). |
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` | Also create the preset's starter items after applying it. |
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
- retains unrecognized stored fields. Unrelated top-level settings (`id_prefix`,
131
- `telemetry`, `locks`, …) are still preserved in both modes.
132
- - Templates are **skipped if a file with that name already exists**; pass
133
- `--force` to overwrite them.
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 touching disk.
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 the workspace is not in sync with the named preset — settings to
141
- add/change or templates missing. It prints what drifted (human summary, or the
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`) always exits `0` and just reports.
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`. **Custom item-field _values_ are not captured**:
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
- **Seed creation.** `--with-seeds` uses the host SDK client and the invocation's
170
- workspace, author and active schema. It needs neither a `pm` executable on PATH
171
- nor git. Each seed remains independent: native validation failures are reported
172
- per item, successful seeds stay created, and any failure exits nonzero. Dry runs
173
- retain the same preview. Failures show the native SDK validation detail instead
174
- of the subprocess CLI's generic error headline. A missing host `client.create` capability fails clearly.
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":"AAAA,0FAA0F;AAC1F,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,iGAAiG;AACjG,MAAM,UAAU,qBAAqB;IACnC,IAAI,KAAa,CAAC;IAClB,IAAI,CAAC;QACH,2EAA2E;QAC3E,8EAA8E;QAC9E,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;YAAE,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,QAAQ,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACzG,KAAK,GAAG,EAAE,CAAC,YAAY,CAAC,iCAAiC,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE;cACrE,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,mBAAmB,CAAC,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,KAAK,GAAG,UAAU,EAAE,CAAC;IACvB,CAAC;IACD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,IAAI,GAAG,qBAAqB,EAAE,CAAC;AACrC,MAAM,OAAO,GAAG,MAAM,CAAC;AAEvB,4FAA4F;AAC5F,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9C,0EAA0E;IACjE,QAAQ,GAAG,CAAC,CAAC;IACtB,8EAA8E;IAC9E;QACE,KAAK,CAAC,oUAAoU,CAAC,CAAC;QAC5U,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED,4FAA4F;AAC5F,SAAS,WAAW,CAAC,IAAY;IAC/B,IAAI,CAAC;QAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IAAC,CAAC;IAC5B,OAAO,KAAK,EAAE,CAAC;QAAC,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,KAAK,CAAC;IAAC,CAAC;AACxF,CAAC;AAED,0GAA0G;AAC1G,SAAS,SAAS,CAAC,IAAY;IAC7B,MAAM,KAAK,GAAG,uDAAuD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjF,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9C,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7B,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,UAAU;QAAE,OAAO,KAAK,CAAC;IACjE,IAAI,CAAC;QAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QAAC,OAAO,KAAK,CAAC;IAAC,CAAC;IAC3C,OAAO,KAAK,EAAE,CAAC;QAAC,OAAQ,KAA+B,CAAC,IAAI,KAAK,OAAO,CAAC;IAAC,CAAC;AAC7E,CAAC;AAED,uHAAuH;AACvH,SAAS,MAAM,CAAC,SAAiB;IAC/B,OAAO,EAAE,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;AAC/E,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,KAAa;IACvD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,yBAAyB,CAAC,CAAC;IACvE,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC;IACtC,IAAI,CAAC;QACH,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7C,SAAS,CAAC;YACR,MAAM,IAAI,GAAG,GAAG,IAAI,IAAI,OAAO,CAAC,GAAG,IAAI,UAAU,EAAE,QAAQ,CAAC;YAC5D,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;YACxC,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YACxD,IAAI,QAAQ,GAAG,KAAK,CAAC;YACrB,IAAI,CAAC;gBACH,KAAK,MAAM,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;oBACzC,IAAI,QAAQ,KAAK,IAAI,IAAI,SAAS,CAAC,QAAQ,CAAC;wBAAE,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC;gBAC5F,CAAC;gBACD,MAAM,OAAO,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;gBAClC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;oBAChD,QAAQ,GAAG,IAAI,CAAC;oBAChB,OAAO,GAAG,EAAE;wBACV,IAAI,CAAC;4BAAC,WAAW,CAAC,IAAI,CAAC,CAAC;wBAAC,CAAC;wBAC1B,MAAM,CAAC;4BAAC,MAAM,IAAI,qBAAqB,EAAE,CAAC;wBAAC,CAAC;oBAC9C,CAAC,CAAC;gBACJ,CAAC;YACH,CAAC;oBAAS,CAAC;gBACT,IAAI,CAAC,QAAQ;oBAAE,WAAW,CAAC,IAAI,CAAC,CAAC;YACnC,CAAC;YACD,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,QAAQ;gBAAE,MAAM,IAAI,qBAAqB,EAAE,CAAC;YAC9D,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;QAC3F,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,qBAAqB,EAAE,CAAC;IACpC,CAAC;AACH,CAAC"}
@@ -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"}