dsh-crate-web 0.1.1 → 0.1.2-preview.2

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "dsh-crate-web",
   "description": "DSH Web Settings surface for DSH Crate export, import, inspect, and history",
-  "version": "0.1.1",
+  "version": "0.1.2-preview.2",
   "type": "module",
   "main": "lib/index.js",
-  "types": "lib/types/index.d.ts",
+  "types": "lib/index.d.ts",
   "exports": {
     ".": {
       "types": "./lib/index.d.ts",
@@ -21,12 +21,19 @@
     "lib/client.js",
     "lib/*.d.ts",
     "restart-helper.mjs",
+    "verify-desktop.mjs",
+    "desktop-patch-helper.mjs",
     "cordis.patch.yml",
     "core/dsh_pack/**/*.py",
-    "runtime/python"
+    "runtime/python",
+    "skills/dsh-crate-troubleshooting/SKILL.md",
+    "skills/dsh-crate-troubleshooting/compatibility.json",
+    "skills/dsh-crate-troubleshooting/reference/*.md",
+    "THIRD-PARTY-LICENSE.txt"
   ],
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "tag": "preview"
   },
   "license": "MIT",
   "dsh": {
@@ -46,6 +53,7 @@
     "bundle": "node scripts/vendor-core.mjs && node scripts/prepare-runtime.mjs && tsdown"
   },
   "peerDependencies": {
+    "@deepseek-ai/dsh-client-connection": "*",
     "@deepseek-ai/cordis": "^4.0.0",
     "@deepseek-ai/dsh-client-locale": "*",
     "@deepseek-ai/dsh-client-runtime": "*",
@@ -68,7 +76,6 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/joezhou172/dsh-crate-web.git"
-  },
-  "author": "joezhou172 <rdhwhyhrg@163.com>"
+    "url": "git+https://github.com/joezhou172/dsh-crate-web.git"
+  }
 }

