@contractspec/lib.contracts 0.0.0-canary-20260119225944 → 0.0.0-canary-20260202053150

package/dist/operations/report/index.js

@@ -0,0 +1,45 @@
+import { installOp } from "../../install.js";
+import { ContractVerificationStatusModel, GetContractVerificationStatusInput, GetContractVerificationStatusOutput, GetContractVerificationStatusQuery } from "./getContractVerificationStatus.js";
+import { ContractVerificationTableDataView } from "../../data-views/report/contractVerificationTable.js";
+
+//#region src/operations/report/index.ts
+const getContractVerificationStatusHandler = async (input, _ctx) => {
+	try {
+		const cmdStdout = await Bun.spawn([
+			"contractspec",
+			"impl",
+			"status",
+			"--format",
+			"json",
+			"--all"
+		], { cwd: input.projectPath }).stdout;
+		const output = await Bun.readableStreamToText(cmdStdout);
+		if (!output) return { contracts: [] };
+		const cliOutput = JSON.parse(output);
+		const contracts = [];
+		for (const spec of cliOutput.results || []) {
+			const contract = {
+				name: spec.specKey,
+				lastVerifiedSha: spec.specHash,
+				lastVerifiedDate: spec.specHash ? (/* @__PURE__ */ new Date()).toISOString() : void 0,
+				surfaces: spec.implementations.filter((impl) => impl.exists).map((impl) => impl.type),
+				driftMismatches: spec.implementations.filter((impl) => !impl.exists).length
+			};
+			contracts.push(contract);
+		}
+		return { contracts };
+	} catch (error) {
+		console.error("Failed to get contract verification status:", error);
+		return { contracts: [] };
+	}
+};
+/**
+* Register report-related operation contracts in the given registry.
+*/
+function registerReportContracts(registry) {
+	installOp(registry, GetContractVerificationStatusQuery, getContractVerificationStatusHandler);
+	return registry;
+}
+
+//#endregion
+export { ContractVerificationStatusModel, ContractVerificationTableDataView, GetContractVerificationStatusInput, GetContractVerificationStatusOutput, GetContractVerificationStatusQuery, getContractVerificationStatusHandler, registerReportContracts };

package/dist/ownership.d.ts

@@ -2,82 +2,207 @@ import { DocId } from "./docs/registry.js";
 import "./docs/index.js";
 
 //#region src/ownership.d.ts
+
+/**
+ * Lifecycle stability stages for specs.
+ *
+ * Specs progress through these stages as they mature:
+ * - `idea`: Initial concept, not implemented
+ * - `in_creation`: Currently being built
+ * - `experimental`: Working but may change significantly
+ * - `beta`: Feature-complete, seeking feedback
+ * - `stable`: Production-ready, breaking changes require major version bump
+ * - `deprecated`: Scheduled for removal, use alternatives
+ */
 declare const StabilityEnum: {
+  /** Initial concept, not yet implemented. */
   readonly Idea: "idea";
+  /** Currently being built, not ready for use. */
   readonly InCreation: "in_creation";
+  /** Working but unstable, may change significantly. */
   readonly Experimental: "experimental";
+  /** Feature-complete, seeking feedback before stabilization. */
   readonly Beta: "beta";
+  /** Production-ready, follows semantic versioning. */
   readonly Stable: "stable";
+  /** Scheduled for removal, use alternatives. */
   readonly Deprecated: "deprecated";
 };
+/** Stability level for a spec's lifecycle stage. */
 type Stability = (typeof StabilityEnum)[keyof typeof StabilityEnum];
+/**
+ * Curated owner identifiers for business/product ownership.
+ *
+ * Used for CODEOWNERS, on-call routing, and approval workflows.
+ * Custom owner strings are also allowed for flexibility.
+ */
 declare const OwnersEnum: {
+  /** Core platform team. */
   readonly PlatformCore: "platform.core";
+  /** Sigil/auth team. */
   readonly PlatformSigil: "platform.sigil";
+  /** Marketplace team. */
   readonly PlatformMarketplace: "platform.marketplace";
+  /** Messaging/notifications team. */
   readonly PlatformMessaging: "platform.messaging";
+  /** Content/CMS team. */
   readonly PlatformContent: "platform.content";
+  /** Feature flags team. */
   readonly PlatformFeatureFlags: "platform.featureflags";
+  /** Finance/billing team. */
   readonly PlatformFinance: "platform.finance";
 };
