@owlmeans/viable-common 0.0.43 → 0.0.45

package/src/design/story.ts

@@ -0,0 +1,221 @@
+import { SpecCategory } from '../ba/consts.js'
+import type { Entity, StoryComponent, StoryScreen, UserStory } from '../ba/types.js'
+import { DesignStaleness, STORY_DESIGN_VERSION } from './consts.js'
+import type { StoryDesign } from './types.js'
+import type { StoryDesignHelper } from './story/types.js'
+
+export const createStoryDesignHelper = (): StoryDesignHelper => {
+  const userStoryOfDesign = (design: StoryDesign): UserStory => {
+    const componentOf = (name: string): StoryComponent | null => {
+      const component = design.components.find(entry => entry.name === name)
+      if (component == null) {
+        return null
+      }
+
+      return {
+        name: component.name,
+        description: '',
+        specs: {
+          [SpecCategory.UX]: component.specs.ux,
+          [SpecCategory.UI]: component.specs.ui,
+        } as Record<SpecCategory, string>,
+        entities: component.entities.map(entity => ({
+          name: entity, description: '', attributes: [],
+        } satisfies Entity)),
+      }
+    }
+
+    const screens: StoryScreen[] = design.screens.map(screen => ({
+      name: screen.name,
+      description: '',
+      ...(screen.section != null ? { section: screen.section } : {}),
+      specs: {
+        [SpecCategory.UX]: screen.specs.ux,
+        [SpecCategory.UI]: screen.specs.ui,
+      } as Record<SpecCategory, string>,
+      components: screen.components
+        .map(componentOf)
+        .filter((component): component is StoryComponent => component != null),
+    }))
+
+    return {
+      story: design.narrative,
+      code: design.code,
+      area: design.area,
+      entity: null as unknown as string,
+      entities: design.entities.map(entity => ({
+        name: entity.name, description: entity.description, attributes: [],
+      } satisfies Entity)),
+      screens,
+    }
+  }
+
+  const screenMapOf = (design: StoryDesign): Record<string, string[]> =>
+    design.screens.reduce<Record<string, string[]>>((map, screen) => {
+      map[screen.name] = [...screen.components]
+
+      return map
+    }, {})
+
+  const designPaths = (design: StoryDesign): string[] => [
+    ...design.types.map(entry => entry.path),
+    ...design.resources.map(entry => entry.path),
+    ...design.models.map(entry => entry.path),
+    ...design.api.map(entry => entry.path),
+    ...design.stores.map(entry => entry.path),
+    ...design.components.flatMap(entry => [entry.viewModelPath, entry.path]),
+    ...design.screens.map(entry => entry.path),
+  ]
+
+  const designStaleness = (
+    design: StoryDesign,
+    now: { narrativeHash: string, projectHash: string, registryHash: string },
+  ): DesignStaleness => {
+    if (design.version !== STORY_DESIGN_VERSION) {
+      return DesignStaleness.Version
+    }
+    if (design.provenance.narrativeHash !== now.narrativeHash) {
+      return DesignStaleness.Narrative
+    }
+    if (design.provenance.projectHash !== now.projectHash) {
+      return DesignStaleness.Project
+    }
+    if (design.provenance.registryHash !== now.registryHash) {
+      return DesignStaleness.Tree
+    }
+
+    return DesignStaleness.Fresh
+  }
+
+  const designHash = (...parts: Array<string | undefined>): string => {
+    const text = parts.filter(part => part != null).join(' ')
+    let hash = 0x811c9dc5
+    for (let at = 0; at < text.length; at += 1) {
+      hash ^= text.charCodeAt(at)
+      hash = Math.imul(hash, 0x01000193) >>> 0
+    }
+
+    return hash.toString(16).padStart(8, '0')
+  }
+
+  const emptyStoryDesign = (
+    input: Pick<StoryDesign, 'code' | 'narrative' | 'area'> & Partial<StoryDesign>,
+  ): StoryDesign => ({
+    version: STORY_DESIGN_VERSION,
+    reserved: {},
+    entities: [],
+    screens: [],
+    components: [],
+    types: [],
+    resources: [],
+    models: [],
+    api: [],
+    stores: [],
+    transitions: [],
+    access: { list: {}, resolvedAt: {} },
+    provenance: {
+      designedAt: new Date().toISOString(),
+      narrativeHash: '',
+      projectHash: '',
+      registryHash: '',
+      paths: [],
+    },
+    ...input,
+  })
+
+  const designDigest = (design: StoryDesign): string => {
+    const lines: string[] = [
+      `Story ${design.code} (${design.area}): ${design.narrative}`,
+    ]
+    if (design.reserved.section != null || design.reserved.screen != null) {
+      lines.push(`Reserved: section=${design.reserved.section ?? '-'} screen=${design.reserved.screen ?? '-'}`)
+    }
+    lines.push('', 'Screens:')
+    for (const screen of design.screens) {
+      lines.push(
+        `- ${screen.name} -> ${screen.path} (alias ${screen.alias}`
+        + `${screen.section != null ? `, section ${screen.section}` : ''}`
+        + `${screen.adopted ? ', existing' : ''}) renders ${screen.components.join(', ') || '-'}`,
+      )
+    }
+    lines.push('', 'Components:')
+    for (const component of design.components) {
+      lines.push(
+        `- ${component.name} -> ${component.path} (+ ${component.viewModelPath})`
+        + `${component.entities.length > 0 ? ` about ${component.entities.join(', ')}` : ''}`,
+      )
+    }
+    lines.push('', 'Data layer:')
+    for (const type of design.types) {
+      lines.push(`- type ${type.path} (${type.entity})`)
+    }
+    for (const resource of design.resources) {
+      lines.push(`- resource ${resource.path} (${resource.entity})`)
+    }
+    for (const model of design.models) {
+      lines.push(`- model ${model.path} (${model.entities.join(', ')})`)
+    }
+    for (const api of design.api) {
+      lines.push(
+        `- api ${api.path} (${api.entity})`
+        + `${api.endpoints.length > 0 ? `: ${api.endpoints.map(e => e.alias).join(', ')}` : ''}`,
+      )
+    }
+    for (const store of design.stores) {
+      lines.push(`- store ${store.path} (${store.entity})`)
+    }
+    if (design.transitions.length > 0) {
+      lines.push('', 'Transitions:')
+      for (const transition of design.transitions) {
+        lines.push(`- ${transition.from} -> ${transition.to} (${transition.action})`)
+      }
+    }
+    const guarded = Object.keys(design.access.list)
+    if (guarded.length > 0) {
+      lines.push('', `Access declared on: ${guarded.join(', ')}`)
+    }
+
+    return lines.join('\n')
+  }
+
+  const amendStoryDesign = (
+    design: StoryDesign, patch: Record<string, unknown>,
+  ): StoryDesign | string => {
+    const forbidden: string[] = []
+
+    const checkList = <T extends { path?: string, alias?: string, name?: string }>(
+      key: string, current: T[], next: unknown,
+    ): void => {
+      if (!Array.isArray(next)) return
+      for (const entry of next as T[]) {
+        const known = current.find(item => item.name === entry.name)
+        if (known == null) continue
+        if (entry.path != null && known.path != null && entry.path !== known.path) {
+          forbidden.push(`${key}.${String(entry.name)}.path`)
+        }
+        if (entry.alias != null && known.alias != null && entry.alias !== known.alias) {
+          forbidden.push(`${key}.${String(entry.name)}.alias`)
+        }
+      }
+    }
+
+    checkList('screens', design.screens, patch.screens)
+    checkList('components', design.components, patch.components)
+
+    if (forbidden.length > 0) {
+      return `Refused: ${forbidden.join(', ')} name artifacts the project's registry allocated. `
+        + 'A design may change what a screen or a component DOES - its UX, its UI, its section, its '
+        + 'endpoints - but never where it lives or what it is called. Rename through the registry, '
+        + 'or leave the name alone and change the behaviour.'
+    }
+
+    return { ...design, ...patch } as StoryDesign
+  }
+
+  return {
+    userStoryOfDesign, screenMapOf, designPaths, designStaleness, designHash, emptyStoryDesign, designDigest,
+    amendStoryDesign,
+  }
+}
+
+export const storyDesignHelper = createStoryDesignHelper()

