@owlmeans/viable-common 0.0.4

package/src/moderation/consts.ts

@@ -0,0 +1,59 @@
+
+/**
+ * What the moderation gate refuses, and nothing more.
+ *
+ * The set is deliberately about the SHAPE of what is being built, never its sector: a product
+ * that handles money, credentials or medical data is ordinary, and a platform that refuses
+ * those refuses most of its own market. What is not ordinary is a product whose purpose is to
+ * collect someone else's credentials, to be mistaken for someone who did not ask to be
+ * represented, or to push messages at people who never asked for them.
+ *
+ * Every generated app has a sign-in screen of its own — that is what an application is — so a
+ * login is never evidence of anything here.
+ *
+ * The set is CLOSED. A new refusal shape belongs inside one of these four, phrased into the
+ * policy prompt: each value is a wire contract with user-facing wording in seven languages
+ * behind it, and a fifth one silently renders as the generic refusal until every one of those
+ * catches up.
+ */
+export enum ModerationCategory {
+  /** Captures credentials, OTPs, card numbers or recovery phrases for a service the requester does not run. */
+  CredentialHarvesting = 'credential-harvesting',
+  /** Presents itself as a named third party — an organization OR a real person — rather than as its own product. */
+  BrandImpersonation = 'brand-impersonation',
+  /** Collects payment details on behalf of a merchant that is not the requester. */
+  PaymentCapture = 'payment-capture',
+  /** Tooling whose purpose is abuse: credential stuffers, phishing-kit builders, bulk-spam senders. */
+  AbuseTooling = 'abuse-tooling',
+}
+
+/**
+ * What is being classified. Carried into the trace so a refusal can be attributed.
+ *
+ * Each value has a framing sentence behind it that tells the classifier whose words it is
+ * reading — the same text means different things as a customer's request, as our own generated
+ * specification, and as a file already sitting inside an approved project.
+ */
+export enum ModerationSubject {
+  Prompt = 'prompt',
+  Specification = 'specification',
+  Story = 'story',
+  /**
+   * A file a human wrote through the project's own editor.
+   *
+   * Deliberately separate from the three above: this is code inside an already-approved
+   * product, so the framing has to stop the classifier from refusing ordinary application
+   * source that happens to contain the word "password" or a payment form.
+   */
+  Source = 'source',
+  /**
+   * What a project is CALLED — and, through its slug, what it is reachable at.
+   *
+   * The only subject that judges an identifier rather than a product, and the only one whose
+   * answer may disagree with {@link ModerationSubject.Specification} about the same brand. A
+   * consumer turns a project's name into a hostname on a domain all of its customers share, so
+   * "a dashboard for our Shopify store" is an ordinary thing to build while `shopify-dashboard`
+   * is not a name it may be reachable at. Descriptions may name a brand; identifiers may not.
+   */
+  Name = 'name',
+}

package/src/moderation/index.ts

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

package/src/moderation/schemas.ts

@@ -0,0 +1,28 @@
+import type { JSONSchemaType } from 'ajv'
+import type { ModerationVerdict } from './types.js'
+
+/**
+ * What the classifier must answer with.
+ *
+ * Kept minimal on purpose: a schema the model must satisfy is also a schema it will try to
+ * fill, and every extra field is another thing it can hallucinate a reason into. The decision
+ * is one boolean; the category exists so the browser can phrase the refusal; the evidence
+ * exists so a human reviewing the trace can see what the model actually reacted to.
+ *
+ * `category` is a free string here even though only `ModerationCategory` values mean anything,
+ * and that is deliberate. Constrained to the enum it made **every** call fail: with nothing to
+ * categorise, a model that allows still fills the field — `"none"`, `""`, `"n/a"` — the
+ * response fails validation, the retry budget runs out, and the gate fails open on every
+ * request while looking like it is working. The value is narrowed in code instead
+ * (`normalizeCategory`), where an unrecognized one is simply absent.
+ */
+export const ModerationVerdictSchema: JSONSchemaType<ModerationVerdict> = {
+  type: 'object',
+  properties: {
+    allowed: { type: 'boolean' },
+    category: { type: 'string', maxLength: 64, nullable: true },
+    evidence: { type: 'string', maxLength: 500, nullable: true },
+  },
+  required: ['allowed'],
+  additionalProperties: false,
+} as unknown as JSONSchemaType<ModerationVerdict>

