@owlmeans/viable-common 0.0.4

package/src/slot/types.ts

@@ -0,0 +1,164 @@
+import type { SlotCommandType, SlotFileCommand, SlotGitCommand, SlotShellCommand, SubProject } from './consts.js'
+
+export type SlotCommand = SlotFileCommand | SlotShellCommand | SlotGitCommand
+
+export interface SlotCommandPayload {
+  type: SlotCommandType
+  command: SlotCommand
+  args?: Record<string, any>
+}
+
+/**
+ * What a shell command answers with.
+ *
+ * `result` is the contract every caller reads: **error text, or `null` for success**. It is not a
+ * transcript — a command that fails returns the diagnostics a fixer or a person can act on, and a
+ * command that succeeds returns nothing at all. The remaining fields belong to the two commands
+ * that report a JOB rather than a verdict ({@link SlotShellCommand.BootCheck} and its status read)
+ * and to the integrity check, which reports a refusal rather than a failure.
+ */
+export interface SlotShellResult {
+  result: string | null
+  /** BootCheck: the job was started; the verdict comes from a BootCheckStatus read. */
+  started?: boolean
+  /** BootCheckStatus: whether a check is still in flight, and when it began. */
+  running?: boolean
+  startedAt?: string
+  /** BootCheckStatus: a verdict is available in `result`. */
+  done?: boolean
+  /** The target's own boot phase, when it got far enough to report one. */
+  phase?: string
+  /** Integrity: whether the tree still holds the generated application. */
+  ok?: boolean
+  violations?: string[]
+}
+
+/**
+ * The shapes the git commands answer with.
+ *
+ * Redeclared here rather than imported: the implementation lives in a package that carries
+ * `simple-git` and a GitHub client, and the connector — which executes these commands through the
+ * `git` CLI on a developer's machine — must not depend on either. The platform keeps answering
+ * with its own richer types; these are the subset both ends agree on.
+ */
+export interface SlotGitFileChange {
+  path: string
+  status: string
+}
+
+export interface SlotGitCommitInfo {
+  hash: string
+  shortHash: string
+  subject: string
+  authorName: string
+  authorEmail: string
+  committedAt: string
+}
+
+export interface SlotGitStatus {
+  initialized: boolean
+  head: SlotGitCommitInfo | null
+  branch: string
+  dirty: boolean
+  changedFiles: number
+  files: SlotGitFileChange[]
+  remoteUrl: string | null
+  ahead: number | null
+  behind: number | null
+}
+
+export interface SlotGitCommitResult {
+  commit: SlotGitCommitInfo | null
+}
+
+export interface SlotGitLogResult {
+  commits: SlotGitCommitInfo[]
+}
+
+/**
+ * Bring a remote repository onto the volume.
+ *
+ * `token` is a per-invocation credential and never reaches the tree: the executor passes it
+ * through the process environment for the one fetch, exactly as push and pull already do, so it
+ * appears in no `.git/config`, no remote URL and no argv anything can observe.
+ */
+export interface SlotGitCloneArgs {
+  remoteUrl: string
+  /** The branch to check out. Absent means whatever the remote calls its default. */
+  branch?: string
+  /** Fetch depth; 0 means the whole history. Defaults to a shallow fetch. */
+  depth?: number
+  token?: string
+}
+
+export interface SlotGitCloneResult {
+  cloned: boolean
+  /** The branch actually checked out — the resolved default, when none was asked for. */
+  branch: string
+  head: SlotGitCommitInfo | null
+  /** Executor diagnostics, when it has any worth reporting. */
+  result?: string
+}
+
+/**
+ * One entry of a {@link SlotFileCommand.StatTree} listing.
+ *
+ * The shape both a publisher and a connector answer with, so a census walks a pod's volume and a
+ * developer's own directory through one contract. `binary` is the executor's own verdict — the
+ * caller has not read the file and cannot form one.
+ */
+export interface FileStat {
+  path: string
+  bytes: number
+  binary: boolean
+  modifiedAt?: string
+}
+
+export interface StatTreeArgs {
+  /** Project-relative directory to walk. Absent means the whole project. */
+  dir?: string
+  /** Entries to return before the answer reports itself truncated. */
+  limit?: number
+}
+
+/**
+ * `total` is what the walk SAW, `entries` what it returned.
+ *
+ * The two differ on a truncated walk, and the difference is what tells a caller its picture of the
+ * tree is partial — a bounded listing that reported only what it returned would be indistinguish-
+ * able from a small repository.
+ */
+export interface StatTreeResult {
+  entries: FileStat[]
+  truncated: boolean
+  total: number
+}
+
+export interface ReadHeadArgs {
+  path: string
+  bytes: number
+}
+
+/** Move everything in the project root under `dir`, leaving the named entries where they are. */
+export interface RelocateArgs {
+  dir: string
+  /** Root-relative names that stay put — the slot's own metadata and markers. */
+  keep?: string[]
+}
+
+export interface RelocateResult {
+  moved: number
+  kept: string[]
+}
+
+export interface RemoveTreeArgs {
+  dir: string
+}
+
+/** Arguments a shell command may carry. */
+export interface SlotShellArgs {
+  subproject?: SubProject
+  /** Free-form arguments for {@link SlotShellCommand.Bun}; absent means a plain install. */
+  args?: string
+  skipBuild?: boolean
+}

