vgxness 1.20.4 → 1.20.6

package/dist/sdd/artifact-portability-service.js

@@ -1,137 +1 @@
-import { redactJsonValue } from '../export/redaction.js';
-import { isSddPhase, sddTopicKey } from './schema.js';
-export const artifactPackageKind = 'vgxness.sdd-artifact-package';
-const defaultContext = { actor: 'artifact-portability-service' };
-const validChangePattern = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
-export class ArtifactPortabilityService {
-    memory;
-    workflow;
-    context;
-    constructor(memory, workflow, context = defaultContext) {
-        this.memory = memory;
-        this.workflow = workflow;
-        this.context = context;
-    }
-    exportPackage(input) {
-        const validIdentity = validateIdentity(input.project, input.change);
-        if (!validIdentity.ok)
-            return validIdentity;
-        const listed = this.memory.listArtifactsByTopicPrefix(input.project, `sdd/${input.change}/`, this.context);
-        if (!listed.ok)
-            return listed;
-        const artifacts = listed.value.filter(isCanonicalArtifact).map(toPortableArtifact);
-        if (artifacts.length === 0)
-            return failure(`No SDD artifacts found for ${input.project}/${input.change}`);
-        const artifactPackage = {
-            kind: artifactPackageKind,
-            version: 1,
-            project: input.project,
-            change: input.change,
-            exportedAt: new Date().toISOString(),
-            artifacts,
-        };
-        return { ok: true, value: redactJsonValue(artifactPackage) };
-    }
-    validatePackage(input) {
-        if (!isRecord(input))
-            return failure('Package must be a JSON object');
-        if (input.kind !== artifactPackageKind)
-            return failure('Package kind is invalid');
-        if (input.version !== 1)
-            return failure('Package version is invalid');
-        if (typeof input.project !== 'string' || input.project.trim().length === 0)
-            return failure('Package project is required');
-        if (typeof input.change !== 'string' || !validChangePattern.test(input.change))
-            return failure('Package change is invalid');
-        if (typeof input.exportedAt !== 'string' || input.exportedAt.trim().length === 0)
-            return failure('Package exportedAt is required');
-        if (!Array.isArray(input.artifacts) || input.artifacts.length === 0)
-            return failure('Package artifacts must not be empty');
-        const artifacts = [];
-        for (const item of input.artifacts) {
-            if (!isRecord(item))
-                return failure('Artifact entry must be an object');
-            if (typeof item.phase !== 'string' || !isSddPhase(item.phase))
-                return failure('Artifact phase is invalid');
-            if (item.topicKey !== sddTopicKey(input.change, item.phase))
-                return failure(`Artifact topicKey must be ${sddTopicKey(input.change, item.phase)}`);
-            if (typeof item.content !== 'string' || item.content.trim().length === 0)
-                return failure('Artifact content must not be empty');
-            artifacts.push({
-                phase: item.phase,
-                topicKey: item.topicKey,
-                content: item.content,
-                ...(typeof item.updatedAt === 'string' ? { updatedAt: item.updatedAt } : {}),
-            });
-        }
-        return {
-            ok: true,
-            value: { kind: artifactPackageKind, version: 1, project: input.project, change: input.change, exportedAt: input.exportedAt, artifacts },
-        };
-    }
-    planImport(input) {
-        const validated = this.validateImport(input);
-        if (!validated.ok)
-            return validated;
-        const plan = { toCreate: [], toOverwrite: [], skipped: [], errors: [] };
-        for (const artifact of validated.value.artifacts) {
-            const existing = this.memory.getArtifact(input.project, artifact.topicKey, this.context);
-            if (existing.ok && input.overwrite === true)
-                plan.toOverwrite.push(artifact.topicKey);
-            else if (existing.ok) {
-                plan.skipped.push(artifact.topicKey);
-                plan.errors.push(`Artifact already exists: ${artifact.topicKey}`);
-            }
-            else
-                plan.toCreate.push(artifact.topicKey);
-        }
-        return { ok: true, value: plan };
-    }
-    importPackage(input) {
-        const plan = this.planImport(input);
-        if (!plan.ok)
-            return plan;
-        if (plan.value.errors.length > 0)
-            return failure(plan.value.errors.join('; '));
-        const validated = this.validateImport(input);
-        if (!validated.ok)
-            return validated;
-        for (const artifact of validated.value.artifacts) {
-            const saved = this.workflow.saveArtifact({ project: input.project, change: input.change, phase: artifact.phase, content: artifact.content });
-            if (!saved.ok)
-                return saved;
-        }
-        return plan;
-    }
-    validateImport(input) {
-        const identity = validateIdentity(input.project, input.change);
-        if (!identity.ok)
-            return identity;
-        const parsed = this.validatePackage(input.package);
-        if (!parsed.ok)
-            return parsed;
-        if (parsed.value.project !== input.project || parsed.value.change !== input.change)
-            return failure('Package identity does not match import target');
-        return parsed;
-    }
-}
-function isCanonicalArtifact(artifact) {
-    const phase = artifact.topicKey.split('/').at(-1);
-    return phase !== undefined && isSddPhase(phase) && artifact.topicKey === sddTopicKey(artifact.topicKey.split('/')[1] ?? '', phase);
-}
-function toPortableArtifact(artifact) {
-    return { phase: artifact.phase, topicKey: artifact.topicKey, content: artifact.content, updatedAt: artifact.updatedAt };
-}
-function validateIdentity(project, change) {
-    if (project.trim().length === 0)
-        return failure('Project must not be empty');
-    if (!validChangePattern.test(change))
-        return failure(`Invalid SDD change id: ${change}`);
-    return { ok: true, value: { project, change } };
-}
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-function failure(message) {
-    return { ok: false, error: { code: 'validation_failed', message } };
-}
+export * from '../application/sdd/artifact-portability-service.js';

