@owlmeans/viable-common 0.0.4

package/src/dev/schemas.ts

@@ -0,0 +1,124 @@
+import type { JSONSchemaType } from "ajv"
+import type { FileBlock, AccessList, AccessBlock, EntrypointRef } from "./types.js"
+import { AccessLevel } from "./consts.js"
+
+export const FileBlockSchema: JSONSchemaType<FileBlock> = {
+  type: "object",
+  title: "FileList",
+  description: "Object with file list",
+  properties: {
+    files: {
+      type: "array",
+      items: {
+        type: "string",
+        description: "Path to file"
+      },
+      description: "List of file pathes"
+    },
+    why: {
+      type: "string",
+      nullable: true,
+      description: "Explain why you have choosen this file or none at all"
+    }
+  },
+  required: ["files"],
+  additionalProperties: false
+}
+
+export const SourceCodeSchema: JSONSchemaType<{source: string}> = {
+  type: "object",
+  description: "Source code container",
+  properties: {
+    source: {
+      type: "string",
+      description: "Source code content"
+    }
+  },
+  required: ["source"],
+  additionalProperties: false,
+}
+
+export const TechNameSchema: JSONSchemaType<{name: string}> = {
+  type: "object",
+  description: "Object with name",
+  properties: {
+    name: {
+      type: "string",
+      description: "Technical name"
+    }
+  },
+  required: ["name"],
+  additionalProperties: false,
+}
+
+export const EntrypointRefListSchema: JSONSchemaType<{entries: EntrypointRef[]}> = {
+  type: "object",
+  title: "PossibleEntrypointList",
+  description: "Object with a list of entrypoints",
+  properties: {
+    entries: {
+      type: "array",
+      description: "List of entrypoints",
+      items: {
+        type: "object",
+        properties: {
+          alias: {
+            type: "string",
+            description: "Entrypoint alias, e.g. \"web:task-list\" for a screen or \"api:task:list\" for an endpoint"
+          },
+          path: {
+            type: "string",
+            description: "URL path the entrypoint is registered at, e.g. \"/tasks/:taskId\""
+          }
+        },
+        required: ["alias", "path"],
+        additionalProperties: false
+      }
+    }
+  },
+  required: ["entries"],
+  additionalProperties: false
+}
+
+export const AccessBlockSchema: JSONSchemaType<AccessBlock> = {
+  type: "object",
+  title: "AccessBlock",
+  description: "Object with permissions array and access level",
+  properties: {
+    permissions: {
+      type: "array",
+      items: {
+        type: "string",
+        description:
+          "A permission requirement, spelled \"<resource>--<action>\" — \"--\" is TWO hyphens, "
+          + "lowercase kebab-case, singular resource. Append \"@<routeParam>\" to bind the check "
+          + "to one resource instance, naming a param that this same entrypoint's own path "
+          + "carries: \"enquiry--view@enquiryId\" for a route \"/enquiries/:enquiryId\". "
+          + "Omit the suffix for project-wide permissions such as list or create."
+      },
+      description: "List of permissions (to get access any should be satisfied)"
+    },
+    level: {
+      type: "string",
+      enum: Object.values(AccessLevel),
+      description: `
+      Access level:
+- guest - means public access without authentication
+- user - means authenticated user access (no specific permissions required)
+- permissioned - means authenticated access with one of specified permissions
+- admin - means the project owner only: authenticated and holding the admin marker
+      `
+    },
+  },
+  required: ["permissions", "level"],
+  additionalProperties: false
+}
+
+export const AccessListSchema: JSONSchemaType<AccessList> = {
+  type: "object",
+  title: "AccessList",
+  description: "Object mapping entrypoint aliases to access blocks",
+  properties: {},
+  required: [],
+  additionalProperties: AccessBlockSchema,
+}

package/src/dev/types.ts

@@ -0,0 +1,47 @@
+import type { AccessLevel } from "./consts.js"
+
+export interface SourceFile {
+  path: string
+  code: string
+}
+
+export interface PossibleSourceFile extends Partial<SourceFile> {
+  path: string
+}
+
+export interface FileBlock {
+  files: string[]
+  why?: string
+}
+
+export interface AccessBlock {
+  /**
+   * The gate parameters this entrypoint requires, written exactly as they appear in
+   * `gate(OIDC_GATE, [...])`: `<resource>--<action>`, optionally suffixed `@<routeParam>` to bind
+   * the check to one resource instance.
+   *
+   * The selector lives in the STRING rather than in a sibling field, because that is what the model
+   * produces however the field is described to it — and because the array is then the gate's
+   * argument verbatim, so what was described and what gets written cannot disagree about scoping.
+   *
+   * The `@` is the gate's syntax alone. It is stripped before a permission is registered or granted:
+   * a definition stored under a name containing one is a key nothing looks up, and every grant made
+   * against it is a silent no-op.
+   */
+  permissions: string[]
+  level: AccessLevel
+}
+
+/**
+ * Access rules keyed by ENTRYPOINT ALIAS — never by URL or route path. The alias prefix decides
+ * which side a rule is applied on (`api:` = endpoint, anything else = screen); see
+ * `ALIAS_PREFIX_API`.
+ */
+export interface AccessList extends Record<string, AccessBlock> {
+}
+
+/** One entrypoint as the pipeline refers to it: the alias to address it by, and where it lands. */
+export interface EntrypointRef {
+  alias: string
+  path: string
+}

