create-cordisx-plugin 0.1.0-beta.1 → 0.1.0-beta.4

package/README.md

@@ -1,6 +1,6 @@
 # create-cordisx-plugin
 
-Create a minimal trusted-local CordisX plugin project.
+Create trusted-local CordisX plugins in the project shape that fits their use.
 
 ```bash
 npm create cordisx-plugin@beta my-plugin
@@ -11,20 +11,76 @@ npx create-cordisx-plugin@beta my-plugin
 The `@beta` qualifier is required while npm `latest` remains the non-functional
 `0.0.0` package-name reservation.
 
-The generated project includes a version-1 manifest, a structured toolbar
-route, a React page body, TypeScript build, manifest test, and
-`cordisx dev --dry-run` script. The plugin installs only `cordisx`: React,
-React DOM, their types, JSX runtimes, and the initial CordisX component set are
-provided by the Host through `cordisx/react` and `cordisx/ui`. Plugin artifacts
-that bundle a private React copy are rejected.
+The positional command remains the short path for one standalone plugin. Two
+explicit modes cover larger project shapes:
+
+```bash
+# A dedicated repository containing several independent plugin packages.
+npx create-cordisx-plugin@beta --mode workspace my-suite \
+  --plugin chatroom --plugin calendar
+
+# Add a CordisX development package to an existing business project.
+npx create-cordisx-plugin@beta --mode embedded ./my-business-project \
+  --plugin incident-room
+```
+
+`workspace` creates one `cordisx.config.json`, one development server command,
+and independently addressable packages under `plugins/<id>`. Use
+`--package-manager pnpm` to also create `pnpm-workspace.yaml`; npm, Yarn, and Bun
+can use the generated `package.json#workspaces` declaration.
+
+`embedded` creates `.cordisx/config.json`, `.cordisx/package.json`, an
+independent `.cordisx/tsconfig.json`, and `.cordisx/plugins/<id>`. Existing
+business files are not replaced. Repeating the command with a new plugin id
+appends that plugin while preserving the existing CordisX package and config
+fields. The config entries are relative to `.cordisx/config.json`.
+
+Embedded mode defaults to `--integration auto`: it joins a detected pnpm,
+npm, Yarn, or Bun workspace, while retaining `.cordisx` as its own package and
+TypeScript boundary. pnpm workspace integration updates the existing
+`pnpm-workspace.yaml`; the other supported workspace shapes update the root
+`package.json#workspaces`. Use `--integration isolated` to keep installation
+inside `.cordisx`, or `--integration workspace` to require an existing
+supported workspace. `--package-manager` makes non-interactive automation
+deterministic. Existing pnpm comments, quoted keys, and block or flow sequence
+styles are preserved. If the workspace YAML cannot be parsed or its `packages`
+value cannot be updated without changing its meaning, creation stops and rolls
+back without changing the business project.
+
+Every generated plugin includes a version-1 manifest, a structured toolbar
+route, and a component-only React page module. Its standalone, workspace, or
+embedded environment supplies typecheck, production Vite build, manifest test,
+and `cordisx dev --dry-run` commands. Production output uses a stable
+`dist/runtime/module.js` entry plus content-addressed `chunks/`, `assets/`, and formal
+`artifact.json`. Declarations remain outside that closed graph in `dist/types/`.
+CSS and static assets remain external files, and dynamic
+imports load their graph only when reached. Workspaces and embedded projects
+build each plugin separately so independently replaceable generations never
+share output chunks.
+
+Every generated production config calls the public
+`cordisx/vite` `cordisXPluginViteConfig()` helper. That reusable author/Host
+pipeline owns the deterministic output rules, virtualizes only the closed Host
+singleton imports, and emits the formal `dist/runtime/artifact.json`. A portable
+CordisX package manifest points its browser entry at the adjacent prebuilt
+`dist/runtime/module.js`; the Host validates and retains that complete indexed graph.
+
+Development remains one CordisX-owned Vite server and HMR graph using the
+original source entries. The environment installs no private React runtime:
+React, React DOM, their types, JSX runtimes, and the initial CordisX component
+set are provided by the Host through `cordisx/react` and `cordisx/ui`. Plugin
+artifacts that bundle a private React copy are rejected.
 
 The generated route and page use closed route-v2/page-v3 documents with real
 localized title and description dictionaries. Canonical ids, path, outlet,
 params, and chrome remain untranslated machine fields. CordisX owns route and
 page chrome, the React root, theme, error boundary, and lifecycle cleanup; the
-plugin owns only the controlled body component. The generator does not install
-to a marketplace, sign the plugin, provide a permission sandbox, or promise
-hot reload.
+plugin owns only the controlled body component. Local component modules are
+laid out as Vite React Fast Refresh boundaries; plugin entry, manifest, and
+`apply()` changes use Cordis lifecycle replacement. Installed production
+packages update through normal package lifecycle rather than development HMR.
+The generator does not install to a marketplace, sign the plugin, or provide a
+permission sandbox.
 
 The `create-cordisx-plugin` tool itself is licensed under
 `AGPL-3.0-or-later`. Files under its marked `template` directory and projects
@@ -33,3 +89,12 @@ An independent plugin using only public, versioned CordisX plugin interfaces
 may be commercial, sold, distributed through a marketplace, and licensed under
 terms chosen by its author. The custom Exception is not a standard SPDX
 exception and should receive legal review before stable.
