@devtrack-solution/codesdd 1.2.2 → 1.2.4-rc3

package/dist/core/sdd/plugin-sdk-contract.js

@@ -0,0 +1,268 @@
+import { toJSONSchema, z } from 'zod';
+const JSON_SCHEMA_DRAFT = 'https://json-schema.org/draft/2020-12/schema';
+export const CODESDD_PLUGIN_SDK_PACKAGE_NAME = '@devtrack-solution/codesdd-plugin-sdk';
+export const CODESDD_PLUGIN_PACKAGE_PREFIX = '@devtrack-solution/codesdd-plugin-';
+const SDK_PACKAGE_PATTERN = /^@devtrack-solution\/codesdd-plugin-sdk$/;
+const PLUGIN_PACKAGE_PATTERN = /^@devtrack-solution\/codesdd-plugin-[a-z0-9][a-z0-9-]*$/;
+const SEMVER_PATTERN = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+const SEMVER_RANGE_PATTERN = /^(?:[~^]?\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?|[<>]=?\d+\.\d+\.\d+(?:\s+<\d+\.\d+\.\d+)?|\*)$/;
+const FEATURE_REF_PATTERN = /^FEAT-\d{4}$/;
+const DECISION_REF_PATTERN = /^(?:ADR|DEB|EPIC|FEAT|INS)-\d{4}$/;
+const OPERATION_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+const SAFE_RELATIVE_PATH_PATTERN = /^(?!\/)(?![A-Za-z]:[\\/])(?!.*(?:^|[\\/])\.\.(?:[\\/]|$)).+$/;
+const jsonObjectSchema = z.record(z.string(), z.unknown());
+export const pluginRuntimeLanguageSchema = z.enum([
+    'typescript',
+    'javascript',
+    'python',
+    'java',
+    'go',
+    'rust',
+    'csharp',
+    'php',
+    'ruby',
+    'shell',
+    'other',
+]);
+export const pluginRuntimeBridgeSchema = z.enum([
+    'node-library',
+    'stdio-json',
+    'process-cli',
+    'http-local',
+    'container',
+    'wasm',
+]);
+export const pluginRuntimeTransportSchema = z.enum([
+    'sdk-call',
+    'stdin-json',
+    'stdout-json',
+    'file-envelope',
+    'http-json',
+]);
+export const pluginPackageKindSchema = z.enum([
+    'frontend',
+    'backend',
+    'full-stack',
+    'generator',
+    'validator',
+    'evidence',
+    'agent-adapter',
+    'policy-pack',
+]);
+export const pluginPackageGovernanceSchema = z
+    .object({
+    package_name: z.string().regex(PLUGIN_PACKAGE_PATTERN),
+    sdk_package: z.string().regex(SDK_PACKAGE_PATTERN).default(CODESDD_PLUGIN_SDK_PACKAGE_NAME),
+    sdk_version: z.string().regex(SEMVER_RANGE_PATTERN).default('*'),
+    package_kind: pluginPackageKindSchema,
+    versioning: z.literal('semver').default('semver'),
+    registry: z.enum(['workspace', 'npm', 'private-npm', 'artifact-registry', 'custom']).default('workspace'),
+    keywords: z.array(z.string().min(1)).default([]),
+    internal_package: z.boolean().default(false),
+})
+    .superRefine((value, context) => {
+    const requiredKeywords = ['codesdd-plugin', value.package_kind];
+    for (const keyword of requiredKeywords) {
+        if (!value.keywords.includes(keyword)) {
+            context.addIssue({
+                code: 'custom',
+                path: ['keywords'],
+                message: `Plugin package governance must include keyword '${keyword}'.`,
+            });
+        }
+    }
+});
+export const pluginLanguageRuntimeSchema = z
+    .object({
+    language: pluginRuntimeLanguageSchema,
+    runtime: z.string().min(1),
+    bridge: pluginRuntimeBridgeSchema,
+    input_transport: pluginRuntimeTransportSchema,
+    output_transport: pluginRuntimeTransportSchema,
+    command: z.string().min(1).optional(),
+    args: z.array(z.string()).default([]),
+    package_manager: z.string().min(1).optional(),
+    min_versions: z.record(z.string(), z.string()).default({}),
+    env_allowlist: z.array(z.string().regex(/^[A-Z_][A-Z0-9_]*$/)).default([]),
+})
+    .superRefine((runtime, context) => {
+    const nodeNative = runtime.language === 'typescript' || runtime.language === 'javascript';
+    if (runtime.bridge === 'node-library' && !nodeNative) {
+        context.addIssue({
+            code: 'custom',
+            path: ['bridge'],
+            message: 'node-library bridge is only valid for TypeScript or JavaScript plugins.',
+        });
+    }
+    if (runtime.bridge !== 'node-library' && !runtime.command) {
+        context.addIssue({
+            code: 'custom',
+            path: ['command'],
+            message: 'Non Node-library plugin runtimes must declare an executable command.',
+        });
+    }
+    if (runtime.bridge === 'stdio-json' && runtime.input_transport !== 'stdin-json') {
+        context.addIssue({
+            code: 'custom',
+            path: ['input_transport'],
+            message: 'stdio-json runtimes must receive invocation envelopes through stdin-json.',
+        });
+    }
+    if (runtime.bridge === 'stdio-json' && runtime.output_transport !== 'stdout-json') {
+        context.addIssue({
+            code: 'custom',
+            path: ['output_transport'],
+            message: 'stdio-json runtimes must emit responses through stdout-json.',
+        });
+    }
+});
+export const pluginArtifactLayerSchema = z.enum([
+    'root',
+    'domain',
+    'application',
+    'infrastructure',
+    'presentation',
+    'shared',
+    'tests',
+    'docs',
+    'sdd',
+    'config',
+    'assets',
+]);
+export const pluginArtifactKindSchema = z.enum([
+    'source',
+    'test',
+    'documentation',
+    'configuration',
+    'schema',
+    'evidence',
+    'migration',
+    'asset',
+    'package-metadata',
+]);
+export const pluginArtifactRoleSchema = z.enum([
+    'interface',
+    'type',
+    'implementation',
+    'abstraction',
+    'business-object',
+    'value-object',
+    'entity',
+    'repository-port',
+    'use-case',
+    'service',
+    'handler',
+    'adapter',
+    'mapper',
+    'module',
+    'controller',
+    'dto',
+    'validator',
+    'policy',
+    'manifest',
+    'fixture',
+    'test',
+    'documentation',
+    'evidence',
+]);
+export const pluginArtifactOperationSchema = z.enum([
+    'planned',
+    'created',
+    'modified',
+    'deleted',
+    'unchanged',
+    'validated',
+]);
+export const pluginArtifactMapEntrySchema = z
+    .object({
+    path: z.string().regex(SAFE_RELATIVE_PATH_PATTERN),
+    operation: pluginArtifactOperationSchema,
+    artifact_kind: pluginArtifactKindSchema,
+    role: pluginArtifactRoleSchema,
+    layer: pluginArtifactLayerSchema,
+    content_type: z.string().min(1),
+    reason: z.string().min(1),
+    language: pluginRuntimeLanguageSchema.optional(),
+    context: z.string().min(1).optional(),
+    implementation: z.enum(['concrete', 'abstract', 'contract', 'generated', 'manual']).default('manual'),
+    decision_refs: z.array(z.string().regex(DECISION_REF_PATTERN)).default([]),
+    source_refs: z.array(z.string().min(1)).default([]),
+    tags: z.array(z.string().min(1)).default([]),
+    metadata: jsonObjectSchema.default({}),
+})
+    .superRefine((entry, context) => {
+    if (entry.layer === 'domain' && entry.role === 'repository-port') {
+        context.addIssue({
+            code: 'custom',
+            path: ['role'],
+            message: 'Repository ports in new Foundation BO-pattern contexts belong in application ports/out, not domain.',
+        });
+    }
+    if (entry.layer === 'domain' && entry.role === 'entity' && !entry.decision_refs.some((ref) => ref.startsWith('ADR-'))) {
+        context.addIssue({
+            code: 'custom',
+            path: ['decision_refs'],
+            message: 'Domain entities require an ADR reference unless they are part of an approved legacy entity-pattern context.',
+        });
+    }
+});
+export const pluginArtifactMapSchema = z.object({
+    schema_version: z.literal(1),
+    sdk_package: z.literal(CODESDD_PLUGIN_SDK_PACKAGE_NAME).default(CODESDD_PLUGIN_SDK_PACKAGE_NAME),
+    feature_ref: z.string().regex(FEATURE_REF_PATTERN).optional(),
+    operation_id: z.string().regex(OPERATION_ID_PATTERN).optional(),
+    plugin_ref: z
+        .object({
+        id: z.string().min(1),
+        version: z.string().regex(SEMVER_PATTERN),
+    })
+        .optional(),
+    generated_at: z.string().datetime(),
+    artifacts: z.array(pluginArtifactMapEntrySchema).default([]),
+});
+export function buildPluginPackageName(pluginId) {
+    const normalized = pluginId
+        .trim()
+        .toLowerCase()
+        .replace(/^codesdd-plugin-/u, '')
+        .replace(/[^a-z0-9]+/gu, '-')
+        .replace(/^-+|-+$/gu, '');
+    if (!normalized) {
+        throw new Error('Plugin id cannot produce an empty package name.');
+    }
+    return `${CODESDD_PLUGIN_PACKAGE_PREFIX}${normalized}`;
+}
+export function validatePluginPackageGovernance(value, sourceLabel = 'plugin package governance') {
+    const result = pluginPackageGovernanceSchema.safeParse(value);
+    if (!result.success) {
+        throw new Error(`${sourceLabel} validation failed: ${result.error.issues.map(formatIssue).join('; ')}`);
+    }
+    return result.data;
+}
+export function validatePluginArtifactMap(value, sourceLabel = 'plugin artifact map') {
+    const result = pluginArtifactMapSchema.safeParse(value);
+    if (!result.success) {
+        throw new Error(`${sourceLabel} validation failed: ${result.error.issues.map(formatIssue).join('; ')}`);
+    }
+    return result.data;
+}
+export function buildPluginSdkJsonSchemas() {
+    return {
+        'plugin-package-governance.yaml': normalizeJsonSchema(pluginPackageGovernanceSchema, 'CodeSDD Plugin SDK Package Governance', 'Package naming, versioning, registry, and keyword contract for @devtrack-solution/codesdd-plugin-sdk plugin packages.'),
+        'plugin-language-runtime.yaml': normalizeJsonSchema(pluginLanguageRuntimeSchema, 'CodeSDD Plugin SDK Language Runtime', 'Language-agnostic runtime bridge contract for TypeScript, JavaScript, Python, Java, Go, Rust, C#, shell, and custom plugin implementations.'),
+        'plugin-artifact-map.yaml': normalizeJsonSchema(pluginArtifactMapSchema, 'CodeSDD Plugin SDK Artifact Map', 'Typed file map for plugin-planned artifacts with layer, role, kind, operation, decision refs, and source refs.'),
+    };
+}
+function normalizeJsonSchema(schema, title, description) {
+    return {
+        ...toJSONSchema(schema),
+        $schema: JSON_SCHEMA_DRAFT,
+        title,
+        description,
+    };
+}
+function formatIssue(issue) {
+    const issuePath = issue.path.length > 0 ? issue.path.join('.') : '<root>';
+    return `${issuePath}: ${issue.message}`;
+}
+//# sourceMappingURL=plugin-sdk-contract.js.map

