@owlmeans/viable-common 0.0.32 → 0.0.34

package/src/intent/consts.ts

@@ -0,0 +1,66 @@
+/**
+ * The intent-first hand-off — how a prompt typed on the public site reaches the platform.
+ *
+ * A visitor types the idea for a project on the marketing site before they have an account. The
+ * site cannot write into the platform's browser storage (IndexedDB is per origin) and must not put
+ * the prompt in a URL, so the prompt takes a short detour through the platform's own cache: the
+ * site stashes it behind an unguessable reference, sends the browser to the platform with only that
+ * reference, and the platform picks the prompt up once — after which it lives in the visitor's own
+ * browser until they decide what to do with it.
+ *
+ * Everything here is serializable and runtime-free: the site, the manager API and the manager web
+ * read the same declarations, and none of them may reinvent a name the others parse.
+ */
+
+/** Every address of the hand-off. API routes are guest routes; the landing is a screen. */
+export const intent = Object.freeze({
+  base: 'viable:manager-api:intent:base',
+  stash: 'viable:manager-api:intent:stash',
+  pickup: 'viable:manager-api:intent:pickup',
+  landing: 'viable:manager-web:intent:landing',
+} as const)
+
+/** Where the guest API lives, and the screen the visitor's browser is sent to. */
+export const INTENT_API_PATH = '/public/intent'
+export const INTENT_LANDING_PATH = '/start'
+
+/** The flow the two sides walk. */
+export const INTENT_FLOW = 'viable:intent'
+
+/**
+ * How long the platform keeps a stashed prompt waiting for pickup. Short on purpose: the pickup
+ * happens the moment the browser lands, so anything older was abandoned, and a prompt is personal
+ * data the platform has no business holding once nobody is coming for it.
+ */
+export const INTENT_TTL_SECONDS = 120
+
+/** The longest prompt the platform will create a project from (`PromptSchema` in viable). */
+export const INTENT_PROMPT_MAX = 8192
+
+/**
+ * The reference's shape: `createIdOfLength(24)` — Base58, so no `0`, `O`, `I` or `l`. Anything else
+ * is refused before the cache is asked, which keeps a crafted reference from ever being a key.
+ */
+export const INTENT_REF_LENGTH = 24
+export const INTENT_REF_PATTERN = '^[1-9A-HJ-NP-Za-km-z]{24}$'
+
+/** The flow payload key carrying the reference — short, because a payload is CSV-joined. */
+export const INTENT_PAYLOAD_REF = 'ref'
+
+/** How long the visitor's draft survives in their own browser waiting for a decision. */
+export const INTENT_DRAFT_TTL_MS = 24 * 60 * 60 * 1000
+
+/** How long a suspended landing waits while the visitor signs in or registers. */
+export const INTENT_SUSPEND_TTL_MS = 30 * 60 * 1000
+
+/** Steps of {@link intentFlow}, exported so a screen never spells one as a literal. */
+export enum IntentFlowStep {
+  /** The public site: the prompt is typed and stashed. */
+  Compose = 'compose',
+  /** The platform's landing screen: the stash is picked up. */
+  Land = 'land',
+  /** The platform's own sign-in dispatcher. */
+  SignIn = 'sign-in',
+  /** The platform's home screen, where the draft is offered back. */
+  Review = 'review',
+}

package/src/intent/entrypoints.ts

@@ -0,0 +1,43 @@
+import { contract, openProtocol, protocol, typed } from '@owlmeans/entrypoint'
+import { frontend, route, RouteMethod } from '@owlmeans/route'
+import { INTENT_API_PATH, INTENT_LANDING_PATH, intent } from './consts.js'
+import { IntentPickupBodySchema, IntentStashBodySchema } from './schemas.js'
+import type {
+  IntentPickupBody, IntentPickupResult, IntentProtocolOptions, IntentStashBody, IntentStashResult,
+} from './types.js'
+
+/**
+ * Declare the intent-first hand-off: two GUEST API routes and the landing screen's address.
+ *
+ * No guard and no gate anywhere on the API — the caller is a visitor who has no account yet — and
+ * no `service` on any route: each consumer fills it in (the public site names the platform's
+ * services in its own configuration; the manager binds them to its own).
+ *
+ * TODO(cors): these routes ride the framework's global `origin: '*'` CORS policy (no credentials).
+ * If viable ever restricts allowed origins globally, this entrypoint must keep answering the public
+ * site's origins — owlmeans.com, owlmeans.pl and, in dev/stage, `http://localhost:4321`.
+ *
+ * The landing screen is `sticky`, like the OAuth consent screens: it is an ordinary in-app screen
+ * that a visitor arrives at directly from another origin.
+ */
+export const makeIntentProtocols = (opts: IntentProtocolOptions = {}) => {
+  const base = openProtocol(route(intent.base, opts.path ?? INTENT_API_PATH))
+
+  return {
+    base,
+
+    stash: protocol(
+      route(intent.stash, '/', { parent: base, method: RouteMethod.POST }),
+      contract.request({ body: typed<IntentStashBody>(IntentStashBodySchema) }, typed<IntentStashResult>()),
+    ),
+
+    pickup: protocol(
+      route(intent.pickup, '/pickup', { parent: base, method: RouteMethod.POST }),
+      contract.request({ body: typed<IntentPickupBody>(IntentPickupBodySchema) }, typed<IntentPickupResult>()),
+    ),
+
+    landing: openProtocol(route(intent.landing, opts.landing ?? INTENT_LANDING_PATH, frontend()), { sticky: true }),
+  }
+}
+
+export type IntentProtocols = ReturnType<typeof makeIntentProtocols>