package/src/moderation/types.ts

@@ -0,0 +1,68 @@
+import type { ModerationCategory, ModerationSubject } from './consts.js'
+
+/**
+ * What the moderation classifier returns.
+ *
+ * `evidence` is diagnostic only — it reaches the trace and the logs, never the user. What the
+ * user is told derives from `category` in the browser, so a refusal reads the same in all
+ * seven languages and the model never gets to write UI copy.
+ */
+export interface ModerationVerdict {
+  allowed: boolean
+  /**
+   * Free string on the wire, narrowed to {@link ModerationCategory} by `normalizeCategory`.
+   * A model that is allowing has nothing to categorise and will still put something here.
+   */
+  category?: string
+  evidence?: string
+}
+
+/**
+ * The three outcomes, separated from the IO so the policy can be read and tested on its own.
+ *
+ * `shadow` means the verdict was negative and is being recorded but not acted on.
+ */
+export type ModerationAction = 'allow' | 'refuse' | 'shadow'
+
+/**
+ * The two operational levers on the gate.
+ *
+ * Both exist because a blocking classifier will eventually be wrong about a real customer, and
+ * at that moment the fix has to be faster than a deploy. `enforce: false` keeps the verdicts
+ * flowing into the traces while refusing nothing, which is also how a change to the policy
+ * prompt should be evaluated before it is trusted.
+ */
+export interface ModerationPolicy {
+  /** Defaults to ON. Set false to compute and trace verdicts without acting on them. */
+  enforce?: boolean
+  /** Entity ids released from the gate entirely. */
+  bypassEntities?: string[]
+}
+
+/** What a caller needs in order to refuse: never the model's own words. */
+export interface ModerationOutcome {
+  action: ModerationAction
+  /**
+   * Always present when `action` is not `allow`.
+   *
+   * A refusal has to tell the user something specific, so an unrecognized category from the
+   * model is replaced rather than dropped — see `normalizeCategory`.
+   */
+  category?: ModerationCategory
+  /** Diagnostic only. Logged and traced, never rendered. */
+  evidence?: string
+}
+
+/** One classification request. */
+export interface ModerationInput {
+  subject: ModerationSubject
+  /** One text, or several judged together — several is one call, not several. */
+  text: string | string[]
+  /** Whose request this is — the one thing a bypass can be keyed on. */
+  entityId?: string
+  /**
+   * Extra framing appended to the subject's own, for a subject whose meaning depends on where
+   * the text came from — a file's path, for instance.
+   */
+  context?: string
+}

package/src/moderation/utils.ts

@@ -0,0 +1,35 @@
+import { ModerationCategory } from './consts.js'
+import type { ModerationAction, ModerationPolicy, ModerationVerdict } from './types.js'
+
+/**
+ * Narrow whatever the model put in `category` to a real one, or to nothing.
+ *
+ * The wire field is a free string on purpose — see {@link ModerationVerdictSchema}. A model
+ * that is allowing has nothing to categorise and still fills the field, so anything
+ * unrecognized is treated as absent rather than as a failure.
+ */
+export const normalizeCategory = (category?: string): ModerationCategory | undefined => {
+  const values = Object.values(ModerationCategory) as string[]
+
+  return category != null && values.includes(category)
+    ? category as ModerationCategory
+    : undefined
+}
+
+/**
+ * What to do about a verdict.
+ *
+ * Pure, because this is the part with the operational levers on it and the part most likely
+ * to be wrong in a hurry: `enforce` turns the whole gate into an observer without a deploy,
+ * and `bypassEntities` releases one entity when a real customer is wrongly refused.
+ */
+export const decideModeration = (
+  verdict: ModerationVerdict, policy: ModerationPolicy & { entityId?: string } = {}
+): ModerationAction => {
+  if (verdict.allowed) return 'allow'
+  if (policy.entityId != null && policy.bypassEntities?.includes(policy.entityId) === true) return 'allow'
+
+  // Defaults to ON: a gate that has to be switched on is a gate that is off in every
+  // environment nobody remembered to configure.
+  return policy.enforce !== false ? 'refuse' : 'shadow'
+}

