@contractspec/bundle.workspace 4.4.0 → 4.5.0

package/dist/services/adoption/catalog-core.d.ts

@@ -0,0 +1,2 @@
+import type { AdoptionCatalogEntry } from './types';
+export declare const CORE_CATALOG_ENTRIES: AdoptionCatalogEntry[];

package/dist/services/adoption/catalog-entry.d.ts

@@ -0,0 +1,2 @@
+import type { AdoptionCatalogEntry, AdoptionFamily, AdoptionPackageKind } from './types';
+export declare function createCatalogEntry(id: string, packageRef: string, family: AdoptionFamily, packageKind: AdoptionPackageKind, resolutionPriority: number, capabilityTags: string[], preferredUseCases: string[], description: string, options?: Partial<Pick<AdoptionCatalogEntry, 'avoidWhen' | 'platforms' | 'replacementImportHints' | 'runtimes' | 'title'>>): AdoptionCatalogEntry;

package/dist/services/adoption/catalog-runtime.d.ts

@@ -0,0 +1,2 @@
+import type { AdoptionCatalogEntry } from './types';
+export declare const RUNTIME_CATALOG_ENTRIES: AdoptionCatalogEntry[];

package/dist/services/adoption/catalog-shared.d.ts

@@ -0,0 +1,2 @@
+import type { AdoptionCatalogEntry } from './types';
+export declare const SHARED_CATALOG_ENTRIES: AdoptionCatalogEntry[];

package/dist/services/adoption/catalog-solutions.d.ts

@@ -0,0 +1,2 @@
+import type { AdoptionCatalogEntry } from './types';
+export declare const SOLUTION_CATALOG_ENTRIES: AdoptionCatalogEntry[];

package/dist/services/adoption/catalog-ui.d.ts

@@ -0,0 +1,2 @@
+import type { AdoptionCatalogEntry } from './types';
+export declare const UI_CATALOG_ENTRIES: AdoptionCatalogEntry[];

package/dist/services/adoption/catalog.d.ts

@@ -0,0 +1,3 @@
+import type { AdoptionCatalogDocument, AdoptionCatalogEntry } from './types';
+export declare function getContractSpecAdoptionCatalog(): AdoptionCatalogEntry[];
+export declare function createAdoptionCatalogDocument(now?: Date): AdoptionCatalogDocument;

package/dist/services/adoption/index.d.ts

@@ -0,0 +1,6 @@
+export * from './catalog';
+export * from './resolve';
+export * from './tokens';
+export * from './types';
+export * from './workspace';
+export * from './workspace-scan';

package/dist/services/adoption/resolve.d.ts

@@ -0,0 +1,6 @@
+import type { AdoptionResolution, AdoptionResolveInput, AdoptionResolverRuntime, AdoptionSyncInput } from './types';
+export declare function resolveAdoption(runtime: AdoptionResolverRuntime, input: AdoptionResolveInput): Promise<AdoptionResolution>;
+export declare function syncAdoptionCatalog(runtime: AdoptionResolverRuntime, input?: AdoptionSyncInput): Promise<{
+    catalog: import("./types").AdoptionCatalogDocument;
+    catalogPath: string;
+}>;

package/dist/services/adoption/resolve.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/adoption/tokens.d.ts

@@ -0,0 +1,6 @@
+import type { AdoptionCandidate } from './types';
+export declare function normalizeText(value: string): string;
+export declare function tokenize(value: string): string[];
+export declare function uniqueTokens(values: string[]): string[];
+export declare function candidateTokens(candidate: AdoptionCandidate): string[];
+export declare function overlap(left: string[], right: string[]): number;

package/dist/services/adoption/types.d.ts