package/src/topology/card.ts

@@ -0,0 +1,106 @@
+import { SubProject } from '../slot/consts.js'
+import { TOPOLOGY_VERSION } from './consts.js'
+import { orderPackages } from './helpers.js'
+import type { TargetPackageDescriptor, TargetPackageKind, TopologyDescriptor } from './types.js'
+
+/** What `.agents/memory/topology.md` carries in its frontmatter. */
+export interface TopologyMeta extends TopologyDescriptor {
+  version: number
+  updatedAt: string
+}
+
+const ROLES = new Set<string>(Object.values(SubProject))
+const KINDS = new Set<TargetPackageKind>(['library', 'bundle'])
+
+const asStrings = (value: unknown): string[] =>
+  Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : []
+
+/**
+ * Read a package descriptor out of whatever the file held.
+ *
+ * Everything is narrowed rather than trusted: the file is on the target's volume, where a person,
+ * a GitHub pull or a previous platform version may have written it. A descriptor that cannot be
+ * narrowed is DROPPED, never repaired — a package with no name or no recognisable role would
+ * otherwise resolve a path somewhere real and wrong.
+ */
+const parsePackage = (value: unknown): TargetPackageDescriptor | null => {
+  if (value == null || typeof value !== 'object') return null
+  const raw = value as Record<string, unknown>
+  const name = typeof raw.name === 'string' ? raw.name.trim() : ''
+  if (name === '' || name.includes('/') || name.startsWith('.')) return null
+  const roles = asStrings(raw.roles).filter((role): role is SubProject => ROLES.has(role))
+  if (roles.length === 0) return null
+  const kind = KINDS.has(raw.kind as TargetPackageKind) ? raw.kind as TargetPackageKind : 'bundle'
+  const areas = asStrings(raw.areas)
+  const queues = asStrings(raw.queues)
+
+  return {
+    name,
+    roles,
+    kind,
+    dependsOn: asStrings(raw.dependsOn),
+    ...(areas.length > 0 ? { areas: areas as TargetPackageDescriptor['areas'] } : {}),
+    ...(queues.length > 0 ? { queues } : {}),
+  }
+}
+
+/**
+ * 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.
+ */
+export const parseTopologyMeta = (data: unknown): TopologyDescriptor | null => {
+  if (data == null || typeof data !== 'object') return null
+  const raw = data as Record<string, unknown>
+  if (typeof raw.dir !== 'string' || raw.dir.trim() === '') return null
+  const packages = Array.isArray(raw.packages)
+    ? raw.packages.map(parsePackage).filter((pkg): pkg is TargetPackageDescriptor => pkg != null)
+    : []
+  if (packages.length === 0) return null
+
+  return {
+    id: typeof raw.id === 'string' && raw.id !== '' ? raw.id : 'recorded',
+    dir: raw.dir.trim(),
+    packages,
+  }
+}
+
+export const topologyMeta = (topology: TopologyDescriptor): TopologyMeta => ({
+  ...topology,
+  packages: orderPackages(topology.packages),
+  version: TOPOLOGY_VERSION,
+  updatedAt: new Date().toISOString(),
+})
+
+/**
+ * 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.
+ */
+export const renderTopologyCard = (topology: TopologyDescriptor): string => {
+  const ordered = orderPackages(topology.packages)
+  const rows = ordered.map(pkg => {
+    const deps = pkg.dependsOn.length > 0 ? pkg.dependsOn.join(', ') : '—'
+    const extra = [
+      ...(pkg.areas != null ? [`areas: ${pkg.areas.join(', ')}`] : []),
+      ...(pkg.queues != null ? [`queues: ${pkg.queues.join(', ')}`] : []),
+    ].join('; ')
+
+    return `| \`${topology.dir}/${pkg.name}\` | ${pkg.roles.join(', ')} | ${pkg.kind} | ${deps} | ${extra === '' ? '—' : extra} |`
+  })
+
+  return [
+    '# Topology',
+    '',
+    'Which packages this project has, what each one is, and which compile against which.',
+    'Built in the order of the table — a `library` must be built before anything importing it.',
+    '',
+    '| Package | Roles | Kind | Depends on | Notes |',
+    '|---|---|---|---|---|',
+    ...rows,
+    '',
+  ].join('\n')
+}