+
+## CSS authoring
+
+All three modes generate `src/vite-env.d.ts` in each plugin source tree.
+Use side-effect CSS imports in the owning component and keep the complete
+Vite output graph. Explicit `?inline` imports produce text; CSS Modules produce
+class maps only with a compatible Host development transform. Consult the
+[maintained CSS guidance](https://github.com/cordisx/cordisx/blob/main/skills/cordisx-plugin-development/references/css-and-lifecycle.md)
+for ownership, current limitations, and separate HMR/unload verification.

package/dist/cli.js

@@ -1,24 +1,125 @@
 #!/usr/bin/env node
-import { mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { isMap, isScalar, isSeq, parseDocument } from 'yaml';
 const HELP = `Usage:
   npm create cordisx-plugin <directory>
   npx create-cordisx-plugin <directory>
+  create-cordisx-plugin --mode workspace <directory> --plugin <id> [--plugin <id> ...]
+  create-cordisx-plugin --mode embedded <project> --plugin <id> [options]
 
-Creates a minimal trusted-local CordisX plugin project.`;
+Modes:
+  single       Create one standalone plugin project (default)
+  workspace    Create a dedicated multi-plugin workspace
+  embedded     Add one or more plugins under <project>/.cordisx
+
+Options:
+  --plugin <id>                 Plugin id; repeat for multiple plugins
+  --integration <mode>          embedded mode: auto, workspace, or isolated
+  --package-manager <manager>   auto, npm, pnpm, yarn, or bun
+  -h, --help                    Show this help
+
+Embedded mode always creates an independent .cordisx package.json and
+tsconfig.json. With --integration auto it joins an existing workspace when one
+is detected; otherwise it remains an isolated Node project.`;
 function packageName(directory) {
     const normalized = path.basename(path.resolve(directory))
         .normalize('NFKD')
         .toLowerCase()
         .replaceAll(/[^a-z0-9._-]+/g, '-')
         .replace(/^[._-]+|[._-]+$/g, '')
-        .slice(0, 214);
+        .slice(0, 180);
     return normalized === '' ? 'cordisx-plugin' : normalized;
 }
-function pluginId(name) {
+function derivedPluginId(name) {
     return name === 'host' || name.startsWith('cordisx.') ? `local-${name}` : name;
 }
+function explicitPluginId(value) {
+    const id = value.trim();
+    if (!/^[a-z0-9][a-z0-9._-]{0,95}$/.test(id))
+        throw new Error(`invalid plugin id: ${value}`);
+    if (id === 'host' || id.startsWith('cordisx.'))
+        throw new Error(`reserved plugin id: ${id}`);
+    return id;
+}
+function optionValue(argv, index, name) {
+    const current = argv[index];
+    const inline = current?.startsWith(`${name}=`) === true ? current.slice(name.length + 1) : undefined;
+    if (inline !== undefined) {
+        if (inline === '')
+            throw new Error(`${name} requires a value`);
+        return [inline, index];
+    }
+    const next = argv[index + 1];
+    if (next === undefined || next.startsWith('-'))
+        throw new Error(`${name} requires a value`);
+    return [next, index + 1];
+}
+function choice(value, values, name) {
+    if (!values.includes(value))
+        throw new Error(`${name} must be one of: ${values.join(', ')}`);
+    return value;
+}
+function parseArguments(argv) {
+    if (argv.includes('--help') || argv.includes('-h'))
+        return 'help';
+    let mode = 'single';
+    let integration = 'auto';
+    let packageManager;
+    const plugins = [];
+    const positionals = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === '--mode' || argument.startsWith('--mode=')) {
+            const [value, nextIndex] = optionValue(argv, index, '--mode');
+            mode = choice(value, ['single', 'workspace', 'embedded'], '--mode');
+            index = nextIndex;
+            continue;
+        }
+        if (argument === '--plugin' || argument.startsWith('--plugin=')) {
+            const [value, nextIndex] = optionValue(argv, index, '--plugin');
+            plugins.push(explicitPluginId(value));
+            index = nextIndex;
+            continue;
+        }
+        if (argument === '--integration' || argument.startsWith('--integration=')) {
+            const [value, nextIndex] = optionValue(argv, index, '--integration');
+            integration = choice(value, ['auto', 'workspace', 'isolated'], '--integration');
+            index = nextIndex;
+            continue;
+        }
+        if (argument === '--package-manager' || argument.startsWith('--package-manager=')) {
+            const [value, nextIndex] = optionValue(argv, index, '--package-manager');
+            if (value !== 'auto') {
+                packageManager = choice(value, ['npm', 'pnpm', 'yarn', 'bun'], '--package-manager');
+            }
+            index = nextIndex;
+            continue;
+        }
+        if (argument.startsWith('-'))
+            throw new Error(`unknown option: ${argument}\n\n${HELP}`);
+        positionals.push(argument);
+    }
+    if (positionals.length !== 1)
+        throw new Error(HELP);
+    if (mode === 'single' && plugins.length > 0) {
+        throw new Error('--plugin is only valid with --mode workspace or --mode embedded');
+    }
+    if (mode !== 'embedded' && integration !== 'auto')
+        throw new Error('--integration is only valid with --mode embedded');
+    if (mode !== 'single' && plugins.length === 0)
+        throw new Error(`${mode} mode requires at least one --plugin <id>`);
+    if (new Set(plugins).size !== plugins.length)
+        throw new Error('plugin ids must be unique');
+    return {
+        directory: positionals[0],
+        mode,
+        plugins,
+        integration,
+        ...(packageManager === undefined ? {} : { packageManager }),
+    };
+}
 function replaceTokens(value, replacements) {
     let output = value;
     for (const [token, replacement] of Object.entries(replacements)) {
@@ -26,15 +127,12 @@ function replaceTokens(value, replacements) {
     }
     return output;
 }
-async function targetState(target) {
+async function pathState(target) {
     try {
         const targetStat = await stat(target);
         if (!targetStat.isDirectory())
-            throw new Error(`target exists and is not a directory: ${target}`);
-        const entries = await readdir(target);
-        if (entries.length > 0)
-            throw new Error(`target directory is not empty: ${target}`);
-        return 'empty';
+            return 'file';
+        return (await readdir(target)).length === 0 ? 'empty' : 'nonempty';
     }
     catch (error) {
         if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
@@ -42,6 +140,16 @@ async function targetState(target) {
         throw error;
     }
 }
+async function readOptional(file) {
+    try {
+        return await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
 async function renderTemplate(source, destination, replacements) {
     await mkdir(destination, { recursive: true });
     for (const entry of await readdir(source, { withFileTypes: true })) {
@@ -54,28 +162,145 @@ async function renderTemplate(source, destination, replacements) {
         }
         if (!entry.isFile())
             throw new Error(`unsupported template entry: ${input}`);
-        const contents = replaceTokens(await readFile(input, 'utf8'), replacements);
-        await writeFile(output, contents, { encoding: 'utf8', flag: 'wx' });
+        await writeFile(output, replaceTokens(await readFile(input, 'utf8'), replacements), {
+            encoding: 'utf8',
+            flag: 'wx',
+        });
     }
 }
-async function main(argv) {
-    if (argv.includes('--help') || argv.includes('-h')) {
-        console.log(HELP);
-        return;
-    }
-    if (argv.length !== 1 || argv[0]?.startsWith('-'))
-        throw new Error(HELP);
-    const directory = argv[0];
-    if (directory === undefined)
-        throw new Error(HELP);
-    const target = path.resolve(process.cwd(), directory);
-    const state = await targetState(target);
-    const packageRoot = fileURLToPath(new URL('..', import.meta.url));
-    const templateRoot = path.join(packageRoot, 'template');
-    const creatorManifest = JSON.parse(await readFile(path.join(packageRoot, 'package.json'), 'utf8'));
-    if (typeof creatorManifest.version !== 'string' || creatorManifest.version.length === 0) {
-        throw new Error('create-cordisx-plugin package version is invalid');
-    }
+function json(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+function commonCompilerOptions() {
+    return {
+        target: 'ES2022',
+        module: 'NodeNext',
+        moduleResolution: 'NodeNext',
+        jsx: 'react-jsx',
+        jsxImportSource: 'cordisx/react',
+        lib: ['ES2023', 'DOM'],
+        strict: true,
+        declaration: true,
+        forceConsistentCasingInFileNames: true,
+        skipLibCheck: true,
+    };
+}
+function pluginConfig(ids) {
+    return json({
+        version: 1,
+        plugins: ids.map(id => ({ id, entry: `./plugins/${id}/src/index.tsx`, enabled: true, config: {} })),
+    });
+}
+function manifestTest(ids, modulePath) {
+    const imports = ids.map((id, index) => `const plugin${index} = await import('${modulePath(id)}')`).join('\n');
+    const cases = ids.map((id, index) => `  ['${id}', plugin${index}],`).join('\n');
+    return `import assert from 'node:assert/strict'
+import test from 'node:test'
+
+const component = () => null
+const noop = () => undefined
+const React = new Proxy({ Fragment: Symbol('Fragment'), Suspense: component, lazy: () => component }, {
+  get(target, property) { return Reflect.get(target, property) ?? noop },
+})
+globalThis.__cordisxSharedReactRuntime = {
+  React,
+  defineReactPage: page => page,
+  jsxRuntime: { Fragment: React.Fragment, jsx: component, jsxs: component },
+  jsxDevRuntime: { Fragment: React.Fragment, jsxDEV: component },
+  ui: new Proxy({}, { get: () => component }),
+}
+
+${imports}
+
+const plugins = [
+${cases}
+]
+
+test('all configured CordisX plugins export matching manifests', () => {
+  for (const [id, plugin] of plugins) {
+    assert.equal(plugin.manifest.schemaVersion, 1)
+    assert.equal(plugin.manifest.id, id)
+    assert.equal(typeof plugin.apply, 'function')
+  }
+})
+`;
+}
+function projectBuildScript(configName) {
+    return `import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { build } from 'vite'
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const config = JSON.parse(await readFile(path.join(root, '${configName}'), 'utf8'))
+if (config.version !== 1 || !Array.isArray(config.plugins)) throw new Error('CordisX project config must have version 1 and a plugins array')
+const ids = new Set()
+for (const plugin of config.plugins) {
+  if (plugin === null || typeof plugin !== 'object' || typeof plugin.id !== 'string'
+    || !/^[a-z0-9][a-z0-9._-]{0,95}$/.test(plugin.id) || ids.has(plugin.id)) {
+    throw new Error('CordisX project config contains an invalid or duplicated plugin id')
+  }
+  ids.add(plugin.id)
+  await build({ configFile: path.join(root, 'plugins', plugin.id, 'vite.config.ts') })
+}
+`;
+}
+async function renderPluginSource(templateRoot, destination, id, outDir = 'dist/runtime') {
+    const replacements = { packageName: id, pluginId: id, sourceEntry: 'src/index.tsx', outDir };
+    const source = replaceTokens(await readFile(path.join(templateRoot, 'src', '{{packageName}}.tsx'), 'utf8'), replacements);
+    const page = replaceTokens(await readFile(path.join(templateRoot, 'src', 'overview-page.tsx'), 'utf8'), replacements);
+    const viteConfig = replaceTokens(await readFile(path.join(templateRoot, 'vite.config.ts'), 'utf8'), replacements);
+    await mkdir(path.join(destination, 'src'), { recursive: true });
+    await writeFile(path.join(destination, 'src', 'index.tsx'), source, { encoding: 'utf8', flag: 'wx' });
+    await writeFile(path.join(destination, 'src', 'overview-page.tsx'), page, { encoding: 'utf8', flag: 'wx' });
+    await writeFile(path.join(destination, 'src', 'vite-env.d.ts'), await readFile(path.join(templateRoot, 'src', 'vite-env.d.ts'), 'utf8'), { encoding: 'utf8', flag: 'wx' });
+    await writeFile(path.join(destination, 'vite.config.ts'), viteConfig, { encoding: 'utf8', flag: 'wx' });
+    await writeFile(path.join(destination, 'README.md'), `# ${id}\n\nThe local-development lifecycle entry is \`src/index.tsx\`. React page components live in component-only modules such as \`src/overview-page.tsx\` so Vite can apply React Fast Refresh. Production config calls the public \`cordisx/vite\` helper to write one immutable Vite ESM graph with \`module.js\`, content-addressed chunks, CSS, assets, and formal \`artifact.json\` under \`${outDir}/\` relative to this directory. Declarations are emitted separately according to the owning tsconfig. A portable package entry points at the adjacent \`${outDir}/module.js\`; the Host validates and retains the indexed graph.\n\nKeep \`src/vite-env.d.ts\` for Vite CSS types. Ordinary CSS is a side-effect import in its owning component; explicit \`?inline\` yields text. CSS HMR does not prove plugin-unload cleanup. See [CSS guidance](https://github.com/cordisx/cordisx/blob/main/skills/cordisx-plugin-development/references/css-and-lifecycle.md) before changing import forms.\n\nThis plugin starts private and \`UNLICENSED\`. Its generated source is Marked Template Material under the CordisX Independent Plugin Exception; choose a license before distribution.\n`, { encoding: 'utf8', flag: 'wx' });
+    await writeFile(path.join(destination, 'README.zh-Hans.md'), `# ${id}\n\n本地开发的生命周期入口为 \`src/index.tsx\`。React 页面组件位于 \`src/overview-page.tsx\` 等纯组件模块中，因此 Vite 可以应用 React Fast Refresh。生产配置调用公开的 \`cordisx/vite\` helper，在相对于此目录的 \`${outDir}/\` 下生成独立、不可变的 Vite ESM graph，包括 \`module.js\`、带内容摘要的 chunk、CSS、静态资源和正式的 \`artifact.json\`；类型声明按所属 tsconfig 单独输出。可移植 package 的入口指向相邻的 \`${outDir}/module.js\`；Host 会验证并保留该索引 graph。\n\n保留 \`src/vite-env.d.ts\` 提供的 Vite CSS 类型。普通 CSS 使用副作用导入；显式 \`?inline\` 返回文本。CSS HMR 不等于插件卸载回收。更改导入前阅读 [CSS 指导](https://github.com/cordisx/cordisx/blob/main/skills/cordisx-plugin-development/references/css-and-lifecycle.md)。\n\n此插件默认私有且使用 \`UNLICENSED\`。生成源码属于 CordisX 独立插件例外中的已标记模板材料；分发前请选择许可证。\n`, { encoding: 'utf8', flag: 'wx' });
+}
+function pluginPackage(workspaceName, id, cordisxVersion) {
+    return json({
+        name: `${workspaceName}-${id}`.slice(0, 214),
+        version: '0.1.0',
+        private: true,
+        license: 'UNLICENSED',
+        type: 'module',
+        files: ['dist', 'README.md', 'README.zh-Hans.md'],
+        main: './dist/runtime/module.js',
+        types: './dist/types/index.d.ts',
+        exports: {
+            '.': {
+                types: './dist/types/index.d.ts',
+                import: './dist/runtime/module.js',
+                default: './dist/runtime/module.js',
+            },
+        },
+        scripts: {
+            build: 'vite build && tsc -p tsconfig.json --emitDeclarationOnly',
+            typecheck: 'tsc -p tsconfig.json --noEmit',
+        },
+        devDependencies: {
+            '@deepseek-ai/cordis': '4.0.1',
+            cordisx: cordisxVersion,
+            typescript: '^5.9.2',
+            vite: '8.2.2',
+        },
+    });
+}
+function pluginTsconfig() {
+    return json({
+        extends: '../../tsconfig.base.json',
+        compilerOptions: { rootDir: 'src', outDir: 'dist/types', composite: true },
+        include: ['src/**/*.ts', 'src/**/*.tsx'],
+        exclude: ['dist', 'node_modules'],
+    });
+}
+async function createSingle(target, directory, manager, templateRoot, cordisxVersion) {
+    const state = await pathState(target);
+    if (state === 'file')
+        throw new Error(`target exists and is not a directory: ${target}`);
+    if (state === 'nonempty')
+        throw new Error(`target directory is not empty: ${target}`);
     let created = false;
     try {
         if (state === 'missing') {
@@ -83,19 +308,426 @@ async function main(argv) {
             created = true;
         }
         const name = packageName(directory);
+        const id = derivedPluginId(name);
         await renderTemplate(templateRoot, target, {
             packageName: name,
-            pluginId: pluginId(name),
-            cordisxVersion: creatorManifest.version,
+            pluginId: id,
+            cordisxVersion,
+            packageManager: manager,
+            sourceEntry: `src/${id}.tsx`,
+            outDir: 'dist/runtime',
         });
+        if (name !== id)
+            await rename(path.join(target, 'src', `${name}.tsx`), path.join(target, 'src', `${id}.tsx`));
     }
     catch (error) {
-        if (created)
-            await rm(target, { recursive: true, force: true });
+        await rm(target, { recursive: true, force: true });
+        if (!created)
+            await mkdir(target);
         throw error;
     }
-    console.log(`Created CordisX plugin in ${target}`);
-    console.log(`\nNext steps:\n  cd ${directory}\n  npm install\n  npm run check\n  npm run dev:dry-run`);
+}
+async function createWorkspace(target, directory, ids, manager, templateRoot, cordisxVersion) {
+    const state = await pathState(target);
+    if (state === 'file')
+        throw new Error(`target exists and is not a directory: ${target}`);
+    if (state === 'nonempty')
+        throw new Error(`target directory is not empty: ${target}`);
+    let created = false;
+    try {
+        if (state === 'missing') {
+            await mkdir(target, { recursive: false });
+            created = true;
+        }
+        const name = packageName(directory);
+        await writeFile(path.join(target, 'package.json'), json({
+            name,
+            version: '0.1.0',
+            private: true,
+            license: 'UNLICENSED',
+            type: 'module',
+            workspaces: ['plugins/*'],
+            scripts: {
+                build: 'node scripts/build-plugins.mjs && tsc -b --emitDeclarationOnly --force',
+                check: 'tsc -b && node scripts/build-plugins.mjs && tsc -b --emitDeclarationOnly --force && node --test test/plugins.mjs',
+                dev: 'cordisx dev --config ./cordisx.config.json',
+                'dev:dry-run': 'cordisx dev --config ./cordisx.config.json --dry-run',
+                test: 'node --test test/plugins.mjs',
+                typecheck: 'tsc -b',
+            },
+            devDependencies: { cordisx: cordisxVersion, typescript: '^5.9.2', vite: '8.2.2' },
+            engines: { node: '>=22.19' },
+        }), { encoding: 'utf8', flag: 'wx' });
+        await writeFile(path.join(target, 'tsconfig.base.json'), json({ compilerOptions: commonCompilerOptions() }), {
+            encoding: 'utf8',
+            flag: 'wx',
+        });
+        await writeFile(path.join(target, 'tsconfig.json'), json({
+            files: [],
+            references: ids.map(id => ({ path: `./plugins/${id}` })),
+        }), { encoding: 'utf8', flag: 'wx' });
+        await writeFile(path.join(target, 'cordisx.config.json'), pluginConfig(ids), { encoding: 'utf8', flag: 'wx' });
+        await mkdir(path.join(target, 'scripts'), { recursive: true });
+        await writeFile(path.join(target, 'scripts', 'build-plugins.mjs'), projectBuildScript('cordisx.config.json'), {
+            encoding: 'utf8',
+            flag: 'wx',
+        });
+        await writeFile(path.join(target, '.gitignore'), 'node_modules/\ndist/\n*.tsbuildinfo\n', {
+            encoding: 'utf8',
+            flag: 'wx',
+        });
+        await writeFile(path.join(target, 'README.md'), `# ${name}\n\nA dedicated CordisX multi-plugin workspace. Each plugin builds into its own Vite ESM graph so chunks and assets never couple independently replaceable plugin generations.\n\n\`\`\`bash\n${manager} install\n${manager} run check\n${manager} run dev:dry-run\n${manager} run dev\n\`\`\`\n`, { encoding: 'utf8', flag: 'wx' });
+        if (manager === 'pnpm') {
+            await writeFile(path.join(target, 'pnpm-workspace.yaml'), "packages:\n  - 'plugins/*'\n", {
+                encoding: 'utf8',
+                flag: 'wx',
+            });
+        }
+        for (const id of ids) {
+            const pluginRoot = path.join(target, 'plugins', id);
+            await renderPluginSource(templateRoot, pluginRoot, id);
+            await writeFile(path.join(pluginRoot, 'package.json'), pluginPackage(name, id, cordisxVersion), {
+                encoding: 'utf8',
+                flag: 'wx',
+            });
+            await writeFile(path.join(pluginRoot, 'tsconfig.json'), pluginTsconfig(), { encoding: 'utf8', flag: 'wx' });
+        }
+        await mkdir(path.join(target, 'test'), { recursive: true });
+        await writeFile(path.join(target, 'test', 'plugins.mjs'), manifestTest(ids, id => `../plugins/${id}/dist/runtime/module.js`), { encoding: 'utf8', flag: 'wx' });
+    }
+    catch (error) {
+        await rm(target, { recursive: true, force: true });
+        if (!created)
+            await mkdir(target);
+        throw error;
+    }
+}
+function packageManagerFromManifest(contents) {
+    if (contents === undefined)
+        return undefined;
+    const manifest = JSON.parse(contents);
+    if (typeof manifest.packageManager !== 'string')
+        return undefined;
+    const name = manifest.packageManager.split('@')[0];
+    return name === 'npm' || name === 'pnpm' || name === 'yarn' || name === 'bun' ? name : undefined;
+}
+async function detectedPackageManager(projectRoot, manifest) {
+    const declared = packageManagerFromManifest(manifest);
+    if (declared !== undefined)
+        return declared;
+    for (const [file, manager] of [
+        ['pnpm-lock.yaml', 'pnpm'],
+        ['yarn.lock', 'yarn'],
+        ['bun.lock', 'bun'],
+        ['bun.lockb', 'bun'],
+        ['package-lock.json', 'npm'],
+    ]) {
+        if (await readOptional(path.join(projectRoot, file)) !== undefined)
+            return manager;
+    }
+    return 'npm';
+}
+async function detectWorkspace(projectRoot) {
+    for (const file of ['pnpm-workspace.yaml', 'pnpm-workspace.yml']) {
+        const manifestPath = path.join(projectRoot, file);
+        if (await readOptional(manifestPath) !== undefined)
+            return { manager: 'pnpm', kind: 'pnpm-yaml', manifestPath };
+    }
+    const manifestPath = path.join(projectRoot, 'package.json');
+    const contents = await readOptional(manifestPath);
+    if (contents === undefined)
+        return undefined;
+    const manifest = JSON.parse(contents);
+    const workspaces = Array.isArray(manifest.workspaces)
+        ? manifest.workspaces
+        : manifest.workspaces !== null && typeof manifest.workspaces === 'object'
+            ? manifest.workspaces.packages
+            : undefined;
+    if (!Array.isArray(workspaces))
+        return undefined;
+    const manager = await detectedPackageManager(projectRoot, contents);
+    // pnpm intentionally ignores package.json#workspaces; only its YAML file is
+    // evidence that the project is a pnpm workspace.
+    if (manager === 'pnpm')
+        return undefined;
+    return { manager, kind: 'package-json', manifestPath };
+}
+function addPnpmWorkspace(contents, entry) {
+    const normalized = entry.replaceAll('\\', '/');
+    const verifyUpdate = (candidate) => {
+        const updated = parseDocument(candidate, { prettyErrors: true });
+        if (updated.errors.length > 0) {
+            throw new Error('cannot safely update pnpm-workspace.yaml: the updated document did not validate');
+        }
+        const updatedPackages = updated.get('packages', true);
+        if (!isSeq(updatedPackages) || !updatedPackages.items.some(item => isScalar(item) && item.value === normalized)) {
+            throw new Error('cannot safely update pnpm-workspace.yaml: the updated document did not validate');
+        }
+        return candidate;
+    };
+    const document = parseDocument(contents, { keepSourceTokens: true, prettyErrors: true });
+    if (document.errors.length > 0) {
+        throw new Error(`cannot safely update pnpm-workspace.yaml: ${document.errors[0].message}`);
+    }
+    if (!isMap(document.contents)) {
+        throw new Error('cannot safely update pnpm-workspace.yaml: the document root must be a mapping');
+    }
+    const packages = document.get('packages', true);
+    if (packages === undefined && !document.contents.has('packages')) {
+        const range = document.contents.range;
+        if (range === null || range === undefined) {
+            throw new Error('cannot safely update pnpm-workspace.yaml: the root mapping has no editable source range');
+        }
+        const newline = contents.includes('\r\n') ? '\r\n' : '\n';
+        const insertion = `${contents.slice(0, range[1]).endsWith('\n') ? '' : newline}packages:${newline}  - '${normalized.replaceAll("'", "''")}'${newline}`;
+        return verifyUpdate(`${contents.slice(0, range[1])}${insertion}${contents.slice(range[1])}`);
+    }
+    if (!isSeq(packages)) {
+        throw new Error('cannot safely update pnpm-workspace.yaml: packages must be a sequence');
+    }
+    if (packages.anchor !== undefined || packages.tag !== undefined) {
+        throw new Error('cannot safely update pnpm-workspace.yaml: anchored or tagged packages sequences are not supported');
+    }
+    const values = packages.items.map(item => {
+        if (!isScalar(item) || typeof item.value !== 'string') {
+            throw new Error('cannot safely update pnpm-workspace.yaml: every packages entry must be a string');
+        }
+        return item.value;
+    });
+    if (values.includes(normalized))
+        return contents;
+    const range = packages.range;
+    if (range === null || range === undefined) {
+        throw new Error('cannot safely update pnpm-workspace.yaml: packages has no editable source range');
+    }
+    const quoted = `'${normalized.replaceAll("'", "''")}'`;
+    const [start, end] = range;
+    if (packages.flow === true) {
+        const closing = end - 1;
+        if (contents[closing] !== ']') {
+            throw new Error('cannot safely update pnpm-workspace.yaml: packages flow sequence has no closing bracket');
+        }
+        const inner = contents.slice(start + 1, closing);
+        const trailingWhitespace = inner.match(/\s*$/)?.[0] ?? '';
+        const body = inner.slice(0, inner.length - trailingWhitespace.length);
+        const separator = body.trim() === '' || body.trimEnd().endsWith(',') ? '' : ',';
+        const spacing = body === '' || /\s$/.test(body) ? '' : ' ';
+        return verifyUpdate(`${contents.slice(0, start + 1)}${body}${separator}${spacing}${quoted}${trailingWhitespace}${contents.slice(closing)}`);
+    }
+    const source = contents.slice(start, end);
+    const newline = contents.includes('\r\n') ? '\r\n' : '\n';
+    const lineStart = contents.lastIndexOf('\n', start - 1) + 1;
+    const indent = contents.slice(lineStart, start);
+    if (!/^\s*$/.test(indent)) {
+        throw new Error('cannot safely update pnpm-workspace.yaml: packages sequence indentation is ambiguous');
+    }
+    const insertion = source.endsWith('\n') ? `${indent}- ${quoted}${newline}` : `${newline}${indent}- ${quoted}`;
+    return verifyUpdate(`${contents.slice(0, end)}${insertion}${contents.slice(end)}`);
+}
+function addPackageWorkspace(contents, entry) {
+    const manifest = JSON.parse(contents);
+    const current = manifest.workspaces;
+    if (Array.isArray(current)) {
+        if (!current.includes(entry))
+            manifest.workspaces = [...current, entry];
+    }
+    else if (current !== null && typeof current === 'object' && Array.isArray(current.packages)) {
+        const packages = current.packages;
+        if (!packages.includes(entry))
+            manifest.workspaces = { ...current, packages: [...packages, entry] };
+    }
+    else {
+        throw new Error('project package.json has an unsupported workspaces declaration');
+    }
+    return json(manifest);
+}
+function embeddedPackage(projectName, cordisxVersion, packageManagerSpec) {
+    return json({
+        name: `${projectName}-cordisx-development`.slice(0, 214),
+        private: true,
+        license: 'UNLICENSED',
+        type: 'module',
+        ...(packageManagerSpec === undefined ? {} : { packageManager: packageManagerSpec }),
+        scripts: {
+            build: 'node scripts/build-plugins.mjs && tsc -p tsconfig.json --emitDeclarationOnly',
+            check: 'tsc -p tsconfig.json --noEmit && node scripts/build-plugins.mjs && tsc -p tsconfig.json --emitDeclarationOnly && node --test test/*.mjs',
+            dev: 'cordisx dev --config ./config.json',
+            'dev:dry-run': 'cordisx dev --config ./config.json --dry-run',
+            test: 'node --test test/*.mjs',
+            typecheck: 'tsc -p tsconfig.json --noEmit',
+        },
+        devDependencies: {
+            '@deepseek-ai/cordis': '4.0.1',
+            cordisx: cordisxVersion,
+            typescript: '^5.9.2',
+            vite: '8.2.2',
+        },
+        engines: { node: '>=22.19' },
+    });
+}
+function embeddedTsconfig() {
+    return json({
+        compilerOptions: { ...commonCompilerOptions(), rootDir: 'plugins', outDir: 'dist/types' },
+        include: ['plugins/**/*.ts', 'plugins/**/*.tsx'],
+        exclude: ['dist', 'node_modules'],
+    });
+}
+function embeddedReadme(manager, integrated) {
+    const install = integrated
+        ? `Run \`${manager} install\` from the containing workspace root.`
+        : manager === 'pnpm'
+            ? 'Run `pnpm install --ignore-workspace` in this directory.'
+            : `Run \`${manager} install\` in this directory.`;
+    return `# Project CordisX development\n\nThis directory is an independent Node and TypeScript boundary for CordisX plugins embedded in the containing business project. Each configured plugin builds into its own Vite ESM graph under \`dist/runtime/<plugin-id>/\`, while declarations stay in \`dist/types/\`; production chunks and assets do not cross plugin generation boundaries.\n\n${install}\n\nThen run \`${manager} run check\`, \`${manager} run dev:dry-run\`, or \`${manager} run dev\` here.\n`;
+}
+async function existingEmbeddedConfig(file) {
+    const contents = await readOptional(file);
+    if (contents === undefined)
+        return { value: { version: 1, plugins: [] }, ids: [] };
+    const value = JSON.parse(contents);
+    if (value.version !== 1 || !Array.isArray(value.plugins)) {
+        throw new Error(`${file} is not a version-1 CordisX project config`);
+    }
+    const ids = value.plugins.map((plugin, index) => {
+        if (plugin === null || typeof plugin !== 'object' || typeof plugin.id !== 'string') {
+            throw new Error(`${file} plugins[${index}] is invalid`);
+        }
+        return plugin.id;
+    });
+    return { value, ids };
+}
+async function createEmbedded(target, ids, requestedIntegration, requestedManager, templateRoot, cordisxVersion) {
+    const state = await pathState(target);
+    if (state === 'missing')
+        throw new Error(`embedded project does not exist: ${target}`);
+    if (state === 'file')
+        throw new Error(`embedded target is not a directory: ${target}`);
+    const projectManifest = await readOptional(path.join(target, 'package.json'));
+    const workspace = await detectWorkspace(target);
+    const integrated = requestedIntegration === 'workspace'
+        || (requestedIntegration === 'auto' && workspace !== undefined);
+    if (integrated && workspace === undefined) {
+        throw new Error('workspace integration requested, but the project has no supported workspace declaration');
+    }
+    if (integrated && requestedManager !== undefined && requestedManager !== workspace.manager) {
+        throw new Error(`detected ${workspace.manager} workspace does not match --package-manager ${requestedManager}`);
+    }
+    const manager = requestedManager ?? workspace?.manager ?? await detectedPackageManager(target, projectManifest);
+    const declaredManagerSpec = projectManifest === undefined
+        ? undefined
+        : JSON.parse(projectManifest).packageManager;
+    const isolatedManagerSpec = !integrated
+        && typeof declaredManagerSpec === 'string'
+        && declaredManagerSpec.startsWith(`${manager}@`)
+        ? declaredManagerSpec
+        : undefined;
+    const cordisxRoot = path.join(target, '.cordisx');
+    const cordisxRootWasMissing = await pathState(cordisxRoot) === 'missing';
+    const configPath = path.join(cordisxRoot, 'config.json');
+    const existing = await existingEmbeddedConfig(configPath);
+    for (const id of ids) {
+        if (existing.ids.includes(id))
+            throw new Error(`plugin already exists in .cordisx/config.json: ${id}`);
+        if (await pathState(path.join(cordisxRoot, 'plugins', id)) !== 'missing') {
+            throw new Error(`plugin directory already exists: .cordisx/plugins/${id}`);
+        }
+        if (await readOptional(path.join(cordisxRoot, 'test', `${id}.mjs`)) !== undefined) {
+            throw new Error(`plugin test already exists: .cordisx/test/${id}.mjs`);
+        }
+    }
+    const previousFiles = new Map();
+    const pluginRoots = ids.map(id => path.join(cordisxRoot, 'plugins', id));
+    const remember = async (file) => {
+        if (!previousFiles.has(file))
+            previousFiles.set(file, await readOptional(file));
+    };
+    const put = async (file, contents, onlyWhenMissing = false) => {
+        await remember(file);
+        if (onlyWhenMissing && previousFiles.get(file) !== undefined)
+            return;
+        await mkdir(path.dirname(file), { recursive: true });
+        await writeFile(file, contents, 'utf8');
+    };
+    try {
+        const nextPlugins = [
+            ...existing.value.plugins,
+            ...ids.map(id => ({ id, entry: `./plugins/${id}/src/index.tsx`, enabled: true, config: {} })),
+        ];
+        await put(configPath, json({ ...existing.value, plugins: nextPlugins }));
+        await put(path.join(cordisxRoot, 'package.json'), embeddedPackage(packageName(target), cordisxVersion, isolatedManagerSpec), true);
+        await put(path.join(cordisxRoot, 'tsconfig.json'), embeddedTsconfig(), true);
+        await put(path.join(cordisxRoot, 'scripts', 'build-plugins.mjs'), projectBuildScript('config.json'), true);
+        await put(path.join(cordisxRoot, '.gitignore'), 'node_modules/\ndist/\ncache/\n*.tsbuildinfo\n', true);
+        await put(path.join(cordisxRoot, 'README.md'), embeddedReadme(manager, integrated), true);
+        if (!integrated && manager === 'yarn')
+            await put(path.join(cordisxRoot, 'yarn.lock'), '', true);
+        for (const id of ids) {
+            await renderPluginSource(templateRoot, path.join(cordisxRoot, 'plugins', id), id, `../../dist/runtime/${id}`);
+        }
+        for (const id of ids) {
+            await put(path.join(cordisxRoot, 'test', `${id}.mjs`), manifestTest([id], pluginId => `../dist/runtime/${pluginId}/module.js`));
+        }
+        if (integrated) {
+            const workspaceEntry = path.relative(target, cordisxRoot).replaceAll('\\', '/') || '.cordisx';
+            await remember(workspace.manifestPath);
+            const contents = previousFiles.get(workspace.manifestPath);
+            await writeFile(workspace.manifestPath, workspace.kind === 'pnpm-yaml'
+                ? addPnpmWorkspace(contents, workspaceEntry)
+                : addPackageWorkspace(contents, workspaceEntry), 'utf8');
+        }
+    }
+    catch (error) {
+        for (const pluginRoot of pluginRoots)
+            await rm(pluginRoot, { recursive: true, force: true });
+        for (const [file, previous] of [...previousFiles].reverse()) {
+            if (previous === undefined)
+                await rm(file, { force: true });
+            else
+                await writeFile(file, previous, 'utf8');
+        }
+        if (cordisxRootWasMissing)
+            await rm(cordisxRoot, { recursive: true, force: true });
+        throw error;
+    }
+    return { manager, integrated };
+}
+async function main(argv) {
+    const parsed = parseArguments(argv);
+    if (parsed === 'help') {
+        console.log(HELP);
+        return;
+    }
+    const target = path.resolve(process.cwd(), parsed.directory);
+    const packageRoot = fileURLToPath(new URL('..', import.meta.url));
+    const templateRoot = path.join(packageRoot, 'template');
+    const creatorManifest = JSON.parse(await readFile(path.join(packageRoot, 'package.json'), 'utf8'));
+    if (typeof creatorManifest.version !== 'string' || creatorManifest.version.length === 0) {
+        throw new Error('create-cordisx-plugin package version is invalid');
+    }
+    if (parsed.mode === 'single') {
+        const manager = parsed.packageManager ?? 'npm';
+        await createSingle(target, parsed.directory, manager, templateRoot, creatorManifest.version);
+        console.log(`Created CordisX plugin in ${target}`);
+        console.log(`\nNext steps:\n  cd ${parsed.directory}\n  ${manager} install\n  ${manager} run check\n  ${manager} run dev:dry-run`);
+        return;
+    }
+    if (parsed.mode === 'workspace') {
+        const manager = parsed.packageManager ?? 'npm';
+        await createWorkspace(target, parsed.directory, parsed.plugins, manager, templateRoot, creatorManifest.version);
+        console.log(`Created CordisX plugin workspace in ${target}`);
+        console.log(`\nNext steps:\n  cd ${parsed.directory}\n  ${manager} install\n  ${manager} run check\n  ${manager} run dev:dry-run`);
+        return;
+    }
+    const result = await createEmbedded(target, parsed.plugins, parsed.integration, parsed.packageManager, templateRoot, creatorManifest.version);
+    console.log(`Added CordisX plugin${parsed.plugins.length === 1 ? '' : 's'} to ${path.join(target, '.cordisx')}`);
+    console.log(`Environment: ${result.integrated ? `${result.manager} workspace` : `isolated ${result.manager}`}`);
+    if (result.integrated) {
+        console.log(`\nNext steps:\n  cd ${parsed.directory}\n  ${result.manager} install\n  cd .cordisx\n  ${result.manager} run check\n  ${result.manager} run dev:dry-run`);
+    }
+    else {
+        const install = result.manager === 'pnpm' ? 'pnpm install --ignore-workspace' : `${result.manager} install`;
+        console.log(`\nNext steps:\n  cd ${path.join(parsed.directory, '.cordisx')}\n  ${install}\n  ${result.manager} run check\n  ${result.manager} run dev:dry-run`);
+    }
 }
 main(process.argv.slice(2)).catch((error) => {
     console.error(`[create-cordisx-plugin] ${error instanceof Error ? error.message : String(error)}`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-cordisx-plugin",
-  "version": "0.1.0-beta.1",
-  "description": "Create a minimal CordisX plugin project",
+  "version": "0.1.0-beta.4",
+  "description": "Create standalone, workspace, or embedded CordisX plugin projects",
   "type": "module",
   "files": [
     "dist",
@@ -15,10 +15,11 @@
     "create-cordisx-plugin": "dist/cli.js"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "check": "npm run typecheck",
+    "build": "tsc -p tsconfig.json && node scripts/normalize-bin-mode.mjs",
+    "check": "npm run typecheck && npm run build && npm test",
     "check:package": "node scripts/check-package-contents.mjs",
     "prepack": "npm run build",
+    "test": "node --test test/*.node-test.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "engines": {
@@ -42,11 +43,13 @@
   ],
   "publishConfig": {
     "access": "public",
-    "tag": "beta",
     "provenance": true
   },
   "devDependencies": {
     "@types/node": "^22.18.1",
     "typescript": "^5.9.2"
+  },
+  "dependencies": {
+    "yaml": "2.8.1"
   }
 }

package/template/README.md

@@ -1,17 +1,36 @@
 # {{packageName}}
 
 A minimal trusted-local CordisX React plugin. Its manifest is exported from
-`src/{{pluginId}}.tsx`, which is also the runtime entry used by CordisX.
+`src/{{pluginId}}.tsx`, which is also CordisX's local-development entry.
+The page component lives in `src/overview-page.tsx` as a named component-only
+module so local development can preserve its state with React Fast Refresh.
 
 ```bash
-npm install
-npm run check
-npm run dev:dry-run
-npm run dev
+{{packageManager}} install
+{{packageManager}} run check
+{{packageManager}} run dev:dry-run
+{{packageManager}} run dev
 ```
 
-`npm run dev:dry-run` bundles the plugin without launching Codex Desktop.
-`npm run dev` launches the separate CordisX development host.
+`{{packageManager}} run dev:dry-run` validates the plugin module graph without
+launching Codex Desktop. `{{packageManager}} run dev` launches the separate
+CordisX development host. Component-only modules use React Fast Refresh;
+manifest, entry, and `apply()` changes replace the plugin generation.
+
+`{{packageManager}} run build` creates a production Vite ESM graph in `dist/runtime/`.
+Its stable `module.js` entry may load content-addressed JavaScript chunks, CSS,
+and static assets only when an `import()` reaches them. The generated formal
+`artifact.json` records that graph for packaging; declarations are kept outside
+the closed graph in `dist/types/`, and `package.json#files` includes the complete
+`dist/` tree. Production generations remain immutable package
+artifacts and do not use the development HMR connection.
+
+The generated config calls the public `cordisx/vite`
+`cordisXPluginViteConfig()` helper. That shared author/Host pipeline owns the
+output rules, virtualizes only the closed Host singleton imports, and emits the
+formal `dist/runtime/artifact.json`. A portable CordisX package manifest points its
+browser entry at the adjacent prebuilt `dist/runtime/module.js`; the Host validates and
+retains the complete indexed graph.
 
 The template intentionally requests no platform capabilities. It contributes a
 structured toolbar route and a React page body. Import React from
@@ -32,3 +51,25 @@ CordisX plugin interfaces, it may be commercial and use a license you choose.
 Replace `UNLICENSED` in `package.json` with that license before distribution.
 The Exception does not cover copying or modifying CordisX host/runtime/CLI code
 or using private interfaces.
+
+Plugin-owned styles use `import './details.css'` in the owning component (or
+lazy page module). Keep `src/vite-env.d.ts`: Vite types distinguish side-effect
+CSS, CSS Module class maps, and explicit `?inline` text. Ordinary CSS imports
+do not return strings. Component unmount is not CSS-module disposal; verify
+plugin replacement separately from CSS HMR. See the maintained
+[CSS guidance](https://github.com/cordisx/cordisx/blob/main/skills/cordisx-plugin-development/references/css-and-lifecycle.md)
+for lifecycle boundaries and installed-Host CSS Modules limitations.
+
+For operation feedback, use `ctx.notifications.show()` and declare
+`notifications` in plugin injection. Host supplies plugin identity, cards and
+user suppression rules. Do not create a Toast provider, manually positioned
+alert or page-wide operation error; keep field validation and durable business
+state next to the relevant control. See the
+[notification guide](https://github.com/cordisx/cordisx/blob/efbff656d84b482d51598bc5ba303d24134e0c62/.agents/docs/notifications.md).
+Verify SDK/Host availability first: an older version without this service is a
+capability gap, not a reason to build a private DOM fallback.
+
+For modals, use Host `Dialog`/`DialogProvider` from `cordisx/ui` or `ctx.dialogs`.
+Keep full JSX in the body and use structured header/footer actions. The Host
+owns the rightmost close button, focus, theme and lifecycle. See the
+[dialog guide](https://github.com/cordisx/cordisx/blob/main/.agents/docs/dialogs.md).

package/template/README.zh-Hans.md

@@ -0,0 +1,39 @@
+# {{packageName}}
+
+一个最小的 CordisX 本地可信插件。插件清单由
+`src/{{pluginId}}.tsx` 导出；该文件同时也是 CordisX 本地开发使用的入口。
+
+```bash
+{{packageManager}} install
+{{packageManager}} run check
+{{packageManager}} run dev:dry-run
+{{packageManager}} run dev
+```
+
+`{{packageManager}} run dev:dry-run` 会在不启动 Codex Desktop 的情况下打包插件；
+`{{packageManager}} run dev` 会启动独立的 CordisX 开发宿主。
+
+`{{packageManager}} run build` 会在 `dist/runtime/` 中生成生产用 Vite ESM graph。固定入口
+`module.js` 可以在 `import()` 实际触发后再加载带内容摘要的 JavaScript chunk、
+CSS 和静态资源；正式的 `artifact.json` 会记录完整产物图，类型声明则隔离在
+`dist/types/`，
+`package.json#files` 会将整个 `dist/` 纳入打包。生产 generation 仍是不可变包
+产物，不使用开发 HMR 连接。
+
+生成的配置会调用公开的 `cordisx/vite` `cordisXPluginViteConfig()` helper。
+这个作者侧与 Host 共用的流水线负责产物规则，只虚拟化封闭的 Host 单例导入，并
+生成正式的 `dist/runtime/artifact.json`。可移植 CordisX package manifest 应把浏览器入口
+指向相邻的预构建 `dist/runtime/module.js`；Host 会验证并保留该完整索引 graph。
+
+这个生成项目属于 [CordisX 独立插件例外](https://github.com/cordisx/cordisx/blob/main/CORDISX-INDEPENDENT-PLUGIN-EXCEPTION.md)
+定义的“已标记模板材料”。只要它保持为独立插件，并且只使用有文档、带版本的
+CordisX 公共插件接口，就可以用于商业用途并采用你选择的许可证。发布前请将
+`package.json` 中的 `UNLICENSED` 替换为所选许可证。该例外不包括复制或修改
+CordisX Host、Runtime、CLI 代码，也不包括使用私有接口。
+
+插件自有样式在所属组件或 lazy 页面模块中使用 `import './details.css'`。
+保留 `src/vite-env.d.ts`：Vite 类型区分普通 CSS 副作用导入、CSS Modules
+类名映射和显式 `?inline` 文本，普通 CSS 不返回字符串。组件卸载不等于
+CSS 模块回收；CSS HMR 与插件替换需要分别验证。具体生命周期和已安装
+Host 的 CSS Modules 限制见
+[CSS 指导](https://github.com/cordisx/cordisx/blob/main/skills/cordisx-plugin-development/references/css-and-lifecycle.md)。

package/template/package.json

@@ -5,11 +5,23 @@
   "license": "UNLICENSED",
   "description": "A CordisX plugin",
   "type": "module",
-  "main": "./dist/{{pluginId}}.js",
-  "types": "./dist/{{pluginId}}.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "README.zh-Hans.md"
+  ],
+  "main": "./dist/runtime/module.js",
+  "types": "./dist/types/{{pluginId}}.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/{{pluginId}}.d.ts",
+      "import": "./dist/runtime/module.js",
+      "default": "./dist/runtime/module.js"
+    }
+  },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "check": "npm run typecheck && npm run build && npm test",
+    "build": "vite build && tsc -p tsconfig.json --emitDeclarationOnly",
+    "check": "tsc -p tsconfig.json --noEmit && vite build && tsc -p tsconfig.json --emitDeclarationOnly && node --test test/manifest.mjs",
     "dev": "cordisx dev ./src/{{pluginId}}.tsx",
     "dev:dry-run": "cordisx dev ./src/{{pluginId}}.tsx --dry-run",
     "test": "node --test test/manifest.mjs",
@@ -18,7 +30,8 @@
   "devDependencies": {
     "@deepseek-ai/cordis": "4.0.1",
     "cordisx": "{{cordisxVersion}}",
-    "typescript": "^5.9.2"
+    "typescript": "^5.9.2",
+    "vite": "8.2.2"
   },
   "engines": {
     "node": ">=22.19"

package/template/src/overview-page.tsx

@@ -0,0 +1,30 @@
+import { useState } from 'cordisx/react'
+import { Button, Card, Heading, Stack, Text } from 'cordisx/ui'
+import type { CordisXReactPageProps } from 'cordisx/contracts'
+
+export type Messages = {
+  'command.open': undefined
+  'page.title': undefined
+  'page.description': undefined
+  'route.title': undefined
+  'route.description': undefined
+  'counter.label': { count: number }
+}
+
+/** A named component-only module forms a stable React Fast Refresh boundary. */
+export function OverviewPage({ t }: CordisXReactPageProps<Messages>) {
+  const [count, setCount] = useState(0)
+  return (
+    <Stack gap="large">
+      <Heading>{t('page.title')}</Heading>
+      <Card>
+        <Stack gap="medium" align="flex-start">
+          <Text tone="muted">{t('page.description')}</Text>
+          <Button variant="primary" onClick={() => setCount(value => value + 1)}>
+            {t('counter.label', { count })}
+          </Button>
+        </Stack>
+      </Card>
+    </Stack>
+  )
+}

package/template/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/template/src/{{packageName}}.tsx

@@ -1,22 +1,13 @@
 import type { Context } from '@deepseek-ai/cordis'
-import { defineReactPage, useState } from 'cordisx/react'
-import { Button, Card, Heading, Stack, Text } from 'cordisx/ui'
+import { defineReactPage, lazy, Suspense } from 'cordisx/react'
 import {
   CORDISX_PAGE_SCHEMA_V3,
   CORDISX_PLUGIN_MANIFEST_SCHEMA_V1,
   CORDISX_ROUTE_SCHEMA_V2,
   type CordisXPluginManifestV1,
+  type CordisXReactPageProps,
 } from 'cordisx/contracts'
-import type {} from 'cordisx/contracts'
-
-type Messages = {
-  'command.open': undefined
-  'page.title': undefined
-  'page.description': undefined
-  'route.title': undefined
-  'route.description': undefined
-  'counter.label': { count: number }
-}
+import type { Messages } from './overview-page.js'
 
 export const manifest = {
   $schema: CORDISX_PLUGIN_MANIFEST_SCHEMA_V1,
@@ -48,22 +39,20 @@ const route = {
   description: { key: 'route.description', fallback: 'Open the plugin React example.' },
 } as const
 
-const mountOverview = defineReactPage<Messages>(({ t }) => {
-  const [count, setCount] = useState(0)
+const OverviewPage = lazy(async () => {
+  const module = await import('./overview-page.js')
+  return { default: module.OverviewPage }
+})
+
+function OverviewPageBoundary(props: CordisXReactPageProps<Messages>) {
   return (
-    <Stack gap="large">
-      <Heading>{t('page.title')}</Heading>
-      <Card>
-        <Stack gap="medium" align="flex-start">
-          <Text tone="muted">{t('page.description')}</Text>
-          <Button variant="primary" onClick={() => setCount(value => value + 1)}>
-            {t('counter.label', { count })}
-          </Button>
-        </Stack>
-      </Card>
-    </Stack>
+    <Suspense fallback={null}>
+      <OverviewPage {...props} />
+    </Suspense>
   )
-})
+}
+
+const mountOverview = defineReactPage<Messages>(OverviewPageBoundary)
 
 export function apply(ctx: Context): void {
   ctx.i18n.define<Messages>({

package/template/test/manifest.mjs

@@ -1,6 +1,22 @@
 import assert from 'node:assert/strict'
 import test from 'node:test'
-import { apply, inject, manifest } from '../dist/{{pluginId}}.js'
+
+const component = () => null
+const noop = () => undefined
+const React = new Proxy({ Fragment: Symbol('Fragment'), Suspense: component, lazy: () => component }, {
+  get(target, property) {
+    return Reflect.get(target, property) ?? noop
+  },
+})
+globalThis.__cordisxSharedReactRuntime = {
+  React,
+  defineReactPage: page => page,
+  jsxRuntime: { Fragment: React.Fragment, jsx: component, jsxs: component },
+  jsxDevRuntime: { Fragment: React.Fragment, jsxDEV: component },
+  ui: new Proxy({}, { get: () => component }),
+}
+
+const { apply, inject, manifest } = await import('../dist/runtime/module.js')
 
 test('exports a minimal CordisX plugin module', () => {
   assert.equal(manifest.schemaVersion, 1)

package/template/tsconfig.json

@@ -7,7 +7,7 @@
     "jsxImportSource": "cordisx/react",
     "lib": ["ES2023", "DOM"],
     "rootDir": "src",
-    "outDir": "dist",
+    "outDir": "dist/types",
     "strict": true,
     "declaration": true,
     "forceConsistentCasingInFileNames": true,

package/template/vite.config.ts

@@ -0,0 +1,13 @@
+import { fileURLToPath } from 'node:url'
+import { cordisXPluginViteConfig } from 'cordisx/vite'
+
+const projectRoot = fileURLToPath(new URL('.', import.meta.url))
+
+const config: ReturnType<typeof cordisXPluginViteConfig> = cordisXPluginViteConfig({
+  root: projectRoot,
+  entry: fileURLToPath(new URL('./{{sourceEntry}}', import.meta.url)),
+  outDir: fileURLToPath(new URL('./{{outDir}}', import.meta.url)),
+  entryFileName: 'module.js',
+})
+
+export default config