package/src/intent/errors.ts

@@ -0,0 +1,33 @@
+import { ResilientError } from '@owlmeans/error'
+
+export class IntentError extends ResilientError {
+  public static override typeName = `ViableIntent${ResilientError.typeName}`
+
+  constructor(message: string = 'error') {
+    super(IntentError.typeName, `viable-intent:${message}`)
+  }
+}
+
+/** No stashed prompt under that reference — expired, already picked up, or never existed. */
+export class IntentExpired extends IntentError {
+  public static override typeName = `Expired${IntentError.typeName}`
+  /** The reference answers nothing (any more): answered 404. */
+  public static httpStatus = 404
+
+  constructor(message: string = 'error') {
+    super(`expired:${message}`)
+    this.type = IntentExpired.typeName
+  }
+}
+
+/** Too many stashes or pickups from one address, or across everyone. */
+export class IntentThrottled extends IntentError {
+  public static override typeName = `Throttled${IntentError.typeName}`
+  /** Answered 429. */
+  public static httpStatus = 429
+
+  constructor(message: string = 'error') {
+    super(`throttled:${message}`)
+    this.type = IntentThrottled.typeName
+  }
+}

package/src/intent/flow.ts

@@ -0,0 +1,67 @@
+import { DISPATCHER } from '@owlmeans/auth'
+import { HOME } from '@owlmeans/context'
+import type { ShallowFlow } from '@owlmeans/flow'
+import { INTENT_FLOW, INTENT_PAYLOAD_REF, intent, IntentFlowStep } from './consts.js'
+
+const payloadMap = { [INTENT_PAYLOAD_REF]: 0 }
+
+/**
+ * The hand-off flow both sides walk.
+ *
+ * `compose` runs on the public site: the prompt is stashed and `handoff` carries the reference to
+ * `land`, whose module is the platform's landing screen — so the site redirects to
+ * `land`'s address with the payload as query. The landing then enters at `land` FRESH (the
+ * reference arrives as `?ref=`, never as a serialized token, which the platform's own sign-in
+ * parses from `?flow=` on every page), and either goes on to `review` (signed in) or parks the flow
+ * with `suspendFlow` at `sign-in`, whose non-explicit way forward is `review` — the home screen —
+ * so whichever sign-in method finishes lands there.
+ *
+ * The steps address CONCRETE entrypoint aliases, never `$`-prefixed references: this flow is never
+ * the live `FlowService` model and nothing here needs `configureFlows`.
+ */
+export const intentFlow: ShallowFlow = {
+  flow: INTENT_FLOW,
+  initialStep: IntentFlowStep.Compose,
+  steps: {
+    [IntentFlowStep.Compose]: {
+      index: 0,
+      step: IntentFlowStep.Compose,
+      service: '',
+      initial: true,
+      payloadMap,
+      transitions: {
+        handoff: { transition: 'handoff', step: IntentFlowStep.Land },
+      },
+    },
+    [IntentFlowStep.Land]: {
+      index: 1,
+      step: IntentFlowStep.Land,
+      service: '',
+      module: intent.landing,
+      initial: true,
+      payloadMap,
+      transitions: {
+        review: { transition: 'review', step: IntentFlowStep.Review },
+        'sign-in': { transition: 'sign-in', step: IntentFlowStep.SignIn, explicit: true },
+      },
+    },
+    [IntentFlowStep.SignIn]: {
+      index: 2,
+      step: IntentFlowStep.SignIn,
+      service: '',
+      module: DISPATCHER,
+      payloadMap,
+      transitions: {
+        next: { transition: 'next', step: IntentFlowStep.Review },
+      },
+    },
+    [IntentFlowStep.Review]: {
+      index: 3,
+      step: IntentFlowStep.Review,
+      service: '',
+      module: HOME,
+      payloadMap,
+      transitions: {},
+    },
+  },
+}