package/src/topology/consts.ts

@@ -0,0 +1,59 @@
+import { TargetLayout } from '../integrity/consts.js'
+import { SubProject } from '../slot/consts.js'
+import type { TopologyDescriptor } from './types.js'
+
+/**
+ * The two arrangements the platform itself writes.
+ *
+ * They are the DEFAULTS a project falls back to, not the set of arrangements that can exist: a
+ * project records its own topology and may hold packages neither of these names. What makes them
+ * special is only that `detectTargetLayout` can recognise them from the disk, which is what a
+ * consumer needs when a project predates the topology file entirely.
+ *
+ * v1 is frozen. A target's tree is the one it was initialized with, so nothing is ever added here.
+ */
+export const DEFAULT_TOPOLOGY: TopologyDescriptor = {
+  id: 'owlmeans-fullstack',
+  dir: 'sources',
+  packages: [
+    { name: 'common', roles: [SubProject.Common], kind: 'library', dependsOn: [] },
+    // The shared LIBRARY, not the server — that is `api`. It owns the context factory, the config,
+    // the resources, the services, the domain models and the job processors.
+    { name: 'backend', roles: [SubProject.Backend], kind: 'library', dependsOn: ['common'] },
+    { name: 'api', roles: [SubProject.Api], kind: 'bundle', dependsOn: ['common', 'backend'] },
+    { name: 'web', roles: [SubProject.Web, SubProject.Frontend], kind: 'bundle', dependsOn: ['common'] },
+    { name: 'worker', roles: [SubProject.Worker], kind: 'bundle', dependsOn: ['common', 'backend'] },
+  ],
+}
+
+/**
+ * The pre-restructure arrangement, frozen.
+ *
+ * `backend` here is the HTTP SERVER and `frontend` the browser app — the same two words the
+ * current topology uses for other things, which is why roles are mapped per topology and never
+ * joined onto a path.
+ */
+export const LEGACY_TOPOLOGY: TopologyDescriptor = {
+  id: 'owlmeans-fullstack-v1',
+  dir: 'packages',
+  packages: [
+    { name: 'common', roles: [SubProject.Common], kind: 'library', dependsOn: [] },
+    { name: 'backend', roles: [SubProject.Backend, SubProject.Api], kind: 'bundle', dependsOn: ['common'] },
+    { name: 'frontend', roles: [SubProject.Frontend, SubProject.Web], kind: 'bundle', dependsOn: ['common'] },
+  ],
+}
+
+/** The default topology for each layout the platform can detect on disk. */
+export const LAYOUT_TOPOLOGIES: Readonly<Record<TargetLayout, TopologyDescriptor>> = {
+  [TargetLayout.V2]: DEFAULT_TOPOLOGY,
+  [TargetLayout.V1]: LEGACY_TOPOLOGY,
+}
+
+/**
+ * The frontmatter version of `.agents/memory/topology.md`.
+ *
+ * A file written by an older platform is READ, never refused: an unknown or missing version falls
+ * back to the layout default, because a topology nobody can parse must not stop a project from
+ * building.
+ */
+export const TOPOLOGY_VERSION = 1

