@vmz/plugin 0.0.1 → 0.0.3

package/README.md

@@ -1,3 +1,57 @@
 # @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,69 @@
+/**
+ * @vmz/plugin — protocol helpers (no N-API).
+ */
+
+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.3",
+  "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.3"
+  },
+  "keywords": [
+    "vmz",
+    "plugin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/doki-land/vmz-framework.git"