obsidian-plugin-dev-kit 0.0.0-stage → 0.3.2

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 (329) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +223 -2
  3. package/bin/opdk.js +34 -0
  4. package/dist/build/args.d.ts +10 -0
  5. package/dist/build/args.js +45 -0
  6. package/dist/build/bundle-check.d.ts +17 -0
  7. package/dist/build/bundle-check.js +42 -0
  8. package/dist/build/bundle-file.d.ts +4 -0
  9. package/dist/build/bundle-file.js +29 -0
  10. package/dist/build/commands.d.ts +5 -0
  11. package/dist/build/commands.js +109 -0
  12. package/dist/build/config.d.ts +3 -0
  13. package/dist/build/config.js +103 -0
  14. package/dist/build/css-imports.d.ts +23 -0
  15. package/dist/build/css-imports.js +50 -0
  16. package/dist/build/css-step.d.ts +10 -0
  17. package/dist/build/css-step.js +27 -0
  18. package/dist/build/css.d.ts +24 -0
  19. package/dist/build/css.js +47 -0
  20. package/dist/build/options.d.ts +55 -0
  21. package/dist/build/options.js +70 -0
  22. package/dist/build/release.d.ts +5 -0
  23. package/dist/build/release.js +34 -0
  24. package/dist/build/report.d.ts +7 -0
  25. package/dist/build/report.js +16 -0
  26. package/dist/build/vault.d.ts +26 -0
  27. package/dist/build/vault.js +290 -0
  28. package/dist/build-info.json +1 -0
  29. package/dist/cli/argv.d.ts +14 -0
  30. package/dist/cli/argv.js +18 -0
  31. package/dist/cli/commands.d.ts +3 -0
  32. package/dist/cli/commands.js +7 -0
  33. package/dist/cli/main.d.ts +2 -0
  34. package/dist/cli/main.js +23 -0
  35. package/dist/cli/process-reporter.d.ts +5 -0
  36. package/dist/cli/process-reporter.js +15 -0
  37. package/dist/cli/registry.d.ts +4 -0
  38. package/dist/cli/registry.js +15 -0
  39. package/dist/cli/reporter.d.ts +53 -0
  40. package/dist/cli/reporter.js +100 -0
  41. package/dist/cli/run.d.ts +9 -0
  42. package/dist/cli/run.js +61 -0
  43. package/dist/cli/types.d.ts +27 -0
  44. package/dist/cli/types.js +1 -0
  45. package/dist/cli/version.d.ts +13 -0
  46. package/dist/cli/version.js +61 -0
  47. package/dist/config/define-config.d.ts +3 -0
  48. package/dist/config/define-config.js +4 -0
  49. package/dist/config/load-config.d.ts +6 -0
  50. package/dist/config/load-config.js +70 -0
  51. package/dist/config/manifest.d.ts +3 -0
  52. package/dist/config/manifest.js +72 -0
  53. package/dist/config/types.d.ts +146 -0
  54. package/dist/config/types.js +23 -0
  55. package/dist/demo/args.d.ts +4 -0
  56. package/dist/demo/args.js +13 -0
  57. package/dist/demo/checks.d.ts +56 -0
  58. package/dist/demo/checks.js +124 -0
  59. package/dist/demo/commands.d.ts +3 -0
  60. package/dist/demo/commands.js +65 -0
  61. package/dist/demo/config.d.ts +57 -0
  62. package/dist/demo/config.js +337 -0
  63. package/dist/demo/ffmpeg-run.d.ts +18 -0
  64. package/dist/demo/ffmpeg-run.js +59 -0
  65. package/dist/demo/ffmpeg.d.ts +63 -0
  66. package/dist/demo/ffmpeg.js +111 -0
  67. package/dist/demo/films.d.ts +46 -0
  68. package/dist/demo/films.js +134 -0
  69. package/dist/demo/phone-layout.d.ts +38 -0
  70. package/dist/demo/phone-layout.js +98 -0
  71. package/dist/demo/phone-render.d.ts +28 -0
  72. package/dist/demo/phone-render.js +124 -0
  73. package/dist/demo/published.d.ts +16 -0
  74. package/dist/demo/published.js +72 -0
  75. package/dist/demo/run.d.ts +31 -0
  76. package/dist/demo/run.js +397 -0
  77. package/dist/demo/stills.d.ts +21 -0
  78. package/dist/demo/stills.js +62 -0
  79. package/dist/e2e/artifacts.d.ts +27 -0
  80. package/dist/e2e/artifacts.js +90 -0
  81. package/dist/e2e/cleanup.d.ts +54 -0
  82. package/dist/e2e/cleanup.js +109 -0
  83. package/dist/e2e/config.d.ts +9 -0
  84. package/dist/e2e/config.js +42 -0
  85. package/dist/e2e/create-test.d.ts +37 -0
  86. package/dist/e2e/create-test.js +109 -0
  87. package/dist/e2e/demo/clip.d.ts +21 -0
  88. package/dist/e2e/demo/clip.js +44 -0
  89. package/dist/e2e/demo/create-demo.d.ts +42 -0
  90. package/dist/e2e/demo/create-demo.js +439 -0
  91. package/dist/e2e/demo/manifest.d.ts +76 -0
  92. package/dist/e2e/demo/manifest.js +168 -0
  93. package/dist/e2e/demo/names.d.ts +18 -0
  94. package/dist/e2e/demo/names.js +44 -0
  95. package/dist/e2e/demo/options.d.ts +22 -0
  96. package/dist/e2e/demo/options.js +59 -0
  97. package/dist/e2e/demo/ownership.d.ts +27 -0
  98. package/dist/e2e/demo/ownership.js +65 -0
  99. package/dist/e2e/demo/page-scripts.d.ts +82 -0
  100. package/dist/e2e/demo/page-scripts.js +250 -0
  101. package/dist/e2e/demo/png.d.ts +8 -0
  102. package/dist/e2e/demo/png.js +23 -0
  103. package/dist/e2e/demo/presets.d.ts +43 -0
  104. package/dist/e2e/demo/presets.js +20 -0
  105. package/dist/e2e/demo/privacy.d.ts +18 -0
  106. package/dist/e2e/demo/privacy.js +30 -0
  107. package/dist/e2e/demo/still-options.d.ts +22 -0
  108. package/dist/e2e/demo/still-options.js +68 -0
  109. package/dist/e2e/demo/types.d.ts +184 -0
  110. package/dist/e2e/demo/types.js +1 -0
  111. package/dist/e2e/electron-binary.d.ts +15 -0
  112. package/dist/e2e/electron-binary.js +30 -0
  113. package/dist/e2e/fixtures.d.ts +62 -0
  114. package/dist/e2e/fixtures.js +68 -0
  115. package/dist/e2e/gate.d.ts +4 -0
  116. package/dist/e2e/gate.js +8 -0
  117. package/dist/e2e/global-setup.d.ts +11 -0
  118. package/dist/e2e/global-setup.js +17 -0
  119. package/dist/e2e/helpers/commands.d.ts +14 -0
  120. package/dist/e2e/helpers/commands.js +56 -0
  121. package/dist/e2e/helpers/create-helpers.d.ts +24 -0
  122. package/dist/e2e/helpers/create-helpers.js +582 -0
  123. package/dist/e2e/helpers/device-metrics.d.ts +21 -0
  124. package/dist/e2e/helpers/device-metrics.js +25 -0
  125. package/dist/e2e/helpers/ime.d.ts +13 -0
  126. package/dist/e2e/helpers/ime.js +19 -0
  127. package/dist/e2e/helpers/layout-page-scripts.d.ts +103 -0
  128. package/dist/e2e/helpers/layout-page-scripts.js +224 -0
  129. package/dist/e2e/helpers/layout.d.ts +83 -0
  130. package/dist/e2e/helpers/layout.js +148 -0
  131. package/dist/e2e/helpers/mobile.d.ts +31 -0
  132. package/dist/e2e/helpers/mobile.js +26 -0
  133. package/dist/e2e/helpers/page-scripts.d.ts +194 -0
  134. package/dist/e2e/helpers/page-scripts.js +467 -0
  135. package/dist/e2e/helpers/settings.d.ts +8 -0
  136. package/dist/e2e/helpers/settings.js +16 -0
  137. package/dist/e2e/helpers/settle.d.ts +28 -0
  138. package/dist/e2e/helpers/settle.js +33 -0
  139. package/dist/e2e/helpers/types.d.ts +193 -0
  140. package/dist/e2e/helpers/types.js +1 -0
  141. package/dist/e2e/helpers/view-mode.d.ts +23 -0
  142. package/dist/e2e/helpers/view-mode.js +35 -0
  143. package/dist/e2e/index.d.ts +14 -0
  144. package/dist/e2e/index.js +4 -0
  145. package/dist/e2e/internals.d.ts +155 -0
  146. package/dist/e2e/internals.js +8 -0
  147. package/dist/e2e/obsidian-path.d.ts +17 -0
  148. package/dist/e2e/obsidian-path.js +31 -0
  149. package/dist/e2e/options.d.ts +123 -0
  150. package/dist/e2e/options.js +244 -0
  151. package/dist/e2e/page-scripts.d.ts +45 -0
  152. package/dist/e2e/page-scripts.js +53 -0
  153. package/dist/e2e/peers.d.ts +9 -0
  154. package/dist/e2e/peers.js +19 -0
  155. package/dist/e2e/plugins.d.ts +32 -0
  156. package/dist/e2e/plugins.js +119 -0
  157. package/dist/e2e/process-tree.d.ts +33 -0
  158. package/dist/e2e/process-tree.js +133 -0
  159. package/dist/e2e/readiness.d.ts +23 -0
  160. package/dist/e2e/readiness.js +63 -0
  161. package/dist/e2e/seed.d.ts +34 -0
  162. package/dist/e2e/seed.js +122 -0
  163. package/dist/e2e/session.d.ts +71 -0
  164. package/dist/e2e/session.js +266 -0
  165. package/dist/e2e/vault.d.ts +52 -0
  166. package/dist/e2e/vault.js +146 -0
  167. package/dist/e2e/version.d.ts +25 -0
  168. package/dist/e2e/version.js +40 -0
  169. package/dist/eslint/index.d.ts +2 -0
  170. package/dist/eslint/index.js +1 -0
  171. package/dist/eslint/obsidian-plugin.d.ts +49 -0
  172. package/dist/eslint/obsidian-plugin.js +115 -0
  173. package/dist/index.d.ts +3 -0
  174. package/dist/index.js +1 -0
  175. package/dist/kit/args.d.ts +7 -0
  176. package/dist/kit/args.js +21 -0
  177. package/dist/kit/commands.d.ts +3 -0
  178. package/dist/kit/commands.js +52 -0
  179. package/dist/kit/files.d.ts +3 -0
  180. package/dist/kit/files.js +24 -0
  181. package/dist/kit/pins.d.ts +89 -0
  182. package/dist/kit/pins.js +178 -0
  183. package/dist/kit/remote.d.ts +13 -0
  184. package/dist/kit/remote.js +33 -0
  185. package/dist/kit/runners.d.ts +11 -0
  186. package/dist/kit/runners.js +53 -0
  187. package/dist/kit/terminal-text.d.ts +6 -0
  188. package/dist/kit/terminal-text.js +20 -0
  189. package/dist/kit/upgrade.d.ts +26 -0
  190. package/dist/kit/upgrade.js +162 -0
  191. package/dist/peers/resolve.d.ts +8 -0
  192. package/dist/peers/resolve.js +28 -0
  193. package/dist/peers/versions.d.ts +30 -0
  194. package/dist/peers/versions.js +32 -0
  195. package/dist/release/api-check.d.ts +27 -0
  196. package/dist/release/api-check.js +119 -0
  197. package/dist/release/args.d.ts +40 -0
  198. package/dist/release/args.js +120 -0
  199. package/dist/release/assets.d.ts +21 -0
  200. package/dist/release/assets.js +35 -0
  201. package/dist/release/build-check.d.ts +43 -0
  202. package/dist/release/build-check.js +184 -0
  203. package/dist/release/build-script.d.ts +12 -0
  204. package/dist/release/build-script.js +30 -0
  205. package/dist/release/build-tagged.d.ts +26 -0
  206. package/dist/release/build-tagged.js +52 -0
  207. package/dist/release/bump.d.ts +24 -0
  208. package/dist/release/bump.js +58 -0
  209. package/dist/release/changelog.d.ts +25 -0
  210. package/dist/release/changelog.js +148 -0
  211. package/dist/release/check.d.ts +38 -0
  212. package/dist/release/check.js +150 -0
  213. package/dist/release/commands.d.ts +3 -0
  214. package/dist/release/commands.js +154 -0
  215. package/dist/release/committed-tree.d.ts +63 -0
  216. package/dist/release/committed-tree.js +118 -0
  217. package/dist/release/config.d.ts +3 -0
  218. package/dist/release/config.js +28 -0
  219. package/dist/release/gh-access.d.ts +14 -0
  220. package/dist/release/gh-access.js +45 -0
  221. package/dist/release/gh.d.ts +10 -0
  222. package/dist/release/gh.js +33 -0
  223. package/dist/release/git.d.ts +49 -0
  224. package/dist/release/git.js +111 -0
  225. package/dist/release/interrupt.d.ts +30 -0
  226. package/dist/release/interrupt.js +60 -0
  227. package/dist/release/json.d.ts +33 -0
  228. package/dist/release/json.js +81 -0
  229. package/dist/release/kit-check.d.ts +8 -0
  230. package/dist/release/kit-check.js +51 -0
  231. package/dist/release/manifest-rules.d.ts +23 -0
  232. package/dist/release/manifest-rules.js +255 -0
  233. package/dist/release/preflight.d.ts +10 -0
  234. package/dist/release/preflight.js +65 -0
  235. package/dist/release/problems.d.ts +24 -0
  236. package/dist/release/problems.js +11 -0
  237. package/dist/release/project-files.d.ts +14 -0
  238. package/dist/release/project-files.js +16 -0
  239. package/dist/release/publish-command.d.ts +21 -0
  240. package/dist/release/publish-command.js +83 -0
  241. package/dist/release/publish-git.d.ts +37 -0
  242. package/dist/release/publish-git.js +108 -0
  243. package/dist/release/publish-state.d.ts +29 -0
  244. package/dist/release/publish-state.js +70 -0
  245. package/dist/release/publish-verify.d.ts +41 -0
  246. package/dist/release/publish-verify.js +112 -0
  247. package/dist/release/publish-wait.d.ts +25 -0
  248. package/dist/release/publish-wait.js +56 -0
  249. package/dist/release/publish.d.ts +35 -0
  250. package/dist/release/publish.js +181 -0
  251. package/dist/release/release-assets.d.ts +39 -0
  252. package/dist/release/release-assets.js +68 -0
  253. package/dist/release/release.d.ts +37 -0
  254. package/dist/release/release.js +179 -0
  255. package/dist/release/remote.d.ts +12 -0
  256. package/dist/release/remote.js +15 -0
  257. package/dist/release/reproducible.d.ts +16 -0
  258. package/dist/release/reproducible.js +34 -0
  259. package/dist/release/run-tests.d.ts +5 -0
  260. package/dist/release/run-tests.js +17 -0
  261. package/dist/release/semver.d.ts +8 -0
  262. package/dist/release/semver.js +60 -0
  263. package/dist/release/version-rules.d.ts +28 -0
  264. package/dist/release/version-rules.js +63 -0
  265. package/dist/release/versions-json.d.ts +15 -0
  266. package/dist/release/versions-json.js +88 -0
  267. package/dist/release/workflow-run.d.ts +44 -0
  268. package/dist/release/workflow-run.js +71 -0
  269. package/dist/scanner/code-checks.d.ts +41 -0
  270. package/dist/scanner/code-checks.js +82 -0
  271. package/dist/scanner/commands.d.ts +3 -0
  272. package/dist/scanner/commands.js +43 -0
  273. package/dist/scanner/config.d.ts +7 -0
  274. package/dist/scanner/config.js +25 -0
  275. package/dist/scanner/css-check.d.ts +26 -0
  276. package/dist/scanner/css-check.js +63 -0
  277. package/dist/scanner/eslint-nesting.d.ts +16 -0
  278. package/dist/scanner/eslint-nesting.js +45 -0
  279. package/dist/scanner/findings.d.ts +23 -0
  280. package/dist/scanner/findings.js +21 -0
  281. package/dist/scanner/git-files.d.ts +16 -0
  282. package/dist/scanner/git-files.js +73 -0
  283. package/dist/scanner/lint.d.ts +47 -0
  284. package/dist/scanner/lint.js +163 -0
  285. package/dist/scanner/meta-checks.d.ts +8 -0
  286. package/dist/scanner/meta-checks.js +22 -0
  287. package/dist/scanner/outside-project.d.ts +19 -0
  288. package/dist/scanner/outside-project.js +20 -0
  289. package/dist/scanner/run.d.ts +19 -0
  290. package/dist/scanner/run.js +78 -0
  291. package/dist/scanner/scanner-config.d.ts +114 -0
  292. package/dist/scanner/scanner-config.js +207 -0
  293. package/dist/scanner/typescript-gate.d.ts +30 -0
  294. package/dist/scanner/typescript-gate.js +73 -0
  295. package/dist/vitest/build-config.d.ts +17 -0
  296. package/dist/vitest/build-config.js +106 -0
  297. package/dist/vitest/define-unit-config.d.ts +27 -0
  298. package/dist/vitest/define-unit-config.js +45 -0
  299. package/dist/vitest/dom/elements.d.ts +87 -0
  300. package/dist/vitest/dom/elements.js +291 -0
  301. package/dist/vitest/dom/index.d.ts +1 -0
  302. package/dist/vitest/dom/index.js +1 -0
  303. package/dist/vitest/dom/install.d.ts +8 -0
  304. package/dist/vitest/dom/install.js +261 -0
  305. package/dist/vitest/dom/setup.d.ts +1 -0
  306. package/dist/vitest/dom/setup.js +3 -0
  307. package/dist/vitest/index.d.ts +3 -0
  308. package/dist/vitest/index.js +2 -0
  309. package/dist/vitest/options.d.ts +92 -0
  310. package/dist/vitest/options.js +136 -0
  311. package/dist/vitest/peers.d.ts +10 -0
  312. package/dist/vitest/peers.js +51 -0
  313. package/dist/vitest/workspace-root.d.ts +7 -0
  314. package/dist/vitest/workspace-root.js +39 -0
  315. package/docs/build.md +232 -0
  316. package/docs/ci.md +182 -0
  317. package/docs/demo.md +364 -0
  318. package/docs/e2e.md +563 -0
  319. package/docs/release.md +374 -0
  320. package/docs/scanner.md +204 -0
  321. package/docs/unit.md +291 -0
  322. package/package.json +100 -4
  323. package/plugins/opdk/skills/audit/SKILL.md +81 -0
  324. package/plugins/opdk/skills/build/SKILL.md +79 -0
  325. package/plugins/opdk/skills/demo/SKILL.md +102 -0
  326. package/plugins/opdk/skills/e2e/SKILL.md +132 -0
  327. package/plugins/opdk/skills/release/SKILL.md +84 -0
  328. package/plugins/opdk/skills/scanner/SKILL.md +60 -0
  329. package/plugins/opdk/skills/unit/SKILL.md +90 -0