package/src/topology/helpers.ts

@@ -0,0 +1,138 @@
+import { TargetLayout } from '../integrity/consts.js'
+import type { ProjectArea } from '../areas/consts.js'
+import type { SubProject } from '../slot/consts.js'
+import { LAYOUT_TOPOLOGIES, DEFAULT_TOPOLOGY } from './consts.js'
+import type {
+  ResolvedTopology, TargetPackageDescriptor, TopologyDescriptor,
+} from './types.js'
+
+/**
+ * Order the packages so that nothing is built before what it compiles against.
+ *
+ * Kahn's algorithm, with two deliberate tolerances. An edge to a package the topology does not
+ * hold is DROPPED rather than fatal — a project may declare a dependency on something a pull has
+ * not brought in yet, and refusing to order the tree would take the whole build down over one
+ * name. A cycle leaves its members unvisited, and they are appended in declaration order: a cycle
+ * cannot be built correctly in any order, so the useful behaviour is to build it in the order
+ * somebody wrote rather than to throw.
+ */
+export const orderPackages = (packages: TargetPackageDescriptor[]): TargetPackageDescriptor[] => {
+  const known = new Set(packages.map(pkg => pkg.name))
+  const index = new Map(packages.map((pkg, at) => [pkg.name, at]))
+  const pending = new Map(packages.map(pkg => [
+    pkg.name, pkg.dependsOn.filter(dep => known.has(dep) && dep !== pkg.name).length,
+  ]))
+  const dependents = new Map<string, string[]>()
+  for (const pkg of packages) {
+    for (const dep of pkg.dependsOn) {
+      if (!known.has(dep) || dep === pkg.name) continue
+      dependents.set(dep, [...dependents.get(dep) ?? [], pkg.name])
+    }
+  }
+
+  const byName = new Map(packages.map(pkg => [pkg.name, pkg]))
+  const out: TargetPackageDescriptor[] = []
+  // Ready packages are taken in DECLARATION order, not in the order they became ready. Both are
+  // correct builds; only one is the same list every time and the same list a person wrote, and
+  // this order is compared against the shipped layout tables by a test.
+  const ready = packages.filter(pkg => pending.get(pkg.name) === 0).map(pkg => pkg.name)
+  const take = (): string | undefined => {
+    if (ready.length === 0) return undefined
+    let at = 0
+    for (let i = 1; i < ready.length; i++) {
+      if ((index.get(ready[i]) ?? 0) < (index.get(ready[at]) ?? 0)) at = i
+    }
+
+    return ready.splice(at, 1)[0]
+  }
+
+  for (let name = take(); name != null; name = take()) {
+    const pkg = byName.get(name)
+    if (pkg == null) continue
+    out.push(pkg)
+    for (const next of dependents.get(name) ?? []) {
+      const left = (pending.get(next) ?? 0) - 1
+      pending.set(next, left)
+      if (left === 0) ready.push(next)
+    }
+  }
+
+  const seen = new Set(out.map(pkg => pkg.name))
+
+  return [...out, ...packages.filter(pkg => !seen.has(pkg.name))]
+}
+
+/** Resolve the derived halves — build order, library order and the role index. */
+export const resolveTopology = (topology: TopologyDescriptor): ResolvedTopology => {
+  const ordered = orderPackages(topology.packages)
+  const byRole: Partial<Record<SubProject, TargetPackageDescriptor[]>> = {}
+  for (const pkg of ordered) {
+    for (const role of pkg.roles) {
+      byRole[role] = [...byRole[role] ?? [], pkg]
+    }
+  }
+
+  return {
+    ...topology,
+    packages: ordered,
+    build: ordered.map(pkg => pkg.name),
+    libraries: ordered.filter(pkg => pkg.kind === 'library').map(pkg => pkg.name),
+    byRole,
+  }
+}
+
+/** The default topology for a layout already decided. */
+export const topologyOf = (layout: TargetLayout): TopologyDescriptor =>
+  LAYOUT_TOPOLOGIES[layout] ?? DEFAULT_TOPOLOGY
+
+/**
+ * The directory a role names, or `null` when this topology has no package for it.
+ *
+ * `null` rather than the role's own name: a command aimed at a package the tree does not have must
+ * fail where it is issued. Answering with a plausible directory runs it somewhere real and wrong,
+ * which is how a type check once ran against the shared package instead of the one under repair.
+ */
+export const packageForRole = (
+  topology: ResolvedTopology, role: SubProject
+): TargetPackageDescriptor | null => topology.byRole[role]?.[0] ?? null
+
+/** Every package holding a role — more than one only where a topology splits that role. */
+export const packagesForRole = (
+  topology: ResolvedTopology, role: SubProject
+): TargetPackageDescriptor[] => topology.byRole[role] ?? []
+
+/** The package serving an area, for a topology that splits the browser app across several. */
+export const packageForArea = (
+  topology: ResolvedTopology, role: SubProject, area: ProjectArea
+): TargetPackageDescriptor | null => {
+  const candidates = packagesForRole(topology, role)
+  return candidates.find(pkg => pkg.areas?.includes(area) === true)
+    ?? candidates.find(pkg => pkg.areas == null)
+    ?? candidates[0]
+    ?? null
+}
+
+/** `<dir>/<package>` — the only place a topology directory is composed. */
+export const packageDir = (topology: TopologyDescriptor, pkg: TargetPackageDescriptor): string =>
+  `${topology.dir}/${pkg.name}`
+
+/**
+ * Merge a package into a topology, by name.
+ *
+ * This is the ADOPTION path: a package that arrived with a GitHub pull is classified once and
+ * recorded here, so the next run addresses the tree that exists rather than re-deriving one that
+ * does not. Replacing by name rather than appending keeps a re-classification idempotent.
+ */
+export const withPackage = (
+  topology: TopologyDescriptor, pkg: TargetPackageDescriptor
+): TopologyDescriptor => ({
+  ...topology,
+  packages: topology.packages.some(known => known.name === pkg.name)
+    ? topology.packages.map(known => known.name === pkg.name ? pkg : known)
+    : [...topology.packages, pkg],
+})
+
+/** Whether two topologies describe the same arrangement — used to skip a needless rewrite. */
+export const sameTopology = (a: TopologyDescriptor, b: TopologyDescriptor): boolean =>
+  JSON.stringify(orderPackages(a.packages)) === JSON.stringify(orderPackages(b.packages))
+    && a.dir === b.dir

