@vmz/plugin 0.0.1 → 0.0.2

package/README.md

@@ -1,3 +1,53 @@
 # @vmz/plugin
 
-Placeholder package (0.0.1). Reserved for the VMZ project.
+## Build extensions without dissolving the application boundary
+
+`@vmz/plugin` is the foundation for authors who want to extend VMZ with a domain capability: a renderer, a content
+processor, a language integration, an editor, a design-oriented utility, or another contribution that belongs in a
+full-stack application workflow.
+
+## The promise to plugin authors
+
+VMZ should be hospitable to npm and JavaScript ecosystem packages. You should be able to package, version, distribute,
+and compose useful functionality with normal Node tooling. A plugin can contribute declared capabilities and source
+assets without forcing every project to adopt a bespoke compiler fork.
+
+## The promise to application authors
+
+An extension must not make the application opaque. A VMZ plugin is not an unrestricted `transform(code)` escape hatch
+and not an invitation to mutate the compiler's program graph in place. Contributions are versioned and declared so VMZ
+can continue to reason about ownership, execution placement, SSR, resume, testing, diagnostics, and deployment.
+
+This is the tradeoff: plugin authors gain a stable way to participate in VMZ, while users retain a coherent application
+model after installing the plugin. If an integration requires arbitrary runtime injection or hidden semantic rewrites,
+it belongs outside the core VMZ plugin contract.
+
+| A plugin should contribute...                      | A plugin should not become...                            |
+|----------------------------------------------------|----------------------------------------------------------|
+| A declared capability with known inputs and output | A hidden second application runtime                      |
+| Versioned integration behavior                     | An unrestricted semantic rewrite                         |
+| Assets or adapters VMZ can place and test          | A way around server, lifecycle, or deployment boundaries |
+
+## Who should use it
+
+Use this package when you are creating a native VMZ integration, not when you simply need a conventional JavaScript
+library in application code. The latter should remain a normal dependency unless it needs to participate in VMZ's
+compiler-visible boundaries.
+
+## What a strong plugin can unlock 🚀
+
+- A content engine can contribute deterministic rendered output and diagnostics.
+- An editor can declare browser-only delivery while preserving an SSR-readable host.
+- A design tool can expose compile-time tokens without becoming a global runtime store.
+- A deployment adapter can contribute a target without rewriting application semantics.
+- A testing integration can add evidence while preserving VMZ's test model.
+
+## Why contribution beats mutation
+
+Mutation is convenient for the first plugin and expensive for the fiftieth. If every plugin can rewrite any source, graph node, or generated artifact, composition order becomes application semantics and no tool can explain the final result.
+
+A contribution says what capability is being added, which versioned schema it follows, what it reads, what it emits, and where it may execute. That extra structure is what allows npm extensibility and strong compilation to coexist.
+
+## The litmus test
+
+If installing the plugin makes `vmz check`, SSR, resume, tests, or deployment less able to explain the application, the integration is using the wrong boundary. A native plugin should leave VMZ more capable, not less coherent.

package/index.d.ts

