@devtrack-solution/codesdd 1.2.2 → 1.2.3

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

@@ -0,0 +1,453 @@
+import { z } from 'zod';
+import { buildPluginDryRunExecutionPlan, buildPluginRuntimeInvocationPlan, } from './plugin-broker.js';
+import { pluginManifestSchema, } from './plugin-manifest.js';
+import { createPluginRegistryState, } from './plugin-registry.js';
+export const pluginCertificationLevelSchema = z.union([z.literal(0), z.literal(1), z.literal(2)]);
+export const pluginCertificationAchievedLevelSchema = z.union([
+    z.literal(-1),
+    z.literal(0),
+    z.literal(1),
+    z.literal(2),
+]);
+export const pluginCertificationCriterionSchema = z.object({
+    id: z.string().min(1),
+    level: pluginCertificationLevelSchema,
+    status: z.enum(['passed', 'warning', 'failed']),
+    evidence: z.string().min(1),
+    remediation: z.string().min(1),
+    issue_codes: z.array(z.string().min(1)).default([]),
+});
+export const pluginCertificationResultSchema = z.object({
+    schema_version: z.literal(1),
+    generated_at: z.string().datetime(),
+    feature_ref: z.string().regex(/^FEAT-\d{4}$/),
+    plugin_ref: z.object({
+        id: z.string().min(1),
+        version: z.string().min(1),
+    }),
+    capability: z.string().min(1),
+    stack: z.object({
+        language: z.string().min(1).optional(),
+        framework: z.string().min(1).optional(),
+    }).default({}),
+    requested_level: pluginCertificationLevelSchema,
+    achieved_level: pluginCertificationAchievedLevelSchema,
+    status: z.enum(['certified', 'warning', 'failed']),
+    warning_only: z.literal(true),
+    blocking: z.literal(false),
+    dry_run_plan: z.unknown().optional(),
+    apply_readiness_plan: z.unknown().optional(),
+    criteria: z.array(pluginCertificationCriterionSchema).min(1),
+    visualization_markdown: z.string().min(1),
+});
+export function buildPluginCertification(input) {
+    const requestedLevel = input.requestedLevel ?? 2;
+    const generatedAt = normalizeTimestamp(input.generatedAt);
+    const criteria = [];
+    const manifestParse = pluginManifestSchema.safeParse(input.manifest);
+    const pluginRef = resolvePluginRef(input.manifest);
+    const stack = resolveStack(input.manifest, input.technology);
+    if (!manifestParse.success) {
+        criteria.push(criterion({
+            id: 'L0_MANIFEST_SCHEMA_VALID',
+            level: 0,
+            status: 'failed',
+            evidence: manifestParse.error.issues
+                .map((issue) => `${issue.path.join('.') || '<root>'}: ${issue.message}`)
+                .join('; '),
+            remediation: 'Fix the plugin manifest so it satisfies the CodeSDD plugin manifest schema.',
+            issueCodes: ['PLUGIN_CERT_MANIFEST_INVALID'],
+        }));
+        return finalizeResult({
+            generatedAt,
+            featureRef: input.featureRef,
+            pluginRef,
+            capability: input.capability,
+            stack,
+            requestedLevel,
+            criteria,
+        });
+    }
+    const manifest = manifestParse.data;
+    const capability = manifest.capabilities.find((candidate) => candidate.name === input.capability);
+    criteria.push(...levelZeroCriteria(manifest, input.capability, capability));
+    if (requestedLevel >= 1 && capability) {
+        const dryRunProof = buildDryRunProof(manifest, capability, input, generatedAt);
+        criteria.push(dryRunProof.criterion);
+        if (requestedLevel >= 2) {
+            const applyReadiness = buildApplyReadinessProof(manifest, capability, input, generatedAt);
+            criteria.push(applyReadiness.criterion);
+            return finalizeResult({
+                generatedAt,
+                featureRef: input.featureRef,
+                pluginRef: {
+                    id: manifest.id,
+                    version: manifest.version,
+                },
+                capability: input.capability,
+                stack,
+                requestedLevel,
+                dryRunPlan: dryRunProof.plan,
+                applyReadinessPlan: applyReadiness.plan,
+                criteria,
+            });
+        }
+        return finalizeResult({
+            generatedAt,
+            featureRef: input.featureRef,
+            pluginRef: {
+                id: manifest.id,
+                version: manifest.version,
+            },
+            capability: input.capability,
+            stack,
+            requestedLevel,
+            dryRunPlan: dryRunProof.plan,
+            criteria,
+        });
+    }
+    return finalizeResult({
+        generatedAt,
+        featureRef: input.featureRef,
+        pluginRef: {
+            id: manifest.id,
+            version: manifest.version,
+        },
+        capability: input.capability,
+        stack,
+        requestedLevel,
+        criteria,
+    });
+}
+export function renderPluginCertificationMatrix(result) {
+    const rows = result.criteria.map((criterionResult) => [
+        String(criterionResult.level),
+        criterionResult.id,
+        criterionResult.status,
+        criterionResult.issue_codes.length > 0 ? criterionResult.issue_codes.join(', ') : '-',
+        criterionResult.evidence,
+        criterionResult.remediation,
+    ]);
+    return [
+        '# Plugin Certification Matrix',
+        '',
+        `- Plugin: \`${result.plugin_ref.id}@${result.plugin_ref.version}\``,
+        `- Capability: \`${result.capability}\``,
+        `- Requested level: \`${result.requested_level}\``,
+        `- Achieved level: \`${result.achieved_level}\``,
+        `- Status: \`${result.status}\``,
+        '- Warning-only: yes',
+        '- Blocking: no',
+        '',
+        '| Level | Criterion | Status | Issue Codes | Evidence | Remediation |',
+        '| --- | --- | --- | --- | --- | --- |',
+        ...rows.map((row) => `| ${row.map(escapeCell).join(' | ')} |`),
+        '',
+    ].join('\n');
+}
+function levelZeroCriteria(manifest, capabilityName, capability) {
+    const criteria = [
+        criterion({
+            id: 'L0_MANIFEST_SCHEMA_VALID',
+            level: 0,
+            status: 'passed',
+            evidence: `${manifest.id}@${manifest.version} satisfies the plugin manifest schema.`,
+            remediation: 'Keep the manifest schema-valid as capabilities evolve.',
+        }),
+    ];
+    if (!capability) {
+        criteria.push(criterion({
+            id: 'L0_CAPABILITY_DECLARED',
+            level: 0,
+            status: 'failed',
+            evidence: `Capability ${capabilityName} is not declared by ${manifest.id}@${manifest.version}.`,
+            remediation: 'Declare the capability in the plugin manifest or certify an advertised capability.',
+            issueCodes: ['PLUGIN_CERT_CAPABILITY_MISSING'],
+        }));
+        return criteria;
+    }
+    criteria.push(criterion({
+        id: 'L0_CAPABILITY_DECLARED',
+        level: 0,
+        status: 'passed',
+        evidence: `Capability ${capability.name} is declared by ${manifest.id}@${manifest.version}.`,
+        remediation: 'Keep the certified capability name stable or recertify after renaming.',
+    }), criterion({
+        id: 'L0_DRY_RUN_SUPPORTED',
+        level: 0,
+        status: capability.supports_dry_run ? 'passed' : 'failed',
+        evidence: capability.supports_dry_run
+            ? `${capability.name} declares dry-run support.`
+            : `${capability.name} does not declare dry-run support.`,
+        remediation: 'Level 0 certification requires dry-run support for safe enterprise inspection.',
+        issueCodes: capability.supports_dry_run ? [] : ['PLUGIN_CERT_DRY_RUN_UNSUPPORTED'],
+    }), criterion({
+        id: 'L0_CAPABILITY_DETERMINISTIC',
+        level: 0,
+        status: capability.deterministic ? 'passed' : 'failed',
+        evidence: capability.deterministic
+            ? `${capability.name} declares deterministic behavior.`
+            : `${capability.name} does not declare deterministic behavior.`,
+        remediation: 'Declare deterministic behavior only after the same input can reproduce the same normalized plan.',
+        issueCodes: capability.deterministic ? [] : ['PLUGIN_CERT_NON_DETERMINISTIC'],
+    }), criterion({
+        id: 'L0_CAPABILITY_IDEMPOTENT',
+        level: 0,
+        status: capability.idempotent ? 'passed' : 'failed',
+        evidence: capability.idempotent
+            ? `${capability.name} declares idempotent behavior.`
+            : `${capability.name} does not declare idempotent behavior.`,
+        remediation: 'Make repeated dry-run/apply requests safe or restrict the capability before certification.',
+        issueCodes: capability.idempotent ? [] : ['PLUGIN_CERT_NON_IDEMPOTENT'],
+    }));
+    return criteria;
+}
+function buildDryRunProof(manifest, capability, input, generatedAt) {
+    try {
+        const registry = createPluginRegistryState([
+            {
+                manifest,
+                source: input.registrySource ?? defaultRegistrySource(manifest),
+                registered_at: generatedAt,
+            },
+        ], generatedAt);
+        const request = {
+            feature_ref: input.featureRef,
+            capability: capability.name,
+            skill_ref: input.skillRef,
+            inputs: input.inputs ?? {},
+            technology: input.technology,
+            requested_write_scope: input.requestedWriteScope ?? [],
+            require_apply: false,
+            created_at: generatedAt,
+        };
+        const first = buildPluginDryRunExecutionPlan(registry, request);
+        const second = buildPluginDryRunExecutionPlan(registry, request);
+        if (first.status !== 'planned') {
+            return {
+                plan: first,
+                criterion: criterion({
+                    id: 'L1_DRY_RUN_PLAN_RESOLVED',
+                    level: 1,
+                    status: 'failed',
+                    evidence: first.reasons.join('; ') || 'Dry-run plan was unresolved.',
+                    remediation: 'Ensure the registry can resolve the capability and requested write scope.',
+                    issueCodes: ['PLUGIN_CERT_DRY_RUN_UNRESOLVED'],
+                }),
+            };
+        }
+        const deterministic = stableJson(normalizeDryRunPlan(first)) === stableJson(normalizeDryRunPlan(second));
+        return {
+            plan: first,
+            criterion: criterion({
+                id: 'L1_DRY_RUN_DETERMINISTIC',
+                level: 1,
+                status: deterministic ? 'passed' : 'failed',
+                evidence: deterministic
+                    ? `Two dry-run plans for ${capability.name} produced the same normalized envelope and artifact plan.`
+                    : `Two dry-run plans for ${capability.name} diverged after normalization.`,
+                remediation: 'Remove undeclared nondeterminism from the dry-run plan or declare it in a later scenario-level exception.',
+                issueCodes: deterministic ? [] : ['PLUGIN_CERT_DRY_RUN_NON_DETERMINISTIC'],
+            }),
+        };
+    }
+    catch (error) {
+        return {
+            criterion: criterion({
+                id: 'L1_DRY_RUN_DETERMINISTIC',
+                level: 1,
+                status: 'failed',
+                evidence: `Dry-run certification could not be evaluated: ${String(error)}`,
+                remediation: 'Fix dry-run planning inputs before certifying Level 1.',
+                issueCodes: ['PLUGIN_CERT_DRY_RUN_EXCEPTION'],
+            }),
+        };
+    }
+}
+function buildApplyReadinessProof(manifest, capability, input, generatedAt) {
+    try {
+        const registry = createPluginRegistryState([
+            {
+                manifest,
+                source: input.registrySource ?? defaultRegistrySource(manifest),
+                registered_at: generatedAt,
+            },
+        ], generatedAt);
+        const approvalGrants = input.approvalGrants ?? defaultApprovalGrants(capability);
+        const plan = buildPluginRuntimeInvocationPlan(registry, {
+            feature_ref: input.featureRef,
+            capability: capability.name,
+            skill_ref: input.skillRef,
+            inputs: input.inputs ?? {},
+            technology: input.technology,
+            requested_write_scope: input.requestedWriteScope ?? capability.write_scope,
+            require_apply: true,
+            created_at: generatedAt,
+            mode: 'apply',
+            approval_grants: approvalGrants,
+            source_checksum: input.sourceChecksum ?? manifest.supply_chain.checksum,
+            planned_writes: input.plannedWrites ?? capability.write_scope,
+            requested_env: [],
+            network_domains: [],
+            process_spawn_requested: false,
+            filesystem_checks: [],
+        });
+        if (plan.status !== 'ready') {
+            return {
+                plan,
+                criterion: criterion({
+                    id: 'L2_APPLY_SANDBOX_READINESS',
+                    level: 2,
+                    status: 'failed',
+                    evidence: plan.reasons.join('; ') || 'Apply readiness plan was not ready.',
+                    remediation: 'Resolve apply support, approval, checksum, write-scope, or policy issues before Level 2 certification.',
+                    issueCodes: ['PLUGIN_CERT_APPLY_READINESS_BLOCKED'],
+                }),
+            };
+        }
+        const warning = plan.policy?.decision === 'warn';
+        return {
+            plan,
+            criterion: criterion({
+                id: 'L2_APPLY_SANDBOX_READINESS',
+                level: 2,
+                status: warning ? 'warning' : 'passed',
+                evidence: warning
+                    ? `Apply readiness plan is ready with warning policy decision: ${plan.reasons.join('; ')}`
+                    : `Apply readiness plan is ready for sandboxed execution without spawning plugin code.`,
+                remediation: warning
+                    ? 'Review warning policy issues before promoting this certification to a hard release gate.'
+                    : 'Keep apply execution outside CodeSDD core until a runtime adapter is explicitly approved.',
+                issueCodes: warning ? (plan.policy?.issues.map((issue) => issue.code) ?? ['PLUGIN_CERT_APPLY_POLICY_WARNING']) : [],
+            }),
+        };
+    }
+    catch (error) {
+        return {
+            criterion: criterion({
+                id: 'L2_APPLY_SANDBOX_READINESS',
+                level: 2,
+                status: 'failed',
+                evidence: `Apply readiness certification could not be evaluated: ${String(error)}`,
+                remediation: 'Fix runtime planning inputs before certifying Level 2.',
+                issueCodes: ['PLUGIN_CERT_APPLY_READINESS_EXCEPTION'],
+            }),
+        };
+    }
+}
+function finalizeResult(input) {
+    const relevantCriteria = input.criteria.filter((criterionResult) => criterionResult.level <= input.requestedLevel);
+    const achievedLevel = computeAchievedLevel(input.requestedLevel, relevantCriteria);
+    const status = relevantCriteria.some((criterionResult) => criterionResult.status === 'failed')
+        ? 'failed'
+        : relevantCriteria.some((criterionResult) => criterionResult.status === 'warning')
+            ? 'warning'
+            : 'certified';
+    const base = {
+        schema_version: 1,
+        generated_at: input.generatedAt,
+        feature_ref: input.featureRef,
+        plugin_ref: input.pluginRef,
+        capability: input.capability,
+        stack: input.stack,
+        requested_level: input.requestedLevel,
+        achieved_level: achievedLevel,
+        status,
+        warning_only: true,
+        blocking: false,
+        dry_run_plan: input.dryRunPlan,
+        apply_readiness_plan: input.applyReadinessPlan,
+        criteria: relevantCriteria,
+    };
+    return pluginCertificationResultSchema.parse({
+        ...base,
+        visualization_markdown: renderPluginCertificationMatrix(base),
+    });
+}
+function computeAchievedLevel(requestedLevel, criteria) {
+    let achieved = -1;
+    for (let level = 0; level <= requestedLevel; level += 1) {
+        const levelCriteria = criteria.filter((criterionResult) => criterionResult.level === level);
+        if (levelCriteria.length === 0 || levelCriteria.some((criterionResult) => criterionResult.status === 'failed')) {
+            break;
+        }
+        achieved = level;
+    }
+    return achieved;
+}
+function criterion(input) {
+    return pluginCertificationCriterionSchema.parse({
+        id: input.id,
+        level: input.level,
+        status: input.status,
+        evidence: input.evidence,
+        remediation: input.remediation,
+        issue_codes: input.issueCodes ?? [],
+    });
+}
+function normalizeDryRunPlan(plan) {
+    return {
+        status: plan.status,
+        reasons: plan.reasons,
+        envelope: plan.envelope,
+        artifact_plan: plan.artifact_plan,
+    };
+}
+function defaultRegistrySource(manifest) {
+    return {
+        type: 'workspace',
+        uri: `.sdd/plugins/${manifest.id}/codesdd-plugin.yaml`,
+        checksum: manifest.supply_chain.checksum,
+    };
+}
+function defaultApprovalGrants(capability) {
+    return capability.approval === 'none' ? [] : [capability.approval];
+}
+function resolvePluginRef(value) {
+    const record = asRecord(value);
+    return {
+        id: readString(record, 'id') ?? 'unknown-plugin',
+        version: readString(record, 'version') ?? 'unknown-version',
+    };
+}
+function resolveStack(value, fallback) {
+    const technology = asRecord(asRecord(value)?.technology);
+    return {
+        language: readString(technology, 'language') ?? fallback?.language,
+        framework: readString(technology, 'framework') ?? fallback?.framework,
+    };
+}
+function normalizeTimestamp(value) {
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    return value ?? new Date().toISOString();
+}
+function stableJson(value) {
+    return JSON.stringify(sortJson(value));
+}
+function sortJson(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortJson);
+    }
+    const record = asRecord(value);
+    if (!record) {
+        return value;
+    }
+    return Object.fromEntries(Object.keys(record)
+        .sort()
+        .map((key) => [key, sortJson(record[key])]));
+}
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function readString(record, key) {
+    const value = record?.[key];
+    return typeof value === 'string' ? value : undefined;
+}
+function escapeCell(value) {
+    return value.replace(/\|/gu, '\\|').replace(/\n/gu, '<br>');
+}
+//# sourceMappingURL=plugin-certification.js.map

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