package/src/topology/index.ts

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

package/src/topology/types.ts

@@ -0,0 +1,86 @@
+import type { ProjectArea } from '../areas/consts.js'
+import type { SubProject } from '../slot/consts.js'
+
+/**
+ * How a target's workspace packages are ARRANGED — which of them exist, what role each plays and
+ * which compile against which.
+ *
+ * The layout tables this replaces ({@link LAYOUTS}, {@link ROLE_DIRS}) were two hand-written
+ * records keyed by a closed `TargetLayout` enum, so "the target has five packages named
+ * common/backend/api/web/worker" was not a fact ABOUT a project but a constant of the platform.
+ * Everything the pipeline could ever generate had to fit those five names.
+ *
+ * A topology is that same information as DATA: a project carries one, the two shipped layouts are
+ * just the two the platform writes by default, and the tables are derived from them rather than
+ * spelled beside them. That is what lets a target grow a second web application, a library package
+ * nobody planned, or the package a GitHub pull brought in.
+ *
+ * It is deliberately a DESCRIPTION and never a plan. Nothing here says a directory exists — a
+ * caller that acts on a package still checks the disk, exactly as `workerPath` always has.
+ */
+export interface TargetPackageDescriptor {
+  /**
+   * The package's directory name under {@link TopologyDescriptor.dir}, and the tail of its npm
+   * name (`<slug>-<name>`). Unique within a topology.
+   */
+  name: string
+  /**
+   * What this package IS, in the role vocabulary the wire already speaks.
+   *
+   * A list rather than a single value because one package may answer to more than one role in a
+   * smaller arrangement — a target that serves its browser app from the same process that serves
+   * its API is one package holding both `Api` and `Web`. The default topology gives every package
+   * exactly one role.
+   */
+  roles: SubProject[]
+  /**
+   * `library` builds with `tsc -b` and is consumed through its `build/` output at RUN time;
+   * `bundle` bundles itself and keeps every dependency external.
+   *
+   * The distinction is load-bearing rather than descriptive: a bundle resolves its libraries from
+   * `node_modules` when the process starts, so a library that nothing built makes the bundle exit
+   * with a message naming a missing dependency rather than a missing build.
+   */
+  kind: TargetPackageKind
+  /** Sibling package NAMES this one compiles against. The build order is this graph, sorted. */
+  dependsOn: string[]
+  /**
+   * For a package holding the `Web` role: which audiences it serves.
+   *
+   * Absent means all four. A topology that splits the areas across two browser applications is
+   * the reason this exists; nothing generates one yet.
+   */
+  areas?: ProjectArea[]
+  /** For a package holding the `Worker` role: which queues this process consumes. */
+  queues?: string[]
+}
+
+export type TargetPackageKind = 'library' | 'bundle'
+
+/**
+ * One arrangement, named.
+ *
+ * `id` is what a project records; it is compared, never parsed.
+ */
+export interface TopologyDescriptor {
+  id: string
+  /** The directory holding the workspace packages — `sources`, or `packages` for a legacy tree. */
+  dir: string
+  packages: TargetPackageDescriptor[]
+}
+
+/**
+ * A topology read back from a project, with the resolutions every consumer would otherwise redo.
+ *
+ * `build` and `libraries` are DERIVED — a topological sort of `dependsOn` — rather than declared,
+ * because the two lists disagreeing with the graph is a whole class of outage (a library built
+ * after the bundle that imports it) that nobody can see by reading either one.
+ */
+export interface ResolvedTopology extends TopologyDescriptor {
+  /** Every package, in dependency order. */
+  build: string[]
+  /** The `library`-kind packages, in dependency order. */
+  libraries: string[]
+  /** Role → the packages holding it, in topology order. */
+  byRole: Partial<Record<SubProject, TargetPackageDescriptor[]>>
+}