package/src/design/types.ts

@@ -1,8 +1,10 @@
 import type { ProjectArea } from '../areas/consts.js'
-import type { StoryDesignRuntime } from './runtime.js'
+
 import type { AccessList } from '../dev/types.js'
 import type { UXTransition } from '../ux/types.js'
 
+import { StoryActor, StoryAgentKind } from './consts.js'
+
 /**
  * One screen, as the design decided it.
  *
@@ -190,3 +192,81 @@ export interface StoryDesignPort {
   /** Write a design as the card's next revision and answer the revision number it received. */
   put: (cardId: string, design: StoryDesign, opts?: StoryDesignPutOptions) => Promise<number>
 }
+
+/** One queued unit of work. */
+export interface StoryDesignJob {
+  /** The queue it is enqueued onto. */
+  queue: string
+  /** The job name, which becomes the backend-only `job:<name>` protocol alias. */
+  name: string
+  /** The processor module, relative to the worker package's `src`. */
+  path: string
+  /** What it does, in one sentence, for the coder that writes the processor. */
+  purpose: string
+  /**
+   * Why it may not run on the request path.
+   *
+   * Recorded because it is the thing a later run has to be able to disagree with. "It might be
+   * slow" is not a reason; "it calls a model" and "it walks every row of a table the user owns"
+   * are.
+   */
+  reason: string
+  /**
+   * Whether running it twice is safe, and how it was made so.
+   *
+   * A worker can die mid-job; the lock expires and the step re-runs. There is no way to make that
+   * automatic, so the answer is written down where the processor's author has to read it.
+   */
+  idempotency: string
+}
+
+/** An LLM agent or pipeline generated INTO the target. */
+export interface StoryDesignAgent {
+  /** Its alias in the target's own agent registry. */
+  alias: string
+  /** The module, relative to the shared backend package's `src`. */
+  path: string
+  /** What it is for. */
+  purpose: string
+  /** Which of the three shapes this is — a call, a pipeline, or a tool-using agent. */
+  kind: StoryAgentKind
+  /** The job that runs it — an agent is never invoked on the request path. */
+  job?: string
+}
+
+/**
+ * The gate, as the design stage recorded it.
+ *
+ * Absent on a design written before this existed, and read as "none of it" everywhere — which is
+ * both the safe answer and the true one for every story developed until now.
+ */
+export interface StoryDesignRuntime {
+  actor: StoryActor
+  /** Whether this story puts work on the queue at all. */
+  worker: boolean
+  jobs: StoryDesignJob[]
+  agents: StoryDesignAgent[]
+  /**
+   * Whether this story's data belongs in the key/value store rather than in Postgres.
+   *
+   * Postgres is the default and being wrong with it is cheap. This is true only for data with an
+   * expiry, a lock, a counter or a fan-out, and a bounded, namespaced key set.
+   */
+  kv: boolean
+  /**
+   * Which HUMAN story shows the progress of this story's queued work.
+   *
+   * An ephemeral actor cannot report to anybody: there is no screen it owns and no session it runs
+   * in. A story that enqueues work therefore names the story whose screen carries the job feed, and
+   * the permission to enqueue and to watch is granted to that area's role.
+   */
+  feedback?: string
+}
+
+/** What the gate answers with — the model's half of {@link StoryDesignRuntime}. */
+export interface RuntimeDecision {
+  kv: boolean
+  feedback: string
+  jobs: StoryDesignJob[]
+  agents: StoryDesignAgent[]
+}