+/**
+ * Owner identifier for a spec.
+ * Can be a predefined OwnersEnum value or any custom string.
+ */
 type Owner = (typeof OwnersEnum)[keyof typeof OwnersEnum] | (string & {});
+/** @deprecated Use OwnersEnum instead. */
 declare const Owners: {
+  /** Core platform team. */
   readonly PlatformCore: "platform.core";
+  /** Sigil/auth team. */
   readonly PlatformSigil: "platform.sigil";
+  /** Marketplace team. */
   readonly PlatformMarketplace: "platform.marketplace";
+  /** Messaging/notifications team. */
   readonly PlatformMessaging: "platform.messaging";
+  /** Content/CMS team. */
   readonly PlatformContent: "platform.content";
+  /** Feature flags team. */
   readonly PlatformFeatureFlags: "platform.featureflags";
+  /** Finance/billing team. */
   readonly PlatformFinance: "platform.finance";
 };
+/**
+ * Common tags for categorizing specs.
+ *
+ * Used for search, grouping, and documentation navigation.
+ * Custom tag strings are also allowed for flexibility.
+ */
 declare const TagsEnum: {
+  /** Spots/locations domain. */
   readonly Spots: "spots";
+  /** Collectivity/community domain. */
   readonly Collectivity: "collectivity";
+  /** Marketplace domain. */
   readonly Marketplace: "marketplace";
+  /** Seller-related features. */
   readonly Sellers: "sellers";
+  /** Authentication features. */
   readonly Auth: "auth";
+  /** Login flows. */
   readonly Login: "login";
+  /** Signup flows. */
   readonly Signup: "signup";
+  /** Onboarding/guides. */
   readonly Guide: "guide";
+  /** Documentation. */
   readonly Docs: "docs";
+  /** Internationalization. */
   readonly I18n: "i18n";
+  /** Incident management. */
   readonly Incident: "incident";
+  /** Automation/workflows. */
   readonly Automation: "automation";
+  /** Code hygiene/maintenance. */
   readonly Hygiene: "hygiene";
 };
+/**
+ * Tag for categorizing a spec.
+ * Can be a predefined TagsEnum value or any custom string.
+ */
 type Tag = (typeof TagsEnum)[keyof typeof TagsEnum] | (string & {});
+/** @deprecated Use TagsEnum instead. */
 declare const Tags: {
+  /** Spots/locations domain. */
   readonly Spots: "spots";
+  /** Collectivity/community domain. */
   readonly Collectivity: "collectivity";
+  /** Marketplace domain. */
   readonly Marketplace: "marketplace";
+  /** Seller-related features. */
   readonly Sellers: "sellers";
+  /** Authentication features. */
   readonly Auth: "auth";
+  /** Login flows. */
   readonly Login: "login";
+  /** Signup flows. */
   readonly Signup: "signup";
+  /** Onboarding/guides. */
   readonly Guide: "guide";
+  /** Documentation. */
   readonly Docs: "docs";
+  /** Internationalization. */
   readonly I18n: "i18n";
+  /** Incident management. */
   readonly Incident: "incident";
+  /** Automation/workflows. */
   readonly Automation: "automation";
+  /** Code hygiene/maintenance. */
   readonly Hygiene: "hygiene";
 };
