@shiqianjiang/ceru-plugin-cli 0.2.2 → 0.2.4

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 (52) hide show
  1. package/README.md +4 -0
  2. package/dist/dev.js +23 -6
  3. package/dist/index.js +1 -1
  4. package/dist/project.d.ts +2 -0
  5. package/dist/project.js +150 -14
  6. package/package.json +4 -4
  7. package/schemas/config.schema.json +22 -0
  8. package/templates/connected-library/js/package.json +2 -2
  9. package/templates/connected-library/js/tsconfig.json +1 -1
  10. package/templates/connected-library/ts/package.json +2 -2
  11. package/templates/connected-library/ts/tsconfig.json +1 -1
  12. package/templates/guest-adapter/js/package.json +2 -2
  13. package/templates/guest-adapter/js/tsconfig.json +1 -1
  14. package/templates/guest-adapter/ts/package.json +2 -2
  15. package/templates/guest-adapter/ts/tsconfig.json +1 -1
  16. package/templates/importer/js/package.json +2 -2
  17. package/templates/importer/js/tsconfig.json +1 -1
  18. package/templates/importer/ts/package.json +2 -2
  19. package/templates/importer/ts/tsconfig.json +1 -1
  20. package/templates/react/js/package.json +2 -2
  21. package/templates/react/js/tsconfig.json +1 -1
  22. package/templates/react/ts/package.json +2 -2
  23. package/templates/react/ts/tsconfig.json +1 -1
  24. package/templates/snapshot.json +1 -1
  25. package/templates/source/js/README.md +4 -0
  26. package/templates/source/js/ceru.plugin.json +10 -0
  27. package/templates/source/js/package.json +2 -2
  28. package/templates/source/js/src/index.js +6 -2
  29. package/templates/source/js/src/plugin.config.js +14 -0
  30. package/templates/source/js/tsconfig.json +1 -1
  31. package/templates/source/ts/README.md +5 -0
  32. package/templates/source/ts/ceru.plugin.json +10 -0
  33. package/templates/source/ts/package.json +2 -2
  34. package/templates/source/ts/src/index.ts +4 -2
  35. package/templates/source/ts/src/plugin.config.ts +14 -0
  36. package/templates/source/ts/tsconfig.json +1 -1
  37. package/templates/vue/js/package.json +2 -2
  38. package/templates/vue/js/tsconfig.json +1 -1
  39. package/templates/vue/ts/package.json +2 -2
  40. package/templates/vue/ts/tsconfig.json +1 -1
  41. package/templates/vue-tsx/js/package.json +2 -2
  42. package/templates/vue-tsx/js/tsconfig.json +1 -1
  43. package/templates/vue-tsx/ts/package.json +2 -2
  44. package/templates/vue-tsx/ts/tsconfig.json +1 -1
  45. package/templates/web-dist/js/package.json +2 -2
  46. package/templates/web-dist/js/tsconfig.json +1 -1
  47. package/templates/web-dist/ts/package.json +2 -2
  48. package/templates/web-dist/ts/tsconfig.json +1 -1
  49. package/templates/web-surface/js/package.json +2 -2
  50. package/templates/web-surface/js/tsconfig.json +1 -1
  51. package/templates/web-surface/ts/package.json +2 -2
  52. package/templates/web-surface/ts/tsconfig.json +1 -1
package/README.md CHANGED
@@ -24,6 +24,10 @@ ceru-plugin sign dist/plugin.js --key .keys/publisher.private.pem
24
24
 
25
25
  Vue/React 生产运行代码会直接打入发行文件,不依赖宿主提供框架。执行 `ceru-plugin preview dist/plugin.js` 可以只加载最终文件验证页面。0.2.0 起发行格式使用静态 `exports.manifest / exports.activate / exports.surfaces`,并支持手写单文件插件。
26
26
 
27
+ 构建产物保留可读的入口名称(如 `LogicMain`、`UiStudioSurface`),并使用 `const` 声明每个 esbuild 入口容器,方便在单文件产物和错误堆栈中定位逻辑。插件源码仍可按需要使用函数或 class;构建器不会强制某一种编程风格。
28
+
29
+ `ceru.plugin.json` 的顶层 `config` 可直接写 JSON 对象,也可写 `@./path/config.ts` 引用 JSON/JS/TS 配置模块。字符串 `@@value` 表示字面量 `@value`。构建器递归展开引用,校验为 JSON 兼容对象,并合并到单文件的 `exports.manifest.config` 中。dev/build 会生成不包含配置值的 `@ceru/plugin-config` 类型声明。
30
+
27
31
  在多根/父目录工作区中,请打开生成的 ceru-plugin.code-workspace 或把插件工程本身加入工作区。已经运行 dev 时选择 Attach to Ceru plugin;Launch 会启动或复用当前项目的 Host。
28
32
 
29
33
  当前 v1 Host 不能直接安装 v2 产物。开发工作台不代替生产凭据保险箱、完整音乐业务或 Guest 安装。
package/dist/dev.js CHANGED
@@ -11,9 +11,23 @@ import { fileURLToPath } from 'node:url';
11
11
  import { createRequire } from 'node:module';
12
12
  import { randomBytes, createHash } from 'node:crypto';
13
13
  import { spawn } from 'node:child_process';
14
- import { readArtifact, parseJsonStrict } from '@shiqianjiang/ceru-plugin-issuer';
14
+ import { readArtifact, parseJsonStrict, resolveArtifactConfig, } from '@shiqianjiang/ceru-plugin-issuer';
15
15
  import { buildProject } from './project.js';
16
16
  const asset = (name) => fileURLToPath(new URL('../assets/' + name, import.meta.url));
