obsidian-plugin-dev-kit 0.0.0-stage → 0.3.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +223 -2
- package/bin/opdk.js +34 -0
- package/dist/build/args.d.ts +10 -0
- package/dist/build/args.js +45 -0
- package/dist/build/bundle-check.d.ts +17 -0
- package/dist/build/bundle-check.js +42 -0
- package/dist/build/bundle-file.d.ts +4 -0
- package/dist/build/bundle-file.js +29 -0
- package/dist/build/commands.d.ts +5 -0
- package/dist/build/commands.js +109 -0
- package/dist/build/config.d.ts +3 -0
- package/dist/build/config.js +103 -0
- package/dist/build/css-imports.d.ts +23 -0
- package/dist/build/css-imports.js +50 -0
- package/dist/build/css-step.d.ts +10 -0
- package/dist/build/css-step.js +27 -0
- package/dist/build/css.d.ts +24 -0
- package/dist/build/css.js +47 -0
- package/dist/build/options.d.ts +55 -0
- package/dist/build/options.js +70 -0
- package/dist/build/release.d.ts +5 -0
- package/dist/build/release.js +34 -0
- package/dist/build/report.d.ts +7 -0
- package/dist/build/report.js +16 -0
- package/dist/build/vault.d.ts +26 -0
- package/dist/build/vault.js +290 -0
- package/dist/build-info.json +1 -0
- package/dist/cli/argv.d.ts +14 -0
- package/dist/cli/argv.js +18 -0
- package/dist/cli/commands.d.ts +3 -0
- package/dist/cli/commands.js +7 -0
- package/dist/cli/main.d.ts +2 -0
- package/dist/cli/main.js +23 -0
- package/dist/cli/process-reporter.d.ts +5 -0
- package/dist/cli/process-reporter.js +15 -0
- package/dist/cli/registry.d.ts +4 -0
- package/dist/cli/registry.js +15 -0
- package/dist/cli/reporter.d.ts +53 -0
- package/dist/cli/reporter.js +100 -0
- package/dist/cli/run.d.ts +9 -0
- package/dist/cli/run.js +61 -0
- package/dist/cli/types.d.ts +27 -0
- package/dist/cli/types.js +1 -0
- package/dist/cli/version.d.ts +13 -0
- package/dist/cli/version.js +61 -0
- package/dist/config/define-config.d.ts +3 -0
- package/dist/config/define-config.js +4 -0
- package/dist/config/load-config.d.ts +6 -0
- package/dist/config/load-config.js +70 -0
- package/dist/config/manifest.d.ts +3 -0
- package/dist/config/manifest.js +72 -0
- package/dist/config/types.d.ts +146 -0
- package/dist/config/types.js +23 -0
- package/dist/demo/args.d.ts +4 -0
- package/dist/demo/args.js +13 -0
- package/dist/demo/checks.d.ts +56 -0
- package/dist/demo/checks.js +124 -0
- package/dist/demo/commands.d.ts +3 -0
- package/dist/demo/commands.js +65 -0
- package/dist/demo/config.d.ts +57 -0
- package/dist/demo/config.js +337 -0
- package/dist/demo/ffmpeg-run.d.ts +18 -0
- package/dist/demo/ffmpeg-run.js +59 -0
- package/dist/demo/ffmpeg.d.ts +63 -0
- package/dist/demo/ffmpeg.js +111 -0
- package/dist/demo/films.d.ts +46 -0
- package/dist/demo/films.js +134 -0
- package/dist/demo/phone-layout.d.ts +38 -0
- package/dist/demo/phone-layout.js +98 -0
- package/dist/demo/phone-render.d.ts +28 -0
- package/dist/demo/phone-render.js +124 -0
- package/dist/demo/published.d.ts +16 -0
- package/dist/demo/published.js +72 -0
- package/dist/demo/run.d.ts +31 -0
- package/dist/demo/run.js +397 -0
- package/dist/demo/stills.d.ts +21 -0
- package/dist/demo/stills.js +62 -0
- package/dist/e2e/artifacts.d.ts +27 -0
- package/dist/e2e/artifacts.js +90 -0
- package/dist/e2e/cleanup.d.ts +54 -0
- package/dist/e2e/cleanup.js +109 -0
- package/dist/e2e/config.d.ts +9 -0
- package/dist/e2e/config.js +42 -0
- package/dist/e2e/create-test.d.ts +37 -0
- package/dist/e2e/create-test.js +109 -0
- package/dist/e2e/demo/clip.d.ts +21 -0
- package/dist/e2e/demo/clip.js +44 -0
- package/dist/e2e/demo/create-demo.d.ts +42 -0
- package/dist/e2e/demo/create-demo.js +439 -0
- package/dist/e2e/demo/manifest.d.ts +76 -0
- package/dist/e2e/demo/manifest.js +168 -0
- package/dist/e2e/demo/names.d.ts +18 -0
- package/dist/e2e/demo/names.js +44 -0
- package/dist/e2e/demo/options.d.ts +22 -0
- package/dist/e2e/demo/options.js +59 -0
- package/dist/e2e/demo/ownership.d.ts +27 -0
- package/dist/e2e/demo/ownership.js +65 -0
- package/dist/e2e/demo/page-scripts.d.ts +82 -0
- package/dist/e2e/demo/page-scripts.js +250 -0
- package/dist/e2e/demo/png.d.ts +8 -0
- package/dist/e2e/demo/png.js +23 -0
- package/dist/e2e/demo/presets.d.ts +43 -0
- package/dist/e2e/demo/presets.js +20 -0
- package/dist/e2e/demo/privacy.d.ts +18 -0
- package/dist/e2e/demo/privacy.js +30 -0
- package/dist/e2e/demo/still-options.d.ts +22 -0
- package/dist/e2e/demo/still-options.js +68 -0
- package/dist/e2e/demo/types.d.ts +184 -0
- package/dist/e2e/demo/types.js +1 -0
- package/dist/e2e/electron-binary.d.ts +15 -0
- package/dist/e2e/electron-binary.js +30 -0
- package/dist/e2e/fixtures.d.ts +62 -0
- package/dist/e2e/fixtures.js +68 -0
- package/dist/e2e/gate.d.ts +4 -0
- package/dist/e2e/gate.js +8 -0
- package/dist/e2e/global-setup.d.ts +11 -0
- package/dist/e2e/global-setup.js +17 -0
- package/dist/e2e/helpers/commands.d.ts +14 -0
- package/dist/e2e/helpers/commands.js +56 -0
- package/dist/e2e/helpers/create-helpers.d.ts +24 -0
- package/dist/e2e/helpers/create-helpers.js +582 -0
- package/dist/e2e/helpers/device-metrics.d.ts +21 -0
- package/dist/e2e/helpers/device-metrics.js +25 -0
- package/dist/e2e/helpers/ime.d.ts +13 -0
- package/dist/e2e/helpers/ime.js +19 -0
- package/dist/e2e/helpers/layout-page-scripts.d.ts +103 -0
- package/dist/e2e/helpers/layout-page-scripts.js +224 -0
- package/dist/e2e/helpers/layout.d.ts +83 -0
- package/dist/e2e/helpers/layout.js +148 -0
- package/dist/e2e/helpers/mobile.d.ts +31 -0
- package/dist/e2e/helpers/mobile.js +26 -0
- package/dist/e2e/helpers/page-scripts.d.ts +194 -0
- package/dist/e2e/helpers/page-scripts.js +467 -0
- package/dist/e2e/helpers/settings.d.ts +8 -0
- package/dist/e2e/helpers/settings.js +16 -0
- package/dist/e2e/helpers/settle.d.ts +28 -0
- package/dist/e2e/helpers/settle.js +33 -0
- package/dist/e2e/helpers/types.d.ts +193 -0
- package/dist/e2e/helpers/types.js +1 -0
- package/dist/e2e/helpers/view-mode.d.ts +23 -0
- package/dist/e2e/helpers/view-mode.js +35 -0
- package/dist/e2e/index.d.ts +14 -0
- package/dist/e2e/index.js +4 -0
- package/dist/e2e/internals.d.ts +155 -0
- package/dist/e2e/internals.js +8 -0
- package/dist/e2e/obsidian-path.d.ts +17 -0
- package/dist/e2e/obsidian-path.js +31 -0
- package/dist/e2e/options.d.ts +123 -0
- package/dist/e2e/options.js +244 -0
- package/dist/e2e/page-scripts.d.ts +45 -0
- package/dist/e2e/page-scripts.js +53 -0
- package/dist/e2e/peers.d.ts +9 -0
- package/dist/e2e/peers.js +19 -0
- package/dist/e2e/plugins.d.ts +32 -0
- package/dist/e2e/plugins.js +119 -0
- package/dist/e2e/process-tree.d.ts +33 -0
- package/dist/e2e/process-tree.js +133 -0
- package/dist/e2e/readiness.d.ts +23 -0
- package/dist/e2e/readiness.js +63 -0
- package/dist/e2e/seed.d.ts +34 -0
- package/dist/e2e/seed.js +122 -0
- package/dist/e2e/session.d.ts +71 -0
- package/dist/e2e/session.js +266 -0
- package/dist/e2e/vault.d.ts +52 -0
- package/dist/e2e/vault.js +146 -0
- package/dist/e2e/version.d.ts +25 -0
- package/dist/e2e/version.js +40 -0
- package/dist/eslint/index.d.ts +2 -0
- package/dist/eslint/index.js +1 -0
- package/dist/eslint/obsidian-plugin.d.ts +49 -0
- package/dist/eslint/obsidian-plugin.js +115 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.js +1 -0
- package/dist/kit/args.d.ts +7 -0
- package/dist/kit/args.js +21 -0
- package/dist/kit/commands.d.ts +3 -0
- package/dist/kit/commands.js +52 -0
- package/dist/kit/files.d.ts +3 -0
- package/dist/kit/files.js +24 -0
- package/dist/kit/pins.d.ts +89 -0
- package/dist/kit/pins.js +178 -0
- package/dist/kit/remote.d.ts +13 -0
- package/dist/kit/remote.js +33 -0
- package/dist/kit/runners.d.ts +11 -0
- package/dist/kit/runners.js +53 -0
- package/dist/kit/terminal-text.d.ts +6 -0
- package/dist/kit/terminal-text.js +20 -0
- package/dist/kit/upgrade.d.ts +26 -0
- package/dist/kit/upgrade.js +162 -0
- package/dist/peers/resolve.d.ts +8 -0
- package/dist/peers/resolve.js +28 -0
- package/dist/peers/versions.d.ts +30 -0
- package/dist/peers/versions.js +32 -0
- package/dist/release/api-check.d.ts +27 -0
- package/dist/release/api-check.js +119 -0
- package/dist/release/args.d.ts +40 -0
- package/dist/release/args.js +120 -0
- package/dist/release/assets.d.ts +21 -0
- package/dist/release/assets.js +35 -0
- package/dist/release/build-check.d.ts +43 -0
- package/dist/release/build-check.js +184 -0
- package/dist/release/build-script.d.ts +12 -0
- package/dist/release/build-script.js +30 -0
- package/dist/release/build-tagged.d.ts +26 -0
- package/dist/release/build-tagged.js +52 -0
- package/dist/release/bump.d.ts +24 -0
- package/dist/release/bump.js +58 -0
- package/dist/release/changelog.d.ts +25 -0
- package/dist/release/changelog.js +148 -0
- package/dist/release/check.d.ts +38 -0
- package/dist/release/check.js +150 -0
- package/dist/release/commands.d.ts +3 -0
- package/dist/release/commands.js +154 -0
- package/dist/release/committed-tree.d.ts +63 -0
- package/dist/release/committed-tree.js +118 -0
- package/dist/release/config.d.ts +3 -0
- package/dist/release/config.js +28 -0
- package/dist/release/gh-access.d.ts +14 -0
- package/dist/release/gh-access.js +45 -0
- package/dist/release/gh.d.ts +10 -0
- package/dist/release/gh.js +33 -0
- package/dist/release/git.d.ts +49 -0
- package/dist/release/git.js +111 -0
- package/dist/release/interrupt.d.ts +30 -0
- package/dist/release/interrupt.js +60 -0
- package/dist/release/json.d.ts +33 -0
- package/dist/release/json.js +81 -0
- package/dist/release/kit-check.d.ts +8 -0
- package/dist/release/kit-check.js +51 -0
- package/dist/release/manifest-rules.d.ts +23 -0
- package/dist/release/manifest-rules.js +255 -0
- package/dist/release/preflight.d.ts +10 -0
- package/dist/release/preflight.js +65 -0
- package/dist/release/problems.d.ts +24 -0
- package/dist/release/problems.js +11 -0
- package/dist/release/project-files.d.ts +14 -0
- package/dist/release/project-files.js +16 -0
- package/dist/release/publish-command.d.ts +21 -0
- package/dist/release/publish-command.js +83 -0
- package/dist/release/publish-git.d.ts +37 -0
- package/dist/release/publish-git.js +108 -0
- package/dist/release/publish-state.d.ts +29 -0
- package/dist/release/publish-state.js +70 -0
- package/dist/release/publish-verify.d.ts +41 -0
- package/dist/release/publish-verify.js +112 -0
- package/dist/release/publish-wait.d.ts +25 -0
- package/dist/release/publish-wait.js +56 -0
- package/dist/release/publish.d.ts +35 -0
- package/dist/release/publish.js +181 -0
- package/dist/release/release-assets.d.ts +39 -0
- package/dist/release/release-assets.js +68 -0
- package/dist/release/release.d.ts +37 -0
- package/dist/release/release.js +179 -0
- package/dist/release/remote.d.ts +12 -0
- package/dist/release/remote.js +15 -0
- package/dist/release/reproducible.d.ts +16 -0
- package/dist/release/reproducible.js +34 -0
- package/dist/release/run-tests.d.ts +5 -0
- package/dist/release/run-tests.js +17 -0
- package/dist/release/semver.d.ts +8 -0
- package/dist/release/semver.js +60 -0
- package/dist/release/version-rules.d.ts +28 -0
- package/dist/release/version-rules.js +63 -0
- package/dist/release/versions-json.d.ts +15 -0
- package/dist/release/versions-json.js +88 -0
- package/dist/release/workflow-run.d.ts +44 -0
- package/dist/release/workflow-run.js +71 -0
- package/dist/scanner/code-checks.d.ts +41 -0
- package/dist/scanner/code-checks.js +82 -0
- package/dist/scanner/commands.d.ts +3 -0
- package/dist/scanner/commands.js +43 -0
- package/dist/scanner/config.d.ts +7 -0
- package/dist/scanner/config.js +25 -0
- package/dist/scanner/css-check.d.ts +26 -0
- package/dist/scanner/css-check.js +63 -0
- package/dist/scanner/eslint-nesting.d.ts +16 -0
- package/dist/scanner/eslint-nesting.js +45 -0
- package/dist/scanner/findings.d.ts +23 -0
- package/dist/scanner/findings.js +21 -0
- package/dist/scanner/git-files.d.ts +16 -0
- package/dist/scanner/git-files.js +73 -0
- package/dist/scanner/lint.d.ts +47 -0
- package/dist/scanner/lint.js +163 -0
- package/dist/scanner/meta-checks.d.ts +8 -0
- package/dist/scanner/meta-checks.js +22 -0
- package/dist/scanner/outside-project.d.ts +19 -0
- package/dist/scanner/outside-project.js +20 -0
- package/dist/scanner/run.d.ts +19 -0
- package/dist/scanner/run.js +78 -0
- package/dist/scanner/scanner-config.d.ts +114 -0
- package/dist/scanner/scanner-config.js +207 -0
- package/dist/scanner/typescript-gate.d.ts +30 -0
- package/dist/scanner/typescript-gate.js +73 -0
- package/dist/vitest/build-config.d.ts +17 -0
- package/dist/vitest/build-config.js +106 -0
- package/dist/vitest/define-unit-config.d.ts +27 -0
- package/dist/vitest/define-unit-config.js +45 -0
- package/dist/vitest/dom/elements.d.ts +87 -0
- package/dist/vitest/dom/elements.js +291 -0
- package/dist/vitest/dom/index.d.ts +1 -0
- package/dist/vitest/dom/index.js +1 -0
- package/dist/vitest/dom/install.d.ts +8 -0
- package/dist/vitest/dom/install.js +261 -0
- package/dist/vitest/dom/setup.d.ts +1 -0
- package/dist/vitest/dom/setup.js +3 -0
- package/dist/vitest/index.d.ts +3 -0
- package/dist/vitest/index.js +2 -0
- package/dist/vitest/options.d.ts +92 -0
- package/dist/vitest/options.js +136 -0
- package/dist/vitest/peers.d.ts +10 -0
- package/dist/vitest/peers.js +51 -0
- package/dist/vitest/workspace-root.d.ts +7 -0
- package/dist/vitest/workspace-root.js +39 -0
- package/docs/build.md +232 -0
- package/docs/ci.md +182 -0
- package/docs/demo.md +364 -0
- package/docs/e2e.md +563 -0
- package/docs/release.md +374 -0
- package/docs/scanner.md +204 -0
- package/docs/unit.md +291 -0
- package/package.json +100 -4
- package/plugins/opdk/skills/audit/SKILL.md +81 -0
- package/plugins/opdk/skills/build/SKILL.md +79 -0
- package/plugins/opdk/skills/demo/SKILL.md +102 -0
- package/plugins/opdk/skills/e2e/SKILL.md +132 -0
- package/plugins/opdk/skills/release/SKILL.md +84 -0
- package/plugins/opdk/skills/scanner/SKILL.md +60 -0
- package/plugins/opdk/skills/unit/SKILL.md +90 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Dmitriy Yurkin
|
|
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
CHANGED
|
@@ -1,3 +1,224 @@
|
|
|
1
|
-
#
|
|
1
|
+
# obsidian-plugin-dev-kit
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/obsidian-plugin-dev-kit) [](https://github.com/Dimagious/obsidian-plugin-dev-kit/actions/workflows/ci.yml) [](LICENSE)
|
|
4
|
+
|
|
5
|
+
Build, lint, release, test and film [Obsidian](https://obsidian.md/) plugins from one dev dependency.
|
|
6
|
+
|
|
7
|
+
> **Status: released. It installs from npm or by git tag (see [Install](#install)); the newest `vX.Y.Z` tag is the current release.** The code was moved here from three plugins that each kept their own copy: [Snipsy](https://github.com/Dimagious/snipsidian), [Dashy](https://github.com/Dimagious/dashsidian) and [Garmy](https://github.com/Dimagious/garmidian). The roadmap below shows what is done and what is planned.
|
|
8
|
+
|
|
9
|
+
## Why
|
|
10
|
+
|
|
11
|
+
Every Obsidian plugin needs the same tooling around its code: a bundle that also runs on phones, a lint setup that matches the community plugin scanner, a release workflow, end-to-end tests in a real Obsidian, and a demo GIF for the README. Copying it between plugins works until the copies drift. In the three plugins above, a fix for the mobile build reached two of them and not the third. This kit keeps that tooling in one place and versions it.
|
|
12
|
+
|
|
13
|
+
## What it includes
|
|
14
|
+
|
|
15
|
+
| Module | What it does |
|
|
16
|
+
|---|---|
|
|
17
|
+
| Build | esbuild for the browser platform, so the bundle works on mobile, plus a check that fails if Node-only code gets into `main.js`; CSS build; copy into a dev vault in watch mode |
|
|
18
|
+
| Scanner and lint | `opdk scan` runs the community plugin scanner's ESLint configuration and its CSS, source and manifest checks before you release, with `eslint-plugin-obsidianmd` pinned in one place; `obsidianPlugin()` gives your own `eslint.config.mjs` the same base |
|
|
19
|
+
| Release | `opdk release check` for CI and before a tag: versions in `package.json`, `manifest.json`, `package-lock.json` and `versions.json`, the manifest rules of the official Obsidian action, a CHANGELOG section, one kit release in `package.json`, the lockfile and the workflow pins, a production build built twice (working tree and committed tree) and compared, and the `minAppVersion` against the API the code calls. `opdk release patch` (or `minor`, `major`, `X.Y.Z`) refuses commits that `origin` has not seen, runs the plugin's `npm test`, bumps the files, moves the `[Unreleased]` notes under the new version, commits and tags, pushes only the tag, waits for the kit's reusable GitHub workflow, verifies its draft release (files, bytes against a local build of the tag, notes, build provenance), publishes it and only then pushes the branch. Release notes come from the CHANGELOG, and no zip is made unless asked |
|
|
20
|
+
| Reusable CI | `plugin-ci.yml`, a reusable GitHub workflow: lint, typecheck, tests, `opdk scan`, `opdk release check`, build and bundle upload, with a read-only token, actions pinned to commit SHAs and a pinned runner |
|
|
21
|
+
| Unit tests | `defineUnitConfig()`, a Vitest config with v8 coverage and a 90/80 gate, an `obsidian` alias, and a split that runs only the files that need a DOM in jsdom; plus the DOM helpers Obsidian adds (`createEl`, `createDiv`, `setText`, `addClass`, `activeDocument` and more) for jsdom |
|
|
22
|
+
| End-to-end tests | Playwright in a real Obsidian through Electron: an isolated vault per test, the trust dialog never shown, readiness by plugin state instead of sleeps, a check of which Obsidian version ran, a trace and a video of the Obsidian window for failures, and helpers for settings, commands, the editor, IME composition, the mobile layout and fakes. Launch over CDP and a mode for recording tests by hand with the Playwright Inspector are planned |
|
|
23
|
+
| Demo films | Films of stills from the real Obsidian: a frozen UI, a visible cursor or tap dot, captions, slow typing, light and dark themes, and a privacy guard that refuses to film a vault that is not the plugin's own; `opdk demo` encodes them to MP4, GIF and poster with ffmpeg, can put a phone film beside its captions, and copies stills (shot at a fixed density) for the README and listings. No audio |
|
|
24
|
+
| Agent skills | One Claude Code skill per module, so a coding agent working in your plugin knows how to use the kit |
|
|
25
|
+
|
|
26
|
+
Your plugin keeps only what is its own: specs, the seed vault and demo scenes.
|
|
27
|
+
|
|
28
|
+
## Install
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
npm install -D -E obsidian-plugin-dev-kit
|
|
32
|
+
npx opdk --help
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
From v0.3.2 the kit is on npm (`-E` pins the exact version). Versions from 0.3.3 on are published by a GitHub workflow and carry npm provenance; 0.3.2 was published by hand. A git tag works too: `npm install -D "github:Dimagious/obsidian-plugin-dev-kit#v0.3.3"`. `opdk kit upgrade` (below) moves only a git-tag install for now. With npm, run `npm install -D -E obsidian-plugin-dev-kit@X.Y.Z`, then in each `uses:` line of the kit's workflows set the commit of that tag (`git ls-remote https://github.com/Dimagious/obsidian-plugin-dev-kit 'refs/tags/vX.Y.Z^{}'`; the tags are annotated, and without `^{}` it prints the tag object) and the comment `# vX.Y.Z`. `opdk release check` compares the comments with the installed version; it cannot check the commit of an npm install, so update the two together.
|
|
36
|
+
|
|
37
|
+
Install size, measured on 2026-11-16: the package is 396 KB packed and 1.3 MB unpacked. In an empty project it brings about 100 MB with its required dependencies, mostly TypeScript, esbuild and the ESLint stack a plugin usually has already. Electron, Playwright, Vitest, `@vitest/coverage-v8` and jsdom are not dependencies of the kit at all: the plugin installs them for end-to-end tests, demo films and unit tests, and the kit checks their versions when it runs and fails with the install command. ESLint and TypeScript 6 are the only peer dependencies; `opdk scan` fails on an older TypeScript, because the community scanner type-checks with 6.
|
|
38
|
+
|
|
39
|
+
## Build
|
|
40
|
+
|
|
41
|
+
`opdk build` builds your plugin's CSS, bundles it with esbuild for the browser platform, and then checks `main.js` for code that only exists under Node. A plugin whose build passed `--platform=node` failed on every phone: esbuild took the `node` branch of the `yaml` package and bundled code that reads `process.env`. Desktop Obsidian has `process`, so only mobile showed it. The platform is fixed here, and the check fails the build if Node-only code gets in anyway.
|
|
42
|
+
|
|
43
|
+

|
|
44
|
+
|
|
45
|
+
When Node-only code gets into the bundle, the build fails:
|
|
46
|
+
|
|
47
|
+

|
|
48
|
+
|
|
49
|
+
Quick start: `npx opdk build`. Details: [docs/build.md](docs/build.md).
|
|
50
|
+
|
|
51
|
+
## Scanner
|
|
52
|
+
|
|
53
|
+
`opdk scan` runs the community plugin scanner's own ESLint configuration (published upstream), a CSS check and a few source checks that reproduce findings seen on plugin listings, over the files git tracks. It fails when a step has a finding; the scanner's ESLint warnings count as findings, advisory `!` lines do not. It type-checks with the plugin's TypeScript, which must be 6, as the scanner's is, and reads every tracked stylesheet; there is no way to ignore a file the scorecard shows. A plugin lost three points of its public score to a joined domain string that no local check saw; this catches that kind of thing before the tag.
|
|
54
|
+
|
|
55
|
+

|
|
56
|
+
|
|
57
|
+
Quick start: `npx opdk scan`. Details: [docs/scanner.md](docs/scanner.md).
|
|
58
|
+
|
|
59
|
+
## End-to-end tests
|
|
60
|
+
|
|
61
|
+
`obsidian-plugin-dev-kit/e2e` runs Playwright specs in the real Obsidian: every test gets its own Obsidian process, a copy of your seed vault and a fresh user-data folder, with your built plugin installed and trusted before the window opens. Obsidian 1.13 moved Settings into a second window and took down five specs of one plugin at once, and harnesses that pressed Escape on the trust dialog and slept to let plugins load raced a slow start. The kit keeps Settings in the main window, sets the trust flag before the vault loads and waits for every plugin's `onload()` to finish, and a failed test leaves a trace and a video of the Obsidian window.
|
|
62
|
+
|
|
63
|
+

|
|
64
|
+
|
|
65
|
+
Quick start: `createObsidianTest({ seedVault })` in `e2e/fixtures.ts`, `defineObsidianConfig()` in `playwright.config.ts`, then `npx playwright test`. Beyond the basics: `test.use({ seed })` puts notes and settings into one test's vault, `obsidian.checkLayout()` lists overflow, small touch targets and missing focus rings, and `AppWithInternals` types Obsidian's internal `app`. Details: [docs/e2e.md](docs/e2e.md).
|
|
66
|
+
|
|
67
|
+
## Demo films
|
|
68
|
+
|
|
69
|
+
The `demo` fixture records your plugin in the real Obsidian as a film of stills: each shot freezes the UI and takes a sharp picture at 2x, with a hold and a caption, and `opdk demo` turns the film into an MP4, a GIF and a poster. Recording the Obsidian window as video caught every stutter of the machine, and the script that finished the job needed Python; a retake that appended frames to the old film made a longer film, and a reel script that only warned when ffmpeg failed let a run that made no GIF end green. Here the timing is the script's, a retake replaces the frames, a failed encode fails the film, and a film of a vault that is not the plugin's own is refused.
|
|
70
|
+
|
|
71
|
+

|
|
72
|
+
|
|
73
|
+
Quick start: `demo.film({ kind: "phone", captions })` and `film.shot({ hold })` in a gated spec, then `npx opdk demo`. For captions beside the phone, set `layout: "phone-captions"` in the `demo` section of `opdk.config.mjs`. A still can go to its own folder (`demo.still(name, { out: "listing" })` with `demo.outputs`) or stay out of the output (`{ publish: false }`). Details: [docs/demo.md](docs/demo.md).
|
|
74
|
+
|
|
75
|
+
## Releases
|
|
76
|
+
|
|
77
|
+
`opdk release` checks a commit, bumps the version everywhere, tags it and publishes the GitHub release, pushing the branch last so the manifest on the default branch moves only after the release is public. Pushing the branch and the tag together lets the directory read a new `manifest.json` before the release workflow had finished, and a hand-written CHANGELOG never reached the release page. Here only the tag is pushed first, the kit's reusable workflow builds, attests and creates a draft with the CHANGELOG section as notes, and `opdk release` checks the draft byte for byte against a build of the tag on your machine before it publishes. The incidents behind this, in [docs/release.md](docs/release.md).
|
|
78
|
+
|
|
79
|
+
Quick start: a tag workflow in the plugin that calls the kit's, pinned to a full commit SHA of the kit,
|
|
80
|
+
|
|
81
|
+
```yaml
|
|
82
|
+
# .github/workflows/release.yml
|
|
83
|
+
name: Release
|
|
84
|
+
on:
|
|
85
|
+
push:
|
|
86
|
+
tags: ['*.*.*']
|
|
87
|
+
permissions:
|
|
88
|
+
contents: write
|
|
89
|
+
id-token: write
|
|
90
|
+
attestations: write
|
|
91
|
+
jobs:
|
|
92
|
+
release:
|
|
93
|
+
uses: Dimagious/obsidian-plugin-dev-kit/.github/workflows/release.yml@<full commit SHA of the kit>
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
then `npx opdk release check` to see what would stop a release, and `npx opdk release patch` to cut one (it needs the GitHub CLI signed in with write access, and `scripts.build` must run `opdk build`). Details, every stop and how to resume: [docs/release.md](docs/release.md).
|
|
97
|
+
|
|
98
|
+
## Continuous integration
|
|
99
|
+
|
|
100
|
+
`.github/workflows/plugin-ci.yml` is a reusable workflow that checks a plugin on every push and pull request: lint, typecheck, unit tests, `opdk scan`, `opdk release check`, the build, and an upload of the bundle as `<plugin id>-bundle`. Three plugins each kept a hand-written `ci.yml` of 45 to 75 lines, and they had drifted (one never ran its lint script). Here the job has a read-only token, every action is pinned to a commit SHA, the runner is pinned to `ubuntu-24.04` instead of `ubuntu-latest`, and the inputs are switches, never commands. Steps that belong to one plugin stay in a second job of its own `ci.yml`.
|
|
101
|
+
|
|
102
|
+
Quick start: call it from the plugin's `ci.yml`, pinned to a full commit SHA of the kit,
|
|
103
|
+
|
|
104
|
+
```yaml
|
|
105
|
+
# .github/workflows/ci.yml
|
|
106
|
+
name: ci
|
|
107
|
+
on:
|
|
108
|
+
push:
|
|
109
|
+
branches: [main]
|
|
110
|
+
pull_request:
|
|
111
|
+
permissions:
|
|
112
|
+
contents: read
|
|
113
|
+
jobs:
|
|
114
|
+
kit:
|
|
115
|
+
uses: Dimagious/obsidian-plugin-dev-kit/.github/workflows/plugin-ci.yml@<full commit SHA of the kit>
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
If your default branch is not `main`, use its name in `branches`. Inputs (all optional): `node-version`, `runs-on`, and a boolean per step (`lint`, `typecheck`, `test`, `scan`, `release-check`, `build`, `upload-bundle`, `coverage-artifact`). Inputs, what each step runs, how to add plugin-specific steps and how to move an existing `ci.yml`: [docs/ci.md](docs/ci.md).
|
|
119
|
+
|
|
120
|
+
## Updating the kit
|
|
121
|
+
|
|
122
|
+
A plugin pins the kit in three places: the tag in `package.json`, the commit in the lockfile, and the commit in each `uses:` line of the kit's workflows. They have to name one release, and `opdk release check` (so CI) fails when they do not. `opdk kit upgrade` moves them together:
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
npx opdk kit upgrade --dry-run # what would change, and the kit's CHANGELOG since your version
|
|
126
|
+
npx opdk kit upgrade # latest release; or: npx opdk kit upgrade v0.3.3
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
On v0.1.0, which has no `kit` command, run it once as `npx -y -p github:Dimagious/obsidian-plugin-dev-kit#v0.3.3 opdk kit upgrade v0.3.3`. It needs a clean git tree, never commits or pushes, and puts `package.json` and the lockfile back if `npm install` fails (run `npm ci` if `node_modules` looks off). Review the diff and open a pull request. Configure Dependabot to ignore the kit (a lone bump of one pin breaks the check; the `ignore` entries are in the docs) and watch the kit's releases on GitHub. Details: [docs/ci.md](docs/ci.md#updating-the-kit).
|
|
130
|
+
|
|
131
|
+
## Unit tests
|
|
132
|
+
|
|
133
|
+
`defineUnitConfig()` from `obsidian-plugin-dev-kit/vitest` is a Vitest config for Obsidian plugins: tests in `src/**/*.test.ts`, v8 coverage with a gate of 90 percent (80 for branches), an `obsidian` alias, and a list of the test files that need a DOM. Those files run in jsdom with Obsidian's DOM helpers (`createDiv`, `setText`, `addClass`, `activeDocument` and the rest) installed; every other file runs in node. Without a shared config, the same `vitest.config.ts` gets copied between plugins and drifts. Hand-written copies of the DOM helpers drift from the app too: a fragment passed to `setText` became a string, where Obsidian appends it. Booting jsdom for every test file is slow: on a plugin with 3,271 tests in 85 files, 32 of which need a DOM, the run went from 30 s to 15 s. `coverage.include` is required, because Vitest 4 and later leave out files no test imports, and an untested file would escape the gate.
|
|
134
|
+
|
|
135
|
+
Quick start: a `vitest.config.ts` with the `vitest`, `@vitest/coverage-v8`, `jsdom` and `vite@^8` dev dependencies,
|
|
136
|
+
|
|
137
|
+
```ts
|
|
138
|
+
import { defineUnitConfig } from "obsidian-plugin-dev-kit/vitest";
|
|
139
|
+
|
|
140
|
+
export default defineUnitConfig({
|
|
141
|
+
rootDir: import.meta.dirname,
|
|
142
|
+
obsidian: "./src/test/stubs/obsidian.ts",
|
|
143
|
+
dom: ["src/ui/**/*.test.ts"],
|
|
144
|
+
coverage: { include: ["src/**/*.ts"], exclude: ["src/main.ts"] },
|
|
145
|
+
});
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
then `npx vitest run --coverage`. Options, finding the files that need a DOM, the helper list and migration notes: [docs/unit.md](docs/unit.md).
|
|
149
|
+
|
|
150
|
+
## Agent skills
|
|
151
|
+
|
|
152
|
+
The repository is also a Claude Code plugin, `opdk`, with one skill per module so a coding agent working in your plugin knows the commands, the options and the traps of that module, plus `/opdk:audit` for a plugin that is already on the kit:
|
|
153
|
+
|
|
154
|
+
| Skill | Use it for |
|
|
155
|
+
| --- | --- |
|
|
156
|
+
| `/opdk:build` | `opdk build`, `opdk build-css`, `opdk assert-bundle`, `opdk build --vault`, mobile-only bundle failures |
|
|
157
|
+
| `/opdk:scanner` | `opdk scan`, community plugin scorecard warnings, `obsidianPlugin()` in `eslint.config.mjs` |
|
|
158
|
+
| `/opdk:e2e` | Playwright specs in the real Obsidian, readiness and timeout failures, helpers |
|
|
159
|
+
| `/opdk:demo` | demo films, GIFs, MP4s, posters and README screenshots, `opdk demo` messages |
|
|
160
|
+
| `/opdk:unit` | `defineUnitConfig()`, coverage gate failures, `createDiv is not defined`, the DOM helpers for jsdom, moving a plugin's Vitest config |
|
|
161
|
+
| `/opdk:release` | `opdk release check`, cutting and publishing a release, a stopped release, the reusable release workflow |
|
|
162
|
+
| `/opdk:audit` | a plugin already on the kit: what it still does by hand, pictures nothing can retake, code outside the coverage gate, tests that pass only in parallel, gaps in the kit; reads and measures first, changes only what you pick |
|
|
163
|
+
|
|
164
|
+
Claude picks a skill by its description, so you can also just ask ("film a demo GIF of my plugin"). Install from inside Claude Code:
|
|
165
|
+
|
|
166
|
+
```text
|
|
167
|
+
/plugin marketplace add Dimagious/obsidian-plugin-dev-kit
|
|
168
|
+
/plugin install opdk@obsidian-plugin-dev-kit
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
The plugin version follows the kit version, and installed copies update when it changes (`/plugin marketplace update obsidian-plugin-dev-kit`, then update the plugin). A fresh install takes `main` as it is then, which can be ahead of the latest tag. The plugin files live in `plugins/opdk/`. A copy of the skills matching the kit version you installed is in `node_modules/obsidian-plugin-dev-kit/plugins/opdk/skills/`; Claude Code loads them only through the plugin.
|
|
172
|
+
|
|
173
|
+
## Roadmap
|
|
174
|
+
|
|
175
|
+
- [ ] Wave 1: build, scanner and lint, end-to-end harness, demo films
|
|
176
|
+
- [x] Build: `opdk build`, `opdk build-css`, `opdk assert-bundle`, dev-vault watch
|
|
177
|
+
- [x] Scanner and lint: `opdk scan`, `obsidianPlugin()`
|
|
178
|
+
- [ ] End-to-end harness: launch, isolation, readiness, trace and video, and the helpers are done; CDP mode is pending
|
|
179
|
+
- [x] Demo films: films of stills, phone layout, stills presets, `opdk demo` (no audio)
|
|
180
|
+
- [x] Wave 2: release, unit-test preset and reusable CI
|
|
181
|
+
- [x] Release: `opdk release check`, `opdk release <bump>`, `opdk release publish`, `opdk release notes`, the reusable `release.yml`
|
|
182
|
+
- [x] Unit-test preset: `defineUnitConfig()`, the DOM helpers for jsdom
|
|
183
|
+
- [x] Reusable CI: `plugin-ci.yml`
|
|
184
|
+
- Wave 3, an integration tests preset, is not planned: only one of the three plugins runs integration tests, and it keeps its own setup
|
|
185
|
+
- [ ] Wave 4: CDP launch mode, if a plugin needs the shipped Obsidian binary
|
|
186
|
+
- [x] Agent skills for build, scanner, e2e, demo, release and unit, installable as a Claude Code plugin
|
|
187
|
+
- [x] An audit skill for plugins already on the kit
|
|
188
|
+
- [ ] Agent skills for the modules that are still to come, written along with them
|
|
189
|
+
|
|
190
|
+
## Development
|
|
191
|
+
|
|
192
|
+
Requires Node 22.13 or newer, or Node 24 or newer.
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
npm ci
|
|
196
|
+
npm run typecheck # tsc over src, bin, tests and config files
|
|
197
|
+
npm run lint # eslint, zero warnings allowed
|
|
198
|
+
npm test # vitest with coverage thresholds (90% lines, functions and statements, 80% branches)
|
|
199
|
+
npm run build # cleans dist/ and compiles src/ with tsc
|
|
200
|
+
npm run smoke # builds, packs, installs the tarball into a temp project, runs opdk --help, --version, `opdk build` and `opdk scan` on a fixture, imports defineConfig and `obsidian-plugin-dev-kit/eslint`
|
|
201
|
+
npm run docs:media # re-records the GIFs in docs/media with VHS (needs `vhs` and `ffmpeg`); run `npm run build` first
|
|
202
|
+
npm run docs:media:e2e # re-records docs/media/e2e.gif from a real Obsidian window (needs Obsidian and `ffmpeg`)
|
|
203
|
+
npm run docs:media:demo # re-records docs/media/demo.gif: the docs-film spec in a real Obsidian, then `opdk demo` (needs Obsidian and `ffmpeg`; run `npm run build` first)
|
|
204
|
+
npm run e2e:smoke # the kit's own e2e specs against a real Obsidian; by hand before a release, not in CI
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
`dist/` is not committed. `npm install` from a git tag runs `prepare`, which builds it, so a broken build breaks every plugin install. CI runs the same checks plus the smoke on every pull request.
|
|
208
|
+
|
|
209
|
+
Releasing: bump `version` in `package.json`, move the `[Unreleased]` entries in `CHANGELOG.md` under the new version, merge, then the owner tags `vX.Y.Z` and pushes the tag. A workflow fails the tag if it differs from `package.json`, and another publishes that version to npm with provenance. Plugins pin the version, for example `obsidian-plugin-dev-kit@0.3.3` from npm or `github:Dimagious/obsidian-plugin-dev-kit#v0.3.3`.
|
|
210
|
+
|
|
211
|
+
## Credits
|
|
212
|
+
|
|
213
|
+
The kit's code is moved from the owner's plugins: [Snipsy](https://github.com/Dimagious/snipsidian), [Dashy](https://github.com/Dimagious/dashsidian) and [Garmy](https://github.com/Dimagious/garmidian).
|
|
214
|
+
|
|
215
|
+
Where each module came from:
|
|
216
|
+
|
|
217
|
+
- Build, bundle check, scanner and the vault copy: Dashy's `build`, `assert-bundle`, `build-css`, `build-vault` and `scorecard-check` scripts and its scanner ESLint configuration.
|
|
218
|
+
- End-to-end fixture: Snipsy's `e2e/fixtures.ts`, `obsidian-version.ts` and `remove-dir.ts` and Garmy's `e2e-setup.sh`.
|
|
219
|
+
- End-to-end helpers: Snipsy's UI helpers (settings, command palette, editor typing, text and clear, IME composition) and Garmy's settings and reading-view helpers; the theme, metadata-cache, notice, properties and scroll helpers and the mobile block come from Dashy's and Garmy's capture and film specs; the sidebar collapse from Dashy and Garmy; the fake swap (`replace`) from Garmy's fake.
|
|
220
|
+
- Demo: Snipsy's cursor and caption overlays, Dashy's tap dot and phone film, and Garmy's reels.
|
|
221
|
+
|
|
222
|
+
## License
|
|
223
|
+
|
|
224
|
+
MIT
|
package/bin/opdk.js
ADDED
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Thin launcher: the CLI lives in TypeScript under src/ and runs from dist/.
|
|
3
|
+
import { existsSync } from "node:fs";
|
|
4
|
+
|
|
5
|
+
const entry = new URL("../dist/cli/main.js", import.meta.url);
|
|
6
|
+
|
|
7
|
+
if (!existsSync(entry)) {
|
|
8
|
+
// Nothing from dist/ can be loaded here, so no reporter and no colour; the glyph keeps the failure style.
|
|
9
|
+
console.error(
|
|
10
|
+
"✗ opdk: the kit is not built: run `npm run build` in the kit; when installed from git, npm runs it via `prepare`.",
|
|
11
|
+
);
|
|
12
|
+
process.exit(1);
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
try {
|
|
16
|
+
const { main } = await import(entry.href);
|
|
17
|
+
process.exitCode = await main(process.argv.slice(2));
|
|
18
|
+
} catch (error) {
|
|
19
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
20
|
+
const stack = process.env.OPDK_DEBUG === "1" && error instanceof Error && error.stack !== undefined
|
|
21
|
+
? error.stack.split("\n")
|
|
22
|
+
: undefined;
|
|
23
|
+
try {
|
|
24
|
+
const { createProcessReporter } = await import(new URL("../dist/cli/process-reporter.js", import.meta.url).href);
|
|
25
|
+
createProcessReporter().error(`opdk: ${message}`, stack);
|
|
26
|
+
} catch {
|
|
27
|
+
// dist/ is too broken to load the reporter: the message still has to reach the user, uncoloured.
|
|
28
|
+
console.error(`✗ opdk: ${message}`);
|
|
29
|
+
if (stack !== undefined) {
|
|
30
|
+
console.error(stack.join("\n"));
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
process.exitCode = 1;
|
|
34
|
+
}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
export interface BuildArgs {
|
|
2
|
+
readonly vault: boolean;
|
|
3
|
+
/** The directory after `--vault`, when given. Otherwise `VAULT_PLUGIN` is used. */
|
|
4
|
+
readonly vaultDir?: string;
|
|
5
|
+
readonly watch: boolean;
|
|
6
|
+
/** Overwrite a vault folder that holds another plugin. */
|
|
7
|
+
readonly force: boolean;
|
|
8
|
+
}
|
|
9
|
+
/** Pure parsing of `opdk build` arguments. Throws a message that says what to type instead. */
|
|
10
|
+
export declare function parseBuildArgs(args: readonly string[]): BuildArgs;
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
const EMPTY_VAULT = "--vault needs a non-empty directory: use --vault=<dir> or --vault <dir>.";
|
|
2
|
+
/** Pure parsing of `opdk build` arguments. Throws a message that says what to type instead. */
|
|
3
|
+
export function parseBuildArgs(args) {
|
|
4
|
+
let vault = false;
|
|
5
|
+
let vaultDir;
|
|
6
|
+
let watch = false;
|
|
7
|
+
let force = false;
|
|
8
|
+
for (let i = 0; i < args.length; i++) {
|
|
9
|
+
const arg = args[i] ?? "";
|
|
10
|
+
if (arg === "--watch") {
|
|
11
|
+
watch = true;
|
|
12
|
+
}
|
|
13
|
+
else if (arg === "--force") {
|
|
14
|
+
force = true;
|
|
15
|
+
}
|
|
16
|
+
else if (arg === "--vault") {
|
|
17
|
+
vault = true;
|
|
18
|
+
const next = args[i + 1];
|
|
19
|
+
if (next === "") {
|
|
20
|
+
throw new Error(EMPTY_VAULT);
|
|
21
|
+
}
|
|
22
|
+
if (next !== undefined && !next.startsWith("-")) {
|
|
23
|
+
vaultDir = next;
|
|
24
|
+
i++;
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
else if (arg.startsWith("--vault=")) {
|
|
28
|
+
vault = true;
|
|
29
|
+
vaultDir = arg.slice("--vault=".length);
|
|
30
|
+
if (vaultDir === "") {
|
|
31
|
+
throw new Error(EMPTY_VAULT);
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
else {
|
|
35
|
+
throw new Error(`Unknown argument "${arg}" for "opdk build". Run "opdk build --help" for the options.`);
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
if (watch && !vault) {
|
|
39
|
+
throw new Error("--watch only works together with --vault: use `opdk build --vault --watch`.");
|
|
40
|
+
}
|
|
41
|
+
if (force && !vault) {
|
|
42
|
+
throw new Error("--force only works together with --vault: use `opdk build --vault --force`.");
|
|
43
|
+
}
|
|
44
|
+
return { vault, ...(vaultDir !== undefined && { vaultDir }), watch, force };
|
|
45
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The bundle has to run where the plugin claims to run.
|
|
3
|
+
*
|
|
4
|
+
* `manifest.json` says `isDesktopOnly: false`, and on a phone there is no
|
|
5
|
+
* Node: no `process`, no `require`, no `__dirname`. Desktop Obsidian is
|
|
6
|
+
* Electron and has all three, so a bundle that reaches for them works
|
|
7
|
+
* perfectly on the machine it was built on and fails on every block on a
|
|
8
|
+
* phone, which is exactly how one plugin release shipped. esbuild was told
|
|
9
|
+
* `--platform=node`, so it took the `node` branch of the `yaml` package's
|
|
10
|
+
* export map and bundled the build that reads `process.env`.
|
|
11
|
+
*
|
|
12
|
+
* Nothing in `src/` refers to any of this; it arrives through a dependency's
|
|
13
|
+
* export conditions, which is why reading our own sources cannot catch it and
|
|
14
|
+
* the built file has to be checked instead.
|
|
15
|
+
*/
|
|
16
|
+
/** Returns one message per Node-only reference found in the bundle text; empty when the bundle is clean. */
|
|
17
|
+
export declare function findNodeOnlyReferences(code: string): string[];
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The bundle has to run where the plugin claims to run.
|
|
3
|
+
*
|
|
4
|
+
* `manifest.json` says `isDesktopOnly: false`, and on a phone there is no
|
|
5
|
+
* Node: no `process`, no `require`, no `__dirname`. Desktop Obsidian is
|
|
6
|
+
* Electron and has all three, so a bundle that reaches for them works
|
|
7
|
+
* perfectly on the machine it was built on and fails on every block on a
|
|
8
|
+
* phone, which is exactly how one plugin release shipped. esbuild was told
|
|
9
|
+
* `--platform=node`, so it took the `node` branch of the `yaml` package's
|
|
10
|
+
* export map and bundled the build that reads `process.env`.
|
|
11
|
+
*
|
|
12
|
+
* Nothing in `src/` refers to any of this; it arrives through a dependency's
|
|
13
|
+
* export conditions, which is why reading our own sources cannot catch it and
|
|
14
|
+
* the built file has to be checked instead.
|
|
15
|
+
*/
|
|
16
|
+
/** Each pattern is something that only exists under Node. */
|
|
17
|
+
const FORBIDDEN = [
|
|
18
|
+
{ re: /\bprocess\s*\.\s*(env|emitWarning|platform|version|cwd|argv)\b/, what: "a `process` reference" },
|
|
19
|
+
{ re: /require\(\s*["']node:/, what: "a `node:` builtin import" },
|
|
20
|
+
{ re: /\b__dirname\b|\b__filename\b/, what: "`__dirname` or `__filename`" },
|
|
21
|
+
];
|
|
22
|
+
/**
|
|
23
|
+
* Minification renames the variable but keeps the property, so the property
|
|
24
|
+
* names are what we look for. These come from the `yaml` Node build.
|
|
25
|
+
*/
|
|
26
|
+
const MARKERS = ["LOG_TOKENS", "LOG_STREAM", "emitWarning"];
|
|
27
|
+
/** Returns one message per Node-only reference found in the bundle text; empty when the bundle is clean. */
|
|
28
|
+
export function findNodeOnlyReferences(code) {
|
|
29
|
+
const problems = [];
|
|
30
|
+
for (const { re, what } of FORBIDDEN) {
|
|
31
|
+
const hit = re.exec(code);
|
|
32
|
+
if (hit) {
|
|
33
|
+
problems.push(`${what}: ${JSON.stringify(hit[0])}`);
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
for (const marker of MARKERS) {
|
|
37
|
+
if (code.includes(marker)) {
|
|
38
|
+
problems.push(`\`${marker}\`, which only the Node build of a dependency contains`);
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
return problems;
|
|
42
|
+
}
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
import type { CommandContext } from "../cli/types.js";
|
|
2
|
+
import type { Manifest } from "../config/types.js";
|
|
3
|
+
/** Runs the Node-only check on a built file and prints the result. Returns the exit code. */
|
|
4
|
+
export declare function checkBundleFile(file: string, manifest: Manifest, ctx: CommandContext): number;
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import { existsSync, readFileSync } from "node:fs";
|
|
2
|
+
import path from "node:path";
|
|
3
|
+
import { findNodeOnlyReferences } from "./bundle-check.js";
|
|
4
|
+
import { formatKib } from "./report.js";
|
|
5
|
+
/** Runs the Node-only check on a built file and prints the result. Returns the exit code. */
|
|
6
|
+
export function checkBundleFile(file, manifest, ctx) {
|
|
7
|
+
const relative = path.relative(ctx.cwd, file);
|
|
8
|
+
// A file outside the plugin would print as ../../x; the absolute path says more.
|
|
9
|
+
const name = relative === "" || relative.startsWith("..") ? file : relative;
|
|
10
|
+
if (manifest.isDesktopOnly === true) {
|
|
11
|
+
ctx.reporter.info("bundle", `${manifest.id} is desktop only and Node is available there: skipping the check of ${name}`);
|
|
12
|
+
return 0;
|
|
13
|
+
}
|
|
14
|
+
if (!existsSync(file)) {
|
|
15
|
+
ctx.reporter.failure("bundle", `${name} is missing: run \`opdk build\` first`);
|
|
16
|
+
return 1;
|
|
17
|
+
}
|
|
18
|
+
const code = readFileSync(file, "utf8");
|
|
19
|
+
const problems = findNodeOnlyReferences(code);
|
|
20
|
+
if (problems.length > 0) {
|
|
21
|
+
ctx.reporter.failure("bundle", `${name} cannot run on mobile:`, {
|
|
22
|
+
details: problems.map((problem) => `- ${problem}`),
|
|
23
|
+
hint: "Check the esbuild platform: an Obsidian plugin bundles as `browser`.",
|
|
24
|
+
});
|
|
25
|
+
return 1;
|
|
26
|
+
}
|
|
27
|
+
ctx.reporter.success("bundle", `${name} is free of Node-only references (${formatKib(Buffer.byteLength(code))})`);
|
|
28
|
+
return 0;
|
|
29
|
+
}
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
import path from "node:path";
|
|
2
|
+
import { loadConfig } from "../config/load-config.js";
|
|
3
|
+
import { readManifest } from "../config/manifest.js";
|
|
4
|
+
import { parseBuildArgs } from "./args.js";
|
|
5
|
+
import { checkBundleFile } from "./bundle-file.js";
|
|
6
|
+
import { runCssStep } from "./css-step.js";
|
|
7
|
+
import { resolveBuild, resolveVaultDir } from "./options.js";
|
|
8
|
+
import { runReleaseBuild } from "./release.js";
|
|
9
|
+
import { runVaultBuild } from "./vault.js";
|
|
10
|
+
const buildUsage = `Usage: opdk build [--vault [dir] | --vault=<dir>] [--watch] [--force]
|
|
11
|
+
|
|
12
|
+
Builds the CSS, bundles the plugin with esbuild for the browser platform (so it
|
|
13
|
+
runs on phones), then checks main.js for Node-only code.
|
|
14
|
+
|
|
15
|
+
Options:
|
|
16
|
+
--vault [dir] Build into a dev vault: unminified main.js in <dir>, plus a fresh
|
|
17
|
+
styles.css and manifest.json. <dir> defaults to $VAULT_PLUGIN
|
|
18
|
+
(also written --vault=<dir>). No bundle check in this mode.
|
|
19
|
+
Refuses a <dir> whose manifest.json holds another plugin id.
|
|
20
|
+
--force With --vault: overwrite <dir> even if it holds another plugin.
|
|
21
|
+
--watch With --vault: rebuild on changes to the sources, the CSS and
|
|
22
|
+
manifest.json. Stop with Ctrl+C. Restart it after editing opdk.config.mjs.
|
|
23
|
+
|
|
24
|
+
Settings come from opdk.config.mjs ("build" section); the plugin id from manifest.json.
|
|
25
|
+
`;
|
|
26
|
+
const cssUsage = `Usage: opdk build-css
|
|
27
|
+
|
|
28
|
+
Inlines the @import lines of the CSS entry (default src/styles/main.css) into
|
|
29
|
+
styles.css. Imports resolve relative to the file that contains them. A missing
|
|
30
|
+
import or an import cycle is an error, and so is a missing entry (exit 1).
|
|
31
|
+
`;
|
|
32
|
+
const assertUsage = `Usage: opdk assert-bundle [file]
|
|
33
|
+
|
|
34
|
+
Fails if the built bundle (default: the build outfile, main.js) contains code that
|
|
35
|
+
exists only under Node (process, node: imports, __dirname, the Node build of a
|
|
36
|
+
dependency), because it would break on mobile. Skipped for desktop-only plugins.
|
|
37
|
+
`;
|
|
38
|
+
export const buildCommand = {
|
|
39
|
+
name: "build",
|
|
40
|
+
summary: "Build CSS, bundle the plugin for the browser platform, check the bundle",
|
|
41
|
+
usage: buildUsage,
|
|
42
|
+
async run(args, ctx) {
|
|
43
|
+
const parsed = parseBuildArgs(args);
|
|
44
|
+
const manifest = readManifest(ctx.cwd);
|
|
45
|
+
const config = await loadConfig(ctx.cwd);
|
|
46
|
+
const build = resolveBuild(config.build);
|
|
47
|
+
if (!parsed.vault) {
|
|
48
|
+
return runReleaseBuild(manifest, build, ctx);
|
|
49
|
+
}
|
|
50
|
+
const { dir, source } = resolveVaultDir(parsed.vaultDir, ctx.env, manifest.id);
|
|
51
|
+
ctx.reporter.info("build", `${manifest.id}: vault target ${dir} (from ${source === "flag" ? "--vault" : "VAULT_PLUGIN"})`);
|
|
52
|
+
const controller = new AbortController();
|
|
53
|
+
const stopListening = parsed.watch ? ctx.onInterrupt?.(() => {
|
|
54
|
+
controller.abort();
|
|
55
|
+
}) : undefined;
|
|
56
|
+
try {
|
|
57
|
+
return await runVaultBuild({
|
|
58
|
+
cwd: ctx.cwd,
|
|
59
|
+
manifest,
|
|
60
|
+
build,
|
|
61
|
+
dir,
|
|
62
|
+
watch: parsed.watch,
|
|
63
|
+
force: parsed.force,
|
|
64
|
+
reporter: ctx.reporter,
|
|
65
|
+
signal: controller.signal,
|
|
66
|
+
});
|
|
67
|
+
}
|
|
68
|
+
finally {
|
|
69
|
+
stopListening?.();
|
|
70
|
+
}
|
|
71
|
+
},
|
|
72
|
+
};
|
|
73
|
+
export const buildCssCommand = {
|
|
74
|
+
name: "build-css",
|
|
75
|
+
summary: "Inline the @import lines of the CSS entry into styles.css",
|
|
76
|
+
usage: cssUsage,
|
|
77
|
+
async run(args, ctx) {
|
|
78
|
+
if (args.length > 0) {
|
|
79
|
+
throw new Error(`"opdk build-css" takes no arguments, got "${args.join(" ")}".`);
|
|
80
|
+
}
|
|
81
|
+
const config = await loadConfig(ctx.cwd);
|
|
82
|
+
const { css } = resolveBuild(config.build);
|
|
83
|
+
if (css === false) {
|
|
84
|
+
ctx.reporter.info("css", 'disabled by "build.css: false" in opdk.config.mjs, nothing to do');
|
|
85
|
+
return 0;
|
|
86
|
+
}
|
|
87
|
+
// The failure below says it all, so the step stays quiet about the missing entry.
|
|
88
|
+
if (runCssStep(ctx.cwd, css, ctx, false).status === "no-entry") {
|
|
89
|
+
ctx.reporter.failure("css", `nothing was built. Create ${css.entry}, or set "build.css.entry" in opdk.config.mjs.`);
|
|
90
|
+
return 1;
|
|
91
|
+
}
|
|
92
|
+
return 0;
|
|
93
|
+
},
|
|
94
|
+
};
|
|
95
|
+
export const assertBundleCommand = {
|
|
96
|
+
name: "assert-bundle",
|
|
97
|
+
summary: "Fail if the built bundle contains Node-only code",
|
|
98
|
+
usage: assertUsage,
|
|
99
|
+
async run(args, ctx) {
|
|
100
|
+
if (args.length > 1 || args[0]?.startsWith("-") === true) {
|
|
101
|
+
throw new Error(`Usage: opdk assert-bundle [file]. Got: ${args.join(" ")}`);
|
|
102
|
+
}
|
|
103
|
+
const manifest = readManifest(ctx.cwd);
|
|
104
|
+
const config = await loadConfig(ctx.cwd);
|
|
105
|
+
const file = path.resolve(ctx.cwd, args[0] ?? resolveBuild(config.build).outfile);
|
|
106
|
+
return checkBundleFile(file, manifest, ctx);
|
|
107
|
+
},
|
|
108
|
+
};
|
|
109
|
+
export const buildCommands = [buildCommand, buildCssCommand, assertBundleCommand];
|