@@ -0,0 +1,99 @@
+import type { ConnectAdoptionConfig, ConnectAdoptionFamily, ConnectVerdict, ResolvedContractsrcConfig } from '@contractspec/lib.contracts-spec/workspace-config';
+import type { FsAdapter } from '../../ports/fs';
+export type AdoptionFamily = ConnectAdoptionFamily;
+export type AdoptionVerdict = ConnectVerdict;
+export type AdoptionSource = 'workspace' | 'contractspec' | 'ecosystem';
+export type AdoptionPackageKind = 'primitive' | 'adapter' | 'module' | 'bundle' | 'app' | 'example';
+export interface AdoptionImportHint {
+    from: string;
+    to: string;
+    note?: string;
+}
+export interface AdoptionCatalogEntry {
+    id: string;
+    source: Exclude<AdoptionSource, 'workspace'>;
+    packageRef: string;
+    family: AdoptionFamily;
+    packageKind: AdoptionPackageKind;
+    title: string;
+    description: string;
+    capabilityTags: string[];
+    preferredUseCases: string[];
+    avoidWhen?: string[];
+    platforms?: string[];
+    runtimes?: string[];
+    replacementImportHints?: AdoptionImportHint[];
+    resolutionPriority: number;
+}
+export interface AdoptionWorkspaceCandidate {
+    id: string;
+    source: 'workspace';
+    family: AdoptionFamily;
+    title: string;
+    description: string;
+    filePath?: string;
+    packageRef?: string;
+    packageKind?: AdoptionPackageKind;
+    capabilityTags: string[];
+    preferredUseCases: string[];
+    resolutionPriority: number;
+}
+export type AdoptionCandidate = AdoptionCatalogEntry | AdoptionWorkspaceCandidate;
+export interface AdoptionCatalogDocument {
+    version: 1;
+    generatedAt: string;
+    entries: AdoptionCatalogEntry[];
+}
+export interface AdoptionWorkspaceIndex {
+    packageCandidates: AdoptionWorkspaceCandidate[];
+    fileCandidates: AdoptionWorkspaceCandidate[];
+}
+export interface AdoptionResolveInput {
+    family: AdoptionFamily;
+    query?: string;
+    symbol?: string;
+    paths?: string[];
+    platform?: string;
+    runtime?: string;
+    currentTarget?: string;
+    config?: ResolvedContractsrcConfig;
+    cwd?: string;
+    workspaceRoot?: string;
+    packageRoot?: string;
+}
+export interface AdoptionResolutionCandidate {
+    candidate: AdoptionCandidate;
+    score: number;
+    matchReasons: string[];
+}
+export interface AdoptionResolution {
+    family: AdoptionFamily;
+    verdict: AdoptionVerdict;
+    selected: AdoptionResolutionCandidate | null;
+    candidates: AdoptionResolutionCandidate[];
+    ambiguous: boolean;
+    exhausted: boolean;
+    reason: string;
+    currentTarget?: string;
+    query: string;
+}
+export interface AdoptionSyncInput {
+    config?: ResolvedContractsrcConfig;
+    cwd?: string;
+    workspaceRoot?: string;
+    packageRoot?: string;
+}
+export interface AdoptionSyncResult {
+    catalogPath: string;
+    catalog: AdoptionCatalogDocument;
+}
+export interface AdoptionResolvedWorkspace {
+    cwd: string;
+    workspaceRoot: string;
+    packageRoot: string;
+    config: ResolvedContractsrcConfig;
+    adoption: NonNullable<ConnectAdoptionConfig>;
+}
+export interface AdoptionResolverRuntime {
+    fs: FsAdapter;
+}

package/dist/services/adoption/workspace-scan.d.ts

@@ -0,0 +1,8 @@
+import type { FsAdapter } from '../../ports/fs';
+import type { AdoptionFamily, AdoptionResolvedWorkspace, AdoptionWorkspaceCandidate } from './types';
+export declare function scanWorkspaceAdoptionCandidates(fs: FsAdapter, workspace: AdoptionResolvedWorkspace): Promise<{
+    fileCandidates: AdoptionWorkspaceCandidate[];
+    packageCandidates: AdoptionWorkspaceCandidate[];
+}>;
+export declare function hasLocalShadcnRegistry(fs: FsAdapter, workspace: AdoptionResolvedWorkspace): Promise<boolean>;
+export declare function inferFamilyFromPath(path: string): AdoptionFamily | null;

