@treasuryspatial/plugin-manifest 0.1.9 → 0.1.13

package/dist/index.js

@@ -1,3 +1,438 @@
+export const CANONICAL_STARTUP_LIGHTING_BASELINE_ID = 'architectural';
+export const CANONICAL_STARTUP_MATERIALS_BASELINE_ID = 'architectural-white';
+export const CANONICAL_STARTUP_HDR_BASELINE_ID = 'preset';
+const trimModeId = (value) => (typeof value === 'string' ? value.trim() : '');
+const normalizeModeIds = (value) => {
+    if (!Array.isArray(value))
+        return [];
+    const seen = new Set();
+    const output = [];
+    for (const entry of value) {
+        const normalized = trimModeId(entry);
+        if (!normalized || seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        output.push(normalized);
+    }
+    return output;
+};
+const buildCanonicalPromptPackFallbackRef = () => ({
+    id: 'vanilla',
+});
+const PLUGIN_MANIFEST_REMOVED_CORE_MATERIAL_SLOTS = ['walls', 'floor', 'ceiling'];
+export class MaterialBaselineContractError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MaterialBaselineContractError';
+    }
+}
+const normalizeSurfaceContract = (value) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return { surfaces: [] };
+    }
+    const rawSurfaces = Array.isArray(value.surfaces)
+        ? value.surfaces
+        : [];
+    const seen = new Set();
+    const surfaces = [];
+    for (const rawSurface of rawSurfaces) {
+        if (!rawSurface || typeof rawSurface !== 'object' || Array.isArray(rawSurface))
+            continue;
+        const id = typeof rawSurface.id === 'string' ? rawSurface.id.trim() : '';
+        if (!id)
+            continue;
+        const normalized = id.toLowerCase();
+        if (seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        surfaces.push({
+            id,
+            label: typeof rawSurface.label === 'string' &&
+                rawSurface.label.trim().length > 0
+                ? rawSurface.label.trim()
+                : id,
+            ...(typeof rawSurface.summary === 'string' &&
+                rawSurface.summary.trim().length > 0
+                ? { summary: rawSurface.summary.trim() }
+                : {}),
+            ...(typeof rawSurface.parentId === 'string' &&
+                rawSurface.parentId.trim().length > 0
+                ? { parentId: rawSurface.parentId.trim() }
+                : {}),
+        });
+    }
+    return { surfaces };
+};
+const validateMaterialBaselinesAgainstSurfaceContract = (toolId, baselines, surfaceContract) => {
+    const declaredSurfaceIds = new Set(surfaceContract.surfaces.map((surface) => surface.id.trim().toLowerCase()));
+    for (const baseline of baselines) {
+        const materials = baseline.materials;
+        if (materials && Object.prototype.hasOwnProperty.call(materials, 'slots')) {
+            throw new MaterialBaselineContractError(`tool '${toolId}' materials baseline '${baseline.id}' declares removed materials.slots. Bind declared Geometry surfaces through materials.surfaces.<surfaceId>.`);
+        }
+        const removedCoreSlots = PLUGIN_MANIFEST_REMOVED_CORE_MATERIAL_SLOTS.filter((slot) => materials ? Object.prototype.hasOwnProperty.call(materials, slot) : false);
+        if (removedCoreSlots.length > 0) {
+            throw new MaterialBaselineContractError(`tool '${toolId}' materials baseline '${baseline.id}' declares removed core material slots: ${removedCoreSlots
+                .map((slot) => `materials.${slot}`)
+                .join(', ')}. Plugin manifests must bind declared Geometry surface ids through materials.surfaces.<surfaceId>; Composer core roles are upload/GH-only.`);
+        }
+        const surfaceBindings = materials && isRecord(materials.surfaces) ? materials.surfaces : {};
+        if (Object.keys(surfaceBindings).length === 0) {
+            throw new MaterialBaselineContractError(`tool '${toolId}' materials baseline '${baseline.id}' declares no materials.surfaces bindings. Plugin material baselines must bind declared Geometry surface ids; use Composer core material presets for whole-model startup defaults.`);
+        }
+        const unknownSurfaceIds = Object.keys(surfaceBindings).filter((surfaceId) => !declaredSurfaceIds.has(surfaceId.trim().toLowerCase()));
+        if (unknownSurfaceIds.length > 0) {
+            throw new MaterialBaselineContractError(`tool '${toolId}' materials baseline '${baseline.id}' binds undeclared surface ids: ${unknownSurfaceIds.join(', ')}. Publish every material target in top-level surfaceContract.surfaces[]; parentId is taxonomy metadata only and is not a material target.`);
+        }
+    }
+};
+const buildStartupDefaultWarning = (options) => {
+    const labelByField = {
+        'baselines.defaults.lightingId': 'lighting',
+        'baselines.defaults.materialsId': 'materials',
+        'baselines.defaults.hdrId': 'HDR',
+    };
+    const codeByField = {
+        'baselines.defaults.lightingId': 'manifest_startup_lighting_noncanonical',
+        'baselines.defaults.materialsId': 'manifest_startup_materials_noncanonical',
+        'baselines.defaults.hdrId': 'manifest_startup_hdr_noncanonical',
+    };
+    const actualValue = trimModeId(options.actualValue) || null;
+    const fieldLabel = labelByField[options.field];
+    return {
+        code: codeByField[options.field],
+        severity: 'warning',
+        field: options.field,
+        expectedValue: options.expectedValue,
+        actualValue,
+        runtimeValue: options.expectedValue,
+        message: actualValue
+            ? `tool '${options.toolId}' declares non-canonical ${fieldLabel} startup default '${actualValue}'. Composer starts with '${options.expectedValue}' until the manifest is fixed.`
+            : `tool '${options.toolId}' is missing canonical ${fieldLabel} startup default '${options.expectedValue}'. Composer starts with '${options.expectedValue}' until the manifest is fixed.`,
+        fix: `Set ${options.field} = '${options.expectedValue}' in the manifest.`,
+    };
+};
+const resolveStartupDefaultWarnings = (tool, baselines) => {
+    const defaults = baselines.defaults ?? {};
+    const warnings = [];
+    const expectedPairs = [
+        ['baselines.defaults.lightingId', defaults.lightingId, CANONICAL_STARTUP_LIGHTING_BASELINE_ID],
+        ['baselines.defaults.materialsId', defaults.materialsId, CANONICAL_STARTUP_MATERIALS_BASELINE_ID],
+        ['baselines.defaults.hdrId', defaults.hdrId, CANONICAL_STARTUP_HDR_BASELINE_ID],
+    ];
+    for (const [field, actualValue, expectedValue] of expectedPairs) {
+        if (trimModeId(actualValue) === expectedValue)
+            continue;
+        warnings.push(buildStartupDefaultWarning({
+            toolId: tool.toolId,
+            field,
+            expectedValue,
+            actualValue: trimModeId(actualValue) || null,
+        }));
+    }
+    return warnings;
+};
+function resolveToolPromptPack(tool) {
+    const allowModes = normalizeModeIds(tool.modeAccess?.allowModes);
+    const denyModes = new Set(normalizeModeIds(tool.modeAccess?.denyModes));
+    for (const modeId of allowModes) {
+        if (denyModes.has(modeId)) {
+            throw new Error(`tool '${tool.toolId}' declares conflicting modeAccess rules for '${modeId}'. Remove the overlap between allowModes and denyModes.`);
+        }
+    }
+    const explicitPromptPack = tool.promptPack;
+    if (!explicitPromptPack) {
+        return buildCanonicalPromptPackFallbackRef();
+    }
+    const refId = trimModeId(explicitPromptPack.id);
+    if (!refId) {
+        throw new Error(`tool '${tool.toolId}' declares promptPack without an id. Provide one stable prompt-pack id or remove the field to use the canonical Spatial Render fallback.`);
+    }
+    if (allowModes.length === 0) {
+        throw new Error(`tool '${tool.toolId}' declares promptPack '${refId}' but has no explicit modeAccess.allowModes. Declare the modes this prompt kit is meant to hydrate.`);
+    }
+    const version = trimModeId(explicitPromptPack.version);
+    return {
+        id: refId,
+        ...(version ? { version } : {}),
+    };
+}
+const DEFAULT_OBJECT3D_PRESENTATION = {
+    kind: 'object3d',
+    defaultViewMode: 'auto',
+    units: {
+        canonicalScene: 'm',
+    },
+    camera: {
+        kind: 'perspective',
+        framingMode: 'iso',
+    },
+    normalization: {
+        recenter: true,
+        floorToZero: true,
+        allowAutoScale: false,
+    },
+    ground: {
+        mode: 'auto',
+        snapToBounds: false,
+    },
+    grid: {
+        mode: 'auto',
+    },
+    curves: {
+        mode: 'auto',
+    },
+    clipping: {
+        nearSafety: 1.6,
+        farSafety: 1.15,
+        minimumFar: 350,
+    },
+};
+const DEFAULT_PLAN2D_PRESENTATION = {
+    kind: 'plan2d',
+    defaultViewMode: '2d',
+    units: {
+        canonicalScene: 'm',
+    },
+    camera: {
+        kind: 'orthographic',
+        framingMode: 'iso',
+    },
+    normalization: {
+        recenter: true,
+        floorToZero: true,
+        allowAutoScale: false,
+    },
+    ground: {
+        mode: 'auto',
+        snapToBounds: true,
+    },
+    grid: {
+        mode: 'auto',
+    },
+    curves: {
+        mode: 'always',
+    },
+    clipping: {
+        nearSafety: 1.8,
+        farSafety: 1.2,
+        minimumFar: 350,
+    },
+};
+const DEFAULT_TOOL_EXECUTION = {
+    timeoutMs: 20_000,
+};
+const hasLegacyPromptingDefinition = (value) => Boolean(value?.packId ||
+    value?.packVersion);
+const isRecord = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const mergeDeep = (base, override) => {
+    const result = { ...base };
+    Object.entries(override).forEach(([key, value]) => {
+        const current = result[key];
+        if (isRecord(current) && isRecord(value)) {
+            result[key] = mergeDeep(current, value);
+            return;
+        }
+        result[key] = value;
+    });
+    return result;
+};
+const normalizeExecution = (execution) => {
+    if (!execution || typeof execution !== 'object')
+        return {};
+    const timeoutMs = Number(execution.timeoutMs);
+    return Number.isFinite(timeoutMs) && timeoutMs > 0
+        ? { timeoutMs: Math.round(timeoutMs) }
+        : {};
+};
+function resolveToolExecution(tool, plugin) {
+    const canonical = normalizeExecution(tool.execution ?? plugin.execution);
+    if (canonical.timeoutMs) {
+        return {
+            execution: {
+                ...DEFAULT_TOOL_EXECUTION,
+                ...canonical,
+            },
+            source: 'canonical',
+        };
+    }
+    return {
+        execution: DEFAULT_TOOL_EXECUTION,
+        source: 'default',
+    };
+}
+export const mergeMapInputs = (base, override) => {
+    if (Array.isArray(override))
+        return override;
+    if (Array.isArray(base))
+        return base;
+    return [];
+};
+const resolveToolUi = (tool, plugin) => {
+    if (plugin.ui && isRecord(plugin.ui)) {
+        return { ui: plugin.ui, source: 'manifest-ui' };
+    }
+    const schemaUi = plugin.schemas?.ui;
+    if (schemaUi && isRecord(schemaUi)) {
+        throw new Error(`tool '${tool.toolId}' declares removed schemas.ui. Move UI to top-level manifest.ui.`);
+    }
+    throw new Error(`tool '${tool.toolId}' is missing top-level manifest.ui. Composer no longer synthesizes controls from schema shape or legacy tool.panels.`);
+};
+export function resolveToolPresentation(manifest) {
+    if (manifest?.presentation) {
+        const canonical = manifest.presentation;
+        const template = canonical.kind === 'plan2d' ? DEFAULT_PLAN2D_PRESENTATION : DEFAULT_OBJECT3D_PRESENTATION;
+        return {
+            presentation: mergeDeep(template, canonical),
+            source: 'canonical',
+        };
+    }
+    return {
+        presentation: DEFAULT_OBJECT3D_PRESENTATION,
+        source: 'default',
+    };
+}
+const cleanIdList = (ids) => {
+    const next = ids?.map((value) => value?.trim()).filter(Boolean);
+    return next && next.length > 0 ? Array.from(new Set(next)) : undefined;
+};
+export function resolveManifestBaselines(manifest) {
+    const canonical = manifest?.baselines ?? {};
+    const defaults = canonical.defaults
+        ? {
+            lightingId: canonical.defaults.lightingId,
+            materialsId: canonical.defaults.materialsId,
+            hdrId: canonical.defaults.hdrId,
+        }
+        : undefined;
+    const availableLightingIds = cleanIdList(canonical.available?.lightingIds);
+    const availableMaterialsIds = cleanIdList(canonical.available?.materialsIds);
+    const availableHdrIds = cleanIdList(canonical.available?.hdrIds);
+    const available = availableLightingIds || availableMaterialsIds || availableHdrIds
+        ? {
+            lightingIds: availableLightingIds,
+            materialsIds: availableMaterialsIds,
+            hdrIds: availableHdrIds,
+        }
+        : undefined;
+    return {
+        defaults,
+        available,
+        lighting: canonical.lighting ?? [],
+        materials: canonical.materials ?? [],
+        hdr: canonical.hdr ?? [],
+    };
+}
+export function resolveManifestCompositions(manifest) {
+    const compositions = Array.isArray(manifest?.compositions) ? manifest.compositions : [];
+    for (const composition of compositions) {
+        if (composition && typeof composition === 'object' && 'render' in composition) {
+            throw new Error(`manifest composition '${composition.id ?? '<unknown>'}' declares removed composition.render. Use lightingBaselineId/materialsBaselineId/hdrBaselineId directly.`);
+        }
+    }
+    return compositions;
+}
+export function resolveCompositionBaselineIds(composition) {
+    return {
+        lightingBaselineId: composition?.lightingBaselineId,
+        materialsBaselineId: composition?.materialsBaselineId,
+        hdrBaselineId: composition?.hdrBaselineId,
+    };
+}
+export function resolveToolDescriptor(tool, plugin) {
+    const rawPlugin = plugin;
+    const rawTool = tool;
+    const pluginExtRecord = plugin.extensions ?? {};
+    const toolExtRecord = tool.extensions ?? {};
+    const { render: _ignoredPluginRender, ...pluginExt } = pluginExtRecord;
+    const { render: _ignoredToolRender, ...toolExt } = toolExtRecord;
+    const hasPluginRenderCompat = Object.prototype.hasOwnProperty.call(pluginExtRecord, 'render');
+    const hasToolRenderCompat = Object.prototype.hasOwnProperty.call(toolExtRecord, 'render');
+    const diagnostics = [];
+    const label = tool.label || pluginExt.label || tool.toolId;
+    const summary = toolExt.summary ??
+        pluginExt.summary ??
+        undefined;
+    const mergedExtensions = {
+        ...toolExt,
+        ...(toolExt.label === undefined && pluginExt.label !== undefined ? { label: pluginExt.label } : {}),
+        ...(toolExt.summary === undefined && pluginExt.summary !== undefined ? { summary: pluginExt.summary } : {}),
+        ...(toolExt.tags === undefined && pluginExt.tags !== undefined ? { tags: pluginExt.tags } : {}),
+    };
+    const canonicalMapInputs = mergeMapInputs(plugin.mapInputs, tool.mapInputs);
+    const promptPack = resolveToolPromptPack(tool);
+    const mapInputs = canonicalMapInputs;
+    const uiResolution = resolveToolUi(tool, plugin);
+    const baselines = resolveManifestBaselines({
+        baselines: plugin.baselines,
+    });
+    const startupDefaultWarnings = resolveStartupDefaultWarnings(tool, baselines);
+    const presentationResolution = resolveToolPresentation({
+        presentation: plugin.presentation,
+    });
+    if (presentationResolution.source !== 'canonical') {
+        diagnostics.push(`tool '${tool.toolId}' is using default object3d presentation; add top-level presentation for explicit scene policy.`);
+    }
+    if (hasPluginRenderCompat || hasToolRenderCompat) {
+        throw new Error(`tool '${tool.toolId}' declares removed extensions.render metadata. Delete extensions.render from the manifest before publish.`);
+    }
+    if (rawPlugin.promptPack && trimModeId(rawPlugin.promptPack.id)) {
+        throw new Error(`tool '${tool.toolId}' declares plugin-level promptPack. Composer only reads tool.promptPack; move prompt pack ids onto the tool manifest.`);
+    }
+    if (Object.prototype.hasOwnProperty.call(rawPlugin, 'surfaceTypes')) {
+        throw new Error(`tool '${tool.toolId}' declares removed plugin.surfaceTypes. Move plugin-owned surface vocabulary into Geometry surface-contract.json and publish it as top-level surfaceContract.`);
+    }
+    if (Object.prototype.hasOwnProperty.call(rawPlugin, 'surfaceMappings')) {
+        throw new Error(`tool '${tool.toolId}' declares removed plugin.surfaceMappings. Active runtime plugins must emit direct b2:surfaceClass values instead of manifest surface mappings.`);
+    }
+    if (hasLegacyPromptingDefinition(rawPlugin.prompting)) {
+        throw new Error(`tool '${tool.toolId}' declares legacy plugin-level prompting metadata. Remove prompting and declare tool.promptPack instead.`);
+    }
+    if (hasLegacyPromptingDefinition(rawTool.prompting)) {
+        throw new Error(`tool '${tool.toolId}' declares legacy top-level prompting metadata. Remove prompting and declare tool.promptPack instead.`);
+    }
+    const legacyPresets = plugin.presets;
+    if (Array.isArray(legacyPresets)) {
+        throw new Error(`tool '${tool.toolId}' declares removed presets[]. Remove presets[] and use top-level compositions[].`);
+    }
+    const executionResolution = resolveToolExecution(tool, plugin);
+    if (executionResolution.source !== 'canonical') {
+        diagnostics.push(`tool '${tool.toolId}' is using the default execution timeout; add canonical execution.timeoutMs in the manifest if the solve is expected to run longer.`);
+    }
+    diagnostics.push(...startupDefaultWarnings.map((warning) => warning.message));
+    const resolvedTagging = plugin.tagging;
+    const surfaceContract = normalizeSurfaceContract(plugin.surfaceContract);
+    validateMaterialBaselinesAgainstSurfaceContract(tool.toolId, baselines.materials ?? [], surfaceContract);
+    return {
+        ...tool,
+        label,
+        extensions: mergedExtensions,
+        pluginId: tool.pipeline?.[0]?.pluginId ?? plugin.pluginId,
+        schema: plugin.schemas.request,
+        responseSchema: plugin.schemas.response,
+        ui: uiResolution.ui,
+        defaults: plugin.defaults,
+        presentation: presentationResolution.presentation,
+        execution: executionResolution.execution,
+        metrics: tool.metrics ?? plugin.metrics,
+        materials: plugin.materials,
+        baselines,
+        compositions: resolveManifestCompositions(plugin),
+        promptPack,
+        mapInputs,
+        surfaceContract,
+        capabilities: plugin.capabilities,
+        tagging: resolvedTagging,
+        summary,
+        compatibility: {
+            uiSource: uiResolution.source,
+            baselinesSource: plugin.baselines ? 'canonical' : 'none',
+            compositionsSource: Array.isArray(plugin.compositions) ? 'canonical' : 'none',
+            presentationSource: presentationResolution.source,
+            executionSource: executionResolution.source,
+            warnings: startupDefaultWarnings,
+            diagnostics,
+        },
+    };
+}
 export { buildDefinitionManifestFromGhInputs } from "./gh/inputsToManifest";
-export { loadSchemas, schemaUrls } from "./schemas";
-export { createDefaultManifestValidator, createManifestValidator } from "./validate";

package/dist/server.d.ts

@@ -0,0 +1,4 @@
+export type { ManifestSchemas } from "./schemas";
+export { loadSchemas, schemaUrls } from "./schemas";
+export { createDefaultManifestValidator, createManifestValidator } from "./validate";
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,8BAA8B,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC"}

package/dist/server.js

@@ -0,0 +1,2 @@
+export { loadSchemas, schemaUrls } from "./schemas";
+export { createDefaultManifestValidator, createManifestValidator } from "./validate";