package/dist/sdd/cockpit-read-model.js

@@ -1,195 +1 @@
-import { sddPhases, sddPrerequisites } from './schema.js';
-export class SddCockpitReadModelService {
-    workflow;
-    constructor(workflow) {
-        this.workflow = workflow;
-    }
-    getReadModel(input) {
-        const cockpit = this.workflow.getCockpit(input);
-        if (!cockpit.ok)
-            return cockpit;
-        return { ok: true, value: buildSddCockpitReadModel(cockpit.value) };
-    }
-    getSurfaceResponse(input) {
-        const cockpit = this.workflow.getCockpit(input);
-        if (!cockpit.ok)
-            return cockpit;
-        return { ok: true, value: buildSddCockpitSurfaceResponse(cockpit.value) };
-    }
-}
-export function buildSddCockpitSurfaceResponse(cockpit, options = {}) {
-    return { ...cockpit, readModel: buildSddCockpitReadModel(cockpit, options) };
-}
-export function buildSddCockpitReadModel(cockpit, options = {}) {
-    const phases = cockpit.phases.map((phase) => toPhaseReadModel(phase, options.operationalEvidenceByPhase?.[phase.phase]));
-    const blockers = toReadBlockers(cockpit);
-    const nextAction = chooseNextAction(cockpit, phases);
-    return {
-        project: cockpit.project,
-        change: cockpit.change,
-        phases,
-        nextAction,
-        blockers,
-        ...(cockpit.gates === undefined ? {} : { gates: cockpit.gates }),
-        guidance: guidanceFor(cockpit, nextAction, blockers),
-        summary: summarize(phases),
-        contentIncluded: false,
-    };
-}
-function toPhaseReadModel(phase, operationalEvidence) {
-    const status = artifactReadStatus(phase);
-    const contentAvailable = phase.present && phase.artifact !== undefined;
-    const reasons = phase.blockers.map((blocker) => blocker.action ?? blocker.reason);
-    const canAccept = phase.present && !phase.accepted && status === 'draft';
-    const canReview = contentAvailable && status === 'draft';
-    return {
-        phase: phase.phase,
-        label: phaseLabel(phase.phase),
-        topicKey: phase.topicKey,
-        artifact: {
-            exists: phase.present,
-            status,
-            contentAvailable,
-            topicKey: phase.topicKey,
-            ...(phase.artifact?.artifactId === undefined ? {} : { artifactId: phase.artifact.artifactId }),
-            ...(phase.artifact?.createdAt === undefined ? {} : { createdAt: phase.artifact.createdAt }),
-            ...(phase.artifact?.updatedAt === undefined ? {} : { updatedAt: phase.artifact.updatedAt }),
-        },
-        acceptance: {
-            accepted: phase.accepted,
-            acceptedByHuman: phase.artifact?.acceptance?.actor.type === 'human',
-            ...(phase.artifact?.acceptance === undefined ? {} : { acceptance: phase.artifact.acceptance }),
-            requiredForNextPhase: isRequiredForLaterPhase(phase.phase),
-        },
-        actionability: {
-            canGenerate: !phase.present && phase.readiness.ready,
-            canReview,
-            canAccept,
-            canReopen: phase.present && status === 'rejected',
-            blocked: !phase.readiness.ready || phase.blockers.length > 0,
-            reasons,
-        },
-        ...(phase.gates === undefined ? {} : { gates: phase.gates }),
-        ...(operationalEvidence === undefined ? {} : { operationalEvidence }),
-        guidance: guidanceForPhase(phase, status, canAccept),
-    };
-}
-function artifactReadStatus(phase) {
-    if (!phase.present)
-        return 'missing';
-    if (phase.legacy)
-        return 'legacy';
-    const state = phase.state;
-    if (state === 'draft' || state === 'accepted' || state === 'rejected' || state === 'superseded' || state === 'missing')
-        return state;
-    return 'unknown';
-}
-function chooseNextAction(cockpit, phases) {
-    const reviewable = phases.find((phase) => phase.actionability.canReview);
-    if (reviewable !== undefined) {
-        return {
-            kind: 'review-artifact',
-            phase: reviewable.phase,
-            label: `Review ${reviewable.phase} artifact and accept it only after explicit human approval.`,
-            requiresConfirmation: false,
-        };
-    }
-    const generatable = phases.find((phase) => phase.actionability.canGenerate);
-    if (generatable !== undefined) {
-        return {
-            kind: 'generate-artifact',
-            phase: generatable.phase,
-            label: `Generate or create the ${generatable.phase} SDD artifact.`,
-            requiresConfirmation: false,
-        };
-    }
-    if (cockpit.next.status === 'complete') {
-        return { kind: 'none', label: 'All SDD phases are human-accepted.', requiresConfirmation: false };
-    }
-    if (cockpit.next.nextPhase !== undefined) {
-        const nextPhase = phases.find((phase) => phase.phase === cockpit.next.nextPhase);
-        return {
-            kind: 'continue-workflow',
-            phase: cockpit.next.nextPhase,
-            label: safeRecommendedAction(cockpit.recommendedAction, nextPhase),
-            requiresConfirmation: false,
-        };
-    }
-    return { kind: 'none', label: cockpit.recommendedAction, requiresConfirmation: false };
-}
-function safeRecommendedAction(recommendedAction, phase) {
-    if (phase === undefined)
-        return recommendedAction;
-    if (!/accept/i.test(recommendedAction))
-        return recommendedAction;
-    if (phase.artifact.status === 'draft')
-        return recommendedAction;
-    if (phase.artifact.status === 'rejected')
-        return `Reopen the ${phase.phase} artifact before further review.`;
-    if (phase.artifact.status === 'superseded')
-        return `Generate or inspect the current canonical ${phase.phase} artifact; superseded metadata is not actionable.`;
-    if (phase.artifact.status === 'legacy')
-        return `Inspect legacy ${phase.phase} metadata before using it in the current SDD flow.`;
-    return recommendedAction;
-}
-function toReadBlockers(cockpit) {
-    return cockpit.aggregateBlockers.map((blocker) => ({
-        phase: blocker.phase,
-        topicKey: blocker.topicKey,
-        code: blocker.kind,
-        message: blocker.reason,
-        severity: blocker.kind === 'missing-topic-key' ? 'info' : 'blocking',
-        ...(blocker.action === undefined ? {} : { action: blocker.action }),
-        ...(blocker.artifactId === undefined ? {} : { artifactId: blocker.artifactId }),
-    }));
-}
-function summarize(phases) {
-    return {
-        totalPhases: phases.length,
-        presentArtifacts: phases.filter((phase) => phase.artifact.exists).length,
-        acceptedArtifacts: phases.filter((phase) => phase.acceptance.accepted).length,
-        missingArtifacts: phases.filter((phase) => phase.artifact.status === 'missing').length,
-        draftArtifacts: phases.filter((phase) => phase.artifact.status === 'draft').length,
-        rejectedArtifacts: phases.filter((phase) => phase.artifact.status === 'rejected').length,
-        supersededArtifacts: phases.filter((phase) => phase.artifact.status === 'superseded').length,
-        legacyArtifacts: phases.filter((phase) => phase.artifact.status === 'legacy').length,
-        isComplete: phases.length === sddPhases.length && phases.every((phase) => phase.acceptance.accepted),
-    };
-}
-function guidanceFor(cockpit, nextAction, blockers) {
-    const phaseStatusByName = new Map(cockpit.phases.map((phase) => [phase.phase, artifactReadStatus(phase)]));
-    const guidance = [nextAction.label];
-    if (cockpit.phases.some((phase) => artifactReadStatus(phase) === 'draft' && !phase.accepted)) {
-        guidance.push('Artifact presence alone does not count as acceptance; explicit human acceptance is required for drafts.');
-    }
-    if (cockpit.next.blockerGuidance !== undefined) {
-        guidance.push(...cockpit.next.blockerGuidance
-            .filter((blocker) => phaseStatusByName.get(blocker.phase) === 'draft' || !/accept/i.test(blocker.action))
-            .map((blocker) => blocker.action));
-    }
-    return [...new Set(guidance)];
-}
-function guidanceForPhase(phase, status, canAccept) {
-    if (status === 'missing')
-        return [`Create the ${phase.phase} artifact when prerequisites are ready.`];
-    if (canAccept)
-        return [`Review ${phase.topicKey}; accept only after explicit human approval.`];
-    if (status === 'accepted')
-        return ['Accepted artifact metadata is available; full content is omitted from this read model.'];
-    if (status === 'rejected')
-        return ['Rejected artifact metadata is available; reopen it before further review.'];
-    if (status === 'superseded')
-        return ['Superseded artifact metadata is available; generate or inspect the current canonical artifact instead.'];
-    if (status === 'legacy')
-        return ['Legacy artifact metadata requires inspection before it can be used for current SDD flow.'];
-    return phase.blockers.map((blocker) => blocker.action ?? blocker.reason);
-}
-function phaseLabel(phase) {
-    return phase
-        .split('-')
-        .map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`)
-        .join(' ');
-}
-function isRequiredForLaterPhase(phase) {
-    return sddPhases.some((candidate) => sddPrerequisites[candidate].includes(phase));
-}
+export * from '../application/sdd/cockpit-read-model.js';

package/dist/sdd/cockpit-types.js

@@ -1 +1 @@
-export {};
+export * from '../domain/sdd/cockpit-types.js';

package/dist/sdd/schema.js

@@ -1,111 +1 @@
-import { z } from 'zod';
-export const sddPhases = ['explore', 'proposal', 'spec', 'design', 'tasks', 'apply-progress', 'verify', 'archive'];
-/**
- * Governance status of an SDD artifact.
- *
- * - `draft`     — present in the DB; satisfies downstream readiness when the
- *                 `VGXNESS_SDD_AUTO_ADVANCE` feature flag is on (or
- *                 `SddWorkflowService` is constructed with `autoAdvance: true`).
- *                 Does NOT count toward the change being `complete`.
- * - `accepted`  — content has been frozen by an explicit human
- *                 `vgxness_sdd_accept_artifact` call. Satisfies downstream
- *                 readiness regardless of the auto-advance flag.
- * - `rejected`  — explicit human rejection. Hard-blocker for downstream
- *                 readiness; can only be cleared by re-opening the artifact.
- * - `superseded`— replaced by a newer artifact under a different topic key.
- *                 Hard-blocker; cannot be re-saved or accepted.
- */
-export const sddArtifactStatuses = ['draft', 'accepted', 'rejected', 'superseded'];
-export const sddArtifactNormalizationWarnings = ['legacy-artifact-defaulted-to-draft', 'invalid-artifact-metadata-defaulted-to-draft'];
-export const SddArtifactStatusSchema = z.enum(sddArtifactStatuses);
-export const SddArtifactNormalizationWarningSchema = z.enum(sddArtifactNormalizationWarnings);
-export const SddArtifactAcceptanceRecordSchema = z
-    .object({
-    actor: z.object({
-        type: z.literal('human'),
-        id: z.string().min(1),
-        displayName: z.string().min(1).optional(),
-    }),
-    acceptedAt: z.string().min(1),
-    note: z.string().optional(),
-})
-    .strict();
-export const SddArtifactReopenRecordSchema = z
-    .object({
-    actor: z.object({
-        type: z.literal('human'),
-        id: z.string().min(1),
-        displayName: z.string().min(1).optional(),
-    }),
-    reopenedAt: z.string().min(1),
-    note: z.string().optional(),
-})
-    .strict();
-export const SddArtifactMetadataSchema = z
-    .object({
-    status: SddArtifactStatusSchema,
-    acceptance: SddArtifactAcceptanceRecordSchema.optional(),
-    reopen: SddArtifactReopenRecordSchema.optional(),
-    supersededByTopicKey: z.string().min(1).optional(),
-    updatedAt: z.string().min(1).optional(),
-})
-    .strict();
-export const SddArtifactEnvelopeSchema = z
-    .object({
-    artifact: z
-        .object({
-        id: z.string(),
-        project: z.string(),
-        topicKey: z.string(),
-        phase: z.string(),
-        content: z.string(),
-        observationId: z.string(),
-        createdAt: z.string(),
-        updatedAt: z.string(),
-    })
-        .strict(),
-    metadata: SddArtifactMetadataSchema,
-    warnings: z.array(SddArtifactNormalizationWarningSchema),
-})
-    .strict();
-export function normalizeSddArtifact(artifact) {
-    if (Object.hasOwn(artifact, 'metadata')) {
-        const parsed = SddArtifactMetadataSchema.safeParse(artifact.metadata);
-        if (parsed.success)
-            return { artifact, metadata: parsed.data, warnings: [] };
-        return {
-            artifact,
-            metadata: { status: 'draft' },
-            warnings: ['invalid-artifact-metadata-defaulted-to-draft'],
-        };
-    }
-    return {
-        artifact,
-        metadata: { status: 'draft' },
-        warnings: ['legacy-artifact-defaulted-to-draft'],
-    };
-}
-export const sddPrerequisites = {
-    explore: [],
-    proposal: ['explore'],
-    spec: ['proposal'],
-    design: ['proposal', 'spec'],
-    tasks: ['proposal', 'spec', 'design'],
-    'apply-progress': ['tasks'],
-    verify: ['apply-progress'],
-    archive: ['verify'],
-};
-export function isSddPhase(value) {
-    return sddPhases.includes(value);
-}
-export function normalizeSddPhaseInput(value) {
-    const normalized = value.trim();
-    if (normalized === 'apply')
-        return 'apply-progress';
-    if (isSddPhase(normalized))
-        return normalized;
-    return undefined;
-}
-export function sddTopicKey(change, phase) {
-    return `sdd/${change}/${phase}`;
-}
+export * from '../domain/sdd/schema.js';