@devtrack-solution/codesdd 1.2.2 → 1.2.3

package/dist/core/sdd/plugin-broker.js

@@ -0,0 +1,482 @@
+import { z } from 'zod';
+import { pluginRegistryStateSchema, resolvePluginCapability, } from './plugin-registry.js';
+import { evaluatePluginTrustPolicy, pluginPolicyEvaluationSchema } from './plugin-policy.js';
+const FEATURE_REF_PATTERN = /^FEAT-\d{4}$/;
+const OPERATION_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+const jsonObjectSchema = z.record(z.string(), z.unknown());
+const pluginInvocationModeSchema = z.enum(['dry-run', 'apply', 'rollback']);
+const approvalGrantSchema = z.enum(['maintainer', 'security', 'architecture-board']);
+const artifactOperationSchema = z.enum(['planned', 'created', 'modified', 'deleted', 'unchanged', 'validated']);
+export const pluginBrokerPlanRequestSchema = z.object({
+    feature_ref: z.string().regex(FEATURE_REF_PATTERN),
+    capability: z.string().min(1),
+    inputs: jsonObjectSchema.default({}),
+    skill_ref: z.string().min(1).optional(),
+    technology: z
+        .object({
+        language: z.string().min(1).optional(),
+        framework: z.string().min(1).optional(),
+    })
+        .optional(),
+    requested_write_scope: z.array(z.string().min(1)).default([]),
+    require_apply: z.boolean().default(false),
+    created_at: z.string().datetime().optional(),
+});
+export const pluginInvocationEnvelopeSchema = z.object({
+    schema_version: z.literal(1),
+    mode: z.literal('dry-run'),
+    feature_ref: z.string().regex(FEATURE_REF_PATTERN),
+    skill_ref: z.string().optional(),
+    plugin_ref: z.object({
+        id: z.string().min(1),
+        version: z.string().min(1),
+    }),
+    capability: z.string().min(1),
+    inputs: jsonObjectSchema,
+    command: z.object({
+        executable: z.string().min(1),
+        args: z.array(z.string()).default([]),
+        timeout_seconds: z.number().int().positive(),
+        env_allowlist: z.array(z.string()).default([]),
+        network: z.enum(['disabled', 'restricted', 'enabled']),
+        process_spawn: z.enum(['forbidden', 'declared']),
+    }),
+    write_scope: z.array(z.string()).default([]),
+    evidence_requirements: z.array(z.string()).default([]),
+});
+export const pluginArtifactManifestEntrySchema = z.object({
+    path: z.string().min(1),
+    operation: artifactOperationSchema,
+    reason: z.string().min(1),
+    checksum_before: z.string().optional(),
+    checksum_after: z.string().optional(),
+    content_type: z.string().optional(),
+});
+export const pluginArtifactManifestSchema = z.object({
+    schema_version: z.literal(1),
+    operation_id: z.string().regex(OPERATION_ID_PATTERN),
+    generated_at: z.string().datetime(),
+    feature_ref: z.string().regex(FEATURE_REF_PATTERN),
+    plugin_ref: z.object({
+        id: z.string().min(1),
+        version: z.string().min(1),
+    }),
+    capability: z.string().min(1),
+    mode: pluginInvocationModeSchema,
+    status: z.enum(['planned', 'applied', 'rolled_back', 'failed']),
+    artifacts: z.array(pluginArtifactManifestEntrySchema).default([]),
+    validation_evidence: z
+        .array(z.object({
+        command: z.string().min(1),
+        status: z.enum(['pending', 'passed', 'failed', 'skipped']),
+        evidence_ref: z.string().optional(),
+    }))
+        .default([]),
+});
+export const pluginRollbackManifestSchema = z.object({
+    schema_version: z.literal(1),
+    operation_id: z.string().regex(OPERATION_ID_PATTERN),
+    generated_at: z.string().datetime(),
+    feature_ref: z.string().regex(FEATURE_REF_PATTERN),
+    plugin_ref: z.object({
+        id: z.string().min(1),
+        version: z.string().min(1),
+    }),
+    capability: z.string().min(1),
+    mode: pluginInvocationModeSchema,
+    status: z.enum(['planned', 'not-required']),
+    reason: z.string().min(1),
+    rollback_steps: z.array(z.string().min(1)).default([]),
+});
+export const pluginRuntimeInvocationRequestSchema = pluginBrokerPlanRequestSchema.extend({
+    mode: pluginInvocationModeSchema.default('dry-run'),
+    operation_id: z.string().regex(OPERATION_ID_PATTERN).optional(),
+    approval_grants: z.array(approvalGrantSchema).default([]),
+    source_checksum: z.string().optional(),
+    planned_writes: z.array(z.string().min(1)).default([]),
+    requested_env: z.array(z.string().min(1)).default([]),
+    network_domains: z.array(z.string().min(1)).default([]),
+    process_spawn_requested: z.boolean().default(false),
+    filesystem_checks: z
+        .array(z.object({
+        path: z.string().min(1),
+        real_path: z.string().min(1),
+        project_root: z.string().min(1),
+        is_symlink: z.boolean().default(false),
+    }))
+        .default([]),
+});
+export const pluginRuntimeInvocationEnvelopeSchema = z.object({
+    schema_version: z.literal(1),
+    operation_id: z.string().regex(OPERATION_ID_PATTERN),
+    created_at: z.string().datetime(),
+    mode: pluginInvocationModeSchema,
+    feature_ref: z.string().regex(FEATURE_REF_PATTERN),
+    skill_ref: z.string().optional(),
+    plugin_ref: z.object({
+        id: z.string().min(1),
+        version: z.string().min(1),
+    }),
+    capability: z.string().min(1),
+    inputs: jsonObjectSchema,
+    command: z.object({
+        executable: z.string().min(1),
+        args: z.array(z.string()).default([]),
+        timeout_seconds: z.number().int().positive(),
+        env_allowlist: z.array(z.string()).default([]),
+        network: z.enum(['disabled', 'restricted', 'enabled']),
+        process_spawn: z.enum(['forbidden', 'declared']),
+        working_directory: z.string().min(1),
+    }),
+    write_scope: z.array(z.string()).default([]),
+    policy: pluginPolicyEvaluationSchema,
+    expected_artifact_manifest: z.object({
+        path: z.string().min(1),
+        required_operations: z.array(artifactOperationSchema).default([]),
+    }),
+    expected_evidence_manifest: z.object({
+        path: z.string().min(1),
+    }),
+    expected_validation_manifest: z.object({
+        path: z.string().min(1),
+        required_statuses: z.array(z.enum(['passed', 'failed', 'partial'])).default([]),
+    }),
+    expected_rollback_manifest: z.object({
+        path: z.string().min(1),
+        required_for_mode: z.boolean(),
+    }),
+    evidence_requirements: z.array(z.string()).default([]),
+});
+export const pluginRuntimeInvocationPlanSchema = z.object({
+    schema_version: z.literal(1),
+    created_at: z.string().datetime(),
+    status: z.enum(['ready', 'blocked', 'unresolved']),
+    request: pluginRuntimeInvocationRequestSchema,
+    reasons: z.array(z.string()).default([]),
+    policy: pluginPolicyEvaluationSchema.optional(),
+    envelope: pluginRuntimeInvocationEnvelopeSchema.optional(),
+    artifact_manifest: pluginArtifactManifestSchema.optional(),
+    rollback_manifest: pluginRollbackManifestSchema.optional(),
+});
+export const pluginDryRunArtifactPlanEntrySchema = z.object({
+    path: z.string().min(1),
+    operation: z.enum(['plan']),
+    reason: z.string().min(1),
+});
+export const pluginDryRunExecutionPlanSchema = z.object({
+    schema_version: z.literal(1),
+    created_at: z.string().datetime(),
+    status: z.enum(['planned', 'unresolved']),
+    request: pluginBrokerPlanRequestSchema,
+    reasons: z.array(z.string()).default([]),
+    envelope: pluginInvocationEnvelopeSchema.optional(),
+    artifact_plan: z.array(pluginDryRunArtifactPlanEntrySchema).default([]),
+});
+export function buildPluginDryRunExecutionPlan(registryState, request) {
+    const parsedRegistry = pluginRegistryStateSchema.parse(registryState);
+    const parsedRequest = pluginBrokerPlanRequestSchema.parse(request);
+    const createdAt = parsedRequest.created_at ?? new Date().toISOString();
+    const resolution = resolvePluginCapability(parsedRegistry, toResolutionRequest(parsedRequest));
+    if (resolution.status === 'unresolved') {
+        return pluginDryRunExecutionPlanSchema.parse({
+            schema_version: 1,
+            created_at: createdAt,
+            status: 'unresolved',
+            request: {
+                ...parsedRequest,
+                created_at: createdAt,
+            },
+            reasons: resolution.reasons,
+            artifact_plan: [],
+        });
+    }
+    const writeScopeCheck = resolveWriteScope(parsedRequest.requested_write_scope, resolution.capability.write_scope);
+    if (!writeScopeCheck.allowed) {
+        return pluginDryRunExecutionPlanSchema.parse({
+            schema_version: 1,
+            created_at: createdAt,
+            status: 'unresolved',
+            request: {
+                ...parsedRequest,
+                created_at: createdAt,
+            },
+            reasons: writeScopeCheck.reasons,
+            artifact_plan: [],
+        });
+    }
+    const envelope = pluginInvocationEnvelopeSchema.parse({
+        schema_version: 1,
+        mode: 'dry-run',
+        feature_ref: parsedRequest.feature_ref,
+        skill_ref: parsedRequest.skill_ref,
+        plugin_ref: {
+            id: resolution.entry.manifest.id,
+            version: resolution.entry.manifest.version,
+        },
+        capability: resolution.capability.name,
+        inputs: parsedRequest.inputs,
+        command: {
+            executable: resolution.entry.manifest.execution.command,
+            args: resolution.entry.manifest.execution.args,
+            timeout_seconds: resolution.entry.manifest.execution.timeout_seconds,
+            env_allowlist: resolution.entry.manifest.execution.env_allowlist,
+            network: resolution.entry.manifest.execution.network,
+            process_spawn: resolution.entry.manifest.execution.process_spawn,
+        },
+        write_scope: writeScopeCheck.writeScope,
+        evidence_requirements: [
+            'artifact_manifest',
+            'evidence_manifest',
+            ...resolution.entry.manifest.validation.commands.map((command) => `validation:${command}`),
+        ],
+    });
+    return pluginDryRunExecutionPlanSchema.parse({
+        schema_version: 1,
+        created_at: createdAt,
+        status: 'planned',
+        request: {
+            ...parsedRequest,
+            created_at: createdAt,
+        },
+        reasons: resolution.reasons,
+        envelope,
+        artifact_plan: writeScopeCheck.writeScope.map((scope) => ({
+            path: scope,
+            operation: 'plan',
+            reason: `${resolution.entry.manifest.id}/${resolution.capability.name} may plan writes under ${scope}.`,
+        })),
+    });
+}
+export function buildPluginRuntimeInvocationPlan(registryState, request) {
+    const parsedRegistry = pluginRegistryStateSchema.parse(registryState);
+    const parsedRequest = pluginRuntimeInvocationRequestSchema.parse(request);
+    const createdAt = parsedRequest.created_at ?? new Date().toISOString();
+    const requestWithCreatedAt = {
+        ...parsedRequest,
+        created_at: createdAt,
+    };
+    const resolution = resolvePluginCapability(parsedRegistry, toRuntimeResolutionRequest(parsedRequest));
+    if (resolution.status === 'unresolved') {
+        return pluginRuntimeInvocationPlanSchema.parse({
+            schema_version: 1,
+            created_at: createdAt,
+            status: 'unresolved',
+            request: requestWithCreatedAt,
+            reasons: resolution.reasons,
+        });
+    }
+    const writeScopeCheck = resolveWriteScope(parsedRequest.requested_write_scope, resolution.capability.write_scope);
+    if (!writeScopeCheck.allowed) {
+        return pluginRuntimeInvocationPlanSchema.parse({
+            schema_version: 1,
+            created_at: createdAt,
+            status: 'unresolved',
+            request: requestWithCreatedAt,
+            reasons: writeScopeCheck.reasons,
+        });
+    }
+    const policy = evaluatePluginTrustPolicy(resolution.entry.manifest, {
+        capability: resolution.capability.name,
+        mode: parsedRequest.mode,
+        approval_grants: parsedRequest.approval_grants,
+        source_checksum: parsedRequest.source_checksum ?? resolution.entry.source.checksum,
+        requested_write_scope: writeScopeCheck.writeScope,
+        planned_writes: parsedRequest.planned_writes,
+        requested_env: parsedRequest.requested_env,
+        network_domains: parsedRequest.network_domains,
+        process_spawn_requested: parsedRequest.process_spawn_requested,
+        filesystem_checks: parsedRequest.filesystem_checks,
+    });
+    const policyReasons = policy.issues.map((issue) => `${issue.severity}:${issue.code}: ${issue.message}`);
+    if (policy.decision === 'deny') {
+        return pluginRuntimeInvocationPlanSchema.parse({
+            schema_version: 1,
+            created_at: createdAt,
+            status: 'blocked',
+            request: requestWithCreatedAt,
+            reasons: [...resolution.reasons, ...policyReasons],
+            policy,
+        });
+    }
+    const operationId = parsedRequest.operation_id ??
+        buildOperationId(parsedRequest.feature_ref, resolution.entry.manifest.id, resolution.capability.name, parsedRequest.mode, createdAt);
+    const pluginRef = {
+        id: resolution.entry.manifest.id,
+        version: resolution.entry.manifest.version,
+    };
+    const evidenceRequirements = [
+        'artifact_manifest',
+        'evidence_manifest',
+        'validation_manifest',
+        'policy_evaluation',
+        'rollback_manifest',
+        ...resolution.entry.manifest.validation.commands.map((command) => `validation:${command}`),
+    ];
+    const evidenceRoot = `.sdd/plugin-evidence/${parsedRequest.feature_ref}/${operationId}`;
+    const artifactManifestPath = `${evidenceRoot}/artifact-manifest.yaml`;
+    const evidenceManifestPath = `${evidenceRoot}/evidence-manifest.yaml`;
+    const validationManifestPath = `${evidenceRoot}/validation-manifest.yaml`;
+    const rollbackManifestPath = `${evidenceRoot}/rollback-manifest.yaml`;
+    const artifactManifest = buildPlannedArtifactManifest({
+        operationId,
+        createdAt,
+        featureRef: parsedRequest.feature_ref,
+        pluginRef,
+        capability: resolution.capability.name,
+        mode: parsedRequest.mode,
+        writeScope: writeScopeCheck.writeScope,
+        validationCommands: resolution.entry.manifest.validation.commands,
+    });
+    const rollbackManifest = buildPlannedRollbackManifest({
+        operationId,
+        createdAt,
+        featureRef: parsedRequest.feature_ref,
+        pluginRef,
+        capability: resolution.capability.name,
+        mode: parsedRequest.mode,
+        supportsRollback: resolution.capability.supports_rollback,
+    });
+    const envelope = pluginRuntimeInvocationEnvelopeSchema.parse({
+        schema_version: 1,
+        operation_id: operationId,
+        created_at: createdAt,
+        mode: parsedRequest.mode,
+        feature_ref: parsedRequest.feature_ref,
+        skill_ref: parsedRequest.skill_ref,
+        plugin_ref: pluginRef,
+        capability: resolution.capability.name,
+        inputs: parsedRequest.inputs,
+        command: {
+            executable: resolution.entry.manifest.execution.command,
+            args: resolution.entry.manifest.execution.args,
+            timeout_seconds: resolution.entry.manifest.execution.timeout_seconds,
+            env_allowlist: resolution.entry.manifest.execution.env_allowlist,
+            network: resolution.entry.manifest.execution.network,
+            process_spawn: resolution.entry.manifest.execution.process_spawn,
+            working_directory: resolution.entry.manifest.execution.working_directory,
+        },
+        write_scope: writeScopeCheck.writeScope,
+        policy,
+        expected_artifact_manifest: {
+            path: artifactManifestPath,
+            required_operations: ['planned'],
+        },
+        expected_evidence_manifest: {
+            path: evidenceManifestPath,
+        },
+        expected_validation_manifest: {
+            path: validationManifestPath,
+            required_statuses: ['passed', 'failed', 'partial'],
+        },
+        expected_rollback_manifest: {
+            path: rollbackManifestPath,
+            required_for_mode: parsedRequest.mode === 'apply' || parsedRequest.mode === 'rollback',
+        },
+        evidence_requirements: evidenceRequirements,
+    });
+    return pluginRuntimeInvocationPlanSchema.parse({
+        schema_version: 1,
+        created_at: createdAt,
+        status: 'ready',
+        request: requestWithCreatedAt,
+        reasons: [...resolution.reasons, ...policyReasons],
+        policy,
+        envelope,
+        artifact_manifest: artifactManifest,
+        rollback_manifest: rollbackManifest,
+    });
+}
+function toResolutionRequest(request) {
+    return {
+        capability: request.capability,
+        technology: request.technology,
+        require_apply: request.require_apply,
+        require_dry_run: true,
+    };
+}
+function toRuntimeResolutionRequest(request) {
+    return {
+        capability: request.capability,
+        technology: request.technology,
+        require_apply: request.require_apply || request.mode === 'apply',
+        require_dry_run: true,
+    };
+}
+function resolveWriteScope(requestedWriteScope, capabilityWriteScope) {
+    const availableScope = [...new Set(capabilityWriteScope)].sort();
+    const requestedScope = [...new Set(requestedWriteScope)].sort();
+    if (requestedScope.length === 0) {
+        return {
+            allowed: true,
+            writeScope: availableScope,
+        };
+    }
+    const denied = requestedScope.filter((scope) => !availableScope.includes(scope));
+    if (denied.length > 0) {
+        return {
+            allowed: false,
+            reasons: denied.map((scope) => `Requested write scope ${scope} is not advertised by the resolved capability.`),
+        };
+    }
+    return {
+        allowed: true,
+        writeScope: requestedScope,
+    };
+}
+function buildOperationId(featureRef, pluginId, capability, mode, createdAt) {
+    const timestamp = createdAt.replace(/\D/gu, '');
+    return normalizeOperationSegment(['plugin-op', featureRef, pluginId, capability, mode, timestamp].join('-'));
+}
+function normalizeOperationSegment(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/gu, '-')
+        .replace(/^-+|-+$/gu, '');
+}
+function buildPlannedArtifactManifest(input) {
+    return pluginArtifactManifestSchema.parse({
+        schema_version: 1,
+        operation_id: input.operationId,
+        generated_at: input.createdAt,
+        feature_ref: input.featureRef,
+        plugin_ref: input.pluginRef,
+        capability: input.capability,
+        mode: input.mode,
+        status: 'planned',
+        artifacts: input.writeScope.map((scope) => ({
+            path: scope,
+            operation: 'planned',
+            reason: `${input.pluginRef.id}/${input.capability} is authorized to report artifact changes under ${scope}.`,
+        })),
+        validation_evidence: input.validationCommands.map((command) => ({
+            command,
+            status: 'pending',
+        })),
+    });
+}
+function buildPlannedRollbackManifest(input) {
+    const rollbackRequired = input.mode === 'apply' || input.mode === 'rollback';
+    const status = rollbackRequired && input.supportsRollback ? 'planned' : 'not-required';
+    return pluginRollbackManifestSchema.parse({
+        schema_version: 1,
+        operation_id: input.operationId,
+        generated_at: input.createdAt,
+        feature_ref: input.featureRef,
+        plugin_ref: input.pluginRef,
+        capability: input.capability,
+        mode: input.mode,
+        status,
+        reason: rollbackRequired
+            ? input.supportsRollback
+                ? 'Rollback evidence is required for mutating executions and rollback-capable capabilities.'
+                : 'Capability does not declare rollback support; rollback evidence is not required.'
+            : 'Rollback evidence is not required for dry-run mode.',
+        rollback_steps: rollbackRequired && input.supportsRollback
+            ? [
+                'Capture pre-apply artifact checksums before mutation.',
+                'Record rollback command and approval evidence when rollback is triggered.',
+            ]
+            : [],
+    });
+}
+//# sourceMappingURL=plugin-broker.js.map