package/src/execution/consts.ts

@@ -0,0 +1,37 @@
+
+/**
+ * Level and effort tiers are owned by `@owlmeans/llm-common` — re-exported here so a
+ * consumer of the viable contracts never needs a second import.
+ */
+export { ExecutionEffort, ExecutionLevel } from '@owlmeans/llm-common'
+
+/**
+ * Serializable role name for model selection. Lives in `common` so the platform,
+ * the serialized execution state, and a future queue consumer can all name roles.
+ *
+ * The generic `ModelRole` in `@owlmeans/llm-common` is an open `string`; this enum is
+ * viable's concrete instance of it.
+ *
+ * IMPORTANT: the string values mirror the library `ChatModelPurpose` enum
+ * (`packages/library/src/consts.ts`) **value-for-value**. Keep the two in sync
+ * until a later phase collapses `ChatModelPurpose` into an alias of `ModelRole`.
+ */
+export enum ModelRole {
+  SeniorBA = 'senior-ba',
+  MiddleBA = 'middle-ba',
+  SeniorUIDeveloper = 'senior-ui-developer',
+  ProduceManager = 'product-manager',
+  MiddleDesigner = 'middle-designer',
+  SeniorDesigner = 'senior-designer',
+  StateArchitect = 'state-architect',
+  MiddleDeveloper = 'middle-developer',
+  SeniorDeveloper = 'senior-developer',
+  ViewArchitect = 'view-architect',
+  DataArchitect = 'data-architect',
+  ApiArchitect = 'api-architect',
+  NavigationArchitect = 'navigation-architect',
+  BackendDomainArchitect = 'backend-domain-architect',
+  DevOrchestrator = 'dev-orchestrator',
+  Utility = 'utility',
+  Picker = 'picker',
+}

package/src/execution/index.ts

@@ -0,0 +1,3 @@
+
+export * from './consts.js'
+export type * from './types.js'

package/src/execution/types.ts

@@ -0,0 +1,55 @@
+import type { BlueprintRef } from '../blueprint/types.js'
+import type {
+  ExecutionState as LlmExecutionState, TaskExecutionState as LlmTaskExecutionState,
+} from '@owlmeans/llm-common'
+import type { PurposeMetadata } from '../agent/types.js'
+import type { AgentProject, Entity, UserStory } from '../ba/types.js'
+import type { UXTransition } from '../ux/types.js'
+import type { SeniorityMode } from '../consts.js'
+
+/**
+ * Model-selection contracts are owned by `@owlmeans/llm-common` — the JSON-safe config
+ * patch, the alias-or-patch override, and the inheritable policy whose resolution
+ * precedence is roleOverride → modelOverride → effort tier → `LlmService.getModel`.
+ * Viable adds no fields to them, so they are re-exported rather than redeclared.
+ */
+export type { ModelConfigPatch, ModelConfigOverride, ModelPolicy } from '@owlmeans/llm-common'
+
+/**
+ * Serializable execution state — no functions, no `FileHelper`, no models.
+ * The runtime `Execution` (library) = this state + attached collaborators.
+ * Extends the generic `@owlmeans/llm-common` state with the viable domain context
+ * every performer needs.
+ */
+export interface ExecutionState extends LlmExecutionState {
+  purpose: PurposeMetadata
+  slot?: string
+  projectId?: string
+  entityId?: string
+  project?: AgentProject
+  entities?: Entity[]
+  /**
+   * Which blueprint this run is building against, as an id plus an override patch.
+   *
+   * A REFERENCE and never the resolved blueprint: an execution state is written into the pipeline
+   * run row at every step boundary, and that row holds keys, never artifacts. The resolved value
+   * is reconstructed from these two fields whenever a helper asks for it, which also means a
+   * blueprint the platform has since corrected reaches a resumed run rather than the copy that was
+   * frozen into it.
+   *
+   * Absent means the platform default — every project created before blueprints existed.
+   */
+  blueprint?: BlueprintRef
+}
+
+/**
+ * Adds viable's task context to the generic resumable fields (`phase` / `completed` /
+ * `cursor` / `data`). The base fields come from viable's own {@link ExecutionState},
+ * so only the resumable half of the llm state is mixed in.
+ */
+export interface TaskExecutionState
+  extends ExecutionState, Omit<LlmTaskExecutionState, keyof LlmExecutionState> {
+  mode?: SeniorityMode
+  story?: UserStory
+  transitions?: UXTransition[]
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+
+export type * from './types.js'
+export * from './ba/index.js'
+export * from './dev/index.js'
+export * from './ux/index.js'
+export * from './preview/index.js'
+export * from './agent/index.js'
+export * from './consts.js'
+export * from './metadata/index.js'
+export * from './areas/index.js'
+export * from './execution/index.js'
+export * from './skills/index.js'
+export * from './moderation/index.js'
+export * from './integrity/index.js'
+export * from './topology/index.js'
+export * from './blueprint/index.js'
+export * from './slot/index.js'
+export * from './connect/index.js'
+export * from './convert/index.js'
+export * from './scaffold/index.js'
+export * from './design/index.js'
+export * from './branding.js'