@@ -0,0 +1,38 @@
1
+ import type { Reporter } from "../cli/reporter.js";
2
+ import type { OpdkConfig } from "../config/types.js";
3
+ import { type OverlayFile } from "./committed-tree.js";
4
+ import { type RunGit } from "./git.js";
5
+ import { CleanupSet, type InterruptHooks } from "./interrupt.js";
6
+ import { type GroupResult } from "./problems.js";
7
+ import { type ProjectFiles } from "./project-files.js";
8
+ /** Which of the checks that cost time (a build, a type-aware lint) run. The cheap ones always do. */
9
+ export interface CheckFlags {
10
+ /** `--no-build`: skips `build`, `assets` and `reproducible`. */
11
+ readonly build: boolean;
12
+ /** `--no-reproducible`: builds once instead of twice. */
13
+ readonly reproducible: boolean;
14
+ /** `--no-api`: skips the `minAppVersion` against API check. */
15
+ readonly api: boolean;
16
+ }
17
+ export declare const ALL_CHECKS: CheckFlags;
18
+ export interface CheckInput {
19
+ readonly cwd: string;
20
+ readonly config: OpdkConfig;
21
+ readonly tag: string | undefined;
22
+ readonly flags: CheckFlags;
23
+ readonly reporter: Reporter;
24
+ /** Ctrl+C handling. Without it (a test) the temp folders of an interrupted check are not removed. */
25
+ readonly interrupt?: InterruptHooks;
26
+ /** Shared with a caller that registers its own Ctrl+C guard (the release); the check then adds to it and registers none. */
27
+ readonly cleanups?: CleanupSet;
28
+ /** Git for the committed tree of the reproducibility check. Defaults to the real thing in `cwd`. */
29
+ readonly run?: RunGit;
30
+ /** Files that the caller changed but has not committed yet; laid over the committed tree so it matches the commit to come. */
31
+ readonly overlay?: readonly OverlayFile[];
32
+ }
33
+ /** The groups that need no build, in the order they print. Exported for the bump, which reuses them before it builds. */
34
+ export declare function staticResults(files: ProjectFiles, changelogFile: string, tag: string | undefined): GroupResult[];
35
+ /** Prints the results in group order. Returns the number of errors. */
36
+ export declare function reportResults(results: readonly GroupResult[], flags: CheckFlags, reporter: Reporter): number;
37
+ /** `opdk release check`: every rule that decides whether this commit can be released. Returns the exit code. */
38
+ export declare function runReleaseCheck(input: CheckInput): Promise<number>;
@@ -0,0 +1,150 @@
1
+ import { loadWorkflows } from "../kit/files.js";
2
+ import { resolveBuild } from "../build/options.js";
3
+ import { checkChangelog } from "./changelog.js";
4
+ import { checkBuildScript } from "./build-script.js";
5
+ import { extractCommittedTree } from "./committed-tree.js";
6
+ import { createRunGit } from "./git.js";
7
+ import { CleanupSet, guardInterrupt } from "./interrupt.js";
8
+ import { asRecord, findFormatIssue } from "./json.js";
9
+ import { checkManifestRules } from "./manifest-rules.js";
10
+ import { CHECK_GROUPS, errorProblem, hasErrors } from "./problems.js";
11
+ import { loadProjectFiles, valueOf } from "./project-files.js";
12
+ import { checkVersionSync } from "./version-rules.js";
13
+ import { checkVersionsJson } from "./versions-json.js";
14
+ import { checkKit } from "./kit-check.js";
15
+ export const ALL_CHECKS = { build: true, reproducible: true, api: true };
16
+ const SKIPPED = {
17
+ build: (flags) => (flags.build ? undefined : "--no-build"),
18
+ assets: (flags) => (flags.build ? undefined : "--no-build"),
19
+ reproducible: (flags) => (!flags.build ? "--no-build" : flags.reproducible ? undefined : "--no-reproducible"),
20
+ api: (flags) => (flags.api ? undefined : "--no-api"),
21
+ };
22
+ function fileProblems(files) {
23
+ const problems = [];
24
+ // manifest.json is never missing or invalid here (callers return earlier), so only its format check applies.
25
+ const names = [
26
+ ["package.json", files.packageJson, true],
27
+ ["package-lock.json", files.lock, false],
28
+ ["manifest.json", files.manifest, false],
29
+ ];
30
+ for (const [name, loaded, required] of names) {
31
+ if (loaded.kind === "invalid") {
32
+ problems.push(errorProblem("versions", `${name} is not valid JSON: ${loaded.message}.`, "Fix the syntax."));
33
+ }
34
+ else if (loaded.kind === "missing" && required) {
35
+ problems.push(errorProblem("versions", `${name} is missing.`, "Run opdk from the plugin root."));
36
+ }
37
+ else if (loaded.kind === "ok") {
38
+ // `opdk release <bump>` rewrites this file and refuses one it cannot write back as it is: say so before release day.
39
+ const issue = findFormatIssue(loaded.text, loaded.value, name);
40
+ if (issue !== undefined) {
41
+ problems.push(errorProblem("versions", issue.message, issue.hint));
42
+ }
43
+ }
44
+ }
45
+ return problems;
46
+ }
47
+ function versionsResult(files, version, tag) {
48
+ const problems = [
49
+ ...fileProblems(files),
50
+ ...checkVersionSync({ manifest: valueOf(files.manifest), packageJson: valueOf(files.packageJson), lock: valueOf(files.lock) }, tag),
51
+ ];
52
+ const places = files.lock.kind === "ok" ? "manifest.json, package.json and package-lock.json" : "manifest.json and package.json";
53
+ return { group: "versions", passed: `${places} are all ${version}${tag === undefined ? "" : `, tag ${tag} matches`}`, problems };
54
+ }
55
+ /** The groups that need no build, in the order they print. Exported for the bump, which reuses them before it builds. */
56
+ export function staticResults(files, changelogFile, tag) {
57
+ const manifest = asRecord(valueOf(files.manifest));
58
+ const version = typeof manifest?.version === "string" ? manifest.version : "";
59
+ const minAppVersion = typeof manifest?.minAppVersion === "string" ? manifest.minAppVersion : undefined;
60
+ return [
61
+ versionsResult(files, version, tag),
62
+ { group: "versions.json", passed: `${version} maps to ${minAppVersion ?? "?"}`, problems: checkVersionsJson(files.versions, version, minAppVersion) },
63
+ { group: "manifest", passed: "manifest.json follows the directory's rules", problems: checkManifestRules(manifest) },
64
+ { group: "changelog", passed: `${changelogFile} has a section for ${version}`, problems: checkChangelog(files.changelog, version, changelogFile) },
65
+ ];
66
+ }
67
+ /** Prints the results in group order. Returns the number of errors. */
68
+ export function reportResults(results, flags, reporter) {
69
+ let errors = 0;
70
+ for (const group of CHECK_GROUPS) {
71
+ const skipped = SKIPPED[group]?.(flags);
72
+ const result = results.find((candidate) => candidate.group === group);
73
+ if (skipped !== undefined) {
74
+ reporter.info("check", `${group}: skipped (${skipped})`);
75
+ }
76
+ else if (result !== undefined) {
77
+ errors += reportGroup(result, reporter);
78
+ }
79
+ }
80
+ return errors;
81
+ }
82
+ function reportGroup(result, reporter) {
83
+ let errors = 0;
84
+ for (const problem of result.problems) {
85
+ const text = `${problem.group}: ${problem.message}`;
86
+ if (problem.severity === "warning") {
87
+ reporter.warn("check", text);
88
+ }
89
+ else {
90
+ errors++;
91
+ reporter.failure("check", text, { ...(problem.details !== undefined && { details: problem.details }), ...(problem.hint !== undefined && { hint: problem.hint }) });
92
+ }
93
+ }
94
+ if (!hasErrors(result.problems)) {
95
+ reporter.success("check", `${result.group}: ${result.passed}`);
96
+ }
97
+ return errors;
98
+ }
99
+ /** `opdk release check`: every rule that decides whether this commit can be released. Returns the exit code. */
100
+ export async function runReleaseCheck(input) {
101
+ const cleanups = input.cleanups ?? new CleanupSet();
102
+ const guard = input.cleanups === undefined ? guardInterrupt(input.interrupt, cleanups, input.reporter) : undefined;
103
+ try {
104
+ return await checkWith(input, cleanups);
105
+ }
106
+ finally {
107
+ guard?.stop();
108
+ }
109
+ }
110
+ async function checkWith({ cwd, config, tag, flags, reporter, run, overlay }, cleanups) {
111
+ const changelogFile = config.release?.changelog ?? "CHANGELOG.md";
112
+ const files = loadProjectFiles(cwd, changelogFile);
113
+ const manifest = asRecord(valueOf(files.manifest));
114
+ if (files.manifest.kind !== "ok" || manifest === undefined) {
115
+ const why = files.manifest.kind === "invalid" ? `is not valid JSON: ${files.manifest.message}` : files.manifest.kind === "missing" ? `is missing in ${cwd}` : "must contain a JSON object";
116
+ reporter.failure("check", `manifest.json ${why}.`, { hint: "Run opdk from the plugin root." });
117
+ return 1;
118
+ }
119
+ const id = typeof manifest.id === "string" ? manifest.id : "plugin";
120
+ const version = typeof manifest.version === "string" ? manifest.version : "?";
121
+ const minAppVersion = typeof manifest.minAppVersion === "string" ? manifest.minAppVersion : undefined;
122
+ reporter.info("check", `${id} ${version}${tag === undefined ? "" : ` (tag ${tag})`}`);
123
+ const results = [...staticResults(files, changelogFile, tag), checkKit(files, loadWorkflows(cwd))];
124
+ if (flags.build) {
125
+ // Loaded here, not at the top, like the scan: the build pulls in esbuild.
126
+ const { checkBuild } = await import("./build-check.js");
127
+ const git = run ?? createRunGit(cwd);
128
+ results.push(...(await checkBuild({
129
+ cwd,
130
+ manifestText: files.manifest.text,
131
+ desktopOnly: manifest.isDesktopOnly === true,
132
+ build: resolveBuild(config.build),
133
+ reproducible: flags.reproducible,
134
+ buildNotes: checkBuildScript(valueOf(files.packageJson)),
135
+ cleanups,
136
+ committed: (workDir) => extractCommittedTree({ cwd, run: git, workDir, overlay: overlay ?? [] }),
137
+ })));
138
+ }
139
+ if (flags.api) {
140
+ const { checkApiUsage } = await import("./api-check.js");
141
+ results.push(await checkApiUsage({ cwd, minAppVersion, build: resolveBuild(config.build) }));
142
+ }
143
+ const errors = reportResults(results, flags, reporter);
144
+ if (errors > 0) {
145
+ reporter.failure("check", `${id} ${version}: ${String(errors)} problem(s), not ready to release.`, { hint: "Fix them and rerun `opdk release check`." });
146
+ return 1;
147
+ }
148
+ reporter.success("check", `${id} ${version}: ready to release.`);
149
+ return 0;
150
+ }
@@ -0,0 +1,3 @@
1
+ import type { Command } from "../cli/types.js";
2
+ export declare const releaseCommand: Command;
3
+ export declare const releaseCommands: readonly Command[];
@@ -0,0 +1,154 @@
1
+ import { loadConfig } from "../config/load-config.js";
2
+ import { parseReleaseArgs } from "./args.js";
3
+ import { runReleaseCheck } from "./check.js";
4
+ import { createRunGit } from "./git.js";
5
+ import { changelogNotes, createPushFlow, runPublishCommand } from "./publish-command.js";
6
+ import { runRelease } from "./release.js";
7
+ import { createRunTests } from "./run-tests.js";
8
+ import { resolveTag } from "./version-rules.js";
9
+ const releaseUsage = `Usage: opdk release check [--tag <name>] [--no-build] [--no-reproducible] [--no-api]
10
+ opdk release <patch|minor|major|X.Y.Z> [--dry-run] [--no-push] [--timeout <minutes>] [--zip]
11
+ [--no-build] [--no-reproducible] [--no-api] [--no-test]
12
+ opdk release publish [X.Y.Z] [--timeout <minutes>] [--zip]
13
+ opdk release notes [X.Y.Z]
14
+
15
+ opdk release check (for CI and before a release) fails with exit 1, one line per problem and what to do about it:
16
+ versions manifest.json, package.json and package-lock.json (both version fields) hold the same
17
+ x.y.z version (no "v", no pre-release); with --tag <name>, or GITHUB_REF_NAME when
18
+ GITHUB_REF_TYPE=tag, the tag is that version
19
+ versions.json a file that exists and is an object; the current version maps to the manifest's minAppVersion;
20
+ minAppVersion never goes down as versions go up (errors). A key or value that is not a version
21
+ is a warning, as in the official action.
22
+ manifest the rules of the official obsidianmd/obsidian-workflows action: required fields, id, name
23
+ and description rules, author without email or URL, HTTPS URLs, isDesktopOnly a boolean,
24
+ version not 0.0.0, minAppVersion a version (warnings print as "!" and do not fail).
25
+ Differences from the action: author, minAppVersion and isDesktopOnly are required (the
26
+ action only recommends them); a banned word in the id is a warning, in the name an error;
27
+ helpUrl is accepted and its URL checked; authorUrl, helpUrl and fundingUrl of the wrong type
28
+ are errors; the action's check that authorUrl is not the plugin's own repository is covered
29
+ by the general warning that authorUrl links to a repository.
30
+ changelog CHANGELOG.md has a "## [X.Y.Z]" section with at least one entry
31
+ build a production build into a temp folder (your main.js and styles.css are not touched), the
32
+ Node-only bundle check. Warns when package.json scripts.build (else build:plugin, else
33
+ compile: the order the community directory uses) does not run \`opdk build\`, because the
34
+ directory rebuilds main.js with that script
35
+ kit when the plugin depends on the kit: the tag in package.json, the commit the lockfile resolved
36
+ it to and every "uses: <owner>/obsidian-plugin-dev-kit/.github/workflows/<file>@<sha> # vX.Y.Z"
37
+ line of .github/workflows/*.yml name one release. No network: the lockfile's version stands
38
+ for the tag. A plugin that does not use the kit, or its workflows, passes. Fix: \`opdk kit upgrade\`
39
+ assets main.js is produced, styles.css when the plugin has CSS, the manifest asset is the root one
40
+ reproducible builds the working tree, then builds the committed tree (git archive HEAD, extracted to
41
+ another temp folder, with the plugin's node_modules linked in) and compares main.js and
42
+ styles.css byte for byte. It catches inputs git does not hold (untracked or ignored files,
43
+ the build fails there) and absolute paths of this machine in the output. It does not compare
44
+ the Node or esbuild version (this machine's node_modules is reused), lockfile drift or line
45
+ endings on other operating systems. With uncommitted changes the committed tree is what is
46
+ compared and the output says so; outside a git repository, or before the first commit, it
47
+ builds the working tree twice and warns that this proves much less, and so do pnpm and
48
+ Yarn PnP installs (two builds of the working tree). git archive applies export-ignore from
49
+ .gitattributes, and Git LFS files are pointer text in it, so a build input tracked by LFS
50
+ makes the comparison differ. On a mismatch it names the first differing offset and the
51
+ likely causes
52
+ api minAppVersion against the API the code calls (obsidianmd/no-unsupported-api, type-aware;
53
+ needs \`npm ci\` first). It lints the files esbuild puts into main.js (not node_modules);
54
+ a shipped file that no tsconfig covers is an error. Blind spot: the rule reads @since tags
55
+ from obsidian.d.ts through the TypeScript program, so it reports nothing when the program
56
+ does not contain the real one (for example a tsconfig "paths" entry pointing obsidian at a
57
+ stub), and the check cannot tell. \`opdk scan\` does not change.
58
+
59
+ Skipping: --no-build skips build, assets and reproducible (a quick CI step); --no-reproducible builds
60
+ once; --no-api skips the API check. The version, versions.json, manifest, kit and changelog checks always run.
61
+
62
+ opdk release <patch|minor|major|X.Y.Z> cuts a release. Preflight: inside a git repository, clean
63
+ tree, on the default branch (origin/HEAD, or release.defaultBranch), neither behind nor ahead of origin (it
64
+ fetches; commits that origin has not seen have not run CI, so push them through a pull request first), the tag
65
+ absent locally and on origin, "## [Unreleased]" in the changelog with entries. Then it:
66
+ - runs the plugin's \`npm test\` (output shown) before anything is changed; a failure stops the release with
67
+ nothing modified. --no-test skips it. A package.json without a "test" script prints a warning and goes on;
68
+ - sets the version in package.json, package-lock.json and manifest.json, adds it to versions.json (an existing
69
+ entry is never rewritten) and moves the [Unreleased] entries under "## [X.Y.Z] - YYYY-MM-DD", leaving an
70
+ empty [Unreleased] (the compare links at the bottom are updated when the file has them);
71
+ - runs the release check on the result; when it fails, or on Ctrl+C, the files are restored, the temp
72
+ folders removed and nothing is committed (Ctrl+C exits with 130);
73
+ - commits "chore(release): X.Y.Z" and creates the annotated tag X.Y.Z;
74
+ - then the push flow (below), unless --no-push, which stops at the local tag.
75
+ --dry-run runs everything up to the commit, prints the diff and restores the files: no commit or tag is
76
+ created, nothing is pushed and gh is never called, but it does fetch from origin and ask it for the tag (ls-remote).
77
+
78
+ The push flow (also \`opdk release publish [X.Y.Z]\`, which starts from an existing local tag and continues
79
+ after any stop; every step checks what is already done). It needs the GitHub CLI, signed in with write access
80
+ to the repository origin points at (checked before anything is bumped), and a workflow in the plugin that
81
+ runs on tag pushes and calls the kit's release workflow: uses: Dimagious/obsidian-plugin-dev-kit/.github/workflows/release.yml@<full
82
+ commit SHA of the kit>. Call it, do not copy it: the attestations are checked against the kit's file. publish
83
+ without a version uses the version in manifest.json; --dry-run never calls gh, so it skips the gh check. The
84
+ plugin's build script (build, else build:plugin, else compile) must run \`opdk build\`: the assets are compared
85
+ with an \`opdk build\` of the tag, and a plugin that builds some other way fails that comparison after the tag is
86
+ already pushed. It:
87
+ 1. pushes only the tag (git push origin refs/tags/X.Y.Z); never the branch yet, never with force;
88
+ 2. waits for the run of the kit's release workflow on that commit (other workflows on the same push, such as
89
+ Pages, are ignored; a progress line when its state changes, 20 minutes by default, --timeout <minutes> to
90
+ change); when it fails it prints the run URL and stops, the tag stays. If no such run starts within 3
91
+ minutes, the plugin's tag workflow does not call the kit's release.yml;
92
+ 3. checks the draft release: a draft, main.js and manifest.json, styles.css only if the plugin has CSS, no
93
+ other asset (--zip also expects <id>-<version>.zip); notes equal to the CHANGELOG section at the tag;
94
+ downloads the assets and compares them byte for byte
95
+ with a build of the tagged commit made here (the committed-tree build of the reproducible check) and
96
+ with the committed manifest.json (the zip is checked for presence and size only); runs gh attestation
97
+ verify on each attested file for the repository, the tag, the tagged commit and the signer, which must be
98
+ the kit's release.yml at any ref (--cert-identity-regex, anchored); two releases for one tag stop it;
99
+ 4. publishes it (gh release edit --draft=false --latest) and confirms it is public and the latest release;
100
+ 5. pushes the release commit to the default branch (no force; later local commits stay local, and nothing is
101
+ pushed when origin already holds the commit). When origin rejects it the release is already public: the
102
+ message says to merge origin's commits without rewriting the release commit;
103
+ 6. prints the release and run URLs.
104
+ Every stop, and Ctrl+C (exit 130), prints what is on origin and the command to resume:
105
+ opdk release publish X.Y.Z. A stop whose hint says to release a new version prints opdk release patch instead.
106
+ A failed workflow is fixed by a new patch version, or re-run on GitHub (a failed run can leave a draft: delete it before re-running)
107
+ and resumed; nothing is ever moved or deleted by opdk.
108
+
109
+ opdk release notes [X.Y.Z] prints the body of the "## [X.Y.Z]" section of the changelog (X.Y.Z defaults to
110
+ the manifest version): the release workflow uses it for the release notes. Exit 1 when the section is
111
+ missing or empty.
112
+
113
+ Settings come from opdk.config.mjs ("release" section: changelog, defaultBranch; "build" section for the build).
114
+ `;
115
+ export const releaseCommand = {
116
+ name: "release",
117
+ summary: "Check that a commit can be released, cut a release, publish it, or print its changelog notes",
118
+ usage: releaseUsage,
119
+ async run(args, ctx) {
120
+ const parsed = parseReleaseArgs(args);
121
+ const config = await loadConfig(ctx.cwd);
122
+ const onInterrupt = ctx.onInterrupt?.bind(ctx);
123
+ // The CLI exits through the exit code; Ctrl+C has no return path, so the listener ends the process itself.
124
+ const interrupt = onInterrupt === undefined ? undefined : { onInterrupt, exit: (code) => process.exit(code) };
125
+ if (parsed.mode === "check") {
126
+ return runReleaseCheck({ cwd: ctx.cwd, config, tag: resolveTag(parsed.tag, ctx.env), flags: parsed.flags, reporter: ctx.reporter, ...(interrupt !== undefined && { interrupt }) });
127
+ }
128
+ if (parsed.mode === "notes") {
129
+ ctx.stdout(changelogNotes(ctx.cwd, config, parsed.version));
130
+ return 0;
131
+ }
132
+ const push = { cwd: ctx.cwd, config, reporter: ctx.reporter, pushing: parsed.pushing, ...(interrupt !== undefined && { interrupt }) };
133
+ if (parsed.mode === "publish") {
134
+ return runPublishCommand(push, parsed.version);
135
+ }
136
+ return runRelease({
137
+ cwd: ctx.cwd,
138
+ spec: parsed.spec,
139
+ dryRun: parsed.dryRun,
140
+ flags: parsed.flags,
141
+ config,
142
+ reporter: ctx.reporter,
143
+ stdout: (text) => {
144
+ ctx.stdout(text);
145
+ },
146
+ run: createRunGit(ctx.cwd),
147
+ ...(interrupt !== undefined && { interrupt }),
148
+ now: () => new Date(),
149
+ ...(parsed.pushing.push && { push: createPushFlow(push) }),
150
+ ...(parsed.test && { test: createRunTests(ctx.cwd) }),
151
+ });
152
+ },
153
+ };
154
+ export const releaseCommands = [releaseCommand];
@@ -0,0 +1,63 @@
1
+ import { type RunGit } from "./git.js";
2
+ /** A file the release is about to commit, laid over the extracted tree so the copy matches the commit-to-be. */
3
+ export interface OverlayFile {
4
+ readonly path: string;
5
+ readonly content: string;
6
+ }
7
+ export type CommittedTree = {
8
+ readonly kind: "ready";
9
+ /** The folder holding the extracted files, at a path other than the plugin folder. */
10
+ readonly dir: string;
11
+ /** Short hash of the commit the copy was made from. */
12
+ readonly commit: string;
13
+ /** `git status --porcelain` lines the copy does not contain (changed or untracked files), minus the overlay. */
14
+ readonly uncommitted: readonly string[];
15
+ } | {
16
+ readonly kind: "unavailable";
17
+ readonly reason: string;
18
+ /** What to do about it; the caller has a default for the missing-repository case. */
19
+ readonly hint?: string;
20
+ };
21
+ export interface CommittedTreeInput {
22
+ readonly cwd: string;
23
+ readonly run: RunGit;
24
+ /** An empty folder to extract into; its parent holds the tar file. */
25
+ readonly workDir: string;
26
+ readonly overlay: readonly OverlayFile[];
27
+ /** The commit-ish to extract. Default `HEAD`; the publish step passes the release tag. */
28
+ readonly ref?: string;
29
+ }
30
+ /** The part of a directory entry the linking decision needs (`fs.Dirent` has it). */
31
+ export interface EntryLike {
32
+ readonly name: string;
33
+ isDirectory(): boolean;
34
+ isSymbolicLink(): boolean;
35
+ }
36
+ /**
37
+ * Whether an entry of `node_modules` gets a link. `.bin` is skipped, and so are plain files such as
38
+ * `.package-lock.json` and `.modules.yaml`: a Windows junction can only point at a folder. A symlink is kept
39
+ * (npm workspaces and `npm link` put them there).
40
+ */
41
+ export declare function isLinkableEntry(entry: EntryLike): boolean;
42
+ /**
43
+ * Names the install layout the committed-tree build cannot work with, or `undefined` for a plain npm layout.
44
+ * pnpm keeps the dependencies of a package next to its real path under `node_modules/.pnpm`, and Yarn PnP has no
45
+ * `node_modules` to link, so a linked copy would not resolve imports the way the real folder does.
46
+ */
47
+ export declare function unsupportedInstallLayout(exists: (relative: string) => boolean): string | undefined;
48
+ /**
49
+ * `git archive HEAD` of the plugin folder, extracted to `workDir/plugin-copy` with the plugin's packages
50
+ * reachable through symlinks. Building there and comparing with the working-tree build catches inputs git does not
51
+ * hold (untracked or ignored files) and absolute paths of this machine in the output. It does not catch a different
52
+ * Node or esbuild version or lockfile drift, because `node_modules` is the one on this machine.
53
+ *
54
+ * `git archive` applies `export-ignore` from `.gitattributes`, which a checkout does not; a build that needs such a
55
+ * file fails in the copy and says so. Git LFS files are pointer text in the archive, so a build input tracked by LFS
56
+ * makes the comparison differ.
57
+ *
58
+ * A pnpm or Yarn PnP install is not extracted (see `unsupportedInstallLayout`): `unavailable` makes the caller
59
+ * compare two builds of the working tree.
60
+ *
61
+ * Throws when git or tar fails inside a repository; returns `unavailable` when there is no repository or commit.
62
+ */
63
+ export declare function extractCommittedTree({ cwd, run, workDir, overlay, ref }: CommittedTreeInput): Promise<CommittedTree>;
@@ -0,0 +1,118 @@
1
+ import { execFile } from "node:child_process";
2
+ import { existsSync, mkdirSync, readdirSync, symlinkSync, writeFileSync } from "node:fs";
3
+ import path from "node:path";
4
+ import { promisify } from "node:util";
5
+ import { gitFreeEnvironment } from "../scanner/git-files.js";
6
+ import { tryGit } from "./git.js";
7
+ const execFileAsync = promisify(execFile);
8
+ /** The path a porcelain line is about (`XY path`, or `XY old -> new`). */
9
+ const porcelainPath = (line) => {
10
+ const rest = line.slice(3);
11
+ const arrow = rest.indexOf(" -> ");
12
+ return arrow === -1 ? rest : rest.slice(arrow + 4);
13
+ };
14
+ /**
15
+ * Whether an entry of `node_modules` gets a link. `.bin` is skipped, and so are plain files such as
16
+ * `.package-lock.json` and `.modules.yaml`: a Windows junction can only point at a folder. A symlink is kept
17
+ * (npm workspaces and `npm link` put them there).
18
+ */
19
+ export function isLinkableEntry(entry) {
20
+ return entry.name !== ".bin" && (entry.isDirectory() || entry.isSymbolicLink());
21
+ }
22
+ /**
23
+ * Names the install layout the committed-tree build cannot work with, or `undefined` for a plain npm layout.
24
+ * pnpm keeps the dependencies of a package next to its real path under `node_modules/.pnpm`, and Yarn PnP has no
25
+ * `node_modules` to link, so a linked copy would not resolve imports the way the real folder does.
26
+ */
27
+ export function unsupportedInstallLayout(exists) {
28
+ if (exists("node_modules/.pnpm") || exists("node_modules/.modules.yaml")) {
29
+ return "pnpm install";
30
+ }
31
+ if (exists(".pnp.cjs") || exists(".pnp.js")) {
32
+ return "Yarn PnP install";
33
+ }
34
+ return undefined;
35
+ }
36
+ /**
37
+ * Makes the plugin's packages reachable from the copy. The folder itself is not linked: esbuild resolves a linked
38
+ * `node_modules` to its real location and then writes `../../..` paths into the unminified output, which would read
39
+ * as a difference. Each package is linked instead (a scope folder is real, its packages are links) and the build runs
40
+ * with `preserveSymlinks`, so the paths stay `node_modules/<package>/...`. Does nothing when the plugin has no
41
+ * `node_modules` or the commit holds one.
42
+ */
43
+ function linkNodeModules(source, target) {
44
+ if (!existsSync(source) || existsSync(target)) {
45
+ return;
46
+ }
47
+ mkdirSync(target);
48
+ // A junction needs no admin rights on Windows; the type is ignored elsewhere.
49
+ const link = (from, to) => {
50
+ symlinkSync(from, to, "junction");
51
+ };
52
+ for (const entry of readdirSync(source, { withFileTypes: true })) {
53
+ if (!isLinkableEntry(entry)) {
54
+ continue;
55
+ }
56
+ if (entry.name.startsWith("@") && entry.isDirectory()) {
57
+ mkdirSync(path.join(target, entry.name));
58
+ for (const scoped of readdirSync(path.join(source, entry.name))) {
59
+ link(path.join(source, entry.name, scoped), path.join(target, entry.name, scoped));
60
+ }
61
+ }
62
+ else {
63
+ link(path.join(source, entry.name), path.join(target, entry.name));
64
+ }
65
+ }
66
+ }
67
+ /**
68
+ * `git archive HEAD` of the plugin folder, extracted to `workDir/plugin-copy` with the plugin's packages
69
+ * reachable through symlinks. Building there and comparing with the working-tree build catches inputs git does not
70
+ * hold (untracked or ignored files) and absolute paths of this machine in the output. It does not catch a different
71
+ * Node or esbuild version or lockfile drift, because `node_modules` is the one on this machine.
72
+ *
73
+ * `git archive` applies `export-ignore` from `.gitattributes`, which a checkout does not; a build that needs such a
74
+ * file fails in the copy and says so. Git LFS files are pointer text in the archive, so a build input tracked by LFS
75
+ * makes the comparison differ.
76
+ *
77
+ * A pnpm or Yarn PnP install is not extracted (see `unsupportedInstallLayout`): `unavailable` makes the caller
78
+ * compare two builds of the working tree.
79
+ *
80
+ * Throws when git or tar fails inside a repository; returns `unavailable` when there is no repository or commit.
81
+ */
82
+ export async function extractCommittedTree({ cwd, run, workDir, overlay, ref = "HEAD" }) {
83
+ if ((await tryGit(run, ["rev-parse", "--is-inside-work-tree"])) !== "true") {
84
+ return { kind: "unavailable", reason: "the folder is not inside a git repository" };
85
+ }
86
+ const commit = await tryGit(run, ["rev-parse", "--short", "--verify", "--quiet", `${ref}^{commit}`]);
87
+ if (commit === undefined || commit === "") {
88
+ return { kind: "unavailable", reason: ref === "HEAD" ? "the repository has no commit yet" : `the repository has no commit ${ref}` };
89
+ }
90
+ const layout = unsupportedInstallLayout((relative) => existsSync(path.join(cwd, relative)));
91
+ if (layout !== undefined) {
92
+ return {
93
+ kind: "unavailable",
94
+ reason: `${layout}: compared two builds of the working tree, not the committed tree (its packages cannot be linked into a copy)`,
95
+ hint: "Use an npm layout (npm ci) to compare the committed tree, or accept the weaker check.",
96
+ };
97
+ }
98
+ const overlaid = new Set(overlay.map((file) => file.path));
99
+ const uncommitted = (await run(["--no-optional-locks", "status", "--porcelain"])).split("\n").filter((line) => line !== "" && !overlaid.has(porcelainPath(line)));
100
+ const tarFile = path.join(workDir, "committed.tar");
101
+ const dir = path.join(workDir, "plugin-copy");
102
+ mkdirSync(dir);
103
+ // Run inside the plugin folder, git archives only that folder, so a plugin in a subfolder of a repository works.
104
+ await run(["archive", "--format=tar", "-o", tarFile, ref]);
105
+ try {
106
+ await execFileAsync("tar", ["-xf", tarFile, "-C", dir], { env: gitFreeEnvironment(process.env) });
107
+ }
108
+ catch (error) {
109
+ throw new Error(`tar could not extract the committed tree: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
110
+ }
111
+ linkNodeModules(path.join(cwd, "node_modules"), path.join(dir, "node_modules"));
112
+ for (const file of overlay) {
113
+ const target = path.join(dir, file.path);
114
+ mkdirSync(path.dirname(target), { recursive: true });
115
+ writeFileSync(target, file.content);
116
+ }
117
+ return { kind: "ready", dir, commit, uncommitted };
118
+ }
@@ -0,0 +1,3 @@
1
+ import type { ReleaseConfig } from "../config/types.js";
2
+ /** Checks and copies the `release` section of `opdk.config.mjs`. Every error names the offending key. */
3
+ export declare function validateReleaseConfig(value: unknown, source: string): ReleaseConfig;
@@ -0,0 +1,28 @@
1
+ import path from "node:path";
2
+ const RELEASE_KEYS = ["changelog", "defaultBranch"];
3
+ /** Checks and copies the `release` section of `opdk.config.mjs`. Every error names the offending key. */
4
+ export function validateReleaseConfig(value, source) {
5
+ if (typeof value !== "object" || value === null || Array.isArray(value)) {
6
+ throw new Error(`${source}: "release" must be an object.`);
7
+ }
8
+ const unknown = Object.keys(value).filter((key) => !RELEASE_KEYS.includes(key));
9
+ if (unknown.length > 0) {
10
+ throw new Error(`${source}: unknown key(s) in "release": ${unknown.join(", ")}. Allowed keys: ${RELEASE_KEYS.join(", ")}.`);
11
+ }
12
+ const changelog = optionalString(value, "changelog", source);
13
+ const defaultBranch = optionalString(value, "defaultBranch", source);
14
+ if (changelog !== undefined && (path.isAbsolute(changelog) || changelog.split(/[\\/]/).includes(".."))) {
15
+ throw new Error(`${source}: "release.changelog" must be a path inside the plugin folder, such as "CHANGELOG.md".`);
16
+ }
17
+ return { ...(changelog !== undefined && { changelog }), ...(defaultBranch !== undefined && { defaultBranch }) };
18
+ }
19
+ function optionalString(record, key, source) {
20
+ const value = Object.hasOwn(record, key) ? Reflect.get(record, key) : undefined;
21
+ if (value === undefined) {
22
+ return undefined;
23
+ }
24
+ if (typeof value !== "string" || value === "") {
25
+ throw new Error(`${source}: "release.${key}" must be a non-empty string.`);
26
+ }
27
+ return value;
28
+ }
@@ -0,0 +1,14 @@
1
+ import type { RunGit } from "./git.js";
2
+ import { type RunGh } from "./gh.js";
3
+ import { type RepoSlug } from "./remote.js";
4
+ export interface GhAccess {
5
+ readonly slug: RepoSlug;
6
+ readonly permission: string;
7
+ }
8
+ /** The repository `origin` points at, from the configured URL (not the one rewritten by `insteadOf`). */
9
+ export declare function originSlug(run: RunGit): Promise<RepoSlug>;
10
+ /**
11
+ * `gh` is installed, signed in, and may write to the repository `origin` points at. One `gh repo view` answers all
12
+ * three; its error text (not signed in, repository not found for this account) is passed on with the fix.
13
+ */
14
+ export declare function checkGhAccess(run: RunGit, gh: RunGh): Promise<GhAccess>;
@@ -0,0 +1,45 @@
1
+ import { GH_INSTALL_HINT } from "./gh.js";
2
+ import { asRecord } from "./json.js";
3
+ import { StepFailure } from "./publish-state.js";
4
+ import { parseRemoteUrl, slugText } from "./remote.js";
5
+ const CAN_RELEASE = new Set(["WRITE", "MAINTAIN", "ADMIN"]);
6
+ /** The repository `origin` points at, from the configured URL (not the one rewritten by `insteadOf`). */
7
+ export async function originSlug(run) {
8
+ let url;
9
+ try {
10
+ url = (await run(["config", "--get", "remote.origin.url"])).trim();
11
+ }
12
+ catch {
13
+ throw new StepFailure('the repository has no remote called "origin".', "Add it with `git remote add origin <url>`.");
14
+ }
15
+ const slug = parseRemoteUrl(url);
16
+ if (slug === undefined) {
17
+ throw new StepFailure(`origin (${url}) does not look like a GitHub repository URL.`, "The release flow needs https://github.com/<owner>/<repo>.git or git@github.com:<owner>/<repo>.git.");
18
+ }
19
+ return slug;
20
+ }
21
+ /**
22
+ * `gh` is installed, signed in, and may write to the repository `origin` points at. One `gh repo view` answers all
23
+ * three; its error text (not signed in, repository not found for this account) is passed on with the fix.
24
+ */
25
+ export async function checkGhAccess(run, gh) {
26
+ const slug = await originSlug(run);
27
+ const name = slugText(slug);
28
+ let output;
29
+ try {
30
+ output = await gh.text(["repo", "view", name, "--json", "nameWithOwner,viewerPermission"]);
31
+ }
32
+ catch (error) {
33
+ const message = error instanceof Error ? error.message : String(error);
34
+ if (message.startsWith("gh is not installed")) {
35
+ throw new StepFailure("the GitHub CLI (gh) is not installed.", GH_INSTALL_HINT);
36
+ }
37
+ throw new StepFailure(`gh cannot see ${name}: ${message}`, `Sign in with \`gh auth login\`, or switch to the account that owns ${name} with \`gh auth switch\` (check \`gh auth status\`).`);
38
+ }
39
+ const record = asRecord(JSON.parse(output));
40
+ const permission = typeof record?.viewerPermission === "string" ? record.viewerPermission : "";
41
+ if (!CAN_RELEASE.has(permission)) {
42
+ throw new StepFailure(`the signed-in gh account has ${permission === "" ? "no" : permission.toLowerCase()} access to ${name}, and releasing needs write access.`, "Switch to an account that can push to the repository with `gh auth switch` (check `gh auth status`).");
43
+ }
44
+ return { slug, permission };
45
+ }
@@ -0,0 +1,10 @@
1
+ /** Runs `gh <args>`. `text` returns stdout as text, `bytes` returns it untouched (an asset download). Both reject with gh's own message. */
2
+ export interface RunGh {
3
+ text(args: readonly string[]): Promise<string>;
4
+ bytes(args: readonly string[]): Promise<Buffer>;
5
+ }
6
+ /** Where to get gh; part of the message of every "gh is missing" failure. */
7
+ export declare const GH_INSTALL_HINT = "Install the GitHub CLI from https://cli.github.com and sign in with `gh auth login`.";
8
+ /** The real thing. `gh` never prompts: a missing sign-in is an error with a fix, not a question on the terminal. */
9
+ export declare function createRunGh(cwd: string, baseEnv?: NodeJS.ProcessEnv): RunGh;
10
+ export declare function describeGhFailure(args: readonly string[], error: unknown): string;