package/skills/dsh-crate-troubleshooting/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: dsh-crate-troubleshooting
+description: Diagnose DSH Crate Import, Export and Verify failures from complete diagnostic reports, with version checks and minimal scoped next steps.
+---
+
+# DSH Crate Troubleshooting Skill
+
+Version-aware troubleshooting for DSH Crate diagnostics. Run dsh-crate diagnose report.json --json for a read-only classification; it preserves the complete input report and never executes commands from it.
+
+This Skill ships with the same version as the DSH Crate release it supports.
+The version compatibility contract lives in `compatibility.json`; the code
+registry in `src/dsh_pack/diagnostics.py` is the single source of truth for
+diagnostic codes and stages (rendered into `reference/diagnostics.generated.md`
+and `reference/stages.generated.md` by `scripts/generate-skill-reference.py`).
+
+## 0. Read first
+
+1. `compatibility.json` — what this Skill version supports.
+2. `reference/repair-boundaries.md` — what may be touched at each repair level.
+3. `reference/diagnostics.generated.md` / `reference/stages.generated.md` —
+   codes and stages this release knows.
+4. The incoming diagnostic JSON — never guess what it contains.
+
+## 1. Version Gate (always first)
+
+Read the diagnostic envelope:
+
+```json
+{
+  "producer": "dsh-crate",
+  "crateVersion": "0.1.0",
+  "diagnosticSchemaVersion": 1,
+  "operation": "import",
+  "operationId": "...",
+  "status": "FAIL"
+}
+```
+
+Classify with the compatibility contract:
+
+- `FULL` — same Crate generation and a supported diagnostic schema; diagnose normally.
+- `COMPATIBLE` — older Crate inside the supported range; use compatibility rules, do not assume newer-only behavior.
+- `UNSUPPORTED` — Crate outside the supported range or an unsupported schema. You may interpret the raw evidence, but you MUST NOT apply version-related automatic repair. State clearly: `This diagnostic was produced by DSH Crate <x>, but this Troubleshooting Skill supports <range>. Update the Skill before applying automated repair.`
+
+Missing envelope fields: treat as `UNSUPPORTED` with reason "diagnostic envelope is incomplete"; do not guess the missing values.
+
+## 2. Identify the operation
+
+Use `operation` (e.g. `import`, `export`, `inspect`, `verify`, `create-profile`, `delete-profile`, `switch-profile`). The operation tells you which end state was requested and therefore which "original state unchanged" guarantee applies.
+
+## 3. Identify the failed stage
+
+Look at the issue `stage` and the operation report. Confirm with evidence:
+
+- which Pack file or Profile path is involved;
+- which command was run (and its exit code / stdout / stderr);
+- which plugin/artifact/item is the subject.
+
+`reference/stages.generated.md` maps each stage to its meaning and Import state.
+
+## 4. Collect evidence
+
+Separate **fact** from **hypothesis**:
+
+- Fact: envelope fields, `code`, `stage`, `item`, `expected`, `observed`, `evidence`, `stdout`/`stderr`, exit code, current file state, current Profile state.
+- Hypothesis: anything you infer beyond the evidence. Label it explicitly.
+
+Do not treat a missing check as a pass and do not invent evidence. If the diagnostic says `canContinue: false`, stopping is the correct behavior.
+
+## 5. Match the known diagnostic
+
+Look up `code` in `reference/diagnostics.generated.md`.
+
+- Known code -> use the registry entry (severity, repair level, write scope, suggested checks).
+- Unknown code -> `known: false`, repair level `L3`, write scope `none`. Report the code as unknown; never guess a fix.
+
+## 6. Build a hypothesis
+
+Only after evidence supports it:
+
+1. Read the failing stage and its evidence.
+2. List plausible causes (max 2-3) with the evidence each would need.
+3. Run the cheapest read-only check that discriminates between them.
+4. Proceed only when evidence points at one cause.
+
+If evidence is insufficient, stop and request the missing evidence.
+
+## 7. Select the minimum action
+
+Choose the smallest write that addresses the confirmed cause. Respect the repair level:
+
+- `L0` — read-only. Automatic.
+- `L1` — safe reversible writes. Automatic; see `reference/repair-boundaries.md`.
+- `L2` — must obtain explicit user confirmation before writing.
+- `L3` — never automatic. Report only.
+
+## 8. Respect the write boundary
+
+Never:
+
+- mutate credentials, tokens, cookies, passwords, private keys, or `Authorization` material;
+- delete or modify the original working Profile except through an explicit confirmed operation;
+- modify unrelated Profiles;
+- modify DSH vendor source;
+- lower the verification standard to clear an error (FAIL -> WARNING);
+- fake a Verify PASS.
+
+Scope every write to the target temporary Profile or the exact confirmed target, and record it.
+
+## 9. Execute if allowed
+
+Perform the L1/L2 action exactly as confirmed. If the action fails, do not paper over it: keep the operation `FAIL`, record the new evidence, and stop or request the next confirmed step.
+
+## 10. Verify
+
+Verification is the only arbiter of success:
+
+- Re-run the DSH Crate `verify` for the affected Profile (web or headless mode as configured).
+- `PASS` — report PASS with the verifying evidence.
+- `FAIL` — report FAIL: "Repair did not resolve the original failure."
+- If the affected capability cannot be verified, the result is `UNTESTED`, never PASS.
+
+## 11. Report
+
+Fixed structured output:
+
+```text
+Diagnosis
+---------
+Operation: <operation>
+Stage: <stage>
+Code: <code>
+Severity: <severity>
+Item: <item>
+Known: yes/no
+
+Evidence
+--------
+<facts and captured output>
+
+Likely cause
+------------
+<evidence-backed cause>
+
+Confidence
+----------
+High / Medium / Low
+
+Action
+------
+<what was done, or what is proposed>
+
+Write scope
+-----------
+<scope actually touched>
+
+Verification
+------------
+PASS / FAIL / UNTESTED / DEGRADED
+<evidence>
+```
+
+## 12. Stop conditions
+
+Stop and hand back to the user when any of these hold:
+
+- version gate is `UNSUPPORTED`;
+- the code is unknown (L3);
+- the required action is `L2`/`L3` without explicit confirmation;
+- evidence is insufficient to choose a cause;
+- a repair was attempted and verification still fails;
+- the diagnostic says the operation is not allowed to continue.

package/skills/dsh-crate-troubleshooting/compatibility.json