package/src/intent/index.ts

@@ -0,0 +1,6 @@
+export * from './consts.js'
+export * from './schemas.js'
+export * from './errors.js'
+export * from './entrypoints.js'
+export * from './flow.js'
+export type * from './types.js'

package/src/intent/schemas.ts

@@ -0,0 +1,27 @@
+import type { JSONSchemaType } from 'ajv'
+import { INTENT_PROMPT_MAX, INTENT_REF_LENGTH, INTENT_REF_PATTERN } from './consts.js'
+import type { IntentPickupBody, IntentStashBody } from './types.js'
+
+/**
+ * The stash body. `consent` is a constant `true`, not a boolean: the data-processing confirmation is
+ * a precondition of the request existing, so the wire refuses its absence instead of the handler
+ * having to remember to look.
+ */
+export const IntentStashBodySchema: JSONSchemaType<IntentStashBody> = {
+  type: 'object',
+  properties: {
+    prompt: { type: 'string', minLength: 1, maxLength: INTENT_PROMPT_MAX },
+    consent: { type: 'boolean', const: true },
+  },
+  required: ['prompt', 'consent'],
+  additionalProperties: false,
+}
+
+export const IntentPickupBodySchema: JSONSchemaType<IntentPickupBody> = {
+  type: 'object',
+  properties: {
+    ref: { type: 'string', minLength: INTENT_REF_LENGTH, maxLength: INTENT_REF_LENGTH, pattern: INTENT_REF_PATTERN },
+  },
+  required: ['ref'],
+  additionalProperties: false,
+}

package/src/intent/types.ts

@@ -0,0 +1,45 @@
+import type { ResourceRecord } from '@owlmeans/resource'
+
+/** What the public site sends: the prompt and the person's confirmation of its processing. */
+export interface IntentStashBody {
+  prompt: string
+  /** Always `true` — the site's checkbox; a request without it is refused by the schema. */
+  consent: true
+}
+
+/** The reference the platform answers with, and the moment its record expires. */
+export interface IntentStashResult {
+  ref: string
+  /** Epoch milliseconds. */
+  expiresAt: number
+}
+
+export interface IntentPickupBody {
+  ref: string
+}
+
+export interface IntentPickupResult {
+  prompt: string
+}
+
+/**
+ * The prompt as it waits in the visitor's browser between pickup and the decision on the home
+ * screen. `expiresAt` is checked on read — browser storage has no TTL of its own.
+ */
+export interface IntentDraft extends ResourceRecord {
+  id: string
+  /** The reference it was picked up with; a reload of the landing reuses the draft of that ref. */
+  ref: string
+  prompt: string
+  expiresAt: number
+}
+
+/**
+ * Options of {@link makeIntentProtocols}.
+ */
+export interface IntentProtocolOptions {
+  /** Path prefix of the guest API; defaults to `/public/intent`. */
+  path?: string
+  /** Path of the landing screen; defaults to `/start`. */
+  landing?: string
+}

package/src/skills/consts.ts

@@ -85,115 +85,3 @@ export enum ViableSkill {
   LibrariesAi = 'libraries-ai',
   LibrariesGame = 'libraries-game',
 }