@@ -0,0 +1,110 @@
+/** VMZ plugin protocol helpers — types + identity `define*` (no N-API). */
+
+export { PLUGIN_PROTOCOL } from '@vmz/protocol';
+
+export function contentHash(content: string | Buffer): string;
+
+/** Resolve a path next to the calling module (`import.meta.url`). */
+export function pluginFileUrl(importMetaUrl: string, relativePath: string): string;
+
+/**
+ * Load a real source file shipped with the plugin (typically `components/*.vmz`).
+ * Do not embed `.vmz` SFC text inside `vmz.plugin.ts`.
+ */
+export function loadPluginSource(
+    importMetaUrl: string,
+    relativePath: string,
+): {
+    content: string;
+    contentHash: string;
+    absPath: string;
+};
+
+export type PluginStage = 'workspace_resolve' | 'source_adapter' | 'analyzer' | 'target';
+
+export interface PluginManifest {
+    name: string;
+    version: string;
+    protocol?: string;
+    stages: PluginStage[];
+    deterministic?: boolean;
+}
+
+export interface ResolvedPackage {
+    name: string;
+    root: string;
+    version?: string;
+}
+
+export interface PluginContext {
+    project: string;
+    outDir: string;
+    stage: PluginStage | string;
+    protocol: string;
+    packages: ResolvedPackage[];
+    /** Default engines from `vmz.config`. */
+    engines?: VmzEngines;
+}
+
+export interface ContributionItem {
+    id: string;
+    kind: string;
+    path?: string;
+    content?: string;
+    contentHash?: string;
+    content_hash?: string;
+    materialize?: boolean;
+    severity?: string;
+    message?: string;
+    code?: string;
+    targetId?: string;
+    target_id?: string;
+    targetKind?: string;
+    target_kind?: string;
+    type?: string;
+    manifest?: unknown;
+    manifestJson?: string;
+    manifest_json?: string;
+    detail?: string;
+    /** Engine registration (host-recognized analyzer/source sidecar). */
+    engine?: string;
+    engineKind?: 'code' | 'math' | 'markdown' | string;
+}
+
+export interface ContributionBatchInput {
+    stage: PluginStage | string;
+    cacheKey?: string;
+    deterministic?: boolean;
+    items: ContributionItem[];
+}
+
+export interface VmzPlugin {
+    manifest: PluginManifest;
+    contribute?: (
+        ctx: PluginContext,
+    ) => Promise<ContributionBatchInput[] | ContributionBatchInput> | ContributionBatchInput[] | ContributionBatchInput;
+}
+
+export interface VmzEngines {
+    /** Default for `<Code>` when `engine` prop omitted. */
+    code?: string;
+    /** Default for `<Math>` when `engine` prop omitted. */
+    math?: string;
+    /** Default for `<Markdown>` when `engine` prop omitted; also used by `vmz document`. */
+    markdown?: string;
+}
+
+export interface VmzUserConfig {
+    plugins?: Array<string | VmzPlugin | Promise<VmzPlugin>>;
+    engines?: VmzEngines;
+}
+
+export type DefinePluginInput = PluginManifest & {
+    contribute?: VmzPlugin['contribute'];
+};
+
+/** Identity helper for IDE inference. */
+export function definePlugin(def: DefinePluginInput): VmzPlugin;
+
+/** Identity helper for `vmz.config.ts` inference. */
+export function defineConfig(config: VmzUserConfig): VmzUserConfig;

package/index.js

@@ -0,0 +1,70 @@
+/**
+ * @vmz/plugin — protocol helpers (no N-API).
+ * Design: 规划设计/vmz/14-Node-NAPI与插件宿主.md
+ */
+
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { PLUGIN_PROTOCOL } from '@vmz/protocol';
+
+export { PLUGIN_PROTOCOL };
+
+/**
+ * @param {string | Buffer} content
+ * @returns {string}
+ */
+export function contentHash(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+
+/**
+ * Resolve a path next to the calling module (`import.meta.url`).
+ * @param {string} importMetaUrl
+ * @param {string} relativePath
+ */
+export function pluginFileUrl(importMetaUrl, relativePath) {
+    return path.join(path.dirname(fileURLToPath(importMetaUrl)), relativePath);
+}
+
+/**
+ * Load a real `.vmz` (or other text) shipped beside `vmz.plugin.ts`.
+ * Do not embed SFC source as JS/TS string templates.
+ * @param {string} importMetaUrl `import.meta.url` of the plugin module
+ * @param {string} relativePath e.g. `components/Katex.vmz`
+ * @returns {{ content: string, contentHash: string, absPath: string }}
+ */
+export function loadPluginSource(importMetaUrl, relativePath) {
+    const absPath = pluginFileUrl(importMetaUrl, relativePath);
+    const content = readFileSync(absPath, 'utf8');
+    return { content, contentHash: contentHash(content), absPath };
+}
+
+/**
+ * @param {import('./index.js').DefinePluginInput} def
+ * @returns {import('./index.js').VmzPlugin}
+ */
+export function definePlugin(def) {
+    if (!def?.name || !def?.version || !Array.isArray(def.stages)) {
+        throw new Error('definePlugin requires name, version, stages[]');
+    }
+    return {
+        manifest: {
+            name: def.name,
+            version: def.version,
+            protocol: def.protocol ?? PLUGIN_PROTOCOL,
+            stages: def.stages,
+            deterministic: def.deterministic ?? true,
+        },
+        contribute: def.contribute,
+    };
+}
+
+/**
+ * @param {import('./index.js').VmzUserConfig} config
+ * @returns {import('./index.js').VmzUserConfig}
+ */
+export function defineConfig(config) {
+    return config ?? {};
+}

package/package.json

@@ -1,12 +1,32 @@
 {
   "name": "@vmz/plugin",
-  "version": "0.0.1",
-  "description": "VMZ placeholder 鈥?not for production use.",
+  "version": "0.0.2",
+  "type": "module",
+  "description": "VMZ plugin protocol types and definePlugin / defineConfig helpers (no N-API)",
   "license": "MIT",
-  "private": false,
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
   "files": [
+    "index.js",
+    "index.d.ts",
     "README.md"
   ],
+  "dependencies": {
+    "@vmz/protocol": "0.0.2"
+  },
+  "keywords": [
+    "vmz",
+    "plugin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/doki-land/vmz-framework.git"