@@ -0,0 +1,109 @@
+import { type DevTrackApiScaffoldDryRunPlan } from './devtrack-api-appliance.js';
+import { type PluginRuntimeInvocationPlan } from './plugin-broker.js';
+import { type PluginManifest } from './plugin-manifest.js';
+type PluginInvocationMode = 'dry-run' | 'apply' | 'rollback';
+export interface PluginCliInspectResult {
+    schema_version: 1;
+    manifest_path: string;
+    plugin_ref: {
+        id: string;
+        version: string;
+    };
+    contract_version: number;
+    technology: PluginManifest['technology'];
+    capabilities: Array<{
+        name: string;
+        supports_dry_run: boolean;
+        supports_apply: boolean;
+        supports_rollback: boolean;
+        write_scope: string[];
+        approval: string;
+        risk_tier: string;
+    }>;
+    execution: Pick<PluginManifest['execution'], 'command' | 'args' | 'timeout_seconds' | 'network' | 'process_spawn'>;
+    governance: Pick<PluginManifest['governance'], 'owner' | 'trust_tier' | 'risk_tier' | 'policy_packs'>;
+    validation: PluginManifest['validation'];
+    compression: PluginManifest['compression'];
+}
+export interface PluginCliPlanOptions {
+    feature_ref: string;
+    capability: string;
+    mode?: PluginInvocationMode;
+    skill_ref?: string;
+    inputs?: Record<string, unknown>;
+    requested_write_scope?: string[];
+    approval_grants?: string[];
+    operation_id?: string;
+    source_checksum?: string;
+    planned_writes?: string[];
+    requested_env?: string[];
+    network_domains?: string[];
+    process_spawn_requested?: boolean;
+    technology?: {
+        language?: string;
+        framework?: string;
+    };
+    created_at?: string;
+}
+export interface PluginCliPlanResult {
+    schema_version: 1;
+    manifest_path: string;
+    plan: PluginRuntimeInvocationPlan;
+    workcell_runner: PluginCliWorkcellRunner;
+}
+export interface PluginCliWorkcellRunner {
+    schema_version: 1;
+    status: PluginRuntimeInvocationPlan['status'];
+    parameterization: {
+        owner: 'llm';
+        source: 'runtime-plan-request';
+        feature_ref: string;
+        capability: string;
+    };
+    execution: {
+        owner: 'plugin-cli';
+        mode: 'dry-run' | 'apply' | 'rollback';
+        command: {
+            executable: string;
+            args: string[];
+            working_directory: string;
+        };
+        compression: {
+            mode: 'pretooluse';
+            enabled: boolean;
+            engine: PluginManifest['compression']['engine'];
+            tee: PluginManifest['compression']['tee'];
+            max_output_tokens: number;
+            exclude_commands: string[];
+            applied: boolean;
+            wrapped_command: {
+                executable: string;
+                args: string[];
+            } | null;
+        };
+    };
+    evidence: {
+        required: string[];
+    };
+    rollback: {
+        supported: boolean;
+    };
+}
+export interface DevTrackApiScaffoldDryRunCliOptions {
+    feature_ref: string;
+    project_name: string;
+    package_name?: string;
+    operation_id?: string;
+    requested_write_scope?: string[];
+    created_at?: string;
+}
+export interface DevTrackApiScaffoldDryRunCliResult {
+    schema_version: 1;
+    manifest_path: string;
+    plan: DevTrackApiScaffoldDryRunPlan;
+}
+export declare function inspectPluginManifestFromFile(manifestPath: string): Promise<PluginCliInspectResult>;
+export declare function planPluginInvocationFromFile(manifestPath: string, options: PluginCliPlanOptions): Promise<PluginCliPlanResult>;
+export declare function planDevTrackApiScaffoldDryRunFromFile(manifestPath: string, options: DevTrackApiScaffoldDryRunCliOptions): Promise<DevTrackApiScaffoldDryRunCliResult>;
+export {};
+//# sourceMappingURL=plugin-cli.d.ts.map