prizmkit 1.1.165 → 1.1.167

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.
@@ -1,25 +1,30 @@
1
1
  {
2
2
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3
3
  "$id": "https://prizmkit.dev/schemas/deployment-declaration.schema.json",
4
- "title": "Optional PrizmKit Deployment Declaration",
5
- "description": "Complete non-sensitive schema for optional prizmkit.deploy.json. The file is advisory evidence, not execution authorization. Secret values are prohibited.",
4
+ "title": "PrizmKit Deployment Profile Declaration Index",
5
+ "description": "Optional non-sensitive schema v2 for prizmkit.deploy.json. It declares Profile hints and policy but is not target-state or execution authorization.",
6
6
  "type": "object",
7
7
  "additionalProperties": false,
8
8
  "required": [
9
9
  "schema_version",
10
- "project_root",
10
+ "default_profile",
11
11
  "native_config_files",
12
- "profile_hints",
13
- "secret_references",
14
- "commands",
15
- "capability_hints"
12
+ "profiles",
13
+ "secret_references"
16
14
  ],
17
15
  "properties": {
18
16
  "schema_version": {
19
- "const": 1
17
+ "const": 2
20
18
  },
21
- "project_root": {
22
- "const": "."
19
+ "default_profile": {
20
+ "oneOf": [
21
+ {
22
+ "type": "null"
23
+ },
24
+ {
25
+ "$ref": "#/$defs/profileId"
26
+ }
27
+ ]
23
28
  },
24
29
  "native_config_files": {
25
30
  "type": "array",
@@ -29,11 +34,11 @@
29
34
  "$ref": "#/$defs/projectRelativePath"
30
35
  }
31
36
  },
32
- "profile_hints": {
37
+ "profiles": {
33
38
  "type": "array",
34
- "maxItems": 20,
39
+ "maxItems": 50,
35
40
  "items": {
36
- "$ref": "#/$defs/profileHint"
41
+ "$ref": "#/$defs/profileDeclaration"
37
42
  }
38
43
  },
39
44
  "secret_references": {
@@ -42,46 +47,12 @@
42
47
  "items": {
43
48
  "$ref": "#/$defs/secretReference"
44
49
  }
45
- },
46
- "commands": {
47
- "type": "array",
48
- "maxItems": 100,
49
- "items": {
50
- "$ref": "#/$defs/command"
51
- }
52
- },
53
- "capability_hints": {
54
- "type": "array",
55
- "maxItems": 100,
56
- "items": {
57
- "$ref": "#/$defs/capabilityHint"
58
- }
59
50
  }
60
51
  },
61
52
  "$defs": {
62
- "capabilityName": {
63
- "enum": [
64
- "discover",
65
- "connect",
66
- "authenticate",
67
- "build",
68
- "package",
69
- "transfer",
70
- "configure",
71
- "migrate",
72
- "release",
73
- "start",
74
- "stop",
75
- "restart",
76
- "rollback",
77
- "status",
78
- "health",
79
- "logs",
80
- "history",
81
- "validate",
82
- "diagnose",
83
- "takeover"
84
- ]
53
+ "profileId": {
54
+ "type": "string",
55
+ "pattern": "^[a-z][a-z0-9-]{0,63}$"
85
56
  },
86
57
  "projectRelativePath": {
87
58
  "type": "string",
@@ -89,31 +60,67 @@
89
60
  "maxLength": 512,
90
61
  "pattern": "^(?!/)(?![A-Za-z]:)(?!.*\\\\)(?!.*//)(?!.*\/$)(?!\\.{1,2}(?:/|$))(?!.*(?:/)\\.{1,2}(?:/|$))[^\\u0000-\\u001f\\u007f-\\u009f\\ud800-\\udfff]+$"
91
62
  },
92
- "projectRelativeDirectory": {
93
- "oneOf": [
94
- {
95
- "const": "."
63
+ "releasePolicy": {
64
+ "type": "object",
65
+ "additionalProperties": false,
66
+ "required": [
67
+ "source",
68
+ "artifact_ref"
69
+ ],
70
+ "properties": {
71
+ "source": {
72
+ "enum": [
73
+ "project_native",
74
+ "committed_head",
75
+ "promoted_artifact"
76
+ ]
96
77
  },
78
+ "artifact_ref": {
79
+ "type": [
80
+ "string",
81
+ "null"
82
+ ],
83
+ "minLength": 1,
84
+ "maxLength": 512
85
+ }
86
+ },
87
+ "allOf": [
97
88
  {
98
- "$ref": "#/$defs/projectRelativePath"
89
+ "if": {
90
+ "properties": {
91
+ "source": {
92
+ "const": "promoted_artifact"
93
+ }
94
+ },
95
+ "required": [
96
+ "source"
97
+ ]
98
+ },
99
+ "then": {
100
+ "properties": {
101
+ "artifact_ref": {
102
+ "type": "string",
103
+ "minLength": 1
104
+ }
105
+ }
106
+ }
99
107
  }
100
108
  ]
101
109
  },
102
- "profileHint": {
110
+ "profileDeclaration": {
103
111
  "type": "object",
104
112
  "additionalProperties": false,
105
113
  "required": [
106
114
  "id",
107
115
  "environment",
108
116
  "target_ref",
109
- "endpoint_ref",
110
- "actual_ports",
111
- "health_boundary"
117
+ "native_config_files",
118
+ "release_policy",
119
+ "rollback_retention"
112
120
  ],
113
121
  "properties": {
114
122
  "id": {
115
- "type": "string",
116
- "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$"
123
+ "$ref": "#/$defs/profileId"
117
124
  },
118
125
  "environment": {
119
126
  "type": "string",
@@ -125,76 +132,28 @@
125
132
  "minLength": 1,
126
133
  "maxLength": 256
127
134
  },
128
- "endpoint_ref": {
129
- "type": [
130
- "string",
131
- "null"
132
- ],
133
- "maxLength": 512
134
- },
135
- "actual_ports": {
135
+ "native_config_files": {
136
136
  "type": "array",
137
- "maxItems": 32,
137
+ "maxItems": 50,
138
138
  "uniqueItems": true,
139
139
  "items": {
140
- "type": "integer",
141
- "minimum": 1,
142
- "maximum": 65535
143
- }
144
- },
145
- "health_boundary": {
146
- "type": "array",
147
- "maxItems": 32,
148
- "items": {
149
- "$ref": "#/$defs/healthCheck"
140
+ "$ref": "#/$defs/projectRelativePath"
150
141
  }
151
- }
152
- }
153
- },
154
- "healthCheck": {
155
- "type": "object",
156
- "additionalProperties": false,
157
- "required": [
158
- "name",
159
- "kind",
160
- "target_ref",
161
- "expected",
162
- "required"
163
- ],
164
- "properties": {
165
- "name": {
166
- "type": "string",
167
- "minLength": 1,
168
- "maxLength": 128
169
- },
170
- "kind": {
171
- "enum": [
172
- "command",
173
- "service_state",
174
- "network",
175
- "application",
176
- "target_native"
177
- ]
178
- },
179
- "target_ref": {
180
- "type": "string",
181
- "minLength": 1,
182
- "maxLength": 512
183
142
  },
184
- "expected": {
185
- "type": "string",
186
- "minLength": 1,
187
- "maxLength": 256
143
+ "release_policy": {
144
+ "$ref": "#/$defs/releasePolicy"
188
145
  },
189
- "required": {
190
- "type": "boolean"
146
+ "rollback_retention": {
147
+ "type": "integer",
148
+ "minimum": 0,
149
+ "maximum": 10
191
150
  }
192
151
  }
193
152
  },
194
153
  "secretReference": {
195
154
  "type": "object",
196
155
  "additionalProperties": false,
197
- "description": "Name and external source reference only; never include a Secret value, hash, token, password, key, cookie, header, or connection string.",
156
+ "description": "A name and external source reference only; never a Secret value, hash, token, password, key, cookie, header, or connection string.",
198
157
  "required": [
199
158
  "name",
200
159
  "source_ref",
@@ -214,78 +173,6 @@
214
173
  "type": "boolean"
215
174
  }
216
175
  }
217
- },
218
- "command": {
219
- "type": "object",
220
- "additionalProperties": false,
221
- "required": [
222
- "capability",
223
- "executable",
224
- "args",
225
- "working_directory",
226
- "source"
227
- ],
228
- "properties": {
229
- "capability": {
230
- "$ref": "#/$defs/capabilityName"
231
- },
232
- "executable": {
233
- "type": "string",
234
- "minLength": 1,
235
- "maxLength": 256
236
- },
237
- "args": {
238
- "type": "array",
239
- "maxItems": 100,
240
- "items": {
241
- "type": "string",
242
- "maxLength": 1024
243
- }
244
- },
245
- "working_directory": {
246
- "$ref": "#/$defs/projectRelativeDirectory"
247
- },
248
- "source": {
249
- "enum": [
250
- "project_native",
251
- "user_confirmed"
252
- ]
253
- }
254
- }
255
- },
256
- "capabilityHint": {
257
- "type": "object",
258
- "additionalProperties": false,
259
- "required": [
260
- "capability",
261
- "evidence_files",
262
- "manual_checkpoint",
263
- "notes"
264
- ],
265
- "properties": {
266
- "capability": {
267
- "$ref": "#/$defs/capabilityName"
268
- },
269
- "evidence_files": {
270
- "type": "array",
271
- "maxItems": 20,
272
- "uniqueItems": true,
273
- "items": {
274
- "$ref": "#/$defs/projectRelativePath"
275
- }
276
- },
277
- "manual_checkpoint": {
278
- "type": [
279
- "string",
280
- "null"
281
- ],
282
- "maxLength": 512
283
- },
284
- "notes": {
285
- "type": "string",
286
- "maxLength": 512
287
- }
288
- }
289
176
  }
290
177
  }
291
178
  }
@@ -1,90 +1,71 @@
1
- # Legacy Deployment State Migration
1
+ # Legacy Deployment Evidence Migration
2
2
 
3
- Apply this procedure on first use whenever `.prizmkit/deploy/` exists, before creating or modifying `.prizmkit/deploy/deploy.json`. Legacy artifacts are evidence, not authorization and not current output formats.
3
+ Legacy artifacts are evidence, not authorization. Apply this reference when `.prizmkit/deploy/` contains the old `.prizmkit/deploy/deploy.json` sole record or earlier PrizmKit deployment artifacts before writing a v2 Profile record.
4
4
 
5
- ## Safety Invariants
5
+ ## Boundary
6
6
 
7
- - Inventory and validation are read-only and project-scoped.
8
- - Never print, persist, hash, compare, or copy a Secret value.
9
- - Never delete, rename, truncate, normalize, or overwrite a legacy artifact during automatic migration.
10
- - Never continue a legacy writer after inventory, even when conversion is blocked.
11
- - Migrate only necessary, unambiguous, non-sensitive facts corroborated by current evidence.
12
- - Preserve uncertain, malformed, conflicting, Secret-bearing, or unconverted evidence in place.
13
- - A write to the sole record is an ordinary reversible write included in the complete confirmed plan. A source-artifact deletion or modification would require a separate exact dedicated confirmation and is not part of migration.
14
- - Existing project-native deployment configuration outranks legacy PrizmKit state.
7
+ - Inventory only project-local deployment artifacts and do not follow a symlink outside the project.
8
+ - Preserve the old file and every uncertain legacy artifact; migration does not rename, truncate, overwrite, or delete them.
9
+ - Stop every legacy writer after inventory. Future PrizmKit state writes use `.prizmkit/deploy/profiles/<profile-id>.json` only.
10
+ - Convert only necessary non-sensitive facts corroborated by current project or target evidence.
11
+ - Secret values, hashes, raw logs, raw command output, and credential-bearing URLs never move into a v2 artifact.
12
+ - Existing project-native configuration and current target observations outrank legacy PrizmKit claims.
15
13
 
16
- ## Known Legacy Inventory
14
+ ## Known Evidence
17
15
 
18
- Check only project-local paths that exist; do not create missing paths:
16
+ Treat these as possible inputs, not current formats:
19
17
 
20
- | Legacy class | Known identity | Validation and conversion boundary |
21
- |---|---|---|
22
- | Configuration | `.prizmkit/deploy/deploy.config.json` and other clearly PrizmKit-owned config files in that directory | Parse without interpolation. Convert only target/profile references, environment labels, actual observed ports, native config paths, health definitions, release/rollback references, and Secret *names/source references*. Commands become evidence only and must be rediscovered before execution. |
23
- | Pending input | `.prizmkit/deploy/pending-input.json` | Validate shape and operation identity. Carry forward only a still-relevant non-sensitive pending action after rediscovery; otherwise preserve it and ask a fresh question. Never trust it as confirmation. |
24
- | Generated document | `.prizmkit/deploy/deploy.md` | Treat as human-readable, potentially stale evidence. Convert a fact only when corroborated by project-native or current target evidence. Never generate or update this document. |
25
- | Per-event history | `.prizmkit/deploy/deploy-history/*.json` | Parse each bounded file independently. Convert only concise redacted summaries from valid events, newest first, then retain at most the sole-record history limit. Preserve every source file. Never write another event file. |
26
- | Local Secret material | `.prizmkit/deploy/secrets.local.env`, `.prizmkit/deploy/secrets.local.json`, or another clearly Secret-bearing legacy path | Validate path ownership/ignore/permission metadata without displaying content. Do not import values. When safe key-name parsing is necessary and authorized, retain only names, external source reference, and presence; malformed or unsafe content stays untouched. Never create replacement local Secret storage. |
27
- | Target metadata copy/reference | `deploy-metadata.json` or a recorded target metadata path | Treat as stale until compared with current target-native read-only state. Convert only verified release/health/rollback facts. Do not recreate the fixed metadata format. |
28
- | Event/template/script artifact | Any per-release, per-phase, per-target, generated script, archive recipe, or template under the legacy directory | Preserve as evidence. Do not execute, regenerate, migrate as authority, or continue its naming pattern. |
18
+ - `.prizmkit/deploy/deploy.json` schema v1;
19
+ - `.prizmkit/deploy/deploy.config.json` or other old PrizmKit config;
20
+ - `.prizmkit/deploy/pending-input.json`;
21
+ - `.prizmkit/deploy/deploy.md`;
22
+ - `.prizmkit/deploy/deploy-history/*.json`;
23
+ - local Secret files under the legacy directory;
24
+ - copied target metadata, generated scripts, templates, recipes, or per-release/phase/target artifacts.
29
25
 
30
- Do not recursively scan unrelated project content or follow symlinks outside the project. Record a symlink escape or unreadable artifact as a conflict and preserve it untouched.
26
+ Do not execute a legacy command or continue a legacy filename pattern. Local Secret sources remain untouched; retain at most a Secret name, external source reference, and presence state when those facts can be obtained without displaying a value.
31
27
 
32
- ## Procedure
28
+ ## Sole-Record Conversion
33
29
 
34
- ### 1. Inventory
30
+ 1. Parse the old `.prizmkit/deploy/deploy.json` strictly and preserve it unchanged on any malformed, unknown-version, duplicate-key, or sensitive-field finding.
31
+ 2. Read its profile list and unique current.profile_id, then corroborate that Profile and target with current project/target evidence.
32
+ 3. When current has one valid Profile identity and current/latest/recovery facts belong unambiguously to it, create one candidate `.prizmkit/deploy/profiles/<profile-id>.json` containing only:
33
+ - Profile identity and current target fingerprint;
34
+ - Secret references/presence without values;
35
+ - verified current release/live/rollback facts;
36
+ - one concise latest result and bounded history that fit v2;
37
+ - minimal still-relevant recovery.
38
+ 4. Do not create “already deployed” records for other legacy profile hints merely because they were listed in the old global record.
39
+ 5. When current Profile identity is absent, duplicated, unsafe for the lowercase Profile filename contract, or conflicts with target evidence, do not guess. Preserve the old record and ask for one Profile/target decision only when deployment continuation needs it.
40
+ 6. Validate the complete v2 candidate with the Profile schema and semantic validator before writing it. A deploy invocation authorizes this selected-Profile local state conversion; it never authorizes deletion of old evidence.
35
41
 
36
- 1. List the existing `.prizmkit/deploy/` entries without following external symlinks.
37
- 2. Classify each path by the table above or `unknown legacy evidence`.
38
- 3. Record path, class, readability, and validation result without content excerpts that may contain Secrets.
39
- 4. If `deploy.json` already exists, validate it first. Legacy evidence discovered later does not merge automatically into an established record.
42
+ A schema-v1 `latest_result` may use BLOCKED or CANCELLED. Map it only when current evidence proves the semantic outcome:
40
43
 
41
- ### 2. Validate Independently
44
+ - resumable human action → `WAITING_USER` with one pending action;
45
+ - non-resumable unsupported/stopped outcome → `FAILED` with a bounded reason;
46
+ - ambiguous result → omit conversion and preserve the old evidence.
42
47
 
43
- - Parse structured artifacts with strict duplicate-key and type checking where the current environment supports it.
44
- - Reject unknown legacy schema versions as conversion authority; preserve them.
45
- - Treat free-form documents, commands, timestamps, and recorded validation flags as stale claims.
46
- - Check project-native configuration and current read-only target observations before accepting target identity, ports, live release, health, or rollback.
47
- - Detect Secret-like field names and values before any preview. Omit values entirely; do not mask and carry them into the new record.
48
- - Do not resolve a conflict by choosing the newest timestamp alone.
48
+ Never convert an old successful result when its required target/release observations cannot be re-established.
49
49
 
50
- Invalid input does not block read-only discovery, but it blocks conversion of that input and any write that would silently discard its meaning.
50
+ ## Other Legacy Inputs
51
51
 
52
- ### 3. Build a Migration Preview
52
+ - **Configuration:** copy only non-sensitive Profile/target/native-config/release-policy hints corroborated by current files. Old commands are discovery hints, not executable authority.
53
+ - **Pending input:** retain only a still-relevant non-sensitive action after target rediscovery; otherwise ask a fresh question.
54
+ - **Per-event history:** if needed, convert at most the newest 20 concise unambiguous summaries into the selected Profile record. Preserve every source event file.
55
+ - **Generated document/metadata:** use only a fact corroborated by current direct evidence.
56
+ - **Secret-bearing input:** preserve untouched; never import values.
57
+ - **Generated script/template/recipe:** preserve but never execute or regenerate as framework state.
53
58
 
54
- Present one bounded preview containing:
59
+ ## Conflict and Failure
55
60
 
56
- - source paths and validation statuses;
57
- - exact non-sensitive facts proposed for `project`, `profiles`, `secret_references`, `current`, bounded `history`, or `recovery`;
58
- - every conflict or stale/unverified claim;
59
- - every preserved path;
60
- - facts intentionally omitted and why;
61
- - the exact complete resulting `.prizmkit/deploy/deploy.json`.
61
+ Read-only discovery may continue when a legacy input is invalid. A conversion write does not continue when doing so would discard unknown meaning, associate evidence with the wrong Profile, or expose sensitive material.
62
62
 
63
- The preview must not contain legacy Secret values, full logs, raw command output, or unbounded event content.
63
+ After a timeout during candidate record creation, inspect whether that exact Profile record exists and validates before replay. Do not repeat a target deployment to repair local migration state.
64
64
 
65
- ### 4. Confirm and Write Once
66
-
67
- When the user confirms the complete plan containing the migration:
68
-
69
- 1. recheck that every inventoried source path and current evidence used by the preview is unchanged;
70
- 2. validate the complete candidate against `${SKILL_DIR}/references/deploy-record-schema.json`;
71
- 3. create `.prizmkit/deploy/` only if needed and included in the plan;
72
- 4. write a temporary file in the same directory, flush/close it, validate it again, and atomically replace `deploy.json` without following a symlink;
73
- 5. read back and validate the exact written object;
74
- 6. leave every legacy source in place;
75
- 7. stop with `FAILED` if record verification fails, preserving both the live state and legacy evidence.
76
-
77
- Do not claim that atomic replacement provides concurrent-writer safety. This contract assumes one operator.
78
-
79
- ## Conflict and Failure Outcomes
80
-
81
- - **Unambiguous conversion:** write the fact and mark its source `MIGRATED_NON_SECRET`.
82
- - **Secret-bearing source:** keep values untouched, store at most a reference/presence fact, mark `PRESERVED_SECRET`.
83
- - **Malformed or unknown source:** preserve it, mark `INVALID` or `PRESERVED_UNCERTAIN`, and describe the blocker without sensitive content.
84
- - **Conflicting current facts:** use direct current evidence for execution, preserve the legacy conflict in `legacy_migration.conflicts`, and require confirmation of the resulting plan.
85
- - **Unknown write outcome:** inspect whether `deploy.json` exists and validates before any replay; never overwrite merely because the client timed out.
86
- - **No confirmation:** make no managed write and return `WAITING_USER` when a migration write is necessary for continuation.
65
+ When migration is not safely possible, leave all legacy evidence unchanged, report the exact non-sensitive conflict, and continue from current target observations whenever those observations establish a safe deployment action.
87
66
 
88
67
  ## After Migration
89
68
 
90
- Subsequent operations read and update only `deploy.json` for PrizmKit local state. Legacy paths remain read-only evidence until the user separately chooses exact cleanup. Never create or update legacy configuration, pending-input, document, metadata, Secret, template, script, archive, or per-event history artifacts.
69
+ Read and write only the selected `.prizmkit/deploy/profiles/<profile-id>.json` for current PrizmKit state. The optional `prizmkit.deploy.json` declaration may be migrated separately only when the user asks to modify that version-controlled project file.
70
+
71
+ Legacy files remain read-only until the user explicitly chooses exact local cleanup. Removing legacy evidence or a Profile record never decommissions target resources.