@owlmeans/viable-common 0.0.4

package/src/integrity/verify.ts

@@ -0,0 +1,221 @@
+import {
+  detectTargetLayout, IntegrityRule, TARGET_FORBIDDEN_SCRIPTS, TARGET_SLUG_PATTERN,
+  targetManifest, targetPackageName, targetRequiredDeps
+} from './consts.js'
+import type { IntegrityViolation, TargetFileMap, TargetIntegrityReport } from './types.js'
+
+/**
+ * Decide whether a tree is the generated application, from its files alone.
+ *
+ * Pure and IO-free on purpose. The publisher reads the sandbox and calls this; a test reads
+ * the template and calls this; both then agree by construction. It is also why the check is
+ * cheap enough to sit in front of every spawn rather than only at the moments someone
+ * remembered to guard.
+ *
+ * The tree picks the manifest it is verified against. A slot holds the layout it was
+ * initialized with for the life of the project and nothing migrates it, so asserting the
+ * current layout unconditionally does not make the check stricter — it aims it at a tree that
+ * was never there, and every legacy slot answers with one `missing` violation per file it was
+ * never supposed to have. That refuses the application the platform itself generated.
+ *
+ * Every rule collects rather than short-circuits: a tree that fails is usually a person's
+ * repository, and telling them one thing at a time turns a fix into a dozen round trips
+ * through a pull that reverts itself each time.
+ */
+export const verifyTargetShape = (files: TargetFileMap): TargetIntegrityReport => {
+  const violations: IntegrityViolation[] = []
+  const layout = detectTargetLayout(files)
+  const manifest = targetManifest(layout)
+
+  // Only this layout's files. The caller reads the union of every layout's list so that the
+  // probes are in hand before the layout is known — reporting the other layout's paths as
+  // missing would refuse both trees at once.
+  for (const path of manifest.files) {
+    if (files[path] == null) {
+      violations.push({
+        path, rule: IntegrityRule.Missing,
+        detail: `${path} is missing — a Viable project always has it.`
+      })
+    }
+  }
+
+  // The slug is read once, from the root, and every package name is checked against it. A
+  // project the user renamed is still the project; a package that does not carry the root's
+  // name is a different tree wearing the workspace layout.
+  const slug = checkRoot()
+  checkInstallConfig()
+  for (const pkg of manifest.packages) {
+    checkPackage(pkg, slug)
+  }
+  checkMarkers()
+
+  return { ok: violations.length === 0, violations, layout }
+
+  function checkRoot(): string | null {
+    const found = readJson('package.json')
+    if (found == null) return null
+
+    const name = typeof found.name === 'string' ? found.name : ''
+    if (!TARGET_SLUG_PATTERN.test(name)) {
+      violations.push({
+        path: 'package.json', rule: IntegrityRule.PackageName,
+        detail: `The root package name "${String(found.name)}" is not a project slug`
+          + ` — lowercase letters, digits and inner hyphens, up to 32 characters.`
+      })
+    }
+    if (found.type !== 'module') {
+      violations.push({
+        path: 'package.json', rule: IntegrityRule.ModuleType,
+        detail: 'The root package must declare "type": "module".'
+      })
+    }
+
+    // The workspace list is what makes the packages resolve to each other. Both spellings are
+    // the same tree: the glob `create-app` emits, or the entries written out.
+    const declared = Array.isArray(found.workspaces) ? found.workspaces as string[] : []
+    const isGlob = declared.length === 1 && declared[0] === manifest.workspaceGlob
+    const isExplicit = declared.length === manifest.workspaceEntries.length
+      && manifest.workspaceEntries.every(entry => declared.includes(entry))
+    if (!isGlob && !isExplicit) {
+      violations.push({
+        path: 'package.json', rule: IntegrityRule.Workspaces,
+        detail: `The root package must declare the workspaces as ["${manifest.workspaceGlob}"]`
+          + ` or as exactly ${manifest.workspaceEntries.join(', ')}.`
+      })
+    }
+
+    checkScripts('package.json', found)
+
+    return TARGET_SLUG_PATTERN.test(name) ? name : null
+  }
+
+  /**
+   * `bunfig.toml` decides where `bun install` fetches from and how it links.
+   *
+   * A registry line pointed elsewhere makes every dependency in the tree arbitrary code
+   * regardless of how well-formed the manifests are, so it is checked as a shape rather than
+   * a marker: nothing but the hoisted-linker install block belongs in it.
+   */
+  function checkInstallConfig(): void {
+    const content = files['bunfig.toml']
+    if (content == null) return
+
+    const offending = content.split('\n')
+      .map(line => line.trim())
+      .filter(line => line.length > 0 && !line.startsWith('#'))
+      .filter(line => !/^\[install\]$/.test(line) && !/^linker\s*=/.test(line))
+
+    if (offending.length > 0) {
+      violations.push({
+        path: 'bunfig.toml', rule: IntegrityRule.InstallConfig,
+        detail: 'bunfig.toml may only declare the hoisted install linker.'
+      })
+    }
+  }
+
+  function checkPackage(pkg: string, slug: string | null): void {
+    const path = `${manifest.dir}/${pkg}/package.json`
+    const found = readJson(path)
+    if (found == null) return
+
+    // With no readable slug the name and the workspace dependencies have nothing to be checked
+    // against; the root violation already says why, and repeating it per package is noise.
+    if (slug != null) {
+      const expected = targetPackageName(slug, pkg)
+      if (found.name !== expected) {
+        violations.push({
+          path, rule: IntegrityRule.PackageName,
+          detail: `Package must be named "${expected}", not "${String(found.name)}".`
+        })
+      }
+    }
+    if (found.type !== 'module') {
+      violations.push({
+        path, rule: IntegrityRule.ModuleType,
+        detail: `Package "${pkg}" must declare "type": "module".`
+      })
+    }
+
+    const scripts = asRecord(found.scripts)
+    if (scripts.build !== manifest.buildScripts[pkg]) {
+      // The one the platform actually spawns.
+      violations.push({
+        path, rule: IntegrityRule.BuildScript,
+        detail: `The build script of "${pkg}" must be exactly \`${manifest.buildScripts[pkg]}\`.`
+      })
+    }
+    checkScripts(path, found)
+
+    if (slug == null) return
+
+    const deps = { ...asRecord(found.dependencies), ...asRecord(found.devDependencies) }
+    for (const dep of targetRequiredDeps(slug, pkg, layout)) {
+      if (deps[dep] == null) {
+        violations.push({
+          path, rule: IntegrityRule.RequiredDependency,
+          detail: `Package "${pkg}" must depend on ${dep}.`
+        })
+      }
+    }
+  }
+
+  /** Lifecycle hooks run on `bun install`, before anything else has a chance to refuse. */
+  function checkScripts(path: string, found: Record<string, unknown>): void {
+    const scripts = asRecord(found.scripts)
+    for (const hook of TARGET_FORBIDDEN_SCRIPTS) {
+      if (scripts[hook] != null) {
+        violations.push({
+          path, rule: IntegrityRule.LifecycleScript,
+          detail: `Lifecycle script "${hook}" is not allowed in a target project.`
+        })
+      }
+    }
+  }
+
+  function checkMarkers(): void {
+    for (const [path, markers] of Object.entries(manifest.markers)) {
+      const content = files[path]
+      if (content == null) continue
+
+      const absent = markers.filter(marker => !content.includes(marker))
+      if (absent.length > 0) {
+        violations.push({
+          path, rule: IntegrityRule.EntryMarker,
+          detail: `${path} does not look like the generated app's entry: ${absent.join(', ')} not found.`
+        })
+      }
+    }
+  }
+
+  function readJson(path: string): Record<string, unknown> | null {
+    const content = files[path]
+    if (content == null) return null
+    try {
+      const parsed: unknown = JSON.parse(content)
+
+      return typeof parsed === 'object' && parsed !== null
+        ? parsed as Record<string, unknown>
+        : reportUnreadable(path)
+    } catch {
+      return reportUnreadable(path)
+    }
+  }
+
+  function reportUnreadable(path: string): null {
+    violations.push({
+      path, rule: IntegrityRule.Unreadable, detail: `${path} is not a readable JSON object.`
+    })
+
+    return null
+  }
+
+  function asRecord(value: unknown): Record<string, string> {
+    return typeof value === 'object' && value !== null
+      ? value as Record<string, string>
+      : {}
+  }
+}
+
+/** One line per violation — what goes into a log, `slot.lastError`, or a build diagnostic. */
+export const formatIntegrityReport = (report: TargetIntegrityReport): string =>
+  report.violations.map(violation => `${violation.path}: ${violation.detail}`).join('\n')