package/dist/services/adoption/workspace.d.ts

@@ -0,0 +1,3 @@
+import type { FsAdapter } from '../../ports/fs';
+import type { AdoptionResolvedWorkspace, AdoptionSyncInput } from './types';
+export declare function resolveAdoptionWorkspace(fs: FsAdapter, input?: AdoptionSyncInput): Promise<AdoptionResolvedWorkspace>;

package/dist/services/connect/adoption.d.ts

@@ -0,0 +1,10 @@
+import type { WorkspaceAdapters } from '../../ports/logger';
+import * as adoption from '../adoption/index';
+import type { ConnectPatchVerdict, ConnectVerdict, ConnectVerifyInput } from './types';
+export declare function evaluateConnectAdoption(adapters: Pick<WorkspaceAdapters, 'fs'>, input: ConnectVerifyInput): Promise<{
+    check?: ConnectPatchVerdict['checks'][number];
+    reason?: string;
+    remediation?: string[];
+    resolution?: Awaited<ReturnType<typeof adoption.resolveAdoption>>;
+    verdict?: ConnectVerdict;
+}>;

package/dist/services/connect/types.d.ts

@@ -3,7 +3,7 @@ import type { SetupFileResult, SetupGitignoreBehavior, SetupPromptCallbacks } fr
 export type { ConnectVerdict };
 export type ConnectActorType = 'human' | 'agent' | 'service' | 'tool';
 export type ConnectApprovalStatus = 'not_required' | 'pending' | 'approved' | 'rejected' | 'expired';