@@ -0,0 +1,11 @@
+{
+  "name": "dsh-crate-troubleshooting",
+  "skillVersion": "0.1.2-preview.2",
+  "compatibility": {
+    "dshCrate": ">=0.1.0 <0.1.3",
+    "diagnosticSchema": [
+      1
+    ]
+  },
+  "producer": "dsh-crate"
+}

package/skills/dsh-crate-troubleshooting/reference/diagnostics.generated.md

@@ -0,0 +1,96 @@
+# DSH Crate Diagnostic Codes
+
+> Generated from `core/dsh_pack/diagnostics.py` (schema v1, producer `dsh-crate`, crate 0.1.2-preview.2). Do not edit by hand.
+
+Total codes: **79**. Stages: **16**.
+
+| Code | Stage | Severity | Repair | Write scope | Verify after | Summary |
+| --- | --- | --- | --- | --- | --- | --- |
+| `ACTIVE_PROFILE` | delete | BLOCKER | L2 | target-profile | yes | Cannot delete the active Profile. |
+| `ARTIFACT_MEMBER_DUPLICATE` | embedded-install | BLOCKER | L1 | none | yes | Embedded artifact contains a duplicate member. |
+| `ARTIFACT_MEMBER_READ_ERROR` | embedded-install | BLOCKER | L1 | none | yes | Embedded artifact member cannot be read. |
+| `ARTIFACT_MEMBER_TYPE_INVALID` | embedded-install | BLOCKER | L1 | none | yes | Embedded artifact member type is invalid. |
+| `ARTIFACT_PATH_INVALID` | embedded-install | BLOCKER | L1 | none | yes | Embedded artifact path is invalid. |
+| `ARTIFACT_PATH_MISSING` | embedded-install | BLOCKER | L1 | none | yes | Embedded artifact path is missing. |
+| `ARTIFACT_UNPACK_FAILED` | embedded-install | BLOCKER | L1 | temporary-profile | yes | Embedded artifact unpack failed. |
+| `CONFLICT_BUNDLE_COMPOSITION` | composition | BLOCKER | L1 | target-profile | yes | Bundle composition conflict. |
+| `CONFLICT_DUPLICATE_ARTIFACT` | composition | BLOCKER | L1 | none | yes | Duplicate plugin artifact. |
+| `CONFLICT_DUPLICATE_BUNDLE_ORDER` | composition | BLOCKER | L1 | none | yes | Duplicate Bundle order. |
+| `CRATE_VERSION_MISSING` | planning | BLOCKER | L1 | dsh-home | yes | DSH Crate package version is missing. |
+| `DELETE_CONFIRMATION_REQUIRED` | delete | BLOCKER | L2 | target-profile | yes | Delete requires explicit confirmation. |
+| `EMBEDDED_DEPENDENCIES_INSTALL_FAILED` | embedded-install | BLOCKER | L1 | temporary-profile | yes | Embedded dependency install failed. |
+| `EMBEDDED_DEPENDENCIES_TIMEOUT` | embedded-install | BLOCKER | L1 | temporary-profile | yes | Embedded dependency install timed out. |
+| `EMBEDDED_NPM_FAILED` | embedded-install | BLOCKER | L1 | temporary-profile | yes | Embedded npm install failed. |
+| `EMBEDDED_NPM_UNAVAILABLE` | embedded-install | BLOCKER | L1 | temporary-profile | yes | npm is unavailable for embedded install. |
+| `ENVIRONMENT_EXACT_MATCH` | environment | INFO | L0 | none | yes | Environment matches the source. |
+| `ENVIRONMENT_OS_MISMATCH` | environment | WARNING | L0 | none | yes | Operating system differs from the source. |
+| `ENVIRONMENT_VERSION_MISMATCH` | environment | WARNING | L0 | none | yes | Environment version differs from the source. |
+| `FORMAT_ERROR` | preflight | BLOCKER | L1 | none | yes | Pack format is invalid. |
+| `HASH_MISMATCH` | preflight | BLOCKER | L1 | none | yes | Pack hash mismatch. |
+| `HASH_OR_INTEGRITY_ERROR` | preflight | BLOCKER | L1 | none | yes | Pack hash or integrity check failed. |
+| `HEADLESS_RUNNER_FAILED` | runtime | BLOCKER | L1 | none | yes | Headless runtime failed. |
+| `IMPORT_FAILED` | commit | BLOCKER | L1 | temporary-profile | yes | Import failed. |
+| `INTEGRITY_FILE_MISSING` | preflight | BLOCKER | L1 | none | yes | Integrity record is missing. |
+| `INTEGRITY_FILE_SET_MISMATCH` | preflight | BLOCKER | L1 | none | yes | Integrity file set does not match. |
+| `NETWORK_INSTALL_FAILED` | network-install | BLOCKER | L1 | temporary-profile | yes | Network install failed. |
+| `NETWORK_INSTALL_REQUIRED` | network-install | WARNING | L0 | none | yes | Network install will be required. |
+| `NETWORK_INSTALL_TIMEOUT` | network-install | BLOCKER | L1 | temporary-profile | yes | Network install timed out. |
+| `NETWORK_PACKAGE_MISSING` | network-install | BLOCKER | L1 | temporary-profile | yes | Network package is missing. |
+| `NETWORK_SOURCE_UNSUPPORTED` | network-install | BLOCKER | L1 | temporary-profile | yes | Network source type is unsupported. |
+| `OFFICIAL_BUNDLE_MISSING` | planning | BLOCKER | L1 | dsh-home | yes | Official DSH Bundle cannot be resolved. |
+| `OPTIONAL_ARTIFACT_MISSING` | reference-install | WARNING | L0 | none | yes | Optional artifact is missing. |
+| `OPTIONAL_PLUGIN_MISSING` | reference-install | WARNING | L0 | none | yes | Optional plugin is missing. |
+| `OVERWRITE_CONFIRMATION_REQUIRED` | planning | BLOCKER | L2 | target-profile | yes | Overwrite requires explicit confirmation. |
+| `OVERWRITE_MODE_REQUIRED` | planning | BLOCKER | L2 | target-profile | yes | Overwrite mode is required. |
+| `PACKAGE_IDENTITY_DRIFT` | version-confirmation | BLOCKER | L1 | none | yes | Package identity drift. |
+| `PACKAGE_MANAGER_REQUIRED` | planning | BLOCKER | L0 | none | yes | 新建 Profile 需要正式包管理器。 |
+| `PACKAGE_MANIFEST_INVALID` | planning | BLOCKER | L1 | none | yes | Plugin package manifest is invalid. |
+| `PACKAGE_NAME_INVALID` | planning | BLOCKER | L1 | none | yes | Plugin package name is invalid. |
+| `PACK_READ_ERROR` | planning | BLOCKER | L1 | none | yes | Pack cannot be read. |
+| `PLUGIN_INSTALL_FAILED` | reference-install | BLOCKER | L1 | temporary-profile | yes | Plugin install failed. |
+| `PLUGIN_MISSING` | reference-install | BLOCKER | L1 | temporary-profile | yes | Plugin is missing after install. |
+| `PLUGIN_SMOKE_FAILED` | plugin-smoke | BLOCKER | L1 | none | yes | Plugin smoke test failed. |
+| `PLUGIN_SOURCE_MISSING` | reference-install | BLOCKER | L1 | temporary-profile | yes | Plugin source is missing. |
+| `PLUGIN_SOURCE_UNSAFE` | reference-install | BLOCKER | L2 | target-profile | yes | Plugin source is unsafe. |
+| `PLUGIN_TARGET_EXISTS` | configuration | BLOCKER | L2 | target-profile | yes | Plugin target directory already exists. |
+| `PLUGIN_VERSION_MISMATCH` | version-confirmation | BLOCKER | L1 | temporary-profile | yes | Installed plugin version does not match the Pack. |
+| `PREFLIGHT_BLOCKED` | preflight | BLOCKER | L1 | none | yes | Preflight found BLOCKER findings. |
+| `PREFLIGHT_ERROR` | preflight | BLOCKER | L1 | none | yes | Preflight crashed. |
+| `PROBE_FAILED` | probe | BLOCKER | L1 | none | yes | Runtime probe failed. |
+| `PROFILE_CONFIG_MISSING` | configuration | BLOCKER | L1 | temporary-profile | yes | Profile configuration is missing. |
+| `PROFILE_DELETE_FAILED` | delete | BLOCKER | L1 | target-profile | yes | Profile deletion failed. |
+| `PROFILE_EXISTS` | planning | BLOCKER | L2 | target-profile | yes | Target Profile already exists. |
+| `PROFILE_FILE_EXISTS` | configuration | BLOCKER | L2 | target-profile | yes | Target Profile file already exists. |
+| `PROFILE_MISSING` | planning | BLOCKER | L1 | none | yes | Target Profile does not exist. |
+| `PROFILE_NAME_INVALID` | planning | BLOCKER | L1 | none | yes | Profile name is invalid. |
+| `PROFILE_NAME_MISSING` | planning | BLOCKER | L1 | none | yes | Profile name is missing. |
+| `PROFILE_NAME_RESERVED` | planning | BLOCKER | L1 | none | yes | Profile name is reserved. |
+| `PROFILE_NAME_UNAVAILABLE` | planning | BLOCKER | L1 | none | yes | Profile name is unavailable. |
+| `PROFILE_NOT_FOUND` | delete | BLOCKER | L1 | none | yes | Profile not found. |
+| `PROFILE_PATCH_ADAPTATION_FAILED` | configuration | BLOCKER | L0 | none | yes | 无法证明恢复配置与官方 Loader 配置等价。 |
+| `PROFILE_PATCH_ADAPTER_COMMAND_INVALID` | planning | BLOCKER | L0 | none | yes | 桌面配置适配器命令无效。 |
+| `PROFILE_TARGET_INVALID` | planning | BLOCKER | L1 | none | yes | Import target is invalid. |
+| `PROFILE_TARGET_MISSING` | planning | BLOCKER | L1 | none | yes | Import target is missing. |
+| `REQUIRED_ARTIFACT_MISSING` | reference-install | BLOCKER | L1 | temporary-profile | yes | Required artifact is missing. |
+| `RESTART_NOT_CONFIGURED` | restart | BLOCKER | L2 | environment | yes | DSH restart launcher is not configured. |
+| `RESTART_PORT_NOT_RELEASED` | restart | BLOCKER | L2 | environment | yes | Port was not released after restart. |
+| `RUNNER_EXITED_BEFORE_READY` | runtime | BLOCKER | L1 | none | yes | Runtime exited before ready. |
+| `RUNNER_READY_REGEX_INVALID` | runtime | BLOCKER | L1 | temporary-profile | yes | Runtime readyRegex is invalid. |
+| `RUNNER_READY_TIMEOUT` | runtime | BLOCKER | L1 | none | yes | Runtime ready timeout. |
+| `RUNNER_SPAWN_FAILED` | runtime | BLOCKER | L1 | none | yes | Runtime command could not start. |
+| `SCHEMA_ERROR` | preflight | BLOCKER | L1 | none | yes | Pack schema is unsupported. |
+| `SECRET_MISSING` | planning | WARNING | L0 | none | yes | Required Secret is missing. |
+| `SWITCH_CONFIRMATION_REQUIRED` | planning | BLOCKER | L2 | environment | yes | Profile switch requires explicit confirmation. |
+| `VERSION_MISSING` | environment | WARNING | L0 | none | yes | A recorded version is missing. |
+| `WEB_HTTP_STATUS_MISMATCH` | runtime | BLOCKER | L1 | none | yes | Web HTTP status does not match. |
+| `WEB_HTTP_UNREACHABLE` | runtime | BLOCKER | L1 | none | yes | Web endpoint is unreachable. |
+| `WEB_PORT_NOT_OWNED` | runtime | BLOCKER | L2 | environment | yes | Web port is not owned by the runtime. |
+
+## Repair levels
+
+| Level | Meaning |
+| --- | --- |
+| L0 | No write needed; the diagnostic is advisory or the fix is already applied. |
+| L1 | Safe, reversible writes allowed without confirmation (see repair-boundaries.md). |
+| L2 | Writes that change the target Profile / environment; explicit user confirmation required. |
+| L3 | Never repair; unknown codes and credential-class issues are report-only. |