package/src/preview/consts.ts

@@ -0,0 +1,9 @@
+/**
+ * Enum for OwlMeans preview integration event types
+ */
+export enum PreviewEventType {
+  Error = 'OWLMEANS_PREVIEW_ERROR',
+  CaughtError = 'OWLMEANS_PREVIEW_CONSOLE_ERROR',
+  PromiseRejection = 'OWLMEANS_PREVIEW_PROMISE_REJECTION',
+  FetchError = 'OWLMEANS_PREVIEW_FETCH_ERROR',
+}

package/src/preview/index.ts

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

package/src/preview/types.ts

@@ -0,0 +1,79 @@
+import type { PreviewEventType } from './consts.js'
+
+/**
+ * Base interface for all OwlMeans preview messages
+ */
+export interface OwlMeansPreviewMessage<T extends OwlMenasPreviewPayloads = OwlMenasPreviewPayloads> {
+  type: PreviewEventType
+  payload: T
+}
+
+export interface OwlMeansCaughtErrorPayload {
+  message: string
+  stack?: string
+}
+
+/**
+ * Payload for global error events
+ */
+export interface OwlMeansErrorPayload {
+  message: string
+  source: string
+  line: number
+  col: number
+  stack?: string
+}
+
+/**
+ * Payload for unhandled promise rejection events
+ */
+export interface OwlMeansPromiseRejectionPayload {
+  reason: unknown
+  stack?: string
+}
+
+/**
+ * Payload for fetch error events
+ */
+export interface OwlMeansFetchErrorPayload {
+  url: string | URL | Request
+  options?: RequestInit
+  status: number
+  statusText: string
+  body: string
+}
+
+/**
+ * Specific message types for each event kind
+ */
+export interface OwlMeansErrorMessage extends OwlMeansPreviewMessage<OwlMeansErrorPayload> {
+  type: PreviewEventType.Error
+}
+
+export interface OwlMeansPromiseRejectionMessage extends OwlMeansPreviewMessage<OwlMeansPromiseRejectionPayload> {
+  type: PreviewEventType.PromiseRejection
+}
+
+export interface OwlMeansFetchErrorMessage extends OwlMeansPreviewMessage<OwlMeansFetchErrorPayload> {
+  type: PreviewEventType.FetchError
+}
+
+export interface OwlMeansCaughtErrorMessage extends OwlMeansPreviewMessage<OwlMeansCaughtErrorPayload> {
+  type: PreviewEventType.CaughtError
+}
+
+/**
+ * Union type for all possible OwlMeans preview messages
+ */
+export type OwlMeansPreviewMessages = 
+  | OwlMeansErrorMessage 
+  | OwlMeansPromiseRejectionMessage 
+  | OwlMeansFetchErrorMessage
+  | OwlMeansCaughtErrorMessage
+
+export type OwlMenasPreviewPayloads = 
+  | OwlMeansErrorPayload
+  | OwlMeansPromiseRejectionPayload
+  | OwlMeansFetchErrorPayload
+  | OwlMeansCaughtErrorPayload
+

package/src/scaffold/consts.ts

@@ -0,0 +1,26 @@
+/**
+ * The shapes a drawn widget can take.
+ *
+ * A CLOSED set, and deliberately small: each value maps to one pre-built sketch primitive in the
+ * target's template, so a value nothing can draw is a value that produces a blank card. A story
+ * whose shape is none of these is a list — the commonest thing a screen is, and the safest
+ * placeholder for anything unrecognised.
+ */
+export enum WidgetKind {
+  /** A queue, an index, a feed — records one after another. */
+  List = 'list',
+  /** Records in columns, the shape a back office mostly takes. */
+  Table = 'table',
+  /** The actor SUBMITS something. */
+  Form = 'form',
+  /** A trend or a comparison over time. */
+  Chart = 'chart',
+  /** Headline figures — a summary, a tracker, a status board. */
+  Stat = 'stat',
+}
+
+/** How many of an area's widgets may be adapted onto its home screen. */
+export const AREA_HOME_WIDGET_CAP = 3
+
+/** Sections per area beyond which a top menu stops being navigable. */
+export const AREA_SECTION_CAP = 6