-
-/**
- * Sort weights. Skills render in this order inside the cached block, so the sequence is
- * part of the cache key — reordering them invalidates every prefix at once. Grouped in
- * tens to leave room for a consumer's own skills between them.
- */
-export const SKILL_ORDER: Record<ViableSkill, number> = {
-  [ViableSkill.OutputSourceOnly]: 10,
-  [ViableSkill.OutputTextOnly]: 10,
-  [ViableSkill.ScopeDiscipline]: 15,
-  [ViableSkill.MainFlowFocus]: 12,
-  [ViableSkill.NonTypescriptOutput]: 18,
-  [ViableSkill.TsStyle]: 20,
-  [ViableSkill.TsImports]: 30,
-  [ViableSkill.ReactComponents]: 40,
-  [ViableSkill.OwlMeansEntrypoints]: 41,
-  [ViableSkill.OwlMeansNav]: 42,
-  [ViableSkill.PermissionModel]: 43,
-  [ViableSkill.ShadcnUi]: 44,
-  [ViableSkill.OwlmeansState]: 50,
-  [ViableSkill.FormFeedback]: 51,
-  [ViableSkill.StoreAccess]: 52,
-  [ViableSkill.ViewModelNaming]: 55,
-  // After the frontend rules it builds on (entrypoints, nav, shadcn, form feedback, the store), and
-  // before the backend block — it is only ever carried by analysis and frontend personas.
-  [ViableSkill.LandingGate]: 56,
-  // Analysis and frontend read it the same way LandingGate is read — after the frontend rules it
-  // references (nav, shadcn) — and a backend coder reads it as a server-side check, so it sits
-  // just ahead of the backend block for either audience.
-  [ViableSkill.MarketingConsent]: 57,
-  [ViableSkill.ResourceLayer]: 60,
-  [ViableSkill.ResourceResults]: 62,
-  [ViableSkill.ResourceMigrations]: 64,
-  [ViableSkill.OwlMeansServer]: 70,
-  [ViableSkill.OwlmeansContext]: 65,
-  [ViableSkill.OwlMeansServices]: 66,
-  [ViableSkill.FixerHeuristics]: 75,
-  [ViableSkill.ProjectLayout]: 5,
-  [ViableSkill.AgentTooling]: 8,
-  [ViableSkill.QueueDiscipline]: 67,
-  [ViableSkill.WorkerJobs]: 68,
-  [ViableSkill.TargetAgents]: 69,
-  [ViableSkill.AgenticChoice]: 71,
-  [ViableSkill.TargetLlm]: 72,
-  [ViableSkill.TargetAgentTools]: 73,
-  [ViableSkill.GameDesign]: 45,
-  [ViableSkill.GameScene]: 46,
-  [ViableSkill.GameUi]: 47,
-  [ViableSkill.GameNetworking]: 48,
-  [ViableSkill.LayoutDefinition]: 80,
-  [ViableSkill.ScreenDefinition]: 82,
-  [ViableSkill.LibrariesCommon]: 90,
-  [ViableSkill.LibrariesUiState]: 90,
-  [ViableSkill.LibrariesUi]: 90,
-  [ViableSkill.LibrariesBackend]: 90,
-  [ViableSkill.LibrariesAi]: 90,
-  [ViableSkill.LibrariesGame]: 90,
-}
-
-/**
- * The catalogue entries whose subject a PUBLISHED `@owlmeans` package already documents.
- *
- * The catalogue and `agent-meta/skills/*` state the same contract twice — the P1 duplication —
- * and the duplication is not symmetric: a package skill is versioned with the package and reaches
- * a prompt through `owlmeansPackagesPlugin` whenever the request names that package, while a
- * catalogue entry is a constant here that has to be edited by hand every time the framework moves.
- *
- * Naming the overlap is what makes it a DATA decision instead of a code one. A blueprint lists
- * which of these its prompts carry, and a persona's skills are filtered against that list — so
- * dropping one is a line in a blueprint, and restoring it is the same line. Everything NOT in this
- * set is viable's own (output discipline, scope, the view-model convention, the fixer heuristics,
- * where files live) and always loads, because no published package documents it.
- *
- * The default blueprint currently lists every one of them: the reduction is a real change to what
- * a coder is told, and it is measured against a green end-to-end baseline rather than guessed.
- */
-export const FRAMEWORK_OWNED_SKILLS: ViableSkill[] = [
-  ViableSkill.ResourceLayer,
-  ViableSkill.ResourceResults,
-  ViableSkill.ResourceMigrations,
-  ViableSkill.OwlmeansContext,
-  ViableSkill.OwlMeansServices,
-  ViableSkill.OwlMeansServer,
-  ViableSkill.OwlMeansEntrypoints,
-  ViableSkill.OwlMeansNav,
-  ViableSkill.PermissionModel,
-  ViableSkill.OwlmeansState,
-  ViableSkill.StoreAccess,
-  ViableSkill.ShadcnUi,
-  ViableSkill.ReactComponents,
-  ViableSkill.FormFeedback,
-]
-
-const FRAMEWORK_OWNED = new Set<ViableSkill>(FRAMEWORK_OWNED_SKILLS)
-
-/**
- * Filter a persona's skills against what a blueprint asks for.
- *
- * A skill nobody owns always survives. A framework-owned one survives only while the blueprint
- * lists it — so a blueprint built on another persistence layer stops teaching the Postgres
- * resource contract without anybody editing a persona, and a blueprint that lists nothing at all
- * (the shape a test builds) is read as "everything", because an empty allow-list almost always
- * means "not stated" rather than "none".
- */
-export const skillsForBlueprint = (
-  skills: ViableSkill[], allowed?: ViableSkill[]
-): ViableSkill[] => {
-  if (allowed == null || allowed.length === 0) return skills
-  const permitted = new Set(allowed)
-
-  return skills.filter(skill => !FRAMEWORK_OWNED.has(skill) || permitted.has(skill))
-}

package/src/skills/index.ts

@@ -1,4 +1,3 @@
 
 export * from './consts.js'
-export * from './catalogue.js'
 export * from './roles.js'