package/skills/dsh-crate-troubleshooting/reference/repair-boundaries.md

@@ -0,0 +1,60 @@
+# Repair boundaries
+
+What the DSH Crate Troubleshooting Skill may touch at each repair level.
+This file is manually maintained policy and applies to every code in
+`diagnostics.generated.md` that carries a repair level.
+
+## L0 — Read only (automatic)
+
+- Read the diagnostic, the Pack manifest, `plugins.lock.json`, `profile/` files, and integrity records.
+- Inspect Profile state under DSH_HOME.
+- Check whether files, packages, artifacts, ports, and processes exist.
+- Read versions, manifests, stdout/stderr, and operation history.
+- Never write anything.
+
+## L1 — Safe repair (automatic)
+
+Allowed without confirmation because it never changes the original environment's critical state:
+
+- Clean up the failed temporary/scratch directory created by the Import that already failed.
+- Re-run the read-only Preflight / Inspect to refresh evidence.
+- Re-download a reference-only dependency from its recorded source (network) into the temporary Profile.
+- Re-run Verify after an L1 action.
+- Retry a transient install that failed on a network/timing issue, into the temporary Profile only.
+
+L1 actions never touch:
+
+- the original working Profile;
+- credentials;
+- committed Import targets;
+- installed plugin versions in a committed Profile.
+
+## L2 — Confirmation required
+
+Must show the user the exact target and get explicit confirmation before writing:
+
+- Overwrite an existing Profile (Import overwrite).
+- Switch the active Profile.
+- Restart the DSH runtime.
+- Delete a Profile.
+- Modify Profile configuration.
+- Change an installed plugin version.
+- Replace an embedded artifact.
+
+## L3 — Never automatic (report only)
+
+The Skill never performs, even with confirmation inside an automated flow:
+
+- Modify credentials, tokens, cookies, passwords, private keys, or `Authorization` material.
+- Delete or modify the original working Profile outside an explicitly confirmed operation.
+- Modify unrelated Profiles.
+- Modify DSH vendor source or the DSH Crate package itself.
+- Lower the verification standard (FAIL -> WARNING) or fabricate a Verify PASS.
+
+Unknown codes and unsupported versions default to L3 / no write.
+
+## Defaults
+
+- Unknown code -> repair level `L3`, write scope `none`.
+- Missing envelope -> do not repair; request a matching diagnostic.
+- Unsupported version/schema -> interpret evidence only; no automated repair.