-export type ConnectSurface = 'agent' | 'audit' | 'cli' | 'contract' | 'harness' | 'knowledge' | 'mcp' | 'runtime';
+export type ConnectSurface = 'agent' | 'audit' | 'cli' | 'contract' | 'harness' | 'integration' | 'knowledge' | 'library' | 'mcp' | 'runtime' | 'solution' | 'ui';
 export type ConnectContractKind = 'command' | 'query' | 'event' | 'policy' | 'capability';
 export interface ConnectActorRef {
     id: string;

package/dist/services/deps.d.ts

@@ -1,8 +1,8 @@
 /**
  * Dependency analysis service.
  */
-import { type ContractGraph, type ContractNode } from '@contractspec/module.workspace';
 import type { ResolvedContractsrcConfig } from '@contractspec/lib.contracts-spec';
+import { type ContractGraph, type ContractNode } from '@contractspec/module.workspace';
 import type { FsAdapter } from '../ports/fs';
 /**
  * Options for dependency analysis.

package/dist/services/doctor/checks/config.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/index.d.ts

@@ -3,6 +3,7 @@
  */
 export * from './action-drift/index';
 export * from './action-pr';
+export * as adoption from './adoption/index';
 export * from './agent-guide/index';
 export * from './build';
 export * from './ci-check/index';
@@ -32,6 +33,7 @@ export * from './layer-discovery';
 export * from './list';
 export * from './llm/index';
 export * from './module-loader';
+export * as onboarding from './onboarding/index';
 export * from './openapi/index';
 export * from './package-scaffold';
 export * from './quickstart/index';
@@ -47,6 +49,7 @@ export * from './validate/index';
 export * from './verification-cache/index';
 export * from './verify/index';
 export * as versioning from './versioning/index';
+export type { ReleaseAuthoringDraft, ReleaseAuthoringResult, ReleaseCapsuleReadIssue, SaveReleaseDraftOptions, SaveReleaseDraftResult, } from './versioning/release-service.types';
 export type { SpecVersionAnalysis } from './versioning/types';
 export * as vibe from './vibe/index';
 export * from './view/index';

package/dist/services/integrity.d.ts

@@ -6,8 +6,8 @@
  * - Unresolved references (broken event/op/presentation refs)
  * - Feature coverage metrics
  */
-import { type AnalyzedSpecType, type FeatureScanResult, type RefInfo } from '@contractspec/module.workspace';
 import type { ResolvedContractsrcConfig } from '@contractspec/lib.contracts-spec';
+import { type AnalyzedSpecType, type FeatureScanResult, type RefInfo } from '@contractspec/module.workspace';
 import type { FsAdapter } from '../ports/fs';
 import type { LoggerAdapter } from '../ports/logger';
 import { type ExtractedTestTarget } from './test-link';

package/dist/services/onboarding/catalog.d.ts

@@ -0,0 +1,4 @@
+import type { OnboardingTrackDefinition } from './types';
+export declare const ONBOARDING_TRACKS: readonly OnboardingTrackDefinition[];
+export declare function listOnboardingTracks(): readonly OnboardingTrackDefinition[];
+export declare function getOnboardingTrack(trackId: string): OnboardingTrackDefinition | undefined;

package/dist/services/onboarding/index.d.ts

@@ -0,0 +1,4 @@
+export * from './catalog';
+export * from './render';
+export * from './service';
+export * from './types';

package/dist/services/onboarding/journey.d.ts

@@ -0,0 +1,11 @@
+import type { ConnectSurface } from '../connect/types';
+import type { BuildOnboardingPlanInput, OnboardingBuilderMode, OnboardingPlan, OnboardingTrackDefinition, OnboardingTrackRecommendation } from './types';
+export declare function createOnboardingJourneyPlan(primaryTrack: OnboardingTrackDefinition, tracks: readonly OnboardingTrackDefinition[], workspaceRoot: string, packageRoot: string): Promise<{
+    journeyContext: import("@contractspec/lib.surface-runtime/spec").BundleContext;
+    journeyPlan: import("@contractspec/lib.surface-runtime/runtime/resolve-bundle").ResolvedSurfacePlan;
+}>;
+export declare function resolveRequestedTracks(selectedTracks: BuildOnboardingPlanInput['selectedTracks']): OnboardingTrackDefinition[];
+export declare function resolveBuilderMode(config: OnboardingPlan['config']): OnboardingBuilderMode;
+export declare function buildBuilderNextSteps(builderMode: OnboardingBuilderMode): string[];
+export declare function resolveSelectedExample(primaryTrack: OnboardingTrackDefinition, forcedExampleKey: string | undefined): import("./types").OnboardingExampleRef | undefined;
+export declare function enrichConnectSurfaces(current: readonly ConnectSurface[], recommendations: readonly OnboardingTrackRecommendation[]): ConnectSurface[];

package/dist/services/onboarding/render.d.ts

@@ -0,0 +1,5 @@
+import type { OnboardingPlan } from './types';
+export declare function renderOnboardingGuides(plan: Omit<OnboardingPlan, 'guides'>): {
+    agentGuide: string;
+    humanGuide: string;
+};

package/dist/services/onboarding/service.d.ts

@@ -0,0 +1,5 @@
+import type { WorkspaceAdapters } from '../../ports/logger';
+import { type AdoptionResolverRuntime } from '../adoption';
+import type { BuildOnboardingPlanInput, OnboardingConnectArtifacts, OnboardingPlan } from './types';
+export declare function buildOnboardingPlan(runtime: AdoptionResolverRuntime, input?: BuildOnboardingPlanInput): Promise<OnboardingPlan>;
+export declare function createOnboardingConnectArtifacts(adapters: Pick<WorkspaceAdapters, 'fs' | 'git'>, plan: OnboardingPlan): Promise<OnboardingConnectArtifacts | undefined>;

package/dist/services/onboarding/service.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/onboarding/types.d.ts

@@ -0,0 +1,71 @@
+import type { ResolvedContractsrcConfig } from '@contractspec/lib.contracts-spec/workspace-config';
+import type { ResolvedSurfacePlan } from '@contractspec/lib.surface-runtime/runtime/resolve-bundle';
+import type { BundleContext } from '@contractspec/lib.surface-runtime/spec/types';
+import type { AdoptionFamily, AdoptionResolution } from '../adoption/types';
+import type { ConnectContextPack, ConnectPlanPacket, ConnectSurface } from '../connect/types';
+export type OnboardingTrackId = 'contracts' | 'ui-design' | 'knowledge' | 'ai-agents' | 'learning-journey';
+export type OnboardingBuilderMode = 'none' | 'managed' | 'local' | 'hybrid';
+export interface OnboardingExampleRef {
+    key: string;
+    packageRef: string;
+    title: string;
+    summary: string;
+}
+export interface OnboardingTrackDefinition {
+    id: OnboardingTrackId;
+    title: string;
+    summary: string;
+    description: string;
+    reuseFamily: AdoptionFamily;
+    adoptionQuery: string;
+    adoptionPlatform?: string;
+    primaryDocsRoute: string;
+    secondaryDocsRoutes: string[];
+    packages: string[];
+    recommendedCommands: string[];
+    starterExample: OnboardingExampleRef;
+    advancedExample?: OnboardingExampleRef;
+    connectSurfaces: ConnectSurface[];
+}
+export interface OnboardingTrackRecommendation {
+    track: OnboardingTrackDefinition;
+    selected: boolean;
+    score: number;
+    reason: string;
+    resolution: AdoptionResolution;
+}
+export interface OnboardingGuideRenderResult {
+    agentGuide: string;
+    humanGuide: string;
+}
+export interface BuildOnboardingPlanInput {
+    cwd?: string;
+    workspaceRoot?: string;
+    packageRoot?: string;
+    config?: ResolvedContractsrcConfig;
+    selectedTracks?: OnboardingTrackId[];
+    forcedExampleKey?: string;
+    agentGuidePath?: string;
+    humanGuidePath?: string;
+}
+export interface OnboardingPlan {
+    cwd: string;
+    workspaceRoot: string;
+    packageRoot: string;
+    config: ResolvedContractsrcConfig;
+    builderMode: OnboardingBuilderMode;
+    primaryTrack: OnboardingTrackDefinition;
+    recommendations: OnboardingTrackRecommendation[];
+    journeyContext: BundleContext;
+    journeyPlan: ResolvedSurfacePlan;
+    guides: OnboardingGuideRenderResult;
+    agentGuidePath: string;
+    humanGuidePath: string;
+    selectedExample: OnboardingExampleRef;
+    nextCommands: string[];
+    builderNextSteps: string[];
+}
+export interface OnboardingConnectArtifacts {
+    contextPack: ConnectContextPack;
+    planPacket: ConnectPlanPacket;
+}

package/dist/services/setup/config-generators.d.ts

@@ -33,6 +33,10 @@ export declare function generateCursorRules(options: SetupOptions): string;
  * Generate AGENTS.md content.
  */
 export declare function generateAgentsGuide(options: SetupOptions): string;
+/**
+ * Generate USAGE.md content.
+ */
+export declare function generateUsageGuide(options: SetupOptions): string;
 /**
  * Get the file path for Claude Desktop config based on platform.
  */

package/dist/services/setup/index.d.ts

@@ -6,6 +6,9 @@
 export * from './config-generators';
 export * from './file-merger';
 export * from './gitignore';
+export * from './managed-markdown';
 export * from './presets';
 export * from './setup-service';
+export * from './targets/agents-md';
+export * from './targets/usage-md';
 export * from './types';

package/dist/services/setup/managed-markdown.d.ts

@@ -0,0 +1,8 @@
+export interface ManagedMarkdownSectionConfig {
+    startMarker: string;
+    endMarker: string;
+    note: string;
+}
+export declare function mergeManagedMarkdown(existingContent: string, managedContent: string, config: ManagedMarkdownSectionConfig, legacyContent?: string): string;
+export declare function renderManagedMarkdownBlock(managedContent: string, config: ManagedMarkdownSectionConfig): string;
+export declare function normalizeMarkdownContent(content: string): string;

package/dist/services/setup/targets/agents-md.d.ts

@@ -3,6 +3,8 @@
  */
 import type { FsAdapter } from '../../../ports/fs';
 import type { SetupFileResult, SetupOptions, SetupPromptCallbacks } from '../types';
+export declare const CONTRACTSPEC_AGENTS_BLOCK_START = "<!-- contractspec:init:agents:start -->";
+export declare const CONTRACTSPEC_AGENTS_BLOCK_END = "<!-- contractspec:init:agents:end -->";
 /**
  * Setup AGENTS.md
  */

package/dist/services/setup/targets/index.d.ts

@@ -7,4 +7,5 @@ export { setupCliConfig } from './cli-config';
 export { setupCursorRules } from './cursor-rules';
 export { setupMcpClaude } from './mcp-claude';
 export { setupMcpCursor } from './mcp-cursor';
+export { setupUsageMd } from './usage-md';
 export { setupVscodeSettings } from './vscode-settings';

package/dist/services/setup/targets/usage-md.d.ts

@@ -0,0 +1,5 @@
+import type { FsAdapter } from '../../../ports/fs';
+import type { SetupFileResult, SetupOptions, SetupPromptCallbacks } from '../types';
+export declare const CONTRACTSPEC_USAGE_BLOCK_START = "<!-- contractspec:init:usage:start -->";
+export declare const CONTRACTSPEC_USAGE_BLOCK_END = "<!-- contractspec:init:usage:end -->";
+export declare function setupUsageMd(fs: FsAdapter, options: SetupOptions, prompts: SetupPromptCallbacks): Promise<SetupFileResult>;

package/dist/services/setup/targets/usage-md.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/setup/types.d.ts

@@ -4,7 +4,7 @@
 /**
  * Target components that can be configured during setup.
  */
-export type SetupTarget = 'cli-config' | 'biome-config' | 'vscode-settings' | 'mcp-cursor' | 'mcp-claude' | 'cursor-rules' | 'agents-md';
+export type SetupTarget = 'cli-config' | 'biome-config' | 'vscode-settings' | 'mcp-cursor' | 'mcp-claude' | 'cursor-rules' | 'agents-md' | 'usage-md';
 /**
  * All available setup targets.
  */
@@ -46,7 +46,7 @@ export interface SetupOptions {
     projectName?: string;
     /** Default code owners. */
     defaultOwners?: string[];
-    /** Builder API base URL for managed or hybrid presets. */
+    /** Builder API base URL for Builder presets. */
     builderApiBaseUrl?: string;
     /** Builder control-plane token environment variable name. */
     builderControlPlaneTokenEnvVar?: string;

package/dist/services/validate/spec-validator.d.ts

@@ -26,7 +26,7 @@ export interface ValidateSpecResult {
 export interface DiscoveredSpecValidationResult extends ValidateSpecResult {
     spec: SpecScanResult;
 }
-export declare function validateScannedSpec(spec: SpecScanResult, options?: ValidateSpecOptions): ValidateSpecResult;
+export declare function validateScannedSpec(spec: SpecScanResult, options?: ValidateSpecOptions): Promise<ValidateSpecResult>;
 export declare function validateDiscoveredSpecs(specs: SpecScanResult[], options?: ValidateSpecOptions): Promise<DiscoveredSpecValidationResult[]>;
 /**
  * Validate a spec file.

package/dist/services/validate/spec-validator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/versioning/index.d.ts

@@ -5,6 +5,7 @@
  */
 export { formatChangelogJson, formatConventionalChangelog, formatKeepAChangelog, } from './changelog-formatter';
 export * from './conventional-commits';
+export { prepareReleaseAuthoring, saveReleaseDraft, } from './release-authoring';
 export * from './release-formatters';
 export { buildReleaseArtifacts, checkReleaseArtifacts, initReleaseArtifacts, } from './release-service';
 export * from './release-service.types';

package/dist/services/versioning/release-authoring.d.ts

@@ -0,0 +1,14 @@
+import type { AiAdapter } from '../../ports/ai';
+import type { FsAdapter } from '../../ports/fs';
+import type { GitAdapter } from '../../ports/git';
+import type { LoggerAdapter } from '../../ports/logger';
+import type { ReleaseAuthoringOptions, ReleaseAuthoringResult, SaveReleaseDraftOptions, SaveReleaseDraftResult } from './release-service.types';
+interface ReleaseAuthoringAdapters {
+    fs: FsAdapter;
+    git: GitAdapter;
+    logger: LoggerAdapter;
+    ai?: AiAdapter;
+}
+export declare function prepareReleaseAuthoring(adapters: ReleaseAuthoringAdapters, options?: ReleaseAuthoringOptions): Promise<ReleaseAuthoringResult>;
+export declare function saveReleaseDraft(adapters: ReleaseAuthoringAdapters, options: SaveReleaseDraftOptions): Promise<SaveReleaseDraftResult>;
+export {};

package/dist/services/versioning/release-authoring.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/versioning/release-files.d.ts

@@ -1,5 +1,6 @@
 import type { ReleaseCapsule, ReleaseCapsulePackage } from '@contractspec/lib.contracts-spec';
 import type { FsAdapter } from '../../ports/fs';
+import type { ReleaseCapsuleReadIssue } from './release-service.types';
 export interface WorkspacePackageInfo {
     name: string;
     dir: string;
@@ -10,10 +11,16 @@ export interface ParsedChangesetFile {
     summary: string;
     packages: ReleaseCapsulePackage[];
 }
+export interface ReadReleaseCapsulesResult {
+    capsules: Map<string, ReleaseCapsule>;
+    issues: ReleaseCapsuleReadIssue[];
+}
 export declare function listChangesetFiles(fs: FsAdapter, workspaceRoot: string): Promise<string[]>;
 export declare function readChangesets(fs: FsAdapter, workspaceRoot: string): Promise<ParsedChangesetFile[]>;
 export declare function readReleaseCapsules(fs: FsAdapter, workspaceRoot: string, changesets: ParsedChangesetFile[]): Promise<Map<string, ReleaseCapsule>>;
+export declare function readReleaseCapsulesDetailed(fs: FsAdapter, workspaceRoot: string, changesets: ParsedChangesetFile[]): Promise<ReadReleaseCapsulesResult>;
 export declare function discoverWorkspacePackages(fs: FsAdapter, workspaceRoot: string): Promise<WorkspacePackageInfo[]>;
 export declare function matchChangedFilesToPackages(changedFiles: string[], packages: WorkspacePackageInfo[]): string[];
 export declare function renderChangesetMarkdown(summary: string, packages: ReleaseCapsulePackage[]): string;
 export declare function renderReleaseCapsuleYaml(capsule: ReleaseCapsule): string;
+export declare function formatReleaseCapsuleReadIssues(issues: ReleaseCapsuleReadIssue[]): string;

package/dist/services/versioning/release-service.types.d.ts

@@ -1,4 +1,4 @@
-import type { AgentTarget, GeneratedReleaseManifest, ReleaseCapsulePackage, UpgradePlan, VersionBumpType } from '@contractspec/lib.contracts-spec';
+import type { AgentTarget, GeneratedReleaseManifest, MigrationInstruction, ReleaseCapsulePackage, ReleaseCapsuleValidation, ReleaseImpactAudience, UpgradePlan, UpgradePlanStep, VersionBumpType } from '@contractspec/lib.contracts-spec';
 export interface ReleaseInitOptions {
     workspaceRoot?: string;
     baseline?: string;
@@ -36,6 +36,58 @@ export interface ReleaseBuildResult {
     upgradePlan: UpgradePlan;
     releasesBuilt: number;
 }
+export interface ReleaseCapsuleReadIssue {
+    slug: string;
+    filePath: string;
+    message: string;
+    line?: number;
+    column?: number;
+    suggestion?: string;
+}
+export interface ReleaseAuthoringDraft {
+    slug: string;
+    summary: string;
+    releaseType: VersionBumpType;
+    isBreaking: boolean;
+    packages: ReleaseCapsulePackage[];
+    affectedRuntimes: string[];
+    affectedFrameworks: string[];
+    audiences: ReleaseImpactAudience[];
+    deprecations: string[];
+    migrationInstructions: MigrationInstruction[];
+    upgradeSteps: UpgradePlanStep[];
+    validation: ReleaseCapsuleValidation;
+}
+export interface ReleaseAuthoringOptions {
+    workspaceRoot?: string;
+    baseline?: string;
+    slug?: string;
+    summary?: string;
+    releaseType?: VersionBumpType;
+    packages?: string[];
+}
+export interface ReleaseAuthoringResult {
+    workspaceRoot: string;
+    source: 'created' | 'existing';
+    changesetPath: string;
+    capsulePath: string;
+    draft: ReleaseAuthoringDraft;
+    warnings: string[];
+    parseIssues: ReleaseCapsuleReadIssue[];
+    aiAssisted: boolean;
+}
+export interface SaveReleaseDraftOptions {
+    workspaceRoot?: string;
+    draft: ReleaseAuthoringDraft;
+    force?: boolean;
+}
+export interface SaveReleaseDraftResult {
+    source: 'created' | 'updated';
+    changesetPath: string;
+    capsulePath: string;
+    changesetContent: string;
+    capsuleContent: string;
+}
 export interface ReleaseCheckOptions {
     workspaceRoot?: string;
     baseline?: string;

package/dist/templates/additional-contracts.template.d.ts

@@ -0,0 +1,40 @@
+type Stability = 'experimental' | 'beta' | 'stable' | 'deprecated';
+interface BaseTemplateData {
+    key: string;
+    version: string;
+    description: string;
+    owners: string[];
+    tags: string[];
+    stability: Stability;
+    title?: string;
+    domain?: string;
+}
+export interface CapabilitySpecTemplateData extends BaseTemplateData {
+    kind?: 'api' | 'event' | 'data' | 'ui' | 'integration';
+}
+export interface PolicySpecTemplateData extends BaseTemplateData {
+    scope?: 'global' | 'feature' | 'operation';
+}
+export interface TestSpecTemplateData extends BaseTemplateData {
+    targetType: 'operation' | 'workflow';
+    targetKey: string;
+    targetVersion?: string;
+}
+export interface TranslationSpecTemplateData extends BaseTemplateData {
+    locale: string;
+    fallback?: string;
+}
+export interface JobSpecTemplateData extends BaseTemplateData {
+    intervalMs?: number;
+}
+export interface VisualizationSpecTemplateData extends BaseTemplateData {
+    sourceOperationKey: string;
+    sourceOperationVersion?: string;
+}
+export declare function generateCapabilitySpec(data: CapabilitySpecTemplateData): string;
+export declare function generatePolicySpec(data: PolicySpecTemplateData): string;
+export declare function generateTestSpec(data: TestSpecTemplateData): string;
+export declare function generateTranslationSpec(data: TranslationSpecTemplateData): string;
+export declare function generateJobSpec(data: JobSpecTemplateData): string;
+export declare function generateVisualizationSpec(data: VisualizationSpecTemplateData): string;
+export {};