@vmz/vmz 0.0.2 → 0.0.4

package/dist/locale-tooling.js

@@ -1,7 +1,6 @@
 // @ts-nocheck
 /**
- * Locale I5 tooling: explain · diff · extract · pseudo · cross-host conformance.
- * Design: 规划设计/vmz/28 §12–§13
+ * Locale tooling: explain · diff · extract · pseudo · cross-host conformance.
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -11,10 +10,10 @@ import { assertHostMessageInvariant, buildLocaleDeliveryResolution } from './loc
 /**
  * Explain one MessageId: definition, params, variants, fallback, delivery reachability.
  * @param {{
- *   messageId: string,
- *   locale?: string|null,
- *   deliveryId?: string|null,
- *   checkReport: any,
+ * messageId: string,
+ * locale?: string|null,
+ * deliveryId?: string|null,
+ * checkReport: any,
  * }} input
  */
 export function explainLocaleMessage(input) {
@@ -81,9 +80,9 @@ export function explainLocaleMessage(input) {
 /**
  * Diff two locales' catalogs.
  * @param {{
- *   baseLocale: string,
- *   targetLocale: string,
- *   messages: Array<{ messageId: string, variants: Record<string, { template: string, params?: any[] }> }>,
+ * baseLocale: string,
+ * targetLocale: string,
+ * messages: Array<{ messageId: string, variants: Record<string, { template: string, params?: any[] }> }>,
  * }} input
  */
 export function diffLocaleCatalogs(input) {
@@ -250,9 +249,9 @@ export function extractHardcodedText(projectRoot, opts = {}) {
  * Pseudo-localize a source locale for layout/overflow testing.
  * Preserves ICU placeholders; marks provenance — never a production fallback.
  * @param {{
- *   sourceLocale: string,
- *   messages: Array<{ messageId: string, variants: Record<string, { template: string }> }>,
- *   production?: boolean,
+ * sourceLocale: string,
+ * messages: Array<{ messageId: string, variants: Record<string, { template: string }> }>,
+ * production?: boolean,
  * }} input
  */
 export function pseudoLocalizeCatalog(input) {
@@ -296,9 +295,9 @@ export function pseudoLocalizeCatalog(input) {
 /**
  * Cross-host conformance: same MessageId set + catalog hashes + formatter version.
  * @param {{
- *   manifest: any,
- *   messages: any[],
- *   routeIds?: string[],
+ * manifest: any,
+ * messages: any[],
+ * routeIds?: string[],
  * }} input
  */
 export function checkLocaleConformance(input) {

package/dist/log.d.ts

@@ -1,5 +1,5 @@
 /**
- * Unified CLI logging / diagnostics (N2).
+ * Unified CLI logging / diagnostics .
  */
 export declare const log: {
     /** @param {...unknown} args */

package/dist/log.js

@@ -1,6 +1,6 @@
 // @ts-nocheck
 /**
- * Unified CLI logging / diagnostics (N2).
+ * Unified CLI logging / diagnostics .
  */
 /** @param {string} level */
 function stamp(level) {

package/dist/packages.d.ts

@@ -1,6 +1,5 @@
 /**
- * npm / pnpm workspace package resolution helpers (N4.3).
- * Design: `规划设计/vmz/14` — Node owns package resolution; Rust owns semantics.
+ * npm / pnpm workspace package resolution helpers (session).
  */
 /**
  * @typedef {object} ResolvedPackage

package/dist/packages.js

@@ -1,7 +1,6 @@
 // @ts-nocheck
 /**
- * npm / pnpm workspace package resolution helpers (N4.3).
- * Design: `规划设计/vmz/14` — Node owns package resolution; Rust owns semantics.
+ * npm / pnpm workspace package resolution helpers (session).
  */
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import path from 'node:path';

package/dist/plugin-host.d.ts

@@ -1,6 +1,5 @@
 /**
- * Plugin protocol v1 helpers (N3) + typed config loading.
- * Design: 瑙勫垝璁捐/vmz/14-Node-NAPI涓庢彃浠跺涓?md
+ * Plugin protocol v1 helpers + typed config loading.
  */
 import { contentHash, defineConfig, definePlugin } from '@vmz/plugin';
 export { contentHash, defineConfig, definePlugin };
@@ -13,11 +12,20 @@ export declare function importMaybeTs(full: any): Promise<any>;
 /**
  * Load `vmz.config.*` from project root (+ optional root `vmz.plugin.*`).
  * @param {string} project
- * @returns {Promise<{ plugins: import('@vmz/plugin').VmzPlugin[], engines: import('@vmz/plugin').VmzEngines, path: string | null, pluginPath: string | null }>}
+ * @returns {Promise<{
+ *   plugins: import('@vmz/plugin').VmzPlugin[],
+ *   engines: import('@vmz/plugin').VmzEngines,
+ *   delivery: import('@vmz/plugin').SiteDeliveryAuthoring | null,
+ *   application: { id?: string } | null,
+ *   path: string | null,
+ *   pluginPath: string | null,
+ * }>}
  */
 export declare function loadVmzConfig(project: any): Promise<{
     plugins: any[];
     engines: {};
+    delivery: any;
+    application: any;
     path: any;
     pluginPath: any;
 }>;

package/dist/plugin-host.js

@@ -1,7 +1,6 @@
 // @ts-nocheck
 /**
- * Plugin protocol v1 helpers (N3) + typed config loading.
- * Design: 瑙勫垝璁捐/vmz/14-Node-NAPI涓庢彃浠跺涓?md
+ * Plugin protocol v1 helpers + typed config loading.
  */
 import { existsSync } from 'node:fs';
 import path from 'node:path';
@@ -33,13 +32,24 @@ export async function importMaybeTs(full) {
 /**
  * Load `vmz.config.*` from project root (+ optional root `vmz.plugin.*`).
  * @param {string} project
- * @returns {Promise<{ plugins: import('@vmz/plugin').VmzPlugin[], engines: import('@vmz/plugin').VmzEngines, path: string | null, pluginPath: string | null }>}
+ * @returns {Promise<{
+ *   plugins: import('@vmz/plugin').VmzPlugin[],
+ *   engines: import('@vmz/plugin').VmzEngines,
+ *   delivery: import('@vmz/plugin').SiteDeliveryAuthoring | null,
+ *   application: { id?: string } | null,
+ *   path: string | null,
+ *   pluginPath: string | null,
+ * }>}
  */
 export async function loadVmzConfig(project) {
     /** @type {import('@vmz/plugin').VmzPlugin[]} */
     const plugins = [];
     /** @type {import('@vmz/plugin').VmzEngines} */
     let engines = {};
+    /** @type {import('@vmz/plugin').SiteDeliveryAuthoring | null} */
+    let delivery = null;
+    /** @type {{ id?: string } | null} */
+    let application = null;
     /** @type {string | null} */
     let configPath = null;
     /** @type {string | null} */
@@ -52,6 +62,12 @@ export async function loadVmzConfig(project) {
         const cfg = await importMaybeTs(full);
         const raw = cfg?.plugins ?? [];
         engines = cfg?.engines && typeof cfg.engines === 'object' ? { ...cfg.engines } : {};
+        if (cfg?.delivery && typeof cfg.delivery === 'object') {
+            delivery = cfg.delivery;
+        }
+        if (cfg?.application && typeof cfg.application === 'object') {
+            application = cfg.application;
+        }
         for (const entry of raw) {
             plugins.push(await resolvePluginEntry(project, entry));
         }
@@ -65,7 +81,7 @@ export async function loadVmzConfig(project) {
         plugins.push(await resolvePluginEntry(project, full));
         break;
     }
-    return { plugins, engines, path: configPath, pluginPath };
+    return { plugins, engines, delivery, application, path: configPath, pluginPath };
 }
 /**
  * @param {string} project
@@ -158,7 +174,7 @@ export async function applyPlugins(workspace, plugins, opts) {
     return reports;
 }
 /**
- * Only math/code/markdown register interchangeable engines (see design doc 23 §1.1).
+ * Only math/code/markdown register interchangeable engines (see design .
  * @param {{ code: Set<string>, math: Set<string>, markdown: Set<string> }} registered
  * @param {any} item
  */

package/dist/port.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Probe for a free TCP port starting at `start` (inclusive).
+ * Used by `vmz dev` when `--port` is omitted.
+ *
+ * @param {string} host
+ * @param {number} [start=5173]
+ * @param {number} [maxTries=50]
+ * @returns {Promise<number>}
+ */
+export declare function findAvailablePort(host: any, start?: number, maxTries?: number): Promise<unknown>;

package/dist/port.js

@@ -0,0 +1,46 @@
+// @ts-nocheck
+import net from 'node:net';
+/**
+ * Probe for a free TCP port starting at `start` (inclusive).
+ * Used by `vmz dev` when `--port` is omitted.
+ *
+ * @param {string} host
+ * @param {number} [start=5173]
+ * @param {number} [maxTries=50]
+ * @returns {Promise<number>}
+ */
+export function findAvailablePort(host, start = 5173, maxTries = 50) {
+    const first = Number(start);
+    if (!Number.isFinite(first) || first <= 0) {
+        return Promise.reject(new Error(`invalid start port: ${start}`));
+    }
+    return new Promise((resolve, reject) => {
+        let port = first;
+        const attempt = () => {
+            if (port > first + maxTries) {
+                reject(new Error(`no free port in ${first}..${first + maxTries} on ${host}`));
+                return;
+            }
+            const server = net.createServer();
+            server.unref();
+            server.once('error', (err) => {
+                if (err && err.code === 'EADDRINUSE') {
+                    port += 1;
+                    attempt();
+                    return;
+                }
+                reject(err);
+            });
+            server.once('listening', () => {
+                server.close((closeErr) => {
+                    if (closeErr)
+                        reject(closeErr);
+                    else
+                        resolve(port);
+                });
+            });
+            server.listen(port, host);
+        };
+        attempt();
+    });
+}

package/dist/production-observability.d.ts

@@ -0,0 +1,286 @@
+/**
+ * A5: Production observability — trace facets, redaction, CSP/security,
+ * performance budgets, health/readiness, capability closure.
+ */
+export declare const PRODUCTION_OBSERVABILITY_SCHEMA = "vmz.production.observability.v0";
+export declare const PRODUCTION_TRACE_SCHEMA = "vmz.production.trace.v0";
+/** Facets that production traces must be able to carry (08 A5). */
+export declare const REQUIRED_TRACE_FACETS: readonly string[];
+/**
+ * Default Browser Production Profile observability contract.
+ * @param {Record<string, unknown>} [overrides]
+ */
+export declare function browserProductionObservability(overrides?: {}): {
+    schema: string;
+    id: any;
+    trace: {
+        schema: string;
+        requiredFacets: any;
+        retainOnFailure: any;
+    };
+    redaction: {
+        mode: string;
+        replaceWith: any;
+        allowPublicProvenance: boolean;
+        sensitiveKeyPattern: string;
+    };
+    security: {
+        csp: any;
+        requireIntegrityForRemote: boolean;
+        originIsolation: boolean;
+        requireNonceForInline: boolean;
+        cookieNamespace: any;
+        sessionNamespace: any;
+    };
+    capability: {
+        allowlistRequired: boolean;
+        inputOutputSchemaRequired: boolean;
+        timeoutMsDefault: number;
+        cancelSupported: boolean;
+        serverSecretClosure: boolean;
+    };
+    budgets: {
+        irrelevantBindingWork: number;
+        irrelevantRouteRegionRebuild: number;
+        wholeTreeRerender: number;
+        maxArtifactBytes: number;
+        maxHtmlBytes: number;
+        maxClientJsBytes: number;
+        maxPatchCountPerTransition: number;
+    };
+    health: {
+        livePath: any;
+        readyPath: any;
+        gracefulShutdown: {
+            stopAccepting: boolean;
+            drainInFlight: boolean;
+            timeoutMs: number;
+        };
+    };
+    sampling: {
+        diagnosticSampleRate: number;
+        rollbackOnErrorRate: number;
+        latencyBudgetMs: {
+            p95: number;
+            p99: number;
+        };
+    };
+};
+/**
+ * @param {unknown} raw
+ */
+export declare function normalizeObservability(raw: any): {
+    schema: string;
+    id: any;
+    trace: {
+        schema: string;
+        requiredFacets: any;
+        retainOnFailure: any;
+    };
+    redaction: {
+        mode: string;
+        replaceWith: any;
+        allowPublicProvenance: boolean;
+        sensitiveKeyPattern: string;
+    };
+    security: {
+        csp: any;
+        requireIntegrityForRemote: boolean;
+        originIsolation: boolean;
+        requireNonceForInline: boolean;
+        cookieNamespace: any;
+        sessionNamespace: any;
+    };
+    capability: {
+        allowlistRequired: boolean;
+        inputOutputSchemaRequired: boolean;
+        timeoutMsDefault: number;
+        cancelSupported: boolean;
+        serverSecretClosure: boolean;
+    };
+    budgets: {
+        irrelevantBindingWork: number;
+        irrelevantRouteRegionRebuild: number;
+        wholeTreeRerender: number;
+        maxArtifactBytes: number;
+        maxHtmlBytes: number;
+        maxClientJsBytes: number;
+        maxPatchCountPerTransition: number;
+    };
+    health: {
+        livePath: any;
+        readyPath: any;
+        gracefulShutdown: {
+            stopAccepting: boolean;
+            drainInFlight: boolean;
+            timeoutMs: number;
+        };
+    };
+    sampling: {
+        diagnosticSampleRate: number;
+        rollbackOnErrorRate: number;
+        latencyBudgetMs: {
+            p95: number;
+            p99: number;
+        };
+    };
+};
+/**
+ * Redact sensitive keys recursively. Never returns secrets for public provenance.
+ * @param {unknown} value
+ * @param {Record<string, any>} [policy]
+ * @param {{ privilege?: 'public' | 'operator' }} [opts]
+ */
+export declare function redactSensitive(value: any, policy?: {}, opts?: {}): any;
+/**
+ * Validate a production trace carries required facets (as event.facet or mapped kind).
+ * @param {unknown} raw
+ * @param {string[]} [requiredFacets]
+ */
+export declare function validateProductionTrace(raw: any, requiredFacets?: readonly string[]): {
+    ok: boolean;
+    covered: unknown[];
+    errors: any[];
+};
+/**
+ * Build a minimal valid production trace covering all required facets (for CI assembly).
+ * @param {Record<string, unknown>} [meta]
+ */
+export declare function buildCoveringProductionTrace(meta?: {}): {
+    schema: string;
+    status: string;
+    applicationId: any;
+    artifactDigest: any;
+    events: {
+        facet: string;
+        kind: string;
+        stableId: {
+            kind: string;
+            id: string;
+        };
+        generation: number;
+        redacted: boolean;
+        payload: any;
+    }[];
+};
+/**
+ * @param {Record<string, any>} measured
+ * @param {Record<string, any>} budgets
+ */
+export declare function checkProductionBudgets(measured: any, budgets: any): {
+    ok: boolean;
+    violations: any[];
+};
+/**
+ * Validate capability production closure (allowlist + schema + timeout + secret).
+ * @param {Record<string, any>} cap
+ * @param {Record<string, any>} policy
+ */
+export declare function checkCapabilityClosure(cap: any, policy: any): {
+    ok: boolean;
+    errors: any[];
+};
+/**
+ * Merge CSP / security headers into a CDN policy headers list (HTML matches).
+ * @param {Record<string, any>} cdnPolicy
+ * @param {Record<string, any>} security
+ */
+export declare function applySecurityHeadersToCdnPolicy(cdnPolicy: any, security: any): any;
+/**
+ * Measure dist sizes for budget gates.
+ * @param {string} distDir
+ */
+export declare function measureDistBudgets(distDir: any): {
+    artifactBytes: number;
+    htmlBytes: number;
+    clientJsBytes: number;
+    irrelevantBindingWork: number;
+    irrelevantRouteRegionRebuild: number;
+    wholeTreeRerender: number;
+    patchCount: number;
+};
+/**
+ * Write observability contract (+ covering trace sample) under dist/_vmz.
+ * @param {string} distDir
+ * @param {Record<string, unknown>} [overrides]
+ * @param {{ applicationId?: string, artifactDigest?: string }} [meta]
+ */
+export declare function emitProductionObservability(distDir: any, overrides?: {}, meta?: {}): {
+    contract: {
+        schema: string;
+        id: any;
+        trace: {
+            schema: string;
+            requiredFacets: any;
+            retainOnFailure: any;
+        };
+        redaction: {
+            mode: string;
+            replaceWith: any;
+            allowPublicProvenance: boolean;
+            sensitiveKeyPattern: string;
+        };
+        security: {
+            csp: any;
+            requireIntegrityForRemote: boolean;
+            originIsolation: boolean;
+            requireNonceForInline: boolean;
+            cookieNamespace: any;
+            sessionNamespace: any;
+        };
+        capability: {
+            allowlistRequired: boolean;
+            inputOutputSchemaRequired: boolean;
+            timeoutMsDefault: number;
+            cancelSupported: boolean;
+            serverSecretClosure: boolean;
+        };
+        budgets: {
+            irrelevantBindingWork: number;
+            irrelevantRouteRegionRebuild: number;
+            wholeTreeRerender: number;
+            maxArtifactBytes: number;
+            maxHtmlBytes: number;
+            maxClientJsBytes: number;
+            maxPatchCountPerTransition: number;
+        };
+        health: {
+            livePath: any;
+            readyPath: any;
+            gracefulShutdown: {
+                stopAccepting: boolean;
+                drainInFlight: boolean;
+                timeoutMs: number;
+            };
+        };
+        sampling: {
+            diagnosticSampleRate: number;
+            rollbackOnErrorRate: number;
+            latencyBudgetMs: {
+                p95: number;
+                p99: number;
+            };
+        };
+    };
+    trace: {
+        schema: string;
+        status: string;
+        applicationId: any;
+        artifactDigest: any;
+        events: {
+            facet: string;
+            kind: string;
+            stableId: {
+                kind: string;
+                id: string;
+            };
+            generation: number;
+            redacted: boolean;
+            payload: any;
+        }[];
+    };
+    contractPath: string;
+    tracePath: string;
+};
+export declare function observabilityDigest(contract: any): any;
+export declare function sha256Text(text: any): string;