omni-dsh-plugins 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +148 -0
  3. package/dist/bin.js +29487 -0
  4. package/package.json +51 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Diego Souza
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,148 @@
1
+ # omni-dsh-plugins
2
+
3
+ > **Unofficial community project. Not affiliated with, endorsed by, or sponsored by DeepSeek.**
4
+ > DeepSeek names and marks belong to their respective owner.
5
+
6
+ `omni-dsh-plugins` is a thin catalog client and safety boundary for public DeepSeek
7
+ Harness (DSH) plugin entries. Its canonical invocation is:
8
+
9
+ ```bash
10
+ npx omni-dsh-plugins --help
11
+ ```
12
+
13
+ The npm artifact is MIT-licensed executable JavaScript built from the sources in
14
+ [`cli/`](https://github.com/diegosouzapw/awesome-omni-dsh-plugins/tree/main/cli) of this
15
+ repository, published with npm provenance attestation — so the binary you install can be traced
16
+ back to the commit and workflow run that produced it. It carries no credentials and no source
17
+ maps, and the curation engine that assembles the catalog is a separate, private system that
18
+ never ships here.
19
+
20
+ ## Requirements
21
+
22
+ - Node.js 20 or newer.
23
+ - The official `dsh` executable on `PATH` for add, update and remove operations.
24
+ - A public catalog snapshot for discovery. Version `1.0.0` defaults to catalog revision
25
+ `f01d1d2d22b80222c121db6dfc0fd4035c24b390` (160 entries); `--revision` overrides it and stays
26
+ the trust anchor, because a fetched snapshot whose declared revision differs is rejected.
27
+
28
+ ## Discover and validate
29
+
30
+ ```bash
31
+ npx omni-dsh-plugins search vision
32
+ npx omni-dsh-plugins info example-plugin
33
+ npx omni-dsh-plugins catalog validate --catalog ./awesome-omni-dsh-plugins
34
+ npx omni-dsh-plugins catalog validate \
35
+ --catalog ./awesome-omni-dsh-plugins \
36
+ --revision <40-character-commit>
37
+ npx omni-dsh-plugins catalog docs-check ./awesome-omni-dsh-plugins
38
+ npx omni-dsh-plugins catalog github-forms-check ./awesome-omni-dsh-plugins
39
+ ```
40
+
41
+ An empty catalog is valid and reports `0 entries valid; catalog is empty`. `catalog validate`
42
+ performs local structural and semantic validation: safe YAML, the public schema, SPDX, exact
43
+ SemVer, SHA-512 SRI and duplicate identity checks.
44
+ It does not prove repository identity or pinned-source evidence. Those remain a separate
45
+ maintainer provenance gate. The revision is a declared local pin because the public layout has no
46
+ signed snapshot manifest.
47
+
48
+ ## Safe installation boundary
49
+
50
+ Preview an operation without downloads, file changes or subprocesses:
51
+
52
+ ```bash
53
+ npx omni-dsh-plugins add example-plugin --profile web --dry-run
54
+ ```
55
+
56
+ Dry-run is strictly syntactic. It does not load a local or remote catalog and does not read or
57
+ write install state, profiles, cache files, locks or subprocesses. No network request is made.
58
+
59
+ The official DSH command delegates plugin management to pnpm. Package lifecycle or prepare code
60
+ may execute during that delegated step. The CLI therefore refuses mutation unless you provide
61
+ explicit consent:
62
+
63
+ ```bash
64
+ npx omni-dsh-plugins add example-plugin \
65
+ --profile web \
66
+ --allow-code-execution
67
+ npx omni-dsh-plugins update example-plugin \
68
+ --profile web \
69
+ --allow-code-execution
70
+ npx omni-dsh-plugins remove example-plugin \
71
+ --profile web \
72
+ --allow-code-execution
73
+ ```
74
+
75
+ Native Windows policy for v1.0.0: code-executing `add`, `update`, and `remove` are disabled
76
+ before any profile, state, cache, or subprocess access because complete descendant containment
77
+ cannot be proven. Use WSL for mutations. `--dry-run` and the read-only catalog, `search`, `info`,
78
+ `list`, and `doctor` commands remain available. A native Windows recovery marker is never
79
+ auto-cleared; `doctor` reports that documented manual recovery is required.
80
+
81
+ Before delegation, the CLI:
82
+
83
+ - accepts only catalog entries in `eligible` or `verified` state for installation;
84
+ - blocks unavailable, archived, stale and quarantined entries;
85
+ - requires an exact npm version with matching SHA-512 integrity, or an allowlisted GitHub source
86
+ repository with a full 40-character commit pin;
87
+ - stages content under a canonical private cache using temporary paths and atomic rename;
88
+ - rejects path traversal and symlink escapes;
89
+ - reads package metadata without loading or executing plugin code;
90
+ - snapshots the complete DSH profile and restores it if DSH returns a failure;
91
+ - serializes every profile behind one canonical DSH-home mutation lease and global fencing lock;
92
+ - stores catalog-managed install state atomically with generation and fencing-token CAS;
93
+ - records old and intended install-state fingerprints before spawn, then makes a durable
94
+ roll-forward decision only after DSH success and an active-profile fingerprint;
95
+ - invokes `dsh plugin --profile <name> ...` with a literal argument array and `shell: false`.
96
+
97
+ Add and update use a private per-transaction artifact lease and an immutable bounded loopback byte
98
+ channel. A normal or fully reaped POSIX child releases that lease only after close. If the POSIX
99
+ process group cannot be reaped, the CLI retains the profile backup, journal, private artifact and
100
+ global mutation lock; the durable pre-spawn barrier blocks every later mutation. Native Windows
101
+ code-executing mutations are disabled rather than claiming unproven descendant containment.
102
+ Explicit POSIX recovery is available with:
103
+
104
+ ```bash
105
+ npx omni-dsh-plugins recover
106
+ ```
107
+
108
+ Recovery does not load the catalog. Before durable DSH success it rolls back; after durable DSH
109
+ success it verifies the active profile and rolls the intended state forward. Profile finalization,
110
+ artifact release, and marker removal are separate idempotent phases, and the marker is removed
111
+ last. Native Windows markers remain fail-closed for documented manual recovery. `doctor` reports
112
+ the boundary and never performs recovery itself.
113
+
114
+ Add and update converge on the catalog pin and are idempotent. Removing an entry that is not
115
+ catalog-managed is also a successful no-op.
116
+
117
+ ## Inspect the local environment
118
+
119
+ ```bash
120
+ npx omni-dsh-plugins list --profile web
121
+ npx omni-dsh-plugins doctor
122
+ ```
123
+
124
+ These commands are read-only. Output never intentionally includes tokens, credentials, stack
125
+ traces or absolute DSH-home paths.
126
+
127
+ ## Security scope
128
+
129
+ A catalog listing is not an endorsement, certification or guarantee. `eligible` means structural
130
+ and integration checks passed. Only `verified` means an installation smoke test passed for the
131
+ pinned artifact. Review the original repository, commit, license and package behavior before
132
+ granting `--allow-code-execution`.
133
+
134
+ ## Pinned catalog snapshots
135
+
136
+ `--catalog` accepts a local catalog directory, a local
137
+ `omni-dsh-catalog-snapshot-v1` JSON file, or one of two allowlisted HTTPS URLs: the stable
138
+ site-hosted snapshot `https://dsh-plugins.omniroute.online/catalog.snapshot.json` (the
139
+ operational remote source) or the raw GitHub form embedding the revision in its path.
140
+ Remote snapshots require `--revision <40-character-commit-sha>` and the snapshot document must
141
+ declare exactly that SHA. Redirects, alternate hosts, traversal, symlinks, oversized inputs,
142
+ and revision mismatches are rejected before catalog validation.
143
+
144
+ ```bash
145
+ npx omni-dsh-plugins search tui \
146
+ --catalog https://dsh-plugins.omniroute.online/catalog.snapshot.json \
147
+ --revision <published-catalog-revision>
148
+ ```