@owlmeans/viable-common 0.0.44 → 0.0.45

package/src/scaffold/types.ts

@@ -198,6 +198,90 @@ export interface LandingGateAnswer {
   note: string
 }
 
+/**
+ * A band of the landing page that the header menu can jump to — the `id` its section carries.
+ * A CLOSED set: each value is one stamped band, so a value nothing draws is a menu entry that
+ * scrolls nowhere. `LANDING_ANCHOR_BAND` maps each to its band.
+ */
+export type LandingAnchor = 'how' | 'features' | 'use-cases' | 'why' | 'approach' | 'community' | 'about'
+
+/**
+ * The bands a landing page can carry, named in the house order `LANDING_BAND_ORDER` declares.
+ * `problem` is the problem-and-solution band. Which of them a page draws is `landingBandsOf`.
+ */
+export type LandingBand =
+  | 'hero' | 'steps' | 'features' | 'use-cases' | 'problem' | 'differentiator' | 'approach'
+  | 'testimonials' | 'about' | 'closing'
+
+/**
+ * A button or link of the landing page that can open a user story — the place a {@link HomeLink}
+ * attaches to. Which of them a given page actually draws is `homeSlotsOf`.
+ */
+export type LandingSlot =
+  | 'hero.cta' | 'hero.secondary' | 'hero.browse'
+  | 'closing.primary' | 'closing.secondary' | 'closing.link.1' | 'closing.link.2'
+  | 'useCase.1' | 'useCase.2' | 'useCase.3' | 'useCase.4'
+
+/** One entry of the guest header menu: a band to jump to and the word it is shown as. */
+export interface LandingMenuEntry {
+  anchor: LandingAnchor
+  /** 1-2 words in the product's language. */
+  label: string
+}
+
+/** A home button that opens a user story instead of its default action. */
+export interface HomeLink {
+  slot: LandingSlot
+  /** The story's CODE. */
+  story: string
+}
+
+/** One use case of the landing page: who, doing what. */
+export interface LandingUseCase {
+  /** Who this case is for, in a few words. */
+  audience: string
+  title: string
+  text: string
+}
+
+/**
+ * The bands added with the gated landing page carry a `basis`: a passage copied word for word from
+ * the person's own words, the specification or the vision. It is checked downstream, and a band
+ * whose basis is not found there is removed — the band exists only when its claim has a source.
+ */
+export interface LandingUseCases {
+  /** Two to four cases. */
+  cases: LandingUseCase[]
+  basis: string
+}
+
+/** "Why us": what this product does differently, as a short usual-vs-ours contrast. */
+export interface LandingDifferentiator {
+  title: string
+  text: string
+  /** Two to three rows, at most six words on each side. */
+  contrast: { usual: string, ours: string }[]
+  /** The heading over the `usual` column; absent falls back to the stamper's own. */
+  usualLabel?: string | null
+  /** The heading over the `ours` column; absent falls back to the stamper's own. */
+  oursLabel?: string | null
+  basis: string
+}
+
+/** "How we work": the principles the product is run by, three to four. */
+export interface LandingApproach {
+  title?: string | null
+  principles: { title: string, text: string }[]
+  basis: string
+}
+
+/** The about band: who is behind the product. */
+export interface LandingAbout {
+  title: string
+  text: string
+  basis: string
+}
+
 /** The guest area's landing page — the product's public face. */
 export interface GuestHomePlan {
   hero: {
@@ -219,9 +303,21 @@ export interface GuestHomePlan {
   solution: { title: string, text: string }
   /** The bento tiles — four, each optionally anchored by a fragment of the product's interface. */
   features: { title: string, text: string, fragment?: BentoFragment }[]
-  testimonials: { quote: string, name: string, role: string }[]
+  /**
+   * None or exactly two. Optional since the gated landing page: a plan stored before carries it,
+   * and a product whose end users do not choose it for themselves leaves it out.
+   */
+  testimonials?: { quote: string, name: string, role: string }[] | null
   /** "How it works" — three steps taken from the main flow. */
   steps?: { title: string, text: string }[]
+  /** Who it is for, case by case. */
+  useCases?: LandingUseCases | null
+  /** "Why us". */
+  differentiator?: LandingDifferentiator | null
+  /** "How we work". */
+  approach?: LandingApproach | null
+  /** Who is behind the product. */
+  about?: LandingAbout | null
   /** The small section labels and section headings; absent ones fall back to the stamper's own. */
   labels?: {
     steps?: string
@@ -232,7 +328,30 @@ export interface GuestHomePlan {
     testimonialsTitle?: string
     problem?: string
     solution?: string
+    useCases?: string | null
+    useCasesTitle?: string | null
+    differentiator?: string | null
+    approach?: string | null
+    approachTitle?: string | null
+    about?: string | null
   }
+  /**
+   * The guest header menu — two to four bands to jump to. Entries whose band the page does not
+   * draw are dropped; `landingMenuOf` is the one reading of it.
+   */
+  menu?: LandingMenuEntry[] | null
+  /**
+   * Which home buttons open which user story. Absent or `null` means NOT DECIDED yet; `[]` means
+   * decided: none. A slot the page does not draw (`homeSlotsOf`) is ignored.
+   */
+  links?: HomeLink[] | null
+  /**
+   * The story codes whose links were decided at DEVELOPMENT time, one per story asked — a decision
+   * of "no control" included. Absent (or `null`) on a plan whose links the planner decided: then
+   * {@link GuestHomePlan.links} speaks for every story of the plan. Written by code, never asked of
+   * the model.
+   */
+  linksDecided?: string[] | null
   /** The closing band: a headline, a lead, the two pills and two link cards. */
   closing?: {
     headline: string

package/src/skills/consts.ts

@@ -85,3 +85,49 @@ export enum ViableSkill {
   LibrariesAi = 'libraries-ai',
   LibrariesGame = 'libraries-game',
 }
+
+/**
+ * Who the model is being asked to be.
+ *
+ * A persona is per HELPER, not per model role: `ModelRole` selects which model answers,
+ * this selects what it is told it does. Two helpers can share a model and need different
+ * personas, and the same persona can run on a cheap or an expensive model depending on
+ * the effort tier — keeping the two axes separate is what makes that possible.
+ */
+export enum ViablePersona {
+  BusinessAnalyst = 'business-analyst',
+  ProductNaming = 'product-naming',
+  /** Decides what KIND of product a prompt describes — which blueprint case builds it. */
+  ProductArchitect = 'product-architect',
+  UxDesigner = 'ux-designer',
+  VisualDesigner = 'visual-designer',
+
+  LayoutArchitect = 'layout-architect',
+  ComponentArchitect = 'component-architect',
+  StateArchitect = 'state-architect',
+  NavigationArchitect = 'navigation-architect',
+  DomainTypesArchitect = 'domain-types-architect',
+  AccessArchitect = 'access-architect',
+  ApiArchitect = 'api-architect',
+  DatalayerArchitect = 'datalayer-architect',
+  BackendDomainArchitect = 'backend-domain-architect',
+
+  CommonCoder = 'common-coder',
+  UiStateCoder = 'ui-state-coder',
+  UiViewCoder = 'ui-view-coder',
+  UiNavCoder = 'ui-nav-coder',
+  DatalayerCoder = 'datalayer-coder',
+  ApiCoder = 'api-coder',
+  BackendModelCoder = 'backend-model-coder',
+  /** Decides whether a story needs a queue, a worker or an agent — and usually decides it does not. */
+  RuntimeArchitect = 'runtime-architect',
+  /** Writes queue declarations, job processors and the application's own agents. */
+  WorkerCoder = 'worker-coder',
+  FreeFlightCoder = 'free-flight-coder',
+
+  Fixer = 'fixer',
+  Orchestrator = 'orchestrator',
+  SourceExtractor = 'source-extractor',
+  DeclarationLookup = 'declaration-lookup',
+  FixAgent = 'fix-agent',
+}

package/src/skills/index.ts

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

package/src/slot/command/types.ts

@@ -0,0 +1,21 @@
+import type { SlotCommandType } from '../consts.js'
+
+/** The time bounds of one slot command: the caller's timeout and the executor's deadline. */
+export interface SlotCommandHelper {
+  /**
+   * Resolve the caller-side bound for one command.
+   *
+   * One function rather than three lookups at each call site: an asker that forgets the per-command
+   * table inherits twenty minutes for a fifteen-second command, which is the failure this table was
+   * added to stop.
+   */
+  commandTimeout: (type: SlotCommandType, command: string, override?: number) => number
+  /**
+   * Resolve the executor-side deadline for one command.
+   *
+   * Per-command first, per-type second. It was per-type only, which is how a clone inherited the
+   * bound of a `git status` — the same shape as the shell table above, and added for the same
+   * reason.
+   */
+  commandDeadline: (type: SlotCommandType, command: string) => number
+}

package/src/slot/command.ts

@@ -0,0 +1,38 @@
+import { COMMAND_DEADLINES, COMMAND_TIMEOUTS, DEFAULT_COMMAND_DEADLINE, DEFAULT_COMMAND_TIMEOUT, DEFAULT_FILE_COMMAND_DEADLINE, DEFAULT_GIT_COMMAND_DEADLINE, FILE_COMMAND_DEADLINES, FILE_COMMAND_TIMEOUTS, GIT_COMMAND_DEADLINES, GIT_COMMAND_TIMEOUTS, SHELL_COMMAND_TIMEOUTS, SlotCommandType, SlotFileCommand, SlotGitCommand } from './consts.js'
+import type { SlotCommandHelper } from './command/types.js'
+
+export const createSlotCommandHelper = (): SlotCommandHelper => {
+  /** The per-command caller bound for one command, or nothing where its type's default is right. */
+  const perCommandTimeout = (type: SlotCommandType, command: string): number | undefined => {
+    switch (type) {
+      case SlotCommandType.Shell: return SHELL_COMMAND_TIMEOUTS[command]
+      case SlotCommandType.Git: return GIT_COMMAND_TIMEOUTS[command as SlotGitCommand]
+      case SlotCommandType.Database: return COMMAND_TIMEOUTS[SlotCommandType.Database]
+      default: return FILE_COMMAND_TIMEOUTS[command as SlotFileCommand]
+    }
+  }
+
+  const commandTimeout = (
+    type: SlotCommandType, command: string, override?: number
+  ): number => override
+    ?? perCommandTimeout(type, command)
+    ?? COMMAND_TIMEOUTS[type]
+    ?? DEFAULT_COMMAND_TIMEOUT
+
+  const commandDeadline = (type: SlotCommandType, command: string): number => {
+    switch (type) {
+      case SlotCommandType.Shell:
+        return COMMAND_DEADLINES[command] ?? DEFAULT_COMMAND_DEADLINE
+      case SlotCommandType.Git:
+        return GIT_COMMAND_DEADLINES[command as SlotGitCommand] ?? DEFAULT_GIT_COMMAND_DEADLINE
+      case SlotCommandType.Database:
+        return 30_000
+      default:
+        return FILE_COMMAND_DEADLINES[command as SlotFileCommand] ?? DEFAULT_FILE_COMMAND_DEADLINE
+    }
+  }
+
+  return { commandTimeout, commandDeadline }
+}
+
+export const slotCommandHelper = createSlotCommandHelper()

package/src/slot/helpers.ts

@@ -1,29 +1,9 @@
-import { WorkloadKind } from './consts.js'
+import { slotOriginHelper } from './origin.js'
 import type { AddressableSlot } from './types.js'
 
-/**
- * The origin a slot's application answers at.
- *
- * Read back from the slot's stored `host`, never recomposed from a slug — a preview host is a
- * CLAIMED resource with a certificate behind it, and the name a slot ended up with is not always
- * the name its project would compose today. What this adds is the scheme, which is the one part
- * that follows from the kind rather than from the record: a local target is a loopback address and
- * therefore `http`, everything else is TLS-terminated at an edge and therefore `https`.
- */
-export const slotOrigin = (slot: AddressableSlot): string => {
-  const host = slot.host ?? ''
-  if (host === '') return ''
-  if (host.startsWith('http://') || host.startsWith('https://')) return host
+/** @deprecated compat:factory-refactor — use `slotOriginHelper.slotOrigin(…)` */
+export const slotOrigin = (slot: AddressableSlot): string => slotOriginHelper.slotOrigin(slot)
 
-  return `${slot.kind === WorkloadKind.Local ? 'http' : 'https'}://${host}`
-}
-
-/**
- * The exact redirect URIs a target's OIDC client must carry for one origin.
- *
- * Exact, because a provider matches a redirect URI literally and refuses a wildcard — and both
- * entries are needed: the callback the login round trip returns to, and the bare origin, which is
- * where the application's own logout lands.
- */
+/** @deprecated compat:factory-refactor — use `slotOriginHelper.targetRedirectUrisForOrigin(…)` */
 export const targetRedirectUrisForOrigin = (origin: string, callbackPath: string): string[] =>
-  origin === '' ? [] : [origin, `${origin}${callbackPath}`]
+  slotOriginHelper.targetRedirectUrisForOrigin(origin, callbackPath)

package/src/slot/index.ts

@@ -1,6 +1,11 @@
 export * from './consts.js'
+export * from './command.js'
 export * from './utils.js'
 export * from './schemas.js'
 export * from './layout.js'
+export * from './origin.js'
 export * from './helpers.js'
 export type * from './types.js'
+export type * from './command/types.js'
+export type * from './layout/types.js'
+export type * from './origin/types.js'

package/src/slot/layout/types.ts

@@ -0,0 +1,17 @@
+import type { TargetLayout } from '../../integrity/consts.js'
+import type { SubProject } from '../consts.js'
+import type { TargetPaths } from '../types.js'
+
+/** Where a target's roles live, per layout — read off {@link LAYOUTS} and {@link ROLE_DIRS}. */
+export interface SlotLayoutHelper {
+  /**
+   * Resolve a wire-level role to the directory it names in a given layout.
+   *
+   * An unknown value — a role from a sender newer than this reader — falls back to the role's own
+   * name, which is the honest guess for a layout whose packages are named after their roles, and
+   * which fails visibly rather than resolving to some other package's directory.
+   */
+  subprojectDirOf: (layout: TargetLayout, role: SubProject) => string
+  /** Where every role lives, for a layout already decided. */
+  pathsOf: (layout: TargetLayout) => TargetPaths
+}

package/src/slot/layout.ts

@@ -1,7 +1,8 @@
 import { TargetLayout } from '../integrity/index.js'
-import { packageForRole, resolveTopology, topologyOf } from '../topology/index.js'
+import { topologyHelper } from '../topology/resolve.js'
 import { SubProject } from './consts.js'
 import type { TargetPaths } from './types.js'
+import type { SlotLayoutHelper } from './layout/types.js'
 
 /**
  * Where every role lives, per layout — DERIVED from that layout's topology.
@@ -15,8 +16,8 @@ import type { TargetPaths } from './types.js'
  * The VALUES are unchanged, and `topology.spec.ts` pins them against the tables they replaced.
  */
 const pathsOfTopology = (layout: TargetLayout): TargetPaths => {
-  const topology = resolveTopology(topologyOf(layout))
-  const dirOf = (role: SubProject): string | undefined => packageForRole(topology, role)?.name
+  const topology = topologyHelper.resolveTopology(topologyHelper.topologyOf(layout))
+  const dirOf = (role: SubProject): string | undefined => topologyHelper.packageForRole(topology, role)?.name
 
   return {
     layout,
@@ -52,10 +53,10 @@ export const LAYOUTS: Record<TargetLayout, TargetPaths> = {
  * so an unmapped role falls back to its own name here, which is that same visible failure.
  */
 const roleDirsOfTopology = (layout: TargetLayout): Record<SubProject, string> => {
-  const topology = resolveTopology(topologyOf(layout))
+  const topology = topologyHelper.resolveTopology(topologyHelper.topologyOf(layout))
 
   return Object.values(SubProject).reduce<Record<SubProject, string>>((dirs, role) => {
-    dirs[role] = packageForRole(topology, role)?.name ?? role
+    dirs[role] = topologyHelper.packageForRole(topology, role)?.name ?? role
 
     return dirs
   }, {} as Record<SubProject, string>)
@@ -66,15 +67,17 @@ export const ROLE_DIRS: Record<TargetLayout, Record<SubProject, string>> = {
   [TargetLayout.V2]: roleDirsOfTopology(TargetLayout.V2),
 }
 
-/**
- * Resolve a wire-level role to the directory it names in a given layout.
- *
- * An unknown value — a role from a sender newer than this reader — falls back to the role's own
- * name, which is the honest guess for a layout whose packages are named after their roles, and
- * which fails visibly rather than resolving to some other package's directory.
- */
-export const subprojectDirOf = (layout: TargetLayout, role: SubProject): string =>
-  ROLE_DIRS[layout][role] ?? role
+export const createSlotLayoutHelper = (): SlotLayoutHelper => {
+  const subprojectDirOf = (layout: TargetLayout, role: SubProject): string =>
+    ROLE_DIRS[layout][role] ?? role
+
+  const pathsOf = (layout: TargetLayout): TargetPaths => LAYOUTS[layout]
 
-/** Where every role lives, for a layout already decided. */
-export const pathsOf = (layout: TargetLayout): TargetPaths => LAYOUTS[layout]
+  return { subprojectDirOf, pathsOf }
+}
+
+export const slotLayoutHelper = createSlotLayoutHelper()
+
+/** @deprecated compat:factory-refactor — use `slotLayoutHelper.subprojectDirOf(…)` */
+export const subprojectDirOf = (layout: TargetLayout, role: SubProject): string =>
+  slotLayoutHelper.subprojectDirOf(layout, role)

package/src/slot/origin/types.ts

@@ -0,0 +1,23 @@
+import type { AddressableSlot } from '../types.js'
+
+/** Where a slot's application answers, and the redirect URIs its OIDC client needs there. */
+export interface SlotOriginHelper {
+  /**
+   * The origin a slot's application answers at.
+   *
+   * Read back from the slot's stored `host`, never recomposed from a slug — a preview host is a
+   * CLAIMED resource with a certificate behind it, and the name a slot ended up with is not always
+   * the name its project would compose today. What this adds is the scheme, which is the one part
+   * that follows from the kind rather than from the record: a local target is a loopback address and
+   * therefore `http`, everything else is TLS-terminated at an edge and therefore `https`.
+   */
+  slotOrigin: (slot: AddressableSlot) => string
+  /**
+   * The exact redirect URIs a target's OIDC client must carry for one origin.
+   *
+   * Exact, because a provider matches a redirect URI literally and refuses a wildcard — and both
+   * entries are needed: the callback the login round trip returns to, and the bare origin, which is
+   * where the application's own logout lands.
+   */
+  targetRedirectUrisForOrigin: (origin: string, callbackPath: string) => string[]
+}

package/src/slot/origin.ts

@@ -0,0 +1,20 @@
+import { WorkloadKind } from './consts.js'
+import type { AddressableSlot } from './types.js'
+import type { SlotOriginHelper } from './origin/types.js'
+
+export const createSlotOriginHelper = (): SlotOriginHelper => {
+  const slotOrigin = (slot: AddressableSlot): string => {
+    const host = slot.host ?? ''
+    if (host === '') return ''
+    if (host.startsWith('http://') || host.startsWith('https://')) return host
+
+    return `${slot.kind === WorkloadKind.Local ? 'http' : 'https'}://${host}`
+  }
+
+  const targetRedirectUrisForOrigin = (origin: string, callbackPath: string): string[] =>
+    origin === '' ? [] : [origin, `${origin}${callbackPath}`]
+
+  return { slotOrigin, targetRedirectUrisForOrigin }
+}
+
+export const slotOriginHelper = createSlotOriginHelper()

package/src/slot/types.ts

@@ -22,6 +22,7 @@ export interface SlotDatabaseQueryArgs {
   timeoutMs?: number
 }
 
+// Kept as a type: a union of the success and the failure shape.
 export type SlotDatabaseQueryResult = {
   ok: true
   columns: Array<{ name: string; dataType: string }>

package/src/slot/utils.ts

@@ -1,45 +1,10 @@
-import { COMMAND_DEADLINES, COMMAND_TIMEOUTS, DEFAULT_COMMAND_DEADLINE, DEFAULT_COMMAND_TIMEOUT, DEFAULT_FILE_COMMAND_DEADLINE, DEFAULT_GIT_COMMAND_DEADLINE, FILE_COMMAND_DEADLINES, FILE_COMMAND_TIMEOUTS, GIT_COMMAND_DEADLINES, GIT_COMMAND_TIMEOUTS, SHELL_COMMAND_TIMEOUTS, SlotCommandType, SlotFileCommand, SlotGitCommand } from './consts.js'
+import { slotCommandHelper } from './command.js'
+import type { SlotCommandType } from './consts.js'
 
-/** The per-command caller bound for one command, or nothing where its type's default is right. */
-const perCommandTimeout = (type: SlotCommandType, command: string): number | undefined => {
-  switch (type) {
-    case SlotCommandType.Shell: return SHELL_COMMAND_TIMEOUTS[command]
-    case SlotCommandType.Git: return GIT_COMMAND_TIMEOUTS[command as SlotGitCommand]
-    case SlotCommandType.Database: return COMMAND_TIMEOUTS[SlotCommandType.Database]
-    default: return FILE_COMMAND_TIMEOUTS[command as SlotFileCommand]
-  }
-}
+/** @deprecated compat:factory-refactor — use `slotCommandHelper.commandTimeout(…)` */
+export const commandTimeout = (type: SlotCommandType, command: string, override?: number): number =>
+  slotCommandHelper.commandTimeout(type, command, override)
 
-/**
- * Resolve the caller-side bound for one command.
- *
- * One function rather than three lookups at each call site: an asker that forgets the per-command
- * table inherits twenty minutes for a fifteen-second command, which is the failure this table was
- * added to stop.
- */
-export const commandTimeout = (
-  type: SlotCommandType, command: string, override?: number
-): number => override
-  ?? perCommandTimeout(type, command)
-  ?? COMMAND_TIMEOUTS[type]
-  ?? DEFAULT_COMMAND_TIMEOUT
-
-/**
- * Resolve the executor-side deadline for one command.
- *
- * Per-command first, per-type second. It was per-type only, which is how a clone inherited the
- * bound of a `git status` — the same shape as the shell table above, and added for the same
- * reason.
- */
-export const commandDeadline = (type: SlotCommandType, command: string): number => {
-  switch (type) {
-    case SlotCommandType.Shell:
-      return COMMAND_DEADLINES[command] ?? DEFAULT_COMMAND_DEADLINE
-    case SlotCommandType.Git:
-      return GIT_COMMAND_DEADLINES[command as SlotGitCommand] ?? DEFAULT_GIT_COMMAND_DEADLINE
-    case SlotCommandType.Database:
-      return 30_000
-    default:
-      return FILE_COMMAND_DEADLINES[command as SlotFileCommand] ?? DEFAULT_FILE_COMMAND_DEADLINE
-  }
-}
+/** @deprecated compat:factory-refactor — use `slotCommandHelper.commandDeadline(…)` */
+export const commandDeadline = (type: SlotCommandType, command: string): number =>
+  slotCommandHelper.commandDeadline(type, command)

package/src/topology/card/types.ts

@@ -0,0 +1,21 @@
+import type { TopologyDescriptor, TopologyMeta } from '../types.js'
+
+/** The topology file `.agents/memory/topology.md`: its frontmatter, read and written, and its body. */
+export interface TopologyCardHelper {
+  /**
+   * Narrow a parsed frontmatter block into a topology, or answer `null`.
+   *
+   * `null` means "use the layout default", and every caller treats it that way. A topology file
+   * written by a platform version this one cannot read must not stop a project from building — the
+   * arrangement it describes is almost certainly still the default one.
+   */
+  parseTopologyMeta: (data: unknown) => TopologyDescriptor | null
+  topologyMeta: (topology: TopologyDescriptor) => TopologyMeta
+  /**
+   * The body of `.agents/memory/topology.md` — what a model reads, and what a person reads.
+   *
+   * Rendered from the descriptor rather than maintained beside it, for the same reason the layout
+   * tables are: a card that disagrees with the frontmatter teaches the wrong tree.
+   */
+  renderTopologyCard: (topology: TopologyDescriptor) => string
+}