package/skills/dsh-crate-troubleshooting/reference/stages.generated.md

@@ -0,0 +1,22 @@
+# DSH Crate Diagnostic Stages
+
+> Generated from `core/dsh_pack/diagnostics.py` (schema v1). Do not edit by hand.
+
+| Stage | Title | Description | Import state |
+| --- | --- | --- | --- |
+| commit | Commit | Committing the prepared Profile and metadata as a successful Import. | commit |
+| composition | Bundle composition | Composing Bundle patches and Loader rows for the Profile. | composition |
+| configuration | Configuration | Writing Pack profile configuration into the target Profile. | configuration |
+| delete | Delete | Deleting a non-running Profile after explicit confirmation. | delete |
+| embedded-install | Embedded install | Installing an embedded plugin artifact (npm tarball) into the temporary Profile. | embedded-install |
+| environment | Environment | Environment compatibility findings (OS, Node, DSH versions). | environment |
+| network-install | Network install | Downloading and installing a recorded network package. | network-install |
+| planning | Plan | Operation planning: target Profile selection, name validation, pack read, and Import preview. | planning |
+| plugin-smoke | Plugin smoke | Running a plugin-specific smoke test against the runtime. | plugin-smoke |
+| preflight | Preflight | Read-only Inspect/Preflight of a Pack before any Profile change. | preflight |
+| probe | Probe | Running a runtime capability probe after boot. | probe |
+| reference-install | Reference install | Installing or resolving a reference-only plugin source. | reference-install |
+| restart | Restart | Restarting DSH on the target Profile and port. | restart |
+| runtime | Runtime boot | Starting the DSH runtime and waiting for a ready URL. | runtime |
+| surface | Surface | Web surface or Bundle composition surface checks. | surface |
+| version-confirmation | Version confirmation | Confirming the installed package identity matches the Pack resolution. | version-confirmation |