+/**
+ * Common metadata interface for all ContractSpec specifications.
+ *
+ * Every spec type (operations, events, presentations, etc.) extends this
+ * interface to provide consistent ownership, versioning, and discoverability.
+ *
+ * @example
+ * ```typescript
+ * const meta: OwnerShipMeta = {
+ *   key: 'auth.login',
+ *   version: '1.0.0',
+ *   description: 'Authenticates a user with email and password',
+ *   stability: StabilityEnum.Stable,
+ *   owners: [OwnersEnum.PlatformSigil],
+ *   tags: [TagsEnum.Auth, TagsEnum.Login],
+ * };
+ * ```
+ */
 interface OwnerShipMeta {
-  /** Breaking changes => bump version */
+  /**
+   * Semantic version string (e.g., "1.0.0").
+   * Bump for breaking changes according to semver rules.
+   */
   version: string;
-  /** Fully-qualified spec key (e.g., "sigil.beginSignup") */
+  /**
+   * Fully-qualified spec key (e.g., "sigil.beginSignup", "user.created").
+   * Must be unique within the spec type.
+   */
   key: string;
-  /** Human-friendly spec title (e.g., "Signup begin") */
+  /**
+   * Human-friendly title (e.g., "Begin Signup").
+   * Used in documentation and UI.
+   */
   title?: string;
-  /** Short human-friendly summary */
+  /**
+   * Short human-friendly summary of what this spec does.
+   * Should be concise (1-2 sentences).
+   */
   description: string;
+  /**
+   * Business domain this spec belongs to (e.g., "auth", "marketplace").
+   * Used for grouping and discovery.
+   */
   domain?: string;
-  /** Lifecycle marker for comms & tooling */
+  /**
+   * Lifecycle stability marker.
+   * Indicates maturity level and change expectations.
+   */
   stability: Stability;
-  /** Owners for CODEOWNERS / on-call / approvals */
+  /**
+   * Team/individual owners responsible for this spec.
+   * Used for CODEOWNERS, on-call routing, and approvals.
+   */
   owners: Owner[];
-  /** Search tags, grouping, docs navigation */
+  /**
+   * Tags for search, grouping, and documentation navigation.
+   */
   tags: Tag[];
-  /** Doc block(s) for this operation. */
+  /**
+   * Associated DocBlock identifiers for documentation linkage.
+   */
   docId?: DocId[];
 }
 //#endregion

package/dist/ownership.js

@@ -1,4 +1,15 @@
 //#region src/ownership.ts
