@ever-works/contracts 1.0.0

package/README.md

@@ -0,0 +1,62 @@
+# @ever-works/contracts
+
+Shared TypeScript type definitions and runtime-free contracts used across the Ever Works platform.
+
+## Overview
+
+This package contains the cross-cutting type primitives that every other package and app relies on — work items, domain models, form schemas, and API contracts. It has zero runtime dependencies and is published as both ESM and CJS so it can be consumed from Node.js, Next.js, browsers, and the plugin system alike.
+
+`@ever-works/contracts` is a pure type package: no NestJS, no LangChain, no I/O. Anything that needs to be shared between the API, the web app, and standalone plugins lives here.
+
+## Installation
+
+```bash
+pnpm add @ever-works/contracts
+```
+
+## Subpath exports
+
+| Import path                    | Contents                                                          |
+| ------------------------------ | ----------------------------------------------------------------- |
+| `@ever-works/contracts`        | Re-exports of `item`, `domain`, and `form` (default barrel)       |
+| `@ever-works/contracts/item`   | `ItemData`, item lifecycle states, item field shapes              |
+| `@ever-works/contracts/domain` | `DomainType`, domain category metadata                            |
+| `@ever-works/contracts/form`   | Form field schemas (`x-widget`, `x-secret`, etc.) consumed by UIs |
+| `@ever-works/contracts/api`    | REST API request/response shapes                                  |
+
+## Usage
+
+```typescript
+import type { ItemData } from '@ever-works/contracts/item';
+import type { DomainType } from '@ever-works/contracts/domain';
+import type { JsonSchema } from '@ever-works/contracts/form';
+
+const item: ItemData = {
+	name: 'Example',
+	slug: 'example'
+	// ...
+};
+```
+
+## Why a separate package?
+
+- **Plugins stay lightweight.** Plugins import only types — no NestJS, no DB, no agent runtime.
+- **Type drift is caught at compile time.** API, web, agent, and plugins all share the same source of truth.
+- **Cross-runtime safety.** Pure TypeScript means it builds for Node, browser, Edge, and Workers without conditional exports.
+
+## Build
+
+```bash
+pnpm --filter @ever-works/contracts build      # tsup -> ESM + CJS + .d.ts
+pnpm --filter @ever-works/contracts type-check # tsc --noEmit
+```
+
+## Documentation
+
+- [Ever Works documentation](https://docs.ever.works)
+- [Repository](https://github.com/ever-works/ever-works)
+- [Plugin system contracts](../plugin/README.md)
+
+## License
+
+AGPL-3.0

package/dist/api/index.cjs

@@ -0,0 +1,395 @@
+'use strict';
+
+// src/api/generator/generation-method.enum.ts
+var GenerationMethod = /* @__PURE__ */ ((GenerationMethod2) => {
+  GenerationMethod2["CREATE_UPDATE"] = "create-update";
+  GenerationMethod2["RECREATE"] = "recreate";
+  GenerationMethod2["IMPORT"] = "import";
+  return GenerationMethod2;
+})(GenerationMethod || {});
+var WebsiteRepositoryCreationMethod = /* @__PURE__ */ ((WebsiteRepositoryCreationMethod2) => {
+  WebsiteRepositoryCreationMethod2["DUPLICATE"] = "duplicate";
+  WebsiteRepositoryCreationMethod2["CREATE_USING_TEMPLATE"] = "create-using-template";
+  return WebsiteRepositoryCreationMethod2;
+})(WebsiteRepositoryCreationMethod || {});
+
+// src/api/work/schedule.enum.ts
+var WorkScheduleCadence = /* @__PURE__ */ ((WorkScheduleCadence2) => {
+  WorkScheduleCadence2["HOURLY"] = "hourly";
+  WorkScheduleCadence2["EVERY_3_HOURS"] = "every_3_hours";
+  WorkScheduleCadence2["EVERY_8_HOURS"] = "every_8_hours";
+  WorkScheduleCadence2["EVERY_12_HOURS"] = "every_12_hours";
+  WorkScheduleCadence2["DAILY"] = "daily";
+  WorkScheduleCadence2["WEEKLY"] = "weekly";
+  WorkScheduleCadence2["MONTHLY"] = "monthly";
+  return WorkScheduleCadence2;
+})(WorkScheduleCadence || {});
+var WorkScheduleStatus = /* @__PURE__ */ ((WorkScheduleStatus2) => {
+  WorkScheduleStatus2["DISABLED"] = "disabled";
+  WorkScheduleStatus2["ACTIVE"] = "active";
+  WorkScheduleStatus2["PAUSED"] = "paused";
+  WorkScheduleStatus2["CANCELED"] = "canceled";
+  return WorkScheduleStatus2;
+})(WorkScheduleStatus || {});
+var WorkScheduleBillingMode = /* @__PURE__ */ ((WorkScheduleBillingMode2) => {
+  WorkScheduleBillingMode2["SUBSCRIPTION"] = "subscription";
+  WorkScheduleBillingMode2["USAGE"] = "usage";
+  return WorkScheduleBillingMode2;
+})(WorkScheduleBillingMode || {});
+
+// src/api/work/generate-status.enum.ts
+var GenerateStatusType = /* @__PURE__ */ ((GenerateStatusType2) => {
+  GenerateStatusType2["GENERATING"] = "generating";
+  GenerateStatusType2["GENERATED"] = "generated";
+  GenerateStatusType2["ERROR"] = "error";
+  GenerateStatusType2["CANCELLED"] = "cancelled";
+  return GenerateStatusType2;
+})(GenerateStatusType || {});
+
+// src/api/work/generation-metrics.ts
+var WorkHistoryActivityType = /* @__PURE__ */ ((WorkHistoryActivityType2) => {
+  WorkHistoryActivityType2["GENERATION"] = "generation";
+  WorkHistoryActivityType2["ITEM_ADDED"] = "item_added";
+  WorkHistoryActivityType2["ITEM_UPDATED"] = "item_updated";
+  WorkHistoryActivityType2["ITEM_REMOVED"] = "item_removed";
+  WorkHistoryActivityType2["COMPARISON_ADDED"] = "comparison_added";
+  WorkHistoryActivityType2["COMPARISON_REMOVED"] = "comparison_removed";
+  WorkHistoryActivityType2["CATEGORY_CHANGE"] = "category_change";
+  WorkHistoryActivityType2["TAG_CHANGE"] = "tag_change";
+  WorkHistoryActivityType2["COLLECTION_CHANGE"] = "collection_change";
+  WorkHistoryActivityType2["COMMUNITY_PR_MERGED"] = "community_pr_merged";
+  return WorkHistoryActivityType2;
+})(WorkHistoryActivityType || {});
+
+// src/api/work/import-source.dto.ts
+var IMPORT_SOURCE_TYPES = ["data_repo", "awesome_readme", "link_existing", "works_config"];
+var AWESOME_README_IMPORT_MODES = ["clone", "reuse_source"];
+
+// src/api/onboarding/onboarding-status.ts
+var ONBOARDING_TERMINAL_STATUSES = ["deployed", "failed", "rejected"];
+function isTerminalOnboardingStatus(status) {
+  return ONBOARDING_TERMINAL_STATUSES.includes(status);
+}
+
+// src/api/onboarding/wizard-state.ts
+var ROLE_OPTIONS = [
+  { id: "founder-ceo", label: "Founder / CEO", description: "I run the company and wear many hats" },
+  { id: "engineering", label: "Engineering", description: "I build and ship software" },
+  { id: "product", label: "Product", description: "I define what we build and why" },
+  { id: "marketing", label: "Marketing", description: "I grow awareness, content, and campaigns" },
+  { id: "sales", label: "Sales", description: "I find, pitch, and close customers" },
+  { id: "consultant", label: "Consultant", description: "I deliver projects and advice for clients" },
+  { id: "research", label: "Research", description: "I investigate, analyze, and synthesize" },
+  { id: "operations", label: "Operations", description: "I keep the business running smoothly" },
+  { id: "support", label: "Support", description: "I help customers succeed and resolve issues" },
+  { id: "finance", label: "Finance", description: "I manage budgets, billing, and reporting" },
+  { id: "hr", label: "HR", description: "I hire, onboard, and support our people" },
+  { id: "legal", label: "Legal", description: "I handle contracts, compliance, and policy" },
+  { id: "education", label: "Education", description: "I teach, train, or create learning content" },
+  { id: "other", label: "Other", description: "Something else \u2014 tell us more later" }
+];
+var TEAM_SIZE_OPTIONS = [
+  { id: "solo", label: "Solo", description: "Just me" },
+  { id: "small-2-10", label: "Small (2\u201310)", description: "2\u201310 people" },
+  { id: "mid-11-50", label: "Mid (11\u201350)", description: "11\u201350 people" },
+  { id: "large-51-200", label: "Large (51\u2013200)", description: "51\u2013200 people" },
+  { id: "enterprise-200-plus", label: "Enterprise (200+)", description: "More than 200 people" }
+];
+var ONBOARDING_DEFAULT_STATE = {
+  version: 2,
+  lastStep: 0,
+  ai: { choice: "ever-works" },
+  storage: { choice: "ever-works-git" },
+  db: { choice: "ever-works-db" },
+  deploy: { choice: "ever-works" },
+  desktop: { choice: "cloud" },
+  skippedSteps: [],
+  pluginsReviewed: false
+};
+var ONBOARDING_DESKTOP_NEXT_STEPS = {
+  cloud: {
+    choice: "cloud",
+    title: "Start building",
+    description: "Everything runs on the hosted platform \u2014 create your first Work and go."
+  },
+  desktop: {
+    choice: "desktop",
+    title: "Finish your desktop setup",
+    description: "Ever Works Desktop supervises the API and web app on this machine. Check the services are healthy, then pick the job runtime you want them to use.",
+    href: "/settings/job-runtime"
+  },
+  "own-nodes": {
+    choice: "own-nodes",
+    title: "Add your first node",
+    description: "Enroll the machines that should execute your work. Issue an enrollment token here, then run the Desktop Node app or the headless node on each machine.",
+    href: "/settings/fleet"
+  }
+};
+function desktopNextStep(choice) {
+  return ONBOARDING_DESKTOP_NEXT_STEPS[choice ?? "cloud"] ?? ONBOARDING_DESKTOP_NEXT_STEPS.cloud;
+}
+
+// src/api/onboarding/roster.ts
+var ROSTER_LANE_KEYS = [
+  "coordination",
+  "research",
+  "content",
+  "outreach",
+  "visibility",
+  "social",
+  "market-watch"
+];
+var ROSTER_BLUEPRINT_SLUGS = ["general", "growth", "revenue", "insight", "solo-starter"];
+var ROSTER_MAX_LANES = 8;
+var ROSTER_NAME_MAX = 60;
+
+// src/api/onboarding/first-hour.ts
+var ONBOARDING_MILESTONES = [
+  "connectProvider",
+  "meetAgents",
+  "shipTask",
+  "resolveDecision",
+  "scheduleJob"
+];
+var MILESTONE_STATUSES = ["pending", "done", "skipped"];
+var ROSTER_PROVISION_STATES = ["idle", "queued", "creating", "binding", "ready", "partial", "failed"];
+var LANE_OUTCOMES = ["pending", "created", "reused", "skippedNoSeat", "failed"];
+var LANE_FAILURE_REASONS = ["nameUnavailable", "noSeat", "permissionDenied", "timedOut", "unknown"];
+
+// src/api/organization/index.ts
+var UPGRADE_NOT_AVAILABLE_AFTER_MULTIPLE_ORGS = "UPGRADE_NOT_AVAILABLE_AFTER_MULTIPLE_ORGS";
+
+// src/api/active-scope.ts
+var ACTIVE_SCOPE_PERSONAL_SENTINEL = "@personal";
+var ACTIVE_SCOPE_API_HEADER = "x-scope-slug";
+var ACTIVE_SCOPE_BROWSER_HEADER = "x-ever-workspace";
+var ACTIVE_SCOPE_RESPONSE_PROPERTIES = {
+  tenantId: { type: "string", format: "uuid", nullable: true },
+  organizationId: { type: "string", format: "uuid", nullable: true },
+  organizationSlug: { type: "string", nullable: true }
+};
+var ACTIVE_SCOPE_RESPONSE_SCHEMA = {
+  type: "object",
+  properties: ACTIVE_SCOPE_RESPONSE_PROPERTIES,
+  required: Object.keys(ACTIVE_SCOPE_RESPONSE_PROPERTIES)
+};
+
+// src/api/changelog/changelog.enum.ts
+var CHANGELOG_CATEGORIES = ["agents", "decisions", "knowledge", "connections", "costs", "platform"];
+var CHANGELOG_KINDS = ["new", "improved", "fixed", "security"];
+function isChangelogCategory(value) {
+  return typeof value === "string" && CHANGELOG_CATEGORIES.includes(value);
+}
+function isChangelogKind(value) {
+  return typeof value === "string" && CHANGELOG_KINDS.includes(value);
+}
+var UNSAFE_PATH_CHARACTER = /[\\\s\p{Cc}]/u;
+function isSafeInAppPath(raw) {
+  if (typeof raw !== "string" || raw.length === 0) {
+    return false;
+  }
+  if (raw[0] !== "/" || raw[1] === "/") {
+    return false;
+  }
+  return !UNSAFE_PATH_CHARACTER.test(raw);
+}
+var CHANGELOG_SLUG_PATTERN = /^[a-z0-9-]{3,64}$/;
+var CHANGELOG_LIMITS = {
+  titleMaxLength: 80,
+  bodyMaxLength: 600,
+  bodyMaxParagraphs: 3,
+  ctaLabelMaxLength: 32,
+  /** Most slugs one mark-read write may carry. */
+  markReadBatchMax: 25,
+  /** The unread count only ever considers this many of the newest entries. */
+  unreadWindow: 50,
+  /** Default page size for the panel and the full list. */
+  pageSize: 20,
+  /** Largest page a client may request. */
+  pageSizeMax: 50,
+  /** The deepest the list can be paged. */
+  listMax: 200
+};
+
+// src/api/workspace-search/index.ts
+var WORKSPACE_SEARCH_KINDS = [
+  "mission",
+  "task",
+  "agent",
+  "work",
+  "idea",
+  "skill",
+  "team",
+  "knowledge",
+  "run",
+  "decision",
+  "memory",
+  "goal",
+  "meeting",
+  "node",
+  "connection"
+];
+var WORKSPACE_SEARCH_MIN_QUERY_LENGTH = 2;
+var WORKSPACE_SEARCH_MAX_QUERY_LENGTH = 128;
+var WORKSPACE_SEARCH_MAX_TOTAL = 60;
+var WORKSPACE_SEARCH_DEFAULT_PER_KIND = 5;
+var WORKSPACE_SEARCH_MAX_PER_KIND = 25;
+var WORKSPACE_SEARCH_MAX_RECENT = 12;
+
+// src/api/help/help.enum.ts
+var HELP_SECTIONS = [
+  "start-here",
+  "running-the-loop",
+  "your-agents",
+  "setup-and-connections",
+  "money-and-limits",
+  "when-something-goes-wrong"
+];
+var HELP_BLOCK_KINDS = [
+  "paragraph",
+  "heading",
+  "orderedList",
+  "unorderedList",
+  "note",
+  "shortcut",
+  "code",
+  "link",
+  "table"
+];
+var HELP_LINK_TARGET_TYPES = ["article", "screen", "external"];
+var HELP_NOTE_TONES = ["note", "tip", "info", "warning", "danger"];
+var HELP_LIMITS = {
+  maxArticles: 200,
+  titleChars: 70,
+  summaryChars: 200,
+  bodyChars: 6e4,
+  maxHeadings: 80,
+  headingIdMinChars: 2,
+  headingIdMaxChars: 96,
+  maxKeywords: 12,
+  keywordChars: 32,
+  maxDocuments: 8,
+  maxRelated: 5,
+  linkLabelChars: 80,
+  externalHrefChars: 2048
+};
+var HELP_ARTICLE_ID_PATTERN = /^[a-z0-9-]{3,64}$/;
+function isHelpSection(value) {
+  return typeof value === "string" && HELP_SECTIONS.includes(value);
+}
+function isHelpArticleId(value) {
+  return typeof value === "string" && HELP_ARTICLE_ID_PATTERN.test(value);
+}
+
+// src/api/shared-view/shared-view.dto.ts
+var SHARED_VIEW_STATUSES = ["active", "paused"];
+function isSharedViewStatus(value) {
+  return value === "active" || value === "paused";
+}
+var SHARED_VIEW_LIMITS = {
+  /** 256 bits of randomness, base64url without padding. */
+  tokenBytes: 32,
+  tokenLength: 43,
+  /** A view session lives this long before the client exchanges the token again. */
+  viewSessionTtlSeconds: 15 * 60,
+  /** Cards per published column. */
+  columnCardLimit: 50,
+  /** Lines in the published activity strip. */
+  activityLineLimit: 20,
+  /** Labels per published card. */
+  cardLabelLimit: 3,
+  /** Exchanges and reads per token (or per view) per minute. */
+  requestsPerTokenPerMinute: 60,
+  /** Public requests per client per hour. */
+  requestsPerClientPerHour: 600,
+  /** Owner regenerations per Workspace per minute. */
+  regeneratePerMinute: 10,
+  /** A client increments the view count at most once in this window. */
+  viewDedupeWindowSeconds: 10 * 60,
+  /** The `Retry-After` a throttled public request carries. */
+  retryAfterSeconds: 60,
+  /** The live poll cadence of the published page. */
+  pollIntervalSeconds: 20,
+  /** Knowledge class names a selection may hold. */
+  knowledgeClassLimit: 32
+};
+var SHARED_VIEW_NOT_ACTIVE = "shared_view_not_active";
+
+// src/api/shared-view/published-board.dto.ts
+var PUBLISHED_COLUMN_KEYS = ["backlog", "in_flight", "needs_you", "done"];
+
+// src/api/shared-view/publishable-activity.ts
+var PUBLISHABLE_ACTIVITY_ACTIONS = Object.freeze([
+  "task_created",
+  "task_transitioned",
+  "task_completed",
+  "task_assigned",
+  "agent_task_assigned",
+  "agent_run_started",
+  "agent_run_completed",
+  "agent_paused",
+  "agent_resumed"
+]);
+function isPublishableActivityAction(actionType) {
+  return typeof actionType === "string" && PUBLISHABLE_ACTIVITY_ACTIONS.includes(actionType);
+}
+
+exports.ACTIVE_SCOPE_API_HEADER = ACTIVE_SCOPE_API_HEADER;
+exports.ACTIVE_SCOPE_BROWSER_HEADER = ACTIVE_SCOPE_BROWSER_HEADER;
+exports.ACTIVE_SCOPE_PERSONAL_SENTINEL = ACTIVE_SCOPE_PERSONAL_SENTINEL;
+exports.ACTIVE_SCOPE_RESPONSE_SCHEMA = ACTIVE_SCOPE_RESPONSE_SCHEMA;
+exports.AWESOME_README_IMPORT_MODES = AWESOME_README_IMPORT_MODES;
+exports.CHANGELOG_CATEGORIES = CHANGELOG_CATEGORIES;
+exports.CHANGELOG_KINDS = CHANGELOG_KINDS;
+exports.CHANGELOG_LIMITS = CHANGELOG_LIMITS;
+exports.CHANGELOG_SLUG_PATTERN = CHANGELOG_SLUG_PATTERN;
+exports.GenerateStatusType = GenerateStatusType;
+exports.GenerationMethod = GenerationMethod;
+exports.HELP_ARTICLE_ID_PATTERN = HELP_ARTICLE_ID_PATTERN;
+exports.HELP_BLOCK_KINDS = HELP_BLOCK_KINDS;
+exports.HELP_LIMITS = HELP_LIMITS;
+exports.HELP_LINK_TARGET_TYPES = HELP_LINK_TARGET_TYPES;
+exports.HELP_NOTE_TONES = HELP_NOTE_TONES;
+exports.HELP_SECTIONS = HELP_SECTIONS;
+exports.IMPORT_SOURCE_TYPES = IMPORT_SOURCE_TYPES;
+exports.LANE_FAILURE_REASONS = LANE_FAILURE_REASONS;
+exports.LANE_OUTCOMES = LANE_OUTCOMES;
+exports.MILESTONE_STATUSES = MILESTONE_STATUSES;
+exports.ONBOARDING_DEFAULT_STATE = ONBOARDING_DEFAULT_STATE;
+exports.ONBOARDING_DESKTOP_NEXT_STEPS = ONBOARDING_DESKTOP_NEXT_STEPS;
+exports.ONBOARDING_MILESTONES = ONBOARDING_MILESTONES;
+exports.ONBOARDING_TERMINAL_STATUSES = ONBOARDING_TERMINAL_STATUSES;
+exports.PUBLISHABLE_ACTIVITY_ACTIONS = PUBLISHABLE_ACTIVITY_ACTIONS;
+exports.PUBLISHED_COLUMN_KEYS = PUBLISHED_COLUMN_KEYS;
+exports.ROLE_OPTIONS = ROLE_OPTIONS;
+exports.ROSTER_BLUEPRINT_SLUGS = ROSTER_BLUEPRINT_SLUGS;
+exports.ROSTER_LANE_KEYS = ROSTER_LANE_KEYS;
+exports.ROSTER_MAX_LANES = ROSTER_MAX_LANES;
+exports.ROSTER_NAME_MAX = ROSTER_NAME_MAX;
+exports.ROSTER_PROVISION_STATES = ROSTER_PROVISION_STATES;
+exports.SHARED_VIEW_LIMITS = SHARED_VIEW_LIMITS;
+exports.SHARED_VIEW_NOT_ACTIVE = SHARED_VIEW_NOT_ACTIVE;
+exports.SHARED_VIEW_STATUSES = SHARED_VIEW_STATUSES;
+exports.TEAM_SIZE_OPTIONS = TEAM_SIZE_OPTIONS;
+exports.UPGRADE_NOT_AVAILABLE_AFTER_MULTIPLE_ORGS = UPGRADE_NOT_AVAILABLE_AFTER_MULTIPLE_ORGS;
+exports.WORKSPACE_SEARCH_DEFAULT_PER_KIND = WORKSPACE_SEARCH_DEFAULT_PER_KIND;
+exports.WORKSPACE_SEARCH_KINDS = WORKSPACE_SEARCH_KINDS;
+exports.WORKSPACE_SEARCH_MAX_PER_KIND = WORKSPACE_SEARCH_MAX_PER_KIND;
+exports.WORKSPACE_SEARCH_MAX_QUERY_LENGTH = WORKSPACE_SEARCH_MAX_QUERY_LENGTH;
+exports.WORKSPACE_SEARCH_MAX_RECENT = WORKSPACE_SEARCH_MAX_RECENT;
+exports.WORKSPACE_SEARCH_MAX_TOTAL = WORKSPACE_SEARCH_MAX_TOTAL;
+exports.WORKSPACE_SEARCH_MIN_QUERY_LENGTH = WORKSPACE_SEARCH_MIN_QUERY_LENGTH;
+exports.WebsiteRepositoryCreationMethod = WebsiteRepositoryCreationMethod;
+exports.WorkHistoryActivityType = WorkHistoryActivityType;
+exports.WorkScheduleBillingMode = WorkScheduleBillingMode;
+exports.WorkScheduleCadence = WorkScheduleCadence;
+exports.WorkScheduleStatus = WorkScheduleStatus;
+exports.desktopNextStep = desktopNextStep;
+exports.isChangelogCategory = isChangelogCategory;
+exports.isChangelogKind = isChangelogKind;
+exports.isHelpArticleId = isHelpArticleId;
+exports.isHelpSection = isHelpSection;
+exports.isPublishableActivityAction = isPublishableActivityAction;
+exports.isSafeInAppPath = isSafeInAppPath;
+exports.isSharedViewStatus = isSharedViewStatus;
+exports.isTerminalOnboardingStatus = isTerminalOnboardingStatus;