package/src/scaffold/helpers.ts

@@ -0,0 +1,84 @@
+import type { ScaffoldPlan, ScaffoldStoryPlan } from './types.js'
+
+/**
+ * ONE reading of who owns a drawn artifact, so no consumer has to interpret the plan itself.
+ *
+ * The plan carries `sharesWidgetWith` / `sharesScreenWith` as untrusted hints — a model may drop
+ * them, invent a code, point forwards, or build a cycle. These resolve all of that away, and
+ * every one is TOTAL: a code the plan does not hold answers itself, which is the unshared
+ * behaviour and therefore exactly today's drawn tree.
+ *
+ * Pure and IO-free. `fillScaffoldPlan` normalises a plan through them before anything is stamped,
+ * so the stampers and the scaffold loop can read a plan that is already sane.
+ */
+
+/** Which field the arrow is being followed along. */
+export type ShareKind = 'widget' | 'screen'
+
+const pointerOf = (story: ScaffoldStoryPlan, kind: ShareKind): string | undefined =>
+  kind === 'widget' ? story.sharesWidgetWith : story.sharesScreenWith
+
+/**
+ * The code whose artifact this story renders — itself when it owns one.
+ *
+ * Backward-only and bounded: an arrow is followed only to a story EARLIER in plan order, which
+ * makes a cycle unrepresentable rather than merely unlikely, and makes the owner the earliest
+ * member of its group. That is what keeps `widgetDefinition(owner)` stable — the name is a
+ * function of one code, never of the group, so adding a member renames nothing.
+ */
+export const shareOwner = (
+  plan: Pick<ScaffoldPlan, 'stories'>, code: string, kind: ShareKind = 'widget'
+): string => {
+  const order = new Map(plan.stories.map((story, index) => [story.code, index]))
+  const byCode = new Map(plan.stories.map(story => [story.code, story]))
+
+  let current = code
+  // Bounded by the list length: every hop strictly decreases the plan index, so it terminates.
+  for (let hop = 0; hop <= plan.stories.length; hop++) {
+    const story = byCode.get(current)
+    const target = story != null ? pointerOf(story, kind) : undefined
+    if (story == null || target == null || target === '' || target === current) {
+      return current
+    }
+    const here = order.get(current)
+    const there = order.get(target)
+    // Unknown, forward or self-referential — none of them is a group, so the story owns its own.
+    if (here == null || there == null || there >= here) {
+      return current
+    }
+    current = target
+  }
+
+  return current
+}
+
+/**
+ * Owner code → every member, owner first, in plan order.
+ *
+ * The shape the stampers need: one artifact per entry, and the full member list for the notice
+ * that names them.
+ */
+export const shareGroups = (
+  plan: Pick<ScaffoldPlan, 'stories'>, kind: ShareKind = 'widget'
+): Map<string, string[]> => {
+  const groups = new Map<string, string[]>()
+  for (const story of plan.stories) {
+    const owner = shareOwner(plan, story.code, kind)
+    const members = groups.get(owner) ?? []
+    if (!members.includes(owner)) members.push(owner)
+    if (!members.includes(story.code)) members.push(story.code)
+    groups.set(owner, members)
+  }
+
+  return groups
+}
+
+/** Every story that renders this owner's artifact, owner first. Total: an owner alone answers `[code]`. */
+export const shareMembers = (
+  plan: Pick<ScaffoldPlan, 'stories'>, owner: string, kind: ShareKind = 'widget'
+): string[] => shareGroups(plan, kind).get(owner) ?? [owner]
+
+/** Whether this story draws the artifact, as opposed to rendering somebody else's. */
+export const ownsShare = (
+  plan: Pick<ScaffoldPlan, 'stories'>, code: string, kind: ShareKind = 'widget'
+): boolean => shareOwner(plan, code, kind) === code

package/src/scaffold/index.ts

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