package/dist/core/sdd/plugin-certification.d.ts

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+import { type PluginRegistrySource } from './plugin-registry.js';
+export declare const pluginCertificationLevelSchema: z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>]>;
+export declare const pluginCertificationAchievedLevelSchema: z.ZodUnion<readonly [z.ZodLiteral<-1>, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>]>;
+export declare const pluginCertificationCriterionSchema: z.ZodObject<{
+    id: z.ZodString;
+    level: z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>]>;
+    status: z.ZodEnum<{
+        warning: "warning";
+        failed: "failed";
+        passed: "passed";
+    }>;
+    evidence: z.ZodString;
+    remediation: z.ZodString;
+    issue_codes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const pluginCertificationResultSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<1>;
+    generated_at: z.ZodString;
+    feature_ref: z.ZodString;
+    plugin_ref: z.ZodObject<{
+        id: z.ZodString;
+        version: z.ZodString;
+    }, z.core.$strip>;
+    capability: z.ZodString;
+    stack: z.ZodDefault<z.ZodObject<{
+        language: z.ZodOptional<z.ZodString>;
+        framework: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    requested_level: z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>]>;
+    achieved_level: z.ZodUnion<readonly [z.ZodLiteral<-1>, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>]>;
+    status: z.ZodEnum<{
+        warning: "warning";
+        failed: "failed";
+        certified: "certified";
+    }>;
+    warning_only: z.ZodLiteral<true>;
+    blocking: z.ZodLiteral<false>;
+    dry_run_plan: z.ZodOptional<z.ZodUnknown>;
+    apply_readiness_plan: z.ZodOptional<z.ZodUnknown>;
+    criteria: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        level: z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>]>;
+        status: z.ZodEnum<{
+            warning: "warning";
+            failed: "failed";
+            passed: "passed";
+        }>;
+        evidence: z.ZodString;
+        remediation: z.ZodString;
+        issue_codes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    visualization_markdown: z.ZodString;
+}, z.core.$strip>;
+export type PluginCertificationLevel = z.infer<typeof pluginCertificationLevelSchema>;
+export type PluginCertificationAchievedLevel = z.infer<typeof pluginCertificationAchievedLevelSchema>;
+export type PluginCertificationCriterion = z.infer<typeof pluginCertificationCriterionSchema>;
+export type PluginCertificationResult = z.infer<typeof pluginCertificationResultSchema>;
+export interface BuildPluginCertificationInput {
+    manifest: unknown;
+    capability: string;
+    featureRef: string;
+    requestedLevel?: PluginCertificationLevel;
+    generatedAt?: string | Date;
+    skillRef?: string;
+    technology?: {
+        language?: string;
+        framework?: string;
+    };
+    inputs?: Record<string, unknown>;
+    requestedWriteScope?: string[];
+    plannedWrites?: string[];
+    approvalGrants?: Array<'maintainer' | 'security' | 'architecture-board'>;
+    sourceChecksum?: string;
+    registrySource?: PluginRegistrySource;
+}
+export declare function buildPluginCertification(input: BuildPluginCertificationInput): PluginCertificationResult;
+export declare function renderPluginCertificationMatrix(result: Pick<PluginCertificationResult, 'plugin_ref' | 'capability' | 'requested_level' | 'achieved_level' | 'status' | 'criteria'>): string;
+//# sourceMappingURL=plugin-certification.d.ts.map