package/dist/core/sdd/plugin-skill-binding.d.ts

@@ -0,0 +1,151 @@
+import { z } from 'zod';
+import { type PluginRegistryState } from './plugin-registry.js';
+export declare const pluginSkillBindingSchema: z.ZodObject<{
+    schema_version: z.ZodDefault<z.ZodLiteral<1>>;
+    skill_id: z.ZodString;
+    plugin_id: z.ZodString;
+    plugin_version: z.ZodOptional<z.ZodString>;
+    capabilities: z.ZodArray<z.ZodString>;
+    operations: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    priority: z.ZodDefault<z.ZodNumber>;
+    status: z.ZodDefault<z.ZodEnum<{
+        disabled: "disabled";
+        active: "active";
+        deprecated: "deprecated";
+    }>>;
+    rationale: z.ZodOptional<z.ZodString>;
+    technology: z.ZodOptional<z.ZodObject<{
+        language: z.ZodOptional<z.ZodString>;
+        framework: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const pluginSkillBindingResolutionRequestSchema: z.ZodObject<{
+    schema_version: z.ZodDefault<z.ZodLiteral<1>>;
+    feature_ref: z.ZodString;
+    recommended_skills: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    requested_operation: z.ZodOptional<z.ZodString>;
+    requested_capability: z.ZodOptional<z.ZodString>;
+    explicit_plugin_id: z.ZodOptional<z.ZodString>;
+    technology: z.ZodOptional<z.ZodObject<{
+        language: z.ZodOptional<z.ZodString>;
+        framework: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    trust_tiers: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        experimental: "experimental";
+        blocked: "blocked";
+        "local-dev": "local-dev";
+        "enterprise-approved": "enterprise-approved";
+    }>>>;
+    statuses: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        disabled: "disabled";
+        active: "active";
+        blocked: "blocked";
+        deprecated: "deprecated";
+    }>>>;
+    require_apply: z.ZodDefault<z.ZodBoolean>;
+    require_dry_run: z.ZodDefault<z.ZodBoolean>;
+    created_at: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const pluginSkillBindingCandidateSchema: z.ZodObject<{
+    source: z.ZodEnum<{
+        "explicit-plugin": "explicit-plugin";
+        "skill-binding": "skill-binding";
+        "capability-match": "capability-match";
+    }>;
+    skill_id: z.ZodOptional<z.ZodString>;
+    plugin_ref: z.ZodObject<{
+        id: z.ZodString;
+        version: z.ZodString;
+    }, z.core.$strip>;
+    capability: z.ZodString;
+    operation: z.ZodOptional<z.ZodString>;
+    binding_priority: z.ZodOptional<z.ZodNumber>;
+    rank: z.ZodNumber;
+    reasons: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const pluginSkillBindingResolutionSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<1>;
+    created_at: z.ZodString;
+    status: z.ZodEnum<{
+        fallback: "fallback";
+        resolved: "resolved";
+    }>;
+    request: z.ZodObject<{
+        schema_version: z.ZodDefault<z.ZodLiteral<1>>;
+        feature_ref: z.ZodString;
+        recommended_skills: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        requested_operation: z.ZodOptional<z.ZodString>;
+        requested_capability: z.ZodOptional<z.ZodString>;
+        explicit_plugin_id: z.ZodOptional<z.ZodString>;
+        technology: z.ZodOptional<z.ZodObject<{
+            language: z.ZodOptional<z.ZodString>;
+            framework: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        trust_tiers: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            experimental: "experimental";
+            blocked: "blocked";
+            "local-dev": "local-dev";
+            "enterprise-approved": "enterprise-approved";
+        }>>>;
+        statuses: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            disabled: "disabled";
+            active: "active";
+            blocked: "blocked";
+            deprecated: "deprecated";
+        }>>>;
+        require_apply: z.ZodDefault<z.ZodBoolean>;
+        require_dry_run: z.ZodDefault<z.ZodBoolean>;
+        created_at: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    selected: z.ZodOptional<z.ZodObject<{
+        source: z.ZodEnum<{
+            "explicit-plugin": "explicit-plugin";
+            "skill-binding": "skill-binding";
+            "capability-match": "capability-match";
+        }>;
+        skill_id: z.ZodOptional<z.ZodString>;
+        plugin_ref: z.ZodObject<{
+            id: z.ZodString;
+            version: z.ZodString;
+        }, z.core.$strip>;
+        capability: z.ZodString;
+        operation: z.ZodOptional<z.ZodString>;
+        binding_priority: z.ZodOptional<z.ZodNumber>;
+        rank: z.ZodNumber;
+        reasons: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    candidates: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        source: z.ZodEnum<{
+            "explicit-plugin": "explicit-plugin";
+            "skill-binding": "skill-binding";
+            "capability-match": "capability-match";
+        }>;
+        skill_id: z.ZodOptional<z.ZodString>;
+        plugin_ref: z.ZodObject<{
+            id: z.ZodString;
+            version: z.ZodString;
+        }, z.core.$strip>;
+        capability: z.ZodString;
+        operation: z.ZodOptional<z.ZodString>;
+        binding_priority: z.ZodOptional<z.ZodNumber>;
+        rank: z.ZodNumber;
+        reasons: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    reasons: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    fallback: z.ZodOptional<z.ZodObject<{
+        strategy: z.ZodEnum<{
+            "manual-selection": "manual-selection";
+            "llm-guidance": "llm-guidance";
+            "no-compatible-plugin": "no-compatible-plugin";
+        }>;
+        message: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginSkillBinding = z.infer<typeof pluginSkillBindingSchema>;
+export type PluginSkillBindingResolutionRequest = z.infer<typeof pluginSkillBindingResolutionRequestSchema>;
+export type PluginSkillBindingCandidate = z.infer<typeof pluginSkillBindingCandidateSchema>;
+export type PluginSkillBindingResolution = z.infer<typeof pluginSkillBindingResolutionSchema>;
+export type PluginSkillBindingInput = z.input<typeof pluginSkillBindingSchema>;
+export type PluginSkillBindingResolutionRequestInput = z.input<typeof pluginSkillBindingResolutionRequestSchema>;
+export declare function resolvePluginSkillBinding(registryState: PluginRegistryState, bindings: PluginSkillBindingInput[], request: PluginSkillBindingResolutionRequestInput): PluginSkillBindingResolution;
+//# sourceMappingURL=plugin-skill-binding.d.ts.map