package/src/types.ts

@@ -0,0 +1,104 @@
+
+export interface SlotMetadata extends
+  SlotConstMetadata,
+  SlotSecretMetadata,
+  SlotListMetadata,
+  CustomSecretMetadata {
+}
+
+export interface SlotConstMetadata {
+  projectName: string
+  oidcClientId: string
+  oidcRealm: string
+  /**
+   * Fully-qualified PUBLIC OIDC issuer URL the integrated viable IAM serves this client from
+   * (`{host}/oidc`). Populated when the production IAM client is provisioned; the canonical
+   * single value a standalone self-hosted deployment of the exported target uses. Empty until
+   * provisioned.
+   */
+  oidcIssuerUrl: string
+  /**
+   * What the project's owner says about themselves, delivered to the generated application.
+   *
+   * Scalars rather than an object because metadata is scalar — the store is one row per key, and
+   * a nested value would have to be serialized at the boundary anyway.
+   *
+   * `brandingCredit` is the EFFECTIVE value, not the owner's intent: `''` hides the platform
+   * credit and anything else shows it. Absent means shown, so a push that never happened, or one
+   * that lost the value, keeps the credit rather than silently giving away a paid capability.
+   */
+  brandingCopyright: string
+  brandingOrganization: string
+  brandingTermsUrl: string
+  brandingPrivacyUrl: string
+  brandingCredit: string
+  brandingHideCreditIntent: string
+}
+
+export interface SlotSecretMetadata {
+  oidcClientSecret: string
+  /**
+   * The application role's password — the one database credential the generated app legitimately
+   * holds, and the one it already carries inside `DATABASE_URL`.
+   *
+   * The sidecar's SUPERUSER password is deliberately absent from this interface. Everything in
+   * `SlotMetadata` is pushed into the slot as `sandbox-meta.json`, which is a world-readable file
+   * in the untrusted application's own directory; the admin credential is kept platform-side and
+   * reaches the pod only as a Kubernetes Secret mounted into the Postgres container.
+   */
+  dbAppPassword?: string
+  /**
+   * Password of the queue store's `app` ACL user — the whole of what the slot is given for its
+   * Valkey sidecar, and what it already carries inside `VALKEY_URL`.
+   *
+   * The store's `ops` user is deliberately absent for the same reason the Postgres superuser is:
+   * it holds the administrative surface, and everything in `SlotMetadata` lands in the untrusted
+   * application's own directory. Its password lives only in the ACL Secret.
+   */
+  valkeyPassword?: string
+}
+
+export interface SlotListMetadata {
+  permissions: string[]
+  backendEnvVars: string[]
+  frontendEnvVars: string[]
+  /**
+   * Owner-registered allowed OIDC redirect URIs for the production (standalone) client.
+   * Each entry is a full callback URL of a self-hosted deployment of the exported target
+   * project. Combined with the production hosts (generated + custom domain) when the
+   * production IAM client is (re)provisioned.
+   */
+  oidcRedirectUris: string[]
+  /**
+   * Origins the target's own API accepts browser requests from.
+   *
+   * The redirect URIs say where a login may RETURN to; these say who may call the API afterwards.
+   * They are separate lists because they answer different questions and are wrong in different
+   * ways: an unregistered redirect URI is a login that cannot complete, an unlisted origin is an
+   * app that loads and then fails every request it makes.
+   *
+   * Set by the owner for a deployment the platform does not host — a target published on their own
+   * domain, or run on a developer's machine on a port the platform never chose. The platform's own
+   * hosts are always accepted and are never in this list.
+   */
+  allowedOrigins: string[]
+}
+
+export interface CustomSecretMetadata {
+  backendSecrets: Record<string, string>
+  frontendSecrets: Record<string, string>
+}
+
+export interface NonSecretScalarSlotMetadata extends
+  SlotConstMetadata {
+}
+
+export interface ScalarSlotMetadata extends
+  SlotConstMetadata,
+  SlotSecretMetadata {
+}
+
+export interface ConfigSlotMetadata extends
+  SlotConstMetadata,
+  SlotListMetadata {
+}

package/src/ux/consts.ts

@@ -0,0 +1,5 @@
+
+export enum UXTransitionType {
+  Screen = 'screen',
+  Component = 'component'
+}

package/src/ux/index.ts

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