+/**
+* Lifecycle stability stages for specs.
+*
+* Specs progress through these stages as they mature:
+* - `idea`: Initial concept, not implemented
+* - `in_creation`: Currently being built
+* - `experimental`: Working but may change significantly
+* - `beta`: Feature-complete, seeking feedback
+* - `stable`: Production-ready, breaking changes require major version bump
+* - `deprecated`: Scheduled for removal, use alternatives
+*/
 const StabilityEnum = {
 	Idea: "idea",
 	InCreation: "in_creation",
@@ -7,6 +18,12 @@ const StabilityEnum = {
 	Stable: "stable",
 	Deprecated: "deprecated"
 };
+/**
+* Curated owner identifiers for business/product ownership.
+*
+* Used for CODEOWNERS, on-call routing, and approval workflows.
+* Custom owner strings are also allowed for flexibility.
+*/
 const OwnersEnum = {
 	PlatformCore: "platform.core",
 	PlatformSigil: "platform.sigil",
@@ -16,7 +33,14 @@ const OwnersEnum = {
 	PlatformFeatureFlags: "platform.featureflags",
 	PlatformFinance: "platform.finance"
 };
+/** @deprecated Use OwnersEnum instead. */
 const Owners = OwnersEnum;
+/**
+* Common tags for categorizing specs.
+*
+* Used for search, grouping, and documentation navigation.
+* Custom tag strings are also allowed for flexibility.
+*/
 const TagsEnum = {
 	Spots: "spots",
 	Collectivity: "collectivity",
@@ -32,6 +56,7 @@ const TagsEnum = {
 	Automation: "automation",
 	Hygiene: "hygiene"
 };
+/** @deprecated Use TagsEnum instead. */
 const Tags = TagsEnum;
 
 //#endregion

package/dist/policy/context.d.ts

@@ -0,0 +1,237 @@
+//#region src/policy/context.d.ts
+/**
+ * Runtime policy context for opt-in policy enforcement.
+ *
+ * Provides a context object that can be used to check if a user/tenant
+ * has specific roles, permissions, and attributes at runtime.
+ *
+ * @module policy/context
+ *
+ * @example
+ * ```typescript
+ * import { createPolicyContext } from '@contractspec/lib.contracts';
+ *
+ * // Create context from user's roles and permissions
+ * const ctx = createPolicyContext({
+ *   id: 'user-123',
+ *   tenantId: 'tenant-456',
+ *   roles: ['admin', 'editor'],
+ *   permissions: ['read:articles', 'write:articles'],
+ *   attributes: { department: 'engineering' },
+ * });
+ *
+ * // Check roles and permissions
+ * if (ctx.hasRole('admin')) {
+ *   // User has admin role
+ * }
+ *
+ * // Audit access attempts
+ * ctx.auditAccess('article.update', 'allowed');
+ * ```
+ */
+/**
+ * Error thrown when a policy violation occurs.
+ */
+declare class PolicyViolationError extends Error {
+  readonly violationType: PolicyViolationType;
+  readonly details: PolicyViolationDetails;
+  constructor(type: PolicyViolationType, details: PolicyViolationDetails);
+}
+type PolicyViolationType = 'missing_role' | 'missing_permission' | 'missing_attribute' | 'rate_limit_exceeded' | 'consent_required' | 'access_denied';
+interface PolicyViolationDetails {
+  operation?: string;
+  requiredRole?: string;
+  requiredPermission?: string;
+  requiredAttribute?: {
+    key: string;
+    expected: unknown;
+  };
+  rateLimitKey?: string;
+  consentIds?: string[];
+  reason?: string;
+}
+interface RateLimitResult {
+  allowed: boolean;
+  remaining: number;
+  resetAt?: Date;
+  retryAfterMs?: number;
+}
+interface RateLimitState {
+  key: string;
+  count: number;
+  windowStart: number;
+  windowMs: number;
+  limit: number;
+}
+interface AuditEntry {
+  timestamp: Date;
+  operation: string;
+  result: 'allowed' | 'denied';
+  reason?: string;
+  userId?: string;
+  tenantId?: string;
+  attributes?: Record<string, unknown>;
+}
+type AuditHandler = (entry: AuditEntry) => void | Promise<void>;
+/**
+ * User information for policy evaluation.
+ */
+interface PolicyUser {
+  /** Unique user identifier. */
+  id: string;
+  /** Optional tenant/organization ID for multi-tenant contexts. */
+  tenantId?: string;
+  /** Roles assigned to the user. */
+  roles: string[];
+  /** Permissions granted to the user. */
+  permissions: string[];
+  /** Additional attributes for ABAC evaluation. */
+  attributes: Record<string, unknown>;
+}
+/**
+ * Runtime context for checking policy access.
+ *
+ * Created from user information (roles, permissions, attributes).
+ * Provides methods to check and require policy compliance at runtime.
+ */
+interface PolicyContext {
+  /** The user for this context. */
+  readonly user: PolicyUser;
+  /** Set of user roles. */
+  readonly roles: ReadonlySet<string>;
+  /** Set of user permissions. */
+  readonly permissions: ReadonlySet<string>;
+  /**
+   * Check if user has a specific role.
+   * @param role - Role to check
+   * @returns True if user has the role
+   */
+  hasRole(role: string): boolean;
+  /**
+   * Check if user has any of the specified roles.
+   * @param roles - Roles to check
+   * @returns True if user has at least one role
+   */
+  hasAnyRole(roles: string[]): boolean;
+  /**
+   * Check if user has all of the specified roles.
+   * @param roles - Roles to check
+   * @returns True if user has all roles
+   */
+  hasAllRoles(roles: string[]): boolean;
+  /**
+   * Require a role, throwing if not present.
+   * @param role - Role to require
+   * @throws {PolicyViolationError} If role is missing
+   */
+  requireRole(role: string): void;
+  /**
+   * Check if user has a specific permission.
+   * @param permission - Permission to check
+   * @returns True if user has the permission
+   */
+  hasPermission(permission: string): boolean;
+  /**
+   * Check if user has any of the specified permissions.
+   * @param permissions - Permissions to check
+   * @returns True if user has at least one permission
+   */
+  hasAnyPermission(permissions: string[]): boolean;
+  /**
+   * Check if user has all of the specified permissions.
+   * @param permissions - Permissions to check
+   * @returns True if user has all permissions
+   */
+  hasAllPermissions(permissions: string[]): boolean;
+  /**
+   * Require a permission, throwing if not present.
+   * @param permission - Permission to require
+   * @throws {PolicyViolationError} If permission is missing
+   */
+  requirePermission(permission: string): void;
+  /**
+   * Get a user attribute value.
+   * @param key - Attribute key
+   * @returns Attribute value or undefined
+   */
+  getAttribute<T = unknown>(key: string): T | undefined;
+  /**
+   * Check if an attribute matches an expected value.
+   * @param key - Attribute key
+   * @param expected - Expected value
+   * @returns True if attribute equals expected value
+   */
+  checkAttribute(key: string, expected: unknown): boolean;
+  /**
+   * Check if an attribute is one of the allowed values.
+   * @param key - Attribute key
+   * @param allowedValues - Array of allowed values
+   * @returns True if attribute is in allowed values
+   */
+  checkAttributeOneOf(key: string, allowedValues: unknown[]): boolean;
+  /**
+   * Check rate limit for a key.
+   * @param key - Rate limit key (e.g., operation name)
+   * @returns Rate limit result
+   */
+  checkRateLimit(key: string): RateLimitResult;
+  /**
+   * Consume rate limit for a key (increment counter).
+   * @param key - Rate limit key
+   * @param cost - Cost of the operation (default: 1)
+   * @returns Rate limit result after consumption
+   */
+  consumeRateLimit(key: string, cost?: number): RateLimitResult;
+  /**
+   * Record an access attempt for audit purposes.
+   * @param operation - Operation being accessed
+   * @param result - Whether access was allowed or denied
+   * @param reason - Optional reason for the decision
+   */
+  auditAccess(operation: string, result: 'allowed' | 'denied', reason?: string): void;
+}
+interface PolicyContextOptions {
+  /** Rate limit configurations by key. */
+  rateLimits?: Record<string, {
+    limit: number;
+    windowMs: number;
+  }>;
+  /** Handler for audit entries. */
+  auditHandler?: AuditHandler;
+}
+/**
+ * Creates a policy context from user information.
+ *
+ * @param user - User information for policy evaluation
+ * @param options - Additional context options
+ * @returns PolicyContext for checking/requiring policy compliance
+ *
+ * @example
+ * ```typescript
+ * const ctx = createPolicyContext({
+ *   id: 'user-123',
+ *   roles: ['editor'],
+ *   permissions: ['read:articles'],
+ *   attributes: { department: 'marketing' },
+ * });
+ *
+ * ctx.requireRole('editor');
+ * ctx.requirePermission('read:articles');
+ * ```
+ */
+declare function createPolicyContext(user: PolicyUser, options?: PolicyContextOptions): PolicyContext;
+/**
+ * Creates an empty policy context (no roles/permissions).
+ * Useful for anonymous users or testing.
+ */
+declare function createAnonymousPolicyContext(options?: PolicyContextOptions): PolicyContext;
+/**
+ * Creates a bypass policy context with all roles/permissions.
+ * Useful for admin users or internal services.
+ *
+ * @param allRoles - All roles to grant
+ * @param allPermissions - All permissions to grant
+ */
+declare function createBypassPolicyContext(allRoles: string[], allPermissions: string[], options?: PolicyContextOptions): PolicyContext;
+//#endregion
+export { AuditEntry, AuditHandler, PolicyContext, PolicyContextOptions, PolicyUser, PolicyViolationDetails, PolicyViolationError, PolicyViolationType, RateLimitResult, RateLimitState, createAnonymousPolicyContext, createBypassPolicyContext, createPolicyContext };