package/src/metadata/consts.ts

@@ -0,0 +1,118 @@
+
+import type { SpecCategory } from '../ba/consts.js'
+
+/**
+ * Where the pipeline's markdown lives in a generated target.
+ *
+ * The tree follows the AGENTS.md / Agent Skills open standard rather than a private `.viable/`
+ * directory, because the target is an ordinary repository that people and other agents open: a
+ * brief belongs in `docs/`, and durable cross-run knowledge belongs in the agent memory graph
+ * every harness already reads. A directory only this pipeline understands is invisible to all of
+ * them, and a project the user takes home keeps none of it.
+ *
+ * The split is by AUDIENCE, not by writer. `docs/` is the product — read by a person, published
+ * with the repository, meaningful without the agent. `.agents/memory/` is working state — read by
+ * the next run to know what the last one allocated, decided and observed.
+ */
+export const HARNESS_DIR = '.agents'
+export const MEMORY_DIR = `${HARNESS_DIR}/memory`
+export const DOCS_DIR = 'docs'
+
+export const STORIES_DIR = `${DOCS_DIR}/stories`
+export const ENTITIES_DIR = `${DOCS_DIR}/entities`
+
+/** Co-located specs keep their names and their place — beside the source file they describe. */
+export const SPEC_SUFFIX = '.spec.md'
+export const UX_SUFFIX = '.ux.md'
+export const UI_SUFFIX = '.ui.md'
+
+/**
+ * Everything under `docs/` is plain markdown: the directory says what a file is, so the name
+ * does not have to. `docs/stories/CHK-1.md`, not `docs/stories/CHK-1.story.md`.
+ */
+export const STORY_SUFFIX = '.md'
+export const ENTITY_SUFFIX = '.md'
+
+/** The project brief — `docs/project.md`, the first file anyone opens. */
+export const PROJECT_META_NAME = 'project'
+export const PROJECT_META_FILE = `${DOCS_DIR}/${PROJECT_META_NAME}.md`
+
+/**
+ * The name registry — `.agents/memory/registry.md`.
+ *
+ * Project-level, not per-story: a resource alias is a physical table name and an entity directory
+ * is a repository-wide invariant, so a later story has to see what an earlier one allocated. Each
+ * entry records the story that introduced it, which keeps provenance without splitting the file.
+ *
+ * A memory node rather than a doc: it is what the NEXT run must not contradict, and it is
+ * meaningless to a reader of the product.
+ */
+export const REGISTRY_NAME = 'registry'
+export const REGISTRY_FILE = `${MEMORY_DIR}/${REGISTRY_NAME}.md`
+
+/**
+ * The project's rolling history — `.agents/memory/history.md`.
+ *
+ * A file of its own rather than a section of `docs/project.md`, because `writeProject` rebuilds
+ * that file's whole body out of `AgentProject`: a history section there would be destroyed by the
+ * next brief update, silently and with nothing failing.
+ *
+ * It answers "where are we" for every model call that reads it, so it is folded under a ceiling
+ * rather than appended to.
+ */
+export const HISTORY_NAME = 'history'
+export const HISTORY_FILE = `${MEMORY_DIR}/${HISTORY_NAME}.md`
+
+/**
+ * Recorded layout deviations — `.agents/memory/layout.md`.
+ *
+ * The generated target IS-A `@owlmeans/create-app` project, and the pipeline derives every path
+ * from that assumption. A repository the user has since reshaped by hand is still theirs, so a
+ * deviation is RECORDED here instead of being corrected: the next run reads it and addresses the
+ * tree that exists rather than re-deriving one that does not.
+ */
+export const LAYOUT_NAME = 'layout'
+export const LAYOUT_FILE = `${MEMORY_DIR}/${LAYOUT_NAME}.md`
+
+/**
+ * The deployment topology — `.agents/memory/topology.md`.
+ *
+ * Which runtimes the project actually runs (api, web, worker), what each binds, and which queues
+ * carry work between them. A worker exists only once something needs one, so this is the record
+ * of that decision — the thing a later run must not silently re-decide.
+ */
+export const TOPOLOGY_NAME = 'topology'
+export const TOPOLOGY_FILE = `${MEMORY_DIR}/${TOPOLOGY_NAME}.md`
+
+/**
+ * The ceiling on the whole rendered history block, in characters.
+ *
+ * Enforced by truncation after the model answers, never by asking it to obey a limit. The parts
+ * below are budgeted to fit inside it with room for their separators.
+ */
+export const HISTORY_MAX_CHARS = 3000
+export const HISTORY_LAST_EVENT_CHARS = 200
+export const HISTORY_SUMMARY_CHARS = 1600
+export const HISTORY_RECENT_CHARS = 140
+/** How many events stay verbatim before older ones are folded into the prose. */
+export const HISTORY_RECENT_MAX = 8
+/** The heading the verbatim tail is written under. */
+export const HISTORY_RECENT_HEADING = 'Recent'
+
+export const METADATA_SUFFIX: Record<SpecCategory, string> = {
+  ba: SPEC_SUFFIX,
+  ux: UX_SUFFIX,
+  ui: UI_SUFFIX,
+}
+
+/**
+ * Suffixes that mark a CO-LOCATED metadata file — one sitting beside the source it describes.
+ *
+ * Only these three, because everything else the pipeline writes now lives under a directory of
+ * its own: excluding pipeline markdown from a source listing is a question about the path, not
+ * about the tail. Adding `.md` here would hide every README in the project.
+ */
+export const METADATA_SUFFIXES = [SPEC_SUFFIX, UX_SUFFIX, UI_SUFFIX]
+
+/** The trees the pipeline writes into — excluded wholesale when source files are enumerated. */
+export const METADATA_DIRS = [HARNESS_DIR, DOCS_DIR]