package/src/dev/schemas.ts

@@ -1,6 +1,7 @@
 import type { JSONSchemaType } from "ajv"
 import type { FileBlock, AccessList, AccessBlock, EntrypointRef } from "./types.js"
 import { AccessLevel } from "./consts.js"
+import type { ModelAccessBlock } from './types.local.js'
 
 export const FileBlockSchema: JSONSchemaType<FileBlock> = {
   type: "object",
@@ -80,9 +81,6 @@ export const EntrypointRefListSchema: JSONSchemaType<{entries: EntrypointRef[]}>
   additionalProperties: false
 }
 
-/** The part of an {@link AccessBlock} a model is asked for. */
-type ModelAccessBlock = Omit<AccessBlock, 'defaults' | 'entityScoped'>
-
 const ModelAccessBlockSchema: JSONSchemaType<ModelAccessBlock> = {
   type: "object",
   title: "AccessBlock",

package/src/dev/types.local.ts

@@ -0,0 +1,4 @@
+import type { AccessBlock } from './types.js'
+
+/** The part of an {@link AccessBlock} a model is asked for. */
+export interface ModelAccessBlock extends Omit<AccessBlock, 'defaults' | 'entityScoped'> {}

package/src/integrity/consts.local.ts

@@ -0,0 +1,5 @@
+/** Root-level files protected in every layout. */
+export const ROOT_PROTECTED = ['package.json', 'bunfig.toml', 'bun.lock', 'index.js'] as const
+
+/** The harness files, protected in every layout — see {@link TARGET_PROTECTED_FILES}. */
+export const HARNESS_PROTECTED = ['.claude/settings.json', '.agents/scripts/link-skills.sh'] as const