17
+ function mergeConfig(base, override) {
18
+ const result = structuredClone(base);
19
+ for (const [key, value] of Object.entries(override))
20
+ result[key] =
21
+ value &&
22
+ typeof value === 'object' &&
23
+ !Array.isArray(value) &&
24
+ result[key] &&
25
+ typeof result[key] === 'object' &&
26
+ !Array.isArray(result[key])
27
+ ? mergeConfig(result[key], value)
28
+ : structuredClone(value);
29
+ return result;
30
+ }
17
31
  async function readDebugTargets(port) {
18
32
  const response = await fetch('http://127.0.0.1:' + port + '/json/list', {
19
33
  signal: AbortSignal.timeout(750),
@@ -210,16 +224,17 @@ export async function runDev(project, options = {}) {
210
224
  const token = randomBytes(24).toString('hex');
211
225
  const nonce = randomBytes(24).toString('base64');
212
226
  const catalog = JSON.parse(await readFile(asset('catalog.json'), 'utf8'));
213
- let config = {};
227
+ let configOverride = {};
214
228
  try {
215
229
  const configPath = resolve(root, '.ceru-dev/config.json');
216
- config = parseJsonStrict(await readFile(configPath, 'utf8'));
230
+ configOverride = parseJsonStrict(await readFile(configPath, 'utf8'));
217
231
  }
218
232
  catch (error) {
219
233
  if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT')
220
234
  throw error;
221
235
  }
222
236
  const grants = new Map();
237
+ const effectiveConfig = () => mergeConfig(resolveArtifactConfig(artifact.header), configOverride);
223
238
  const sockets = new SocketBroker();
224
239
  const operations = new Map();
225
240
  const storage = new Map();
@@ -330,7 +345,7 @@ export async function runDev(project, options = {}) {
330
345
  migrationWarnings: artifact.migrationWarnings,
331
346
  resources: artifact.resources,
332
347
  catalog,
333
- config,
348
+ config: effectiveConfig(),
334
349
  grants: Object.fromEntries(grants),
335
350
  });
336
351
  return;
@@ -343,7 +358,7 @@ export async function runDev(project, options = {}) {
343
358
  if (url.pathname === '/api/config') {
344
359
  if (!input || typeof input !== 'object' || Array.isArray(input))
345
360
  throw new Error('Config must be an object');
346
- config = input;
361
+ configOverride = input;
347
362
  json(200, { ok: true });
348
363
  return;
349
364
  }
@@ -408,7 +423,9 @@ export async function runDev(project, options = {}) {
408
423
  throw new Error('此独立开发 Host 尚未连接澜音的歌单服务。本地歌单和云歌单由澜音管理;请在正式 Host 中调用此能力。开发环境不会创建替代歌单库。');
409
424
  }
410
425
  if (input.method === 'config.get') {
411
- json(200, { value: config });
426
+ json(200, {
427
+ value: effectiveConfig(),
428
+ });
412
429
  return;
413
430
  }
414
431
  if (input.method === 'storage.get') {
package/dist/index.js CHANGED
@@ -6,7 +6,7 @@ import { createTemplate, generateSigningKeys, parseJsonStrict, PreparedIssuer, r
6
6
  import { buildProject, scaffoldProject, TEMPLATES, writeAtomic } from './project.js';
7
7
  import { runDev } from './dev.js';
8
8
  export { buildProject, loadProject, scaffoldProject, TEMPLATES } from './project.js';
9
- const VERSION = '0.2.2';
9
+ const VERSION = '0.2.4';
10
10
  const HELP = 'Ceru Plugin CLI ' +
11
11
  VERSION +
12
12
  '\n\n' +
package/dist/project.d.ts CHANGED
@@ -1,6 +1,8 @@
1
1
  import { type ArtifactHeader } from '@shiqianjiang/ceru-plugin-issuer';
2
+ import type { JsonObject } from '@shiqianjiang/ceru-plugin-sdk';
2
3
  export interface BuildConfig {
3
4
  manifest: ArtifactHeader['manifest'];
5
+ config?: JsonObject;
4
6
  entries: Record<string, string>;
5
7
  resources?: Record<string, {
6
8
  path: string;
package/dist/project.js CHANGED
@@ -8,7 +8,118 @@ import { spawnSync } from 'node:child_process';
8
8
  import { createRequire } from 'node:module';
9
9
  import { stylesheetPlugin, vuePlugin, webDistEntry } from './frameworks.js';
10
10
  import { hostModulesPlugin, assertBundledDependencies } from './dependencies.js';
11
- import { encodeArtifact, parseJsonStrict, readArtifact, validateManifest, LIMITS, } from '@shiqianjiang/ceru-plugin-issuer';
11
+ import { canonical, encodeArtifact, parseJsonStrict, readArtifact, validateManifest, LIMITS, } from '@shiqianjiang/ceru-plugin-issuer';
12
+ async function resolveConfigValue(root, value, stack = new Set(), depth = 0) {
13
+ if (depth > 32)
14
+ throw new Error('Plugin config references are too deeply nested');
15
+ if (typeof value === 'string') {
16
+ if (value.startsWith('@@'))
17
+ return value.slice(1);
18
+ if (!value.startsWith('@'))
19
+ return value;
20
+ const request = value.slice(1);
21
+ if (!request)
22
+ throw new Error('Plugin config reference cannot be empty');
23
+ const path = await inside(root, request);
24
+ if (stack.has(path))
25
+ throw new Error('Circular plugin config reference: ' + request);
26
+ stack.add(path);
27
+ try {
28
+ const extension = extname(path).toLowerCase();
29
+ let loaded;
30
+ if (extension === '.json') {
31
+ loaded = parseJsonStrict(await readFile(path, 'utf8'));
32
+ }
33
+ else if (['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts'].includes(extension)) {
34
+ const result = await build({
35
+ absWorkingDir: root,
36
+ entryPoints: [path],
37
+ bundle: true,
38
+ write: false,
39
+ format: 'esm',
40
+ platform: 'node',
41
+ target: 'node22',
42
+ logLevel: 'silent',
43
+ });
44
+ if (result.outputFiles.length !== 1)
45
+ throw new Error('Config module emitted sidecar files: ' + request);
46
+ const url = 'data:text/javascript;base64,' +
47
+ Buffer.from(result.outputFiles[0].text).toString('base64') +
48
+ '#' +
49
+ randomUUID();
50
+ const module = await import(url);
51
+ if (!Object.hasOwn(module, 'default'))
52
+ throw new Error('Config module must export default: ' + request);
53
+ loaded = module.default;
54
+ }
55
+ else {
56
+ throw new Error('Config reference must be JSON, JS or TS: ' + request);
57
+ }
58
+ return resolveConfigValue(root, loaded, stack, depth + 1);
59
+ }
60
+ finally {
61
+ stack.delete(path);
62
+ }
63
+ }
64
+ if (value === null || typeof value === 'boolean' || typeof value === 'number')
65
+ return value;
66
+ if (Array.isArray(value))
67
+ return Promise.all(value.map((item) => resolveConfigValue(root, item, stack, depth + 1)));
68
+ if (value && typeof value === 'object') {
69
+ const result = Object.create(null);
70
+ for (const [key, child] of Object.entries(value)) {
71
+ if (['__proto__', 'prototype', 'constructor'].includes(key))
72
+ throw new Error('Unsafe plugin config key: ' + key);
73
+ result[key] = await resolveConfigValue(root, child, stack, depth + 1);
74
+ }
75
+ return result;
76
+ }
77
+ throw new Error('Plugin config must contain only JSON-compatible values');
78
+ }
79
+ function validatePluginConfig(value) {
80
+ if (value === undefined)
81
+ return undefined;
82
+ if (!value || typeof value !== 'object' || Array.isArray(value))
83
+ throw new Error('Plugin config root must resolve to an object');
84
+ return parseJsonStrict(canonical(value));
85
+ }
86
+ function configType(value, depth = 0) {
87
+ if (depth > 24)
88
+ return 'JsonValue';
89
+ if (value === null)
90
+ return 'null';
91
+ if (typeof value === 'string')
92
+ return 'string';
93
+ if (typeof value === 'number')
94
+ return 'number';
95
+ if (typeof value === 'boolean')
96
+ return 'boolean';
97
+ if (Array.isArray(value)) {
98
+ const members = [...new Set(value.map((item) => configType(item, depth + 1)))];
99
+ return 'readonly (' + (members.join(' | ') || 'JsonValue') + ')[]';
100
+ }
101
+ const fields = Object.entries(value).map(([key, child]) => 'readonly ' + JSON.stringify(key) + ': ' + configType(child, depth + 1) + ';');
102
+ return '{ ' + fields.join(' ') + ' }';
103
+ }
104
+ async function writeConfigTypes(root, config) {
105
+ const path = resolve(root, '.ceru-dev/types/plugin-config.d.ts');
106
+ const source = "declare module '@ceru/plugin-config' {\n" +
107
+ " type JsonValue = import('@shiqianjiang/ceru-plugin-sdk').JsonValue\n" +
108
+ ' export type PluginConfig = ' +
109
+ configType(config) +
110
+ '\n const config: PluginConfig\n export default config\n}\n';
111
+ await mkdir(dirname(path), { recursive: true });
112
+ await writeFile(path, source);
113
+ return path;
114
+ }
115
+ function entryFunctionName(id, suffix) {
116
+ const words = id.split(/[^a-zA-Z0-9]+/).filter(Boolean);
117
+ const name = words
118
+ .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
119
+ .join('');
120
+ const base = name || 'Plugin';
121
+ return base.startsWith(suffix) || base.endsWith(suffix) ? base : base + suffix;
122
+ }
12
123
  export async function writeAtomic(path, data, overwrite = false, mode = 0o644) {
13
124
  await mkdir(dirname(path), { recursive: true });
14
125
  if (!overwrite) {
@@ -40,10 +151,16 @@ async function inside(root, path) {
40
151
  }
41
152
  export async function loadProject(project) {
42
153
  const root = await realpath(resolve(project));
43
- const raw = parseJsonStrict(await readFile(resolve(root, 'ceru.plugin.json'), 'utf8'));
154
+ const source = parseJsonStrict(await readFile(resolve(root, 'ceru.plugin.json'), 'utf8'));
155
+ const expanded = await resolveConfigValue(root, source);
156
+ if (!expanded || typeof expanded !== 'object' || Array.isArray(expanded))
157
+ throw new Error('ceru.plugin.json must resolve to an object');
158
+ const raw = expanded;
44
159
  for (const key of Object.keys(raw))
45
160
  if (![
161
+ '$schema',
46
162
  'manifest',
163
+ 'config',
47
164
  'entries',
48
165
  'resources',
49
166
  'output',
@@ -56,6 +173,11 @@ export async function loadProject(project) {
56
173
  // to standalone bundles, without requiring authors to rewrite their source.
57
174
  if (raw.manifest?.engines)
58
175
  delete raw.manifest.engines.libraries;
176
+ if (raw.config !== undefined && raw.manifest?.config !== undefined)
177
+ throw new Error('Define config either at the project root or manifest.config, not both');
178
+ raw.config = validatePluginConfig(raw.config ?? raw.manifest?.config);
179
+ if (raw.config !== undefined)
180
+ raw.manifest.config = raw.config;
59
181
  if (raw.framework && !['vanilla', 'vue', 'react'].includes(raw.framework))
60
182
  throw new Error('Unsupported framework');
61
183
  validateManifest(raw.manifest);
@@ -69,13 +191,16 @@ export async function loadProject(project) {
69
191
  }
70
192
  return { root, config: raw };
71
193
  }
72
- function checkTypes(root) {
194
+ function checkTypes(root, extraFiles = []) {
73
195
  const path = resolve(root, 'tsconfig.json');
74
196
  const read = ts.readConfigFile(path, ts.sys.readFile);
75
197
  if (read.error)
76
198
  throw new Error(ts.flattenDiagnosticMessageText(read.error.messageText, '\n'));
77
199
  const config = ts.parseJsonConfigFileContent(read.config, ts.sys, root);
78
- const program = ts.createProgram(config.fileNames, { ...config.options, noEmit: true });
200
+ const program = ts.createProgram([...new Set([...config.fileNames, ...extraFiles])], {
201
+ ...config.options,
202
+ noEmit: true,
203
+ });
79
204
  const diagnostics = [...config.errors, ...ts.getPreEmitDiagnostics(program)];
80
205
  if (diagnostics.length) {
81
206
  throw new Error(ts.formatDiagnosticsWithColorAndContext(diagnostics, {
@@ -94,10 +219,14 @@ export async function buildProject(project = '.', options = {}) {
94
219
  if (result.status !== 0)
95
220
  throw new Error(result.stdout + result.stderr);
96
221
  }
97
- const program = checkTypes(root);
222
+ const configTypes = await writeConfigTypes(root, config.config ?? {});
223
+ const program = checkTypes(root, [configTypes]);
98
224
  const checker = program.getTypeChecker();
99
225
  const chunks = new Map();
100
226
  const devModules = {};
227
+ const surfaceEntries = new Set((config.manifest.modules.surfaces ?? [])
228
+ .filter((surface) => surface.kind === 'web')
229
+ .map((surface) => surface.entry));
101
230
  const plugins = [hostModulesPlugin(), vuePlugin(root, config.framework), stylesheetPlugin()];
102
231
  const defines = {
103
232
  'process.env.NODE_ENV': '"production"',
@@ -151,9 +280,15 @@ export async function buildProject(project = '.', options = {}) {
151
280
  for (const info of Object.values(result.metafile.outputs))
152
281
  if (info.imports.length)
153
282
  throw new Error('Unbundled import in ' + id);
154
- const source = result.outputFiles[0].text;
283
+ const source = result.outputFiles[0].text.replace(/(^|\n)var __ceru_entry =/, '$1const __ceru_entry =');
155
284
  assertBundledDependencies(source);
156
- chunks.set(id, 'async function(ctx) {\n' +
285
+ chunks.set(id, 'async function ' +
286
+ entryFunctionName(id, id === config.manifest.modules.logic?.entry
287
+ ? 'Logic'
288
+ : surfaceEntries.has(id)
289
+ ? 'Surface'
290
+ : 'Module') +
291
+ '(ctx) {\n' +
157
292
  source +
158
293
  '\nif (typeof __ceru_entry.default !== "function") throw new Error("Entry must default-export a function");\nreturn __ceru_entry.default(ctx);\n}');
159
294
  if (options.development) {
@@ -212,9 +347,10 @@ export async function buildProject(project = '.', options = {}) {
212
347
  const result = await build(base);
213
348
  if (result.outputFiles.length !== 1)
214
349
  throw new Error('webDist emitted an external file');
215
- assertBundledDependencies(result.outputFiles[0].text);
216
- chunks.set(id, 'async function(ctx) {\n' +
217
- result.outputFiles[0].text +
350
+ const source = result.outputFiles[0].text.replace(/(^|\n)var __ceru_entry =/, '$1const __ceru_entry =');
351
+ assertBundledDependencies(source);
352
+ chunks.set(id, 'async function ' + entryFunctionName(id, 'Surface') + '(ctx) {\n' +
353
+ source +
218
354
  '\nreturn __ceru_entry.default(ctx);\n}');
219
355
  if (options.development) {
220
356
  const debug = await build({
@@ -262,7 +398,7 @@ export async function buildProject(project = '.', options = {}) {
262
398
  const logic = chunks.get(logicEntry);
263
399
  if (!logic)
264
400
  throw new Error('Missing compiled logic entry: ' + logicEntry);
265
- body.push('exports.activate = ' + logic + ';');
401
+ body.push('// Invisible plugin logic\nexports.activate = ' + logic + ';');
266
402
  emitted.add(logicEntry);
267
403
  }
268
404
  const visibleSurfaces = (config.manifest.modules.surfaces ?? []).filter((surface) => surface.kind === 'web');
@@ -274,14 +410,14 @@ export async function buildProject(project = '.', options = {}) {
274
410
  emitted.add(surface.entry);
275
411
  return JSON.stringify(surface.id) + ': ' + entry;
276
412
  });
277
- body.push('exports.surfaces = {\n' + entries.join(',\n') + '\n};');
413
+ body.push('// Visible plugin surfaces\nexports.surfaces = {\n' + entries.join(',\n') + '\n};');
278
414
  }
279
415
  const modules = [...chunks].filter(([id]) => !emitted.has(id));
280
416
  if (modules.length)
281
- body.push('exports.modules = {\n' +
417
+ body.push('// Additional plugin modules\nexports.modules = {\n' +
282
418
  modules.map(([id, entry]) => JSON.stringify(id) + ': ' + entry).join(',\n') +
283
419
  '\n};');
284
- body.push('exports.resources = ' + JSON.stringify(resources) + ';');
420
+ body.push('// Embedded static resources\nexports.resources = ' + JSON.stringify(resources) + ';');
285
421
  const header = {
286
422
  formatVersion: 2,
287
423
  syntax: 'js',
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@shiqianjiang/ceru-plugin-cli",
3
- "version": "0.2.2",
3
+ "version": "0.2.4",
4
4
  "description": "TypeScript scaffolding, single-file build, watch, validation, signing and issuance for Ceru plugins",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -13,7 +13,7 @@
13
13
  }
14
14
  },
15
15
  "bin": {
16
- "ceru-plugin": "./dist/bin.js"
16
+ "ceru-plugin": "dist/bin.js"
17
17
  },
18
18
  "files": [
19
19
  "dist",
@@ -32,8 +32,8 @@
32
32
  },
33
33
  "dependencies": {
34
34
  "@babel/core": "^7.29.7",
35
- "@shiqianjiang/ceru-plugin-issuer": "0.2.1",
36
- "@shiqianjiang/ceru-plugin-sdk": "0.2.1",
35
+ "@shiqianjiang/ceru-plugin-issuer": "0.2.2",
36
+ "@shiqianjiang/ceru-plugin-sdk": "0.2.2",
37
37
  "@vue/babel-plugin-jsx": "^2.0.1",
38
38
  "@vue/compiler-sfc": "3.5.43",
39
39
  "axios": "^1.20.0",
@@ -3,6 +3,10 @@
3
3
  "title": "Ceru Plugin Build Configuration",
4
4
  "type": "object",
5
5
  "properties": {
6
+ "$schema": {
7
+ "type": "string",
8
+ "description": "Optional editor schema reference; ignored by the build runtime."
9
+ },
6
10
  "manifest": {
7
11
  "type": "object",
8
12
  "properties": {
@@ -42,6 +46,10 @@
42
46
  "minLength": 1,
43
47
  "maxLength": 4096
44
48
  },
49
+ "config": {
50
+ "type": "object",
51
+ "additionalProperties": true
52
+ },
45
53
  "engines": {
46
54
  "type": "object",
47
55
  "properties": {
@@ -880,6 +888,20 @@
880
888
  ],
881
889
  "additionalProperties": false
882
890
  },
891
+ "config": {
892
+ "oneOf": [
893
+ {
894
+ "type": "object",
895
+ "description": "JSON-compatible defaults exposed through ctx.config.",
896
+ "additionalProperties": true
897
+ },
898
+ {
899
+ "type": "string",
900
+ "pattern": "^@.+",
901
+ "description": "Build-time JSON/JS/TS config reference, for example @./src/plugin.config.ts."
902
+ }
903
+ ]
904
+ },
883
905
  "entries": {
884
906
  "type": "object",
885
907
  "description": "Map stable module IDs to TS/TSX/JS source files",
@@ -11,10 +11,10 @@
11
11
  "preview": "ceru-plugin preview dist/plugin.js"
12
12
  },
13
13
  "dependencies": {
14
- "@shiqianjiang/ceru-plugin-sdk": "^0.2.1"
14
+ "@shiqianjiang/ceru-plugin-sdk": "^0.2.2"
15
15
  },
16
16
  "devDependencies": {
17
- "@shiqianjiang/ceru-plugin-cli": "^0.2.2",
17
+ "@shiqianjiang/ceru-plugin-cli": "^0.2.4",
18
18
  "typescript": "~5.9.3",
19
19
  "electron": "^44.4.2",
20
20
  "prettier": "^3.6.2"
@@ -12,5 +12,5 @@
12
12
  "types": [],
13
13
  "jsx": "react-jsx"
14
14
  },
15
- "include": ["src"]
15
+ "include": ["src", ".ceru-dev/types/**/*.d.ts"]
16
16
  }
@@ -11,10 +11,10 @@
11
11
  "preview": "ceru-plugin preview dist/plugin.js"
12
12
  },
13
13
  "dependencies": {
14
- "@shiqianjiang/ceru-plugin-sdk": "^0.2.1"
14
+ "@shiqianjiang/ceru-plugin-sdk": "^0.2.2"
15
15
  },
16
16
  "devDependencies": {
17
- "@shiqianjiang/ceru-plugin-cli": "^0.2.2",
17
+ "@shiqianjiang/ceru-plugin-cli": "^0.2.4",
18
18
  "typescript": "~5.9.3",
19
19
  "electron": "^44.4.2",
20
20
  "prettier": "^3.6.2"
@@ -12,5 +12,5 @@
12
12
  "types": [],
13
13
  "jsx": "react-jsx"
14
14
  },
15
- "include": ["src"]
15
+ "include": ["src", ".ceru-dev/types/**/*.d.ts"]
16
16
  }
@@ -11,10 +11,10 @@
11
11
  "preview": "ceru-plugin preview dist/plugin.js"
12
12
  },
13
13
  "dependencies": {
14
- "@shiqianjiang/ceru-plugin-sdk": "^0.2.1"
14
+ "@shiqianjiang/ceru-plugin-sdk": "^0.2.2"
15
15
  },
16
16
  "devDependencies": {
17
- "@shiqianjiang/ceru-plugin-cli": "^0.2.2",
17
+ "@shiqianjiang/ceru-plugin-cli": "^0.2.4",
18
18
  "typescript": "~5.9.3",
19
19
  "electron": "^44.4.2",
20
20
  "prettier": "^3.6.2"
@@ -12,5 +12,5 @@
12
12
  "types": [],
13
13
  "jsx": "react-jsx"
14
14
  },
15
- "include": ["src"]
15
+ "include": ["src", ".ceru-dev/types/**/*.d.ts"]
16
16
  }
@@ -11,10 +11,10 @@
11
11
  "preview": "ceru-plugin preview dist/plugin.js"
12
12
  },
13
13
  "dependencies": {
14
- "@shiqianjiang/ceru-plugin-sdk": "^0.2.1"
14
+ "@shiqianjiang/ceru-plugin-sdk": "^0.2.2"
15
15
  },
16
16
  "devDependencies": {
17
- "@shiqianjiang/ceru-plugin-cli": "^0.2.2",
17
+ "@shiqianjiang/ceru-plugin-cli": "^0.2.4",
18
18
  "typescript": "~5.9.3",
19
19
  "electron": "^44.4.2",
20
20
  "prettier": "^3.6.2"
@@ -12,5 +12,5 @@
12
12
  "types": [],
13
13
  "jsx": "react-jsx"
14
14
  },
15
- "include": ["src"]
15
+ "include": ["src", ".ceru-dev/types/**/*.d.ts"]
16
16
  }
@@ -11,10 +11,10 @@
11
11
  "preview": "ceru-plugin preview dist/plugin.js"
12
12
  },
13
13
  "dependencies": {
14
- "@shiqianjiang/ceru-plugin-sdk": "^0.2.1"
14
+ "@shiqianjiang/ceru-plugin-sdk": "^0.2.2"
15
15
  },
16
16
  "devDependencies": {
17
- "@shiqianjiang/ceru-plugin-cli": "^0.2.2",
17
+ "@shiqianjiang/ceru-plugin-cli": "^0.2.4",
18
18
  "typescript": "~5.9.3",
19
19
  "electron": "^44.4.2",
20
20
  "prettier": "^3.6.2"
@@ -12,5 +12,5 @@
12
12
  "types": [],
13
13
  "jsx": "react-jsx"
14
14
  },
15
- "include": ["src"]
15
+ "include": ["src", ".ceru-dev/types/**/*.d.ts"]
16
16
  }
@@ -11,10 +11,10 @@
11
11
  "preview": "ceru-plugin preview dist/plugin.js"
12
12
  },
13
13
  "dependencies": {
14
- "@shiqianjiang/ceru-plugin-sdk": "^0.2.1"
14
+ "@shiqianjiang/ceru-plugin-sdk": "^0.2.2"
15
15
  },
16
16
  "devDependencies": {
17
- "@shiqianjiang/ceru-plugin-cli": "^0.2.2",
17
+ "@shiqianjiang/ceru-plugin-cli": "^0.2.4",
18
18
  "typescript": "~5.9.3",
19
19
  "electron": "^44.4.2",
20
20
  "prettier": "^3.6.2"
@@ -12,5 +12,5 @@
12
12
  "types": [],
13
13
  "jsx": "react-jsx"
14
14
  },
15
- "include": ["src"]
15
+ "include": ["src", ".ceru-dev/types/**/*.d.ts"]
16
16
  }
@@ -11,10 +11,10 @@
11
11
  "preview": "ceru-plugin preview dist/plugin.js"
12
12
  },
13
13
  "dependencies": {
14
- "@shiqianjiang/ceru-plugin-sdk": "^0.2.1"
14
+ "@shiqianjiang/ceru-plugin-sdk": "^0.2.2"
15
15
  },
16
16
  "devDependencies": {
17
- "@shiqianjiang/ceru-plugin-cli": "^0.2.2",
17
+ "@shiqianjiang/ceru-plugin-cli": "^0.2.4",
18
18
  "typescript": "~5.9.3",
19
19
  "electron": "^44.4.2",
20
20
  "prettier": "^3.6.2",
@@ -12,5 +12,5 @@
12
12
  "types": [],
13
13
  "jsx": "react-jsx"
14
14
  },
15
- "include": ["src"]
15
+ "include": ["src", ".ceru-dev/types/**/*.d.ts"]
16
16
  }
@@ -11,10 +11,10 @@
11
11
  "preview": "ceru-plugin preview dist/plugin.js"
12
12
  },
13
13
  "dependencies": {
14
- "@shiqianjiang/ceru-plugin-sdk": "^0.2.1"
14
+ "@shiqianjiang/ceru-plugin-sdk": "^0.2.2"
15
15
  },
16
16
  "devDependencies": {
17
- "@shiqianjiang/ceru-plugin-cli": "^0.2.2",
17
+ "@shiqianjiang/ceru-plugin-cli": "^0.2.4",
18
18
  "typescript": "~5.9.3",
19
19
  "electron": "^44.4.2",
20
20
  "prettier": "^3.6.2",
@@ -12,5 +12,5 @@
12
12
  "types": [],
13
13
  "jsx": "react-jsx"
14
14
  },
15
- "include": ["src"]
15
+ "include": ["src", ".ceru-dev/types/**/*.d.ts"]
16
16
  }
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "version": 1,
3
3
  "source": "https://github.com/CeruMusic/CeruMusic-Plugin-Template",
4
- "digest": "sha256:eb68b7d77e117cdbc4cf8e9fff3b0bc5d99d5aa67d962f5821ebdbb16960c63e",
4
+ "digest": "sha256:1d272f9254f1249079611b29f59837e3277de70d40c911da207bdd935258f415",
5
5
  "files": [
6
6
  "connected-library/js/_gitignore",
7
7
  "connected-library/js/.prettierrc.json",
@@ -19,6 +19,10 @@ VS Code 按 F5 选择 Launch Ceru plugin;已有调试窗口时选择 Attach to
19
19
  激活代码已经执行时,可点击“重新运行”再次命中断点。
20
20
  配置文件有 JSON Schema 提示,SDK 提供参数类型、图标名称与 Lodash 方法补全。
21
21
 
22
+ `ceru.plugin.json` 的 `config` 直接写普通对象。业务代码可用
23
+ `import('@ceru/plugin-config').PluginConfig` 声明配置类型。dev/build 会生成不含值的
24
+ `.ceru-dev/types/plugin-config.d.ts`,JSDoc 可引用 `@ceru/plugin-config`。
25
+
22
26
  ## 宿主资源
23
27
 
24
28
  - 平台图标:icon: { kind: 'host', name: 'platform.tx' }。
@@ -52,6 +52,16 @@
52
52
  "state": 1
53
53
  }
54
54
  },
55
+ "config": {
56
+ "displayName": "Ceru Demo",
57
+ "apiOrigin": "https://music.example.com",
58
+ "sources": {
59
+ "demo": {
60
+ "name": "Demo Source",
61
+ "qualities": ["320k", "flac"]
62
+ }
63
+ }
64
+ },
55
65
  "entries": {
56
66
  "logic.main": "src/index.js"
57
67
  },
@@ -11,10 +11,10 @@
11
11
  "preview": "ceru-plugin preview dist/plugin.js"
12
12
  },
13
13
  "dependencies": {
14
- "@shiqianjiang/ceru-plugin-sdk": "^0.2.1"
14
+ "@shiqianjiang/ceru-plugin-sdk": "^0.2.2"
15
15
  },
16
16
  "devDependencies": {
17
- "@shiqianjiang/ceru-plugin-cli": "^0.2.2",
17
+ "@shiqianjiang/ceru-plugin-cli": "^0.2.4",
18
18
  "typescript": "~5.9.3",
19
19
  "electron": "^44.4.2",
20
20
  "prettier": "^3.6.2"
@@ -1,5 +1,7 @@
1
1
  import { definePlugin } from '@shiqianjiang/ceru-plugin-sdk'
2
2
 
3
+ /** @typedef {import('@ceru/plugin-config').PluginConfig} PluginConfig */
4
+
3
5
  // 本地演示数据。请在接入真实音源时声明所需的网络权限。
4
6
  const tracks = [
5
7
  { id: 'morning', title: 'Morning Light', artist: 'Ceru Demo' },
@@ -7,12 +9,14 @@ const tracks = [
7
9
  { id: 'night', title: 'Night Walk', artist: 'Ceru Demo' },
8
10
  ]
9
11
 
10
- export default definePlugin((ctx) => {
12
+ export default definePlugin(async (ctx) => {
13
+ /** @type {Readonly<PluginConfig>} */
14
+ const config = await ctx.config.get()
11
15
  ctx.actions.register('hello', async () => {
12
16
  await ctx.ui.notify({
13
17
  key: 'welcome',
14
18
  level: 'info',
15
- message: '演示插件已就绪。试试搜索 Morning、Rain 或 Night。',
19
+ message: `${config.displayName} 已就绪。试试搜索 Morning、Rain 或 Night。`,
16
20
  })
17
21
  })
18
22
 
@@ -0,0 +1,14 @@
1
+ import { definePluginConfig } from '@shiqianjiang/ceru-plugin-sdk'
2
+
3
+ const losslessQualities = ['flac']
4
+
5
+ export default definePluginConfig({
6
+ displayName: 'Ceru Demo',
7
+ apiOrigin: 'https://music.example.com',
8
+ sources: {
9
+ demo: {
10
+ name: 'Demo Source',
11
+ qualities: ['320k', ...losslessQualities],
12
+ },
13
+ },
14
+ })
@@ -12,5 +12,5 @@
12
12
  "types": [],
13
13
  "jsx": "react-jsx"
14
14
  },
15
- "include": ["src"]
15
+ "include": ["src", ".ceru-dev/types/**/*.d.ts"]
16
16
  }
@@ -19,6 +19,11 @@ VS Code 按 F5 选择 Launch Ceru plugin;已有调试窗口时选择 Attach to
19
19
  激活代码已经执行时,可点击“重新运行”再次命中断点。
20
20
  配置文件有 JSON Schema 提示,SDK 提供参数类型、图标名称与 Lodash 方法补全。
21
21
 
22
+ `ceru.plugin.json` 的 `config` 直接写普通对象,业务代码从
23
+ `@ceru/plugin-config` 导入自动生成的 `PluginConfig`,再通过
24
+ `await ctx.config.get<PluginConfig>()` 读取。dev/build 会生成不含值的
25
+ `.ceru-dev/types/plugin-config.d.ts`;可从 `@ceru/plugin-config` 导入 `PluginConfig`。
26
+
22
27
  ## 宿主资源
23
28
 
24
29
  - 平台图标:icon: { kind: 'host', name: 'platform.tx' }。
@@ -52,6 +52,16 @@
52
52
  "state": 1
53
53
  }
54
54
  },
55
+ "config": {
56
+ "displayName": "Ceru Demo",
57
+ "apiOrigin": "https://music.example.com",
58
+ "sources": {
59
+ "demo": {
60
+ "name": "Demo Source",
61
+ "qualities": ["320k", "flac"]
62
+ }
63
+ }
64
+ },
55
65
  "entries": {
56
66
  "logic.main": "src/index.ts"
57
67
  },
@@ -11,10 +11,10 @@
11
11
  "preview": "ceru-plugin preview dist/plugin.js"
12
12
  },
13
13
  "dependencies": {
14
- "@shiqianjiang/ceru-plugin-sdk": "^0.2.1"
14
+ "@shiqianjiang/ceru-plugin-sdk": "^0.2.2"
15
15
  },
16
16
  "devDependencies": {
17
- "@shiqianjiang/ceru-plugin-cli": "^0.2.2",
17
+ "@shiqianjiang/ceru-plugin-cli": "^0.2.4",
18
18
  "typescript": "~5.9.3",
19
19
  "electron": "^44.4.2",
20
20
  "prettier": "^3.6.2"
@@ -1,4 +1,5 @@
1
1
  import { definePlugin } from '@shiqianjiang/ceru-plugin-sdk'
2
+ import type { PluginConfig } from '@ceru/plugin-config'
2
3
 
3
4
  // 本地演示数据。请在接入真实音源时声明所需的网络权限。
4
5
  const tracks = [
@@ -7,12 +8,13 @@ const tracks = [
7
8
  { id: 'night', title: 'Night Walk', artist: 'Ceru Demo' },
8
9
  ]
9
10
 
10
- export default definePlugin((ctx) => {
11
+ export default definePlugin(async (ctx) => {
12
+ const config = await ctx.config.get<PluginConfig>()
11
13
  ctx.actions.register('hello', async () => {
12
14
  await ctx.ui.notify({
13
15
  key: 'welcome',
14
16
  level: 'info',
15
- message: '演示插件已就绪。试试搜索 Morning、Rain 或 Night。',
17
+ message: `${config.displayName} 已就绪。试试搜索 Morning、Rain 或 Night。`,
16
18
  })
17
19
  })
18
20
 
@@ -0,0 +1,14 @@
1
+ import { definePluginConfig } from '@shiqianjiang/ceru-plugin-sdk'
2
+
3
+ const losslessQualities = ['flac'] as const
4
+
5
+ export default definePluginConfig({
6
+ displayName: 'Ceru Demo',
7
+ apiOrigin: 'https://music.example.com',
8
+ sources: {
9
+ demo: {
10
+ name: 'Demo Source',
11
+ qualities: ['320k', ...losslessQualities],
12
+ },
13
+ },
14
+ })
@@ -12,5 +12,5 @@
12
12
  "types": [],
13
13
  "jsx": "react-jsx"
14
14
  },
15
- "include": ["src"]
15
+ "include": ["src", ".ceru-dev/types/**/*.d.ts"]
16
16
  }
@@ -11,10 +11,10 @@
11
11
  "preview": "ceru-plugin preview dist/plugin.js"
12
12
  },
13
13
  "dependencies": {
14
- "@shiqianjiang/ceru-plugin-sdk": "^0.2.1"
14
+ "@shiqianjiang/ceru-plugin-sdk": "^0.2.2"
15
15
  },
16
16
  "devDependencies": {
17
- "@shiqianjiang/ceru-plugin-cli": "^0.2.2",
17
+ "@shiqianjiang/ceru-plugin-cli": "^0.2.4",
18
18
  "typescript": "~5.9.3",
19
19
  "electron": "^44.4.2",
20
20
  "prettier": "^3.6.2",
@@ -13,5 +13,5 @@
13
13
  "jsx": "preserve",
14
14
  "jsxImportSource": "vue"
15
15
  },
16
- "include": ["src"]
16
+ "include": ["src", ".ceru-dev/types/**/*.d.ts"]
17
17
  }
@@ -11,10 +11,10 @@
11
11
  "preview": "ceru-plugin preview dist/plugin.js"
12
12
  },
13
13
  "dependencies": {
14
- "@shiqianjiang/ceru-plugin-sdk": "^0.2.1"
14
+ "@shiqianjiang/ceru-plugin-sdk": "^0.2.2"
15
15
  },
16
16
  "devDependencies": {
17
- "@shiqianjiang/ceru-plugin-cli": "^0.2.2",
17
+ "@shiqianjiang/ceru-plugin-cli": "^0.2.4",
18
18
  "typescript": "~5.9.3",
19
19
  "electron": "^44.4.2",
20
20
  "prettier": "^3.6.2",
@@ -13,5 +13,5 @@
13
13
  "jsx": "preserve",
14
14
  "jsxImportSource": "vue"
15
15
  },
16
- "include": ["src"]
16
+ "include": ["src", ".ceru-dev/types/**/*.d.ts"]
17
17
  }
@@ -11,10 +11,10 @@
11
11
  "preview": "ceru-plugin preview dist/plugin.js"
12
12
  },
13
13
  "dependencies": {
14
- "@shiqianjiang/ceru-plugin-sdk": "^0.2.1"
14
+ "@shiqianjiang/ceru-plugin-sdk": "^0.2.2"
15
15
  },
16
16
  "devDependencies": {
17
- "@shiqianjiang/ceru-plugin-cli": "^0.2.2",
17
+ "@shiqianjiang/ceru-plugin-cli": "^0.2.4",
18
18
  "typescript": "~5.9.3",
19
19
  "electron": "^44.4.2",
20
20
  "prettier": "^3.6.2",
@@ -13,5 +13,5 @@
13
13
  "jsx": "preserve",
14
14
  "jsxImportSource": "vue"
15
15
  },
16
- "include": ["src"]
16
+ "include": ["src", ".ceru-dev/types/**/*.d.ts"]
17
17
  }
@@ -11,10 +11,10 @@
11
11
  "preview": "ceru-plugin preview dist/plugin.js"
12
12
  },
13
13
  "dependencies": {
14
- "@shiqianjiang/ceru-plugin-sdk": "^0.2.1"
14
+ "@shiqianjiang/ceru-plugin-sdk": "^0.2.2"
15
15
  },
16
16
  "devDependencies": {
17
- "@shiqianjiang/ceru-plugin-cli": "^0.2.2",
17
+ "@shiqianjiang/ceru-plugin-cli": "^0.2.4",
18
18
  "typescript": "~5.9.3",
19
19
  "electron": "^44.4.2",
20
20
  "prettier": "^3.6.2",
@@ -13,5 +13,5 @@
13
13
  "jsx": "preserve",
14
14
  "jsxImportSource": "vue"
15
15
  },
16
- "include": ["src"]
16
+ "include": ["src", ".ceru-dev/types/**/*.d.ts"]
17
17
  }
@@ -11,10 +11,10 @@
11
11
  "preview": "ceru-plugin preview dist/plugin.js"
12
12
  },
13
13
  "dependencies": {
14
- "@shiqianjiang/ceru-plugin-sdk": "^0.2.1"
14
+ "@shiqianjiang/ceru-plugin-sdk": "^0.2.2"
15
15
  },
16
16
  "devDependencies": {
17
- "@shiqianjiang/ceru-plugin-cli": "^0.2.2",
17
+ "@shiqianjiang/ceru-plugin-cli": "^0.2.4",
18
18
  "typescript": "~5.9.3",
19
19
  "electron": "^44.4.2",
20
20
  "prettier": "^3.6.2"
@@ -12,5 +12,5 @@
12
12
  "types": [],
13
13
  "jsx": "react-jsx"
14
14
  },
15
- "include": ["src"]
15
+ "include": ["src", ".ceru-dev/types/**/*.d.ts"]
16
16
  }
@@ -11,10 +11,10 @@
11
11
  "preview": "ceru-plugin preview dist/plugin.js"
12
12
  },
13
13
  "dependencies": {
14
- "@shiqianjiang/ceru-plugin-sdk": "^0.2.1"
14
+ "@shiqianjiang/ceru-plugin-sdk": "^0.2.2"
15
15
  },
16
16
  "devDependencies": {
17
- "@shiqianjiang/ceru-plugin-cli": "^0.2.2",
17
+ "@shiqianjiang/ceru-plugin-cli": "^0.2.4",
18
18
  "typescript": "~5.9.3",
19
19
  "electron": "^44.4.2",
20
20
  "prettier": "^3.6.2"
@@ -12,5 +12,5 @@
12
12
  "types": [],
13
13
  "jsx": "react-jsx"
14
14
  },
15
- "include": ["src"]
15
+ "include": ["src", ".ceru-dev/types/**/*.d.ts"]
16
16
  }
@@ -11,10 +11,10 @@
11
11
  "preview": "ceru-plugin preview dist/plugin.js"
12
12
  },
13
13
  "dependencies": {
14
- "@shiqianjiang/ceru-plugin-sdk": "^0.2.1"
14
+ "@shiqianjiang/ceru-plugin-sdk": "^0.2.2"
15
15
  },
16
16
  "devDependencies": {
17
- "@shiqianjiang/ceru-plugin-cli": "^0.2.2",
17
+ "@shiqianjiang/ceru-plugin-cli": "^0.2.4",
18
18
  "typescript": "~5.9.3",
19
19
  "electron": "^44.4.2",
20
20
  "prettier": "^3.6.2"
@@ -12,5 +12,5 @@
12
12
  "types": [],
13
13
  "jsx": "react-jsx"
14
14
  },
15
- "include": ["src"]
15
+ "include": ["src", ".ceru-dev/types/**/*.d.ts"]
16
16
  }
@@ -11,10 +11,10 @@
11
11
  "preview": "ceru-plugin preview dist/plugin.js"
12
12
  },
13
13
  "dependencies": {
14
- "@shiqianjiang/ceru-plugin-sdk": "^0.2.1"
14
+ "@shiqianjiang/ceru-plugin-sdk": "^0.2.2"
15
15
  },
16
16
  "devDependencies": {
17
- "@shiqianjiang/ceru-plugin-cli": "^0.2.2",
17
+ "@shiqianjiang/ceru-plugin-cli": "^0.2.4",
18
18
  "typescript": "~5.9.3",
19
19
  "electron": "^44.4.2",
20
20
  "prettier": "^3.6.2"
@@ -12,5 +12,5 @@
12
12
  "types": [],
13
13
  "jsx": "react-jsx"
14
14
  },
15
- "include": ["src"]
15
+ "include": ["src", ".ceru-dev/types/**/*.d.ts"]
16
16
  }