package/src/metadata/index.ts

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

package/src/metadata/types.ts

@@ -0,0 +1,310 @@
+
+import type { SpecCategory } from '../ba/consts.js'
+
+export interface MetadataFile<T extends Record<string, unknown> = Record<string, unknown>> {
+  path: string
+  data: T
+  body: string
+}
+
+export interface MetadataWriteInput<T extends Record<string, unknown> = Record<string, unknown>> {
+  data?: Partial<T>
+  body: string
+}
+
+export enum MetadataKind {
+  Project = 'project',
+  Story = 'story',
+  Source = 'source',
+  History = 'history',
+}
+
+export enum MetadataListKind {
+  Stories = 'stories',
+  Meta = 'meta',
+  // All metadata: the docs/ and .agents/ trees + co-located *.spec/.ux/.ui.md beside sources
+  All = 'all',
+}
+
+/**
+ * Identifies a single metadata document to read:
+ * - Project:  kind=Project, no ref/category needed
+ * - Story:    kind=Story,   ref=story-code
+ * - Source:   kind=Source,  ref=source-path, category=SpecCategory
+ */
+export interface MetadataRef {
+  kind: MetadataKind
+  ref?: string
+  category?: SpecCategory
+}
+
+/**
+ * Identifies a list of metadata documents to enumerate:
+ * - Stories: kind=Stories  → returns story codes
+ * - Meta:    kind=Meta     → returns co-located *.spec/.ux/.ui.md paths;
+ *                            category narrows to one suffix
+ */
+export interface MetadataListRef {
+  kind: MetadataListKind
+  category?: SpecCategory
+}
+
+// ─── Typed frontmatter shapes (Platform: drives ProjectMetadataStore serialisation) ────
+
+/** Frontmatter for docs/project.md */
+export interface ProjectMeta extends Record<string, unknown> {
+  name: string
+  alias: string
+  /**
+   * The language every piece of generated UI text is written in — labels, headings, empty
+   * states, validation messages, i18n values.
+   *
+   * Recorded on the project rather than asked per pass, because a screen scaffolded in one
+   * language and extended in another is a mixed interface that nothing reports: the code
+   * compiles, the tests pass, and only a reader of the running app can see it. An IETF tag
+   * (`en`, `pl`, `pt-BR`).
+   */
+  language: string
+}
+
+/**
+ * Frontmatter for `.agents/memory/history.md`.
+ *
+ * `lastEvent` is written verbatim on every record and rendered as the first line of the history
+ * block. That is what makes "the summary always names the most recent event" a property of the
+ * file rather than a hope about the model that folded it.
+ */
+export interface HistoryMeta extends Record<string, unknown> {
+  version: number
+  updatedAt: string
+  lastEvent: string
+}
+
+/** Frontmatter for docs/entities/<name>.md */
+export interface EntityMeta extends Record<string, unknown> {
+  name: string
+  attributes: Array<{ name: string; description: string }>
+}
+
+/** Ref to a screen inside a docs/stories/<code>.md index */
+export interface StoryScreenRef {
+  name: string
+  path: string
+  /** Top-menu group this screen renders under. A label, never a URL segment. */
+  section?: string
+  components: StoryComponentRef[]
+}
+
+/** Ref to a component inside a docs/stories/<code>.md index */
+export interface StoryComponentRef {
+  name: string
+  path: string
+}
+
+/** Frontmatter for docs/stories/<code>.md */
+export interface StoryMeta extends Record<string, unknown> {
+  code: string
+  status: string
+  primary: boolean
+  /** The audience this story serves; its screens live under that area's entrypoint. */
+  area: string
+  /**
+   * The top-menu section the scaffold reserved for this story, inside its area.
+   *
+   * Assigned before any of the story's code exists, so that the stub screen drawn at
+   * initialization and the real screen developed later land in the SAME menu group — a story
+   * that moves section when it is implemented leaves its own dashboard behind.
+   */
+  section?: string
+  entity: string
+  entities: string[]
+  screens: StoryScreenRef[]
+  transitions: Array<{
+    from: string
+    to: string
+    initiator: string
+    action: string
+    type: string
+  }>
+}
+
+/** Frontmatter for co-located <screen>.spec.md */
+export interface ScreenMeta extends Record<string, unknown> {
+  name: string
+  stories: string[]
+  area?: string
+  section?: string
+  components: string[]
+}
+
+/** Frontmatter for co-located <component>.spec.md */
+export interface ComponentMeta extends Record<string, unknown> {
+  name: string
+  stories: string[]
+  entities: string[]
+}
+
+/**
+ * Payload the agent passes to store.writeStory — all data the developer
+ * collected during one develop run.
+ */
+export interface StoryWriteInput {
+  code: string
+  narrative: string
+  status: string
+  primary: boolean
+  /** Carried through a develop run so the rewrite does not drop the scaffold's assignment. */
+  section?: string
+  /** Likewise the reserved screen name. */
+  screen?: string
+  userStory: import('../ba/types.js').UserStory
+  /** Each entry maps a StoryScreen to its source path in the target project */
+  screenPaths: Record<string, string>
+  /** Each entry maps a StoryComponent to its source path in the target project */
+  componentPaths: Record<string, string>
+  transitions: Array<{
+    from: string
+    to: string
+    initiator: string
+    action: string
+    type: string
+  }>
+}
+
+// ─── Name registry (.agents/memory/registry.md) ───────────────────────────────────────
+
+/**
+ * What a registry entry names.
+ *
+ * One entry per artifact the pipeline can generate, so that "where does this live" and "what is
+ * it called" have exactly one answer for the whole life of the project.
+ */
+export enum RegistryKind {
+  /** The single directory segment an entity owns across models/, resources/ and backend models/ */
+  EntityDir = 'entity-dir',
+  ModelType = 'model-type',
+  Resource = 'resource',
+  BackendModel = 'backend-model',
+  ApiHandlers = 'api-handlers',
+  Service = 'service',
+  Layout = 'layout',
+  Screen = 'screen',
+  Component = 'component',
+  ViewModel = 'view-model',
+  State = 'state',
+  /** Alias-only entry for one endpoint — carries no source path of its own */
+  ApiEntrypoint = 'api-entrypoint',
+}
+
+/**
+ * One allocated name.
+ *
+ * `name` is the lookup key — the entity name for entity-scoped kinds, the definition otherwise.
+ * Everything else is what generated code must use verbatim: a coder that writes a different
+ * directory, and a fixer that renames a reference instead of declaring the missing thing, are the
+ * two failure modes this record exists to make impossible.
+ */
+export interface RegistryAllocation extends Record<string, unknown> {
+  kind: RegistryKind
+  name: string
+  /** Repo-relative source path; empty for alias-only kinds */
+  path: string
+  /** Resource alias (also the physical table name) or entrypoint alias */
+  alias?: string
+  /** Dotted `app.*` reference the generated code uses to reach the alias */
+  appRef?: string
+  /** Exported symbol — screen/layout/component/handler */
+  symbol?: string
+  /**
+   * The FULL assembled route, recorded when an entrypoint is declared — area prefix included.
+   *
+   * The declaration that produces it carries only the tail, because a child path is appended to
+   * its parent's; `areaSegment` is what shortens this value when a declaration is written back.
+   */
+  url?: string
+  /** Parent entrypoint alias — for a screen that is its AREA, for an endpoint its group */
+  parent?: string
+  /** The area a screen belongs to — one of the four {@link ProjectArea} values. */
+  area?: string
+  /** Top-menu group of a screen. A label, never a URL segment. */
+  section?: string
+  /**
+   * A SCAFFOLD placeholder — drawn at initialization, replaced or deleted later.
+   *
+   * The flag is what makes cleanup deterministic instead of a judgement call. It survives until
+   * either the story behind the artifact is implemented (the file is rewritten in place and the
+   * flag is cleared) or something else edits the file, which clears the flag as well: whoever
+   * edited it meant it, so nothing may delete it afterwards.
+   */
+  stub?: boolean
+  /**
+   * SHA-256 of the file exactly as the scaffold wrote it.
+   *
+   * Compared against the file on disk before a stub is deleted. A mismatch means the file is no
+   * longer the placeholder that was written — free flight, the editor or a story implementation
+   * has been in it — so it is kept, and only the `stub` flag is dropped.
+   */
+  hash?: string
+  /** This widget is on its area home's shortlist and renders there in `compact` mode too. */
+  home?: boolean
+  /** Story code that OWNS the allocation — the one its file is named after. */
+  story: string
+  /**
+   * Every story this one artifact stands in for, the owner included.
+   *
+   * A preview widget is drawn per user story only when each story genuinely needs its own; two
+   * steps of one flow that act on the same record through the same shape share ONE widget, and
+   * then the widget belongs to a SET. `story` stays the code the file is named after, because
+   * `widgetDefinition(code)` derives the filename from exactly one; this is what lets
+   * `byStory` answer to every member, and what stops a departing member from retiring an
+   * artifact the others still name.
+   *
+   * Absent on an artifact nobody shares — the ordinary case, and the shape every slot drawn
+   * before sharing existed carries.
+   */
+  stories?: string[]
+}
+
+/** Frontmatter for .agents/memory/registry.md */
+export interface RegistryMeta extends Record<string, unknown> {
+  version: number
+  entries: RegistryAllocation[]
+}
+
+// ─── Layout deviations (.agents/memory/layout.md) ─────────────────────────────────────
+
+/**
+ * One place the repository no longer matches the layout the pipeline derives paths from.
+ *
+ * `expected` is what `naming.ts` would build; `actual` is what is on disk. Both are recorded
+ * because a later run has to do two different things with them — address the file where it is,
+ * and stop proposing to move it back.
+ */
+export interface LayoutDeviation {
+  /** What the pipeline would have derived — a repo-relative path or a directory. */
+  expected: string
+  /** Where the thing actually is. Empty when it was removed outright. */
+  actual: string
+  /** Why it moved, in one sentence, as the run that observed it understood it. */
+  reason: string
+}
+
+/**
+ * Frontmatter for `.agents/memory/layout.md`.
+ *
+ * A generated target IS-A `@owlmeans/create-app` project, and every path the pipeline writes is
+ * derived from that. The volume is the user's, though: they rename, they move, they merge a pull
+ * request. Recording the divergence is what keeps the next run from fighting it — an agent that
+ * re-derives a path it was already told is wrong recreates the file in the old place, and the
+ * project then has two.
+ *
+ * `layout` is which of the two generated shapes the tree started as, so that a slot published
+ * before the `create-app` adoption is still addressed in its own vocabulary.
+ */
+export interface LayoutMeta extends Record<string, unknown> {
+  version: number
+  /** `v1` (packages/{common,backend,frontend}) or `v2` (sources/*). */
+  layout: string
+  updatedAt: string
+  deviations: LayoutDeviation[]
+}