@owlmeans/viable-common 0.0.44 → 0.0.46

package/src/integrity/layout/consts.local.ts

@@ -0,0 +1,188 @@
+import { HARNESS_PROTECTED, ROOT_PROTECTED } from '../consts.local.js'
+import {
+  TARGET_BUNDLED_PACKAGES, TARGET_LEGACY_BUNDLED_PACKAGES, TARGET_LEGACY_PACKAGES, TARGET_LEGACY_PACKAGES_DIR,
+  TARGET_PACKAGES_DIR, TargetLayout, TargetLegacyPackage, TargetPackage,
+} from '../consts.js'
+import type { TargetLayoutManifest } from '../types.js'
+
+/**
+ * The current layout: five workspace packages under `sources/`.
+ *
+ * `common` and `backend` are libraries the other three import, so they emit declarations with
+ * `tsc -b` rather than a bundle; `api`, `web` and `worker` each bundle themselves.
+ */
+export const V2_MANIFEST: TargetLayoutManifest = {
+  layout: TargetLayout.V2,
+  dir: TARGET_PACKAGES_DIR,
+  packages: Object.values(TargetPackage),
+  // The same file the publisher's own filesystem detection probes for (`sources/api`), so the
+  // two answers about one volume cannot disagree.
+  probe: `${TARGET_PACKAGES_DIR}/${TargetPackage.Api}/package.json`,
+  files: [
+    'package.json',
+    'bunfig.toml',
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Common}/package.json`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Common}/tsconfig.json`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Common}/src/index.ts`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Common}/src/entrypoints.ts`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Backend}/package.json`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Backend}/tsconfig.json`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Backend}/src/index.ts`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Backend}/src/context.ts`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Backend}/src/config.ts`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Api}/package.json`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Api}/tsconfig.json`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Api}/rollup.config.js`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Api}/rollup.build.mjs`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Api}/src/index.ts`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Api}/src/owlmeans.ts`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Api}/src/config.ts`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Api}/src/entrypoints.ts`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Web}/package.json`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Web}/tsconfig.json`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Web}/rollup.config.js`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Web}/rollup.build.mjs`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Web}/src/index.tsx`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Web}/src/owlmeans.ts`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Web}/src/config.ts`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Web}/src/entrypoints.ts`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Worker}/package.json`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Worker}/tsconfig.json`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Worker}/rollup.config.js`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Worker}/rollup.build.mjs`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Worker}/src/index.ts`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Worker}/src/owlmeans.ts`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Worker}/src/config.ts`,
+    `${TARGET_PACKAGES_DIR}/${TargetPackage.Worker}/src/entrypoints.ts`,
+  ],
+  protectedFiles: [
+    ...ROOT_PROTECTED,
+    ...HARNESS_PROTECTED,
+    ...Object.values(TargetPackage).flatMap(pkg =>
+      [`${TARGET_PACKAGES_DIR}/${pkg}/package.json`, `${TARGET_PACKAGES_DIR}/${pkg}/tsconfig.json`]),
+    ...TARGET_BUNDLED_PACKAGES.flatMap(pkg =>
+      [`${TARGET_PACKAGES_DIR}/${pkg}/rollup.config.js`, `${TARGET_PACKAGES_DIR}/${pkg}/rollup.build.mjs`]),
+  ],
+  buildScripts: {
+    [TargetPackage.Common]: 'tsc -b',
+    [TargetPackage.Backend]: 'tsc -b',
+    [TargetPackage.Api]: 'bun ./rollup.build.mjs',
+    [TargetPackage.Web]: 'bun ./rollup.build.mjs',
+    [TargetPackage.Worker]: 'bun ./rollup.build.mjs',
+  },
+  requiredDeps: {
+    [TargetPackage.Common]: ['@owlmeans/context', '@owlmeans/entrypoint'],
+    [TargetPackage.Backend]: ['@owlmeans/context', '@owlmeans/postgres-resource'],
+    [TargetPackage.Api]: ['@owlmeans/server-app'],
+    [TargetPackage.Web]: ['@owlmeans/web-client'],
+    [TargetPackage.Worker]: ['@owlmeans/queue', '@owlmeans/redis-queue'],
+  },
+  // `api` and `worker` both reach the database through `backend`, which is the whole reason
+  // `backend` is a library: two runtimes, one context factory, one set of resources. A `worker`
+  // that stopped depending on `backend` is processing jobs against something else.
+  workspaceDeps: {
+    [TargetPackage.Common]: [],
+    [TargetPackage.Backend]: [TargetPackage.Common],
+    [TargetPackage.Api]: [TargetPackage.Common, TargetPackage.Backend],
+    [TargetPackage.Web]: [TargetPackage.Common],
+    [TargetPackage.Worker]: [TargetPackage.Backend],
+  },
+  workspaceGlob: `${TARGET_PACKAGES_DIR}/*`,
+  workspaceEntries: Object.values(TargetPackage).map(pkg => `${TARGET_PACKAGES_DIR}/${pkg}`),
+  markers: {
+    [`${TARGET_PACKAGES_DIR}/${TargetPackage.Common}/src/index.ts`]: ['./entrypoints.js'],
+    [`${TARGET_PACKAGES_DIR}/${TargetPackage.Backend}/src/index.ts`]: ['./context.js'],
+    [`${TARGET_PACKAGES_DIR}/${TargetPackage.Backend}/src/context.ts`]: ['@owlmeans/context', 'makeContext'],
+    [`${TARGET_PACKAGES_DIR}/${TargetPackage.Api}/src/index.ts`]: ['./owlmeans.js', 'initOwlMeans'],
+    [`${TARGET_PACKAGES_DIR}/${TargetPackage.Api}/src/owlmeans.ts`]: ['@owlmeans/server-app', 'makeContext'],
+    [`${TARGET_PACKAGES_DIR}/${TargetPackage.Web}/src/index.tsx`]: ['@owlmeans/web-client', 'renderApp', './owlmeans'],
+    [`${TARGET_PACKAGES_DIR}/${TargetPackage.Web}/src/owlmeans.ts`]: ['makeContext', 'owlCtx'],
+    // The worker binds nothing but its health port; what makes it a worker is that it listens.
+    [`${TARGET_PACKAGES_DIR}/${TargetPackage.Worker}/src/index.ts`]: ['./owlmeans.js', 'initOwlMeans'],
+    [`${TARGET_PACKAGES_DIR}/${TargetPackage.Worker}/src/owlmeans.ts`]: ['@owlmeans/queue', 'makeContext'],
+    // The build configuration itself: what it reads and what it emits. These are the paths the
+    // publisher spawns and serves, so a config that redirects either one is a different program.
+    // Matched loosely enough to survive the `path.resolve(srcDir, …)` the template writes them
+    // with, and strictly enough that an input or an output somewhere else fails.
+    [`${TARGET_PACKAGES_DIR}/${TargetPackage.Api}/rollup.config.js`]: ['input:', 'index.ts', 'dist', 'index.js'],
+    [`${TARGET_PACKAGES_DIR}/${TargetPackage.Web}/rollup.config.js`]: ['input:', 'index.tsx', 'dist', 'bundle.js'],
+    [`${TARGET_PACKAGES_DIR}/${TargetPackage.Worker}/rollup.config.js`]: ['input:', 'index.ts', 'dist', 'index.js'],
+  },
+}
+
+/**
+ * The legacy layout: three workspace packages under `packages/`.
+ *
+ * Frozen — nothing generates one any more, and every rule here is stated against the trees that
+ * exist rather than against a template this repository still ships (it does not). `backend` is
+ * the HTTP server AND the data layer, which is why it carries both `@owlmeans/server-app` and
+ * `@owlmeans/postgres-resource`; `common` is the only library.
+ */
+export const V1_MANIFEST: TargetLayoutManifest = {
+  layout: TargetLayout.V1,
+  dir: TARGET_LEGACY_PACKAGES_DIR,
+  packages: TARGET_LEGACY_PACKAGES,
+  // `packages/backend` again — the publisher's own marker for this layout.
+  probe: `${TARGET_LEGACY_PACKAGES_DIR}/${TargetLegacyPackage.Backend}/package.json`,
+  files: [
+    'package.json',
+    'bunfig.toml',
+    `${TARGET_LEGACY_PACKAGES_DIR}/${TargetLegacyPackage.Common}/package.json`,
+    `${TARGET_LEGACY_PACKAGES_DIR}/${TargetLegacyPackage.Common}/tsconfig.json`,
+    `${TARGET_LEGACY_PACKAGES_DIR}/${TargetLegacyPackage.Common}/src/index.ts`,
+    `${TARGET_LEGACY_PACKAGES_DIR}/${TargetLegacyPackage.Common}/src/entrypoints.ts`,
+    `${TARGET_LEGACY_PACKAGES_DIR}/${TargetLegacyPackage.Backend}/package.json`,
+    `${TARGET_LEGACY_PACKAGES_DIR}/${TargetLegacyPackage.Backend}/tsconfig.json`,
+    `${TARGET_LEGACY_PACKAGES_DIR}/${TargetLegacyPackage.Backend}/rollup.config.js`,
+    `${TARGET_LEGACY_PACKAGES_DIR}/${TargetLegacyPackage.Backend}/rollup.build.mjs`,
+    `${TARGET_LEGACY_PACKAGES_DIR}/${TargetLegacyPackage.Backend}/src/index.ts`,
+    `${TARGET_LEGACY_PACKAGES_DIR}/${TargetLegacyPackage.Backend}/src/owlmeans.ts`,
+    `${TARGET_LEGACY_PACKAGES_DIR}/${TargetLegacyPackage.Backend}/src/config.ts`,
+    `${TARGET_LEGACY_PACKAGES_DIR}/${TargetLegacyPackage.Backend}/src/entrypoints.ts`,
+    `${TARGET_LEGACY_PACKAGES_DIR}/${TargetLegacyPackage.Frontend}/package.json`,
+    `${TARGET_LEGACY_PACKAGES_DIR}/${TargetLegacyPackage.Frontend}/tsconfig.json`,
+    `${TARGET_LEGACY_PACKAGES_DIR}/${TargetLegacyPackage.Frontend}/rollup.config.js`,
+    `${TARGET_LEGACY_PACKAGES_DIR}/${TargetLegacyPackage.Frontend}/rollup.build.mjs`,
+    `${TARGET_LEGACY_PACKAGES_DIR}/${TargetLegacyPackage.Frontend}/src/index.tsx`,
+    `${TARGET_LEGACY_PACKAGES_DIR}/${TargetLegacyPackage.Frontend}/src/owlmeans.ts`,
+    `${TARGET_LEGACY_PACKAGES_DIR}/${TargetLegacyPackage.Frontend}/src/config.ts`,
+    `${TARGET_LEGACY_PACKAGES_DIR}/${TargetLegacyPackage.Frontend}/src/entrypoints.ts`,
+  ],
+  protectedFiles: [
+    ...ROOT_PROTECTED,
+    ...HARNESS_PROTECTED,
+    ...TARGET_LEGACY_PACKAGES.flatMap(pkg =>
+      [`${TARGET_LEGACY_PACKAGES_DIR}/${pkg}/package.json`, `${TARGET_LEGACY_PACKAGES_DIR}/${pkg}/tsconfig.json`]),
+    ...TARGET_LEGACY_BUNDLED_PACKAGES.flatMap(pkg =>
+      [`${TARGET_LEGACY_PACKAGES_DIR}/${pkg}/rollup.config.js`, `${TARGET_LEGACY_PACKAGES_DIR}/${pkg}/rollup.build.mjs`]),
+  ],
+  buildScripts: {
+    [TargetLegacyPackage.Common]: 'tsc -b',
+    [TargetLegacyPackage.Backend]: 'bun ./rollup.build.mjs',
+    [TargetLegacyPackage.Frontend]: 'bun ./rollup.build.mjs',
+  },
+  requiredDeps: {
+    [TargetLegacyPackage.Common]: ['@owlmeans/context', '@owlmeans/entrypoint'],
+    [TargetLegacyPackage.Backend]: ['@owlmeans/server-app', '@owlmeans/postgres-resource'],
+    [TargetLegacyPackage.Frontend]: ['@owlmeans/web-client'],
+  },
+  workspaceDeps: {
+    [TargetLegacyPackage.Common]: [],
+    [TargetLegacyPackage.Backend]: [TargetLegacyPackage.Common],
+    [TargetLegacyPackage.Frontend]: [TargetLegacyPackage.Common],
+  },
+  workspaceGlob: `${TARGET_LEGACY_PACKAGES_DIR}/*`,
+  workspaceEntries: TARGET_LEGACY_PACKAGES.map(pkg => `${TARGET_LEGACY_PACKAGES_DIR}/${pkg}`),
+  markers: {
+    [`${TARGET_LEGACY_PACKAGES_DIR}/${TargetLegacyPackage.Common}/src/index.ts`]: ['./entrypoints.js'],
+    [`${TARGET_LEGACY_PACKAGES_DIR}/${TargetLegacyPackage.Backend}/src/index.ts`]: ['./owlmeans.js', 'initOwlMeans'],
+    [`${TARGET_LEGACY_PACKAGES_DIR}/${TargetLegacyPackage.Backend}/src/owlmeans.ts`]: ['@owlmeans/server-app', 'makeContext'],
+    [`${TARGET_LEGACY_PACKAGES_DIR}/${TargetLegacyPackage.Frontend}/src/index.tsx`]:
+      ['@owlmeans/web-client', 'renderApp', './owlmeans'],
+    [`${TARGET_LEGACY_PACKAGES_DIR}/${TargetLegacyPackage.Frontend}/src/owlmeans.ts`]: ['makeContext', 'owlCtx'],
+    [`${TARGET_LEGACY_PACKAGES_DIR}/${TargetLegacyPackage.Backend}/rollup.config.js`]:
+      ['input:', 'index.ts', 'dist', 'index.js'],
+    [`${TARGET_LEGACY_PACKAGES_DIR}/${TargetLegacyPackage.Frontend}/rollup.config.js`]:
+      ['input:', 'index.tsx', 'dist', 'bundle.js'],
+  },
+}

package/src/integrity/layout/consts.ts

@@ -0,0 +1,79 @@
+import { TargetLayout } from '../consts.js'
+import type { TargetLayoutManifest } from '../types.js'
+import { V1_MANIFEST, V2_MANIFEST } from './consts.local.js'
+
+/**
+ * Every layout the platform is willing to run, keyed by its own name.
+ *
+ * Declared current-first, and the order is load-bearing: detection walks it and takes the first
+ * probe it finds, so a half-migrated tree carrying both is verified against the layout the
+ * platform generates today rather than against the frozen one.
+ */
+export const TARGET_LAYOUTS: Readonly<Record<TargetLayout, TargetLayoutManifest>> = {
+  [TargetLayout.V2]: V2_MANIFEST,
+  [TargetLayout.V1]: V1_MANIFEST,
+}
+
+/**
+ * The files whose presence tells the layouts apart.
+ *
+ * Each layout's probe is a path the other cannot have. They are members of their own layout's
+ * file list too, so a caller that reads {@link TARGET_INTEGRITY_FILES} always has both in hand —
+ * which is the whole reason detection works at all. It did not before: the probe for the legacy
+ * layout was declared but never read, so `detectTargetLayout` could only ever answer `V2`.
+ */
+export const TARGET_LAYOUT_PROBE_FILES: readonly string[] =
+  Object.values(TARGET_LAYOUTS).map(manifest => manifest.probe)
+
+/**
+ * Files a caller must read and hand to `verifyTargetShape`.
+ *
+ * The UNION over every layout, because a caller reads before it knows which layout it is holding
+ * and the probes are what settle that. The verifier reports only the files its selected layout
+ * actually requires, so the extra reads cost a `stat` each and never a violation.
+ *
+ * The verifier is pure and does no IO of its own — the publisher reads these from the PVC, and
+ * a test reads them from the template tree. A path that does not exist is passed as `null`,
+ * which the verifier reports rather than skipping: absence is a violation for everything here.
+ */
+export const TARGET_INTEGRITY_FILES: readonly string[] = [
+  ...new Set(Object.values(TARGET_LAYOUTS).flatMap(manifest => manifest.files)),
+]
+
+/**
+ * Files no user-facing write may touch, through any path — the union over every layout.
+ *
+ * These are the ones that decide what gets EXECUTED — the build scripts, the package manifests
+ * that name them, the compiler configuration that resolves them, and the install configuration.
+ * The agent harness is here for the same reason: `.claude/settings.json` declares a
+ * `SessionStart` hook and `.agents/scripts/link-skills.sh` is the command it spawns, so a write
+ * to either runs code in the slot the next time an agent session opens, with no build and no
+ * request involved. The agent's own generator already refuses the wiring sources
+ * (`WIRING_SOURCES`), but that guard is LLM-scoped: it never saw a manual editor save and never
+ * saw a git merge.
+ *
+ * The union rather than the current layout's list, because this is a path-shaped refusal with
+ * nothing to gain from being narrow: a v2 path cannot exist in a v1 tree, so covering both costs
+ * nothing and covers the legacy slots that were left writable.
+ */
+export const TARGET_PROTECTED_FILES: readonly string[] = [
+  ...new Set(Object.values(TARGET_LAYOUTS).flatMap(manifest => manifest.protectedFiles)),
+]
+
+/**
+ * The current layout's own rules, kept as named constants because consumers outside the verifier
+ * ask about the tree the platform generates today — never about a frozen one.
+ */
+export const TARGET_BUILD_SCRIPTS: Readonly<Record<string, string>> = V2_MANIFEST.buildScripts
+
+export const TARGET_REQUIRED_DEPS: Readonly<Record<string, readonly string[]>> =
+  V2_MANIFEST.requiredDeps
+
+export const TARGET_WORKSPACE_DEPS: Readonly<Record<string, readonly string[]>> =
+  V2_MANIFEST.workspaceDeps
+
+export const TARGET_ENTRY_MARKERS: Readonly<Record<string, readonly string[]>> = V2_MANIFEST.markers
+
+export const TARGET_WORKSPACE_GLOB = V2_MANIFEST.workspaceGlob
+
+export const TARGET_WORKSPACE_ENTRIES: readonly string[] = V2_MANIFEST.workspaceEntries

package/src/integrity/layout/types.ts

@@ -0,0 +1,35 @@
+import type { TargetLayout } from '../consts.js'
+import type { TargetLayoutManifest } from '../types.js'
+
+/** The layouts a target tree may be in: what each asserts, and which one a tree is. */
+export interface TargetLayoutHelper {
+  /** What one layout asserts. */
+  targetManifest: (layout: TargetLayout) => TargetLayoutManifest
+  /**
+   * Whether a tree of this layout can still be GENERATED INTO.
+   *
+   * A legacy target is served, built and run exactly like any other — that is the whole point of
+   * verifying it against its own manifest. What no longer works on it is code generation: every
+   * path builder, every stamped import specifier and the whole `docs/` metadata tree name the
+   * current layout's packages, so a story implemented into a legacy tree writes files into
+   * directories its workspace does not contain. That fails silently — the build succeeds, the
+   * story completes and the application does not change — which is why the platform refuses
+   * instead, and names re-initialization as the one cure.
+   *
+   * `undefined` reads as current: a publisher that predates layout reporting omits it, and reading
+   * that silence as legacy would refuse development for every slot already in the cluster.
+   */
+  isLegacyLayout: (layout: TargetLayout | string | undefined | null) => boolean
+  /**
+   * Which layout a tree is in, from its files alone — IO-free, like everything else here.
+   *
+   * A tree that shows neither probe is reported as the current layout: it is not a target at all,
+   * and the integrity report is what has to say so, in the vocabulary of the layout the platform
+   * generates today.
+   */
+  detectTargetLayout: (files: Record<string, string | null>) => TargetLayout
+  /** `<slug>-<package>` — the only way a workspace package is ever named, in either layout. */
+  targetPackageName: (slug: string, pkg: string) => string
+  /** Everything one package must declare, once the root manifest has named the slug. */
+  targetRequiredDeps: (slug: string, pkg: string, layout?: TargetLayout) => string[]
+}

package/src/integrity/layout.ts

@@ -0,0 +1,39 @@
+import { TARGET_CURRENT_LAYOUT, TargetLayout } from './consts.js'
+import type { TargetLayoutManifest } from './types.js'
+import { TARGET_LAYOUTS } from './layout/consts.js'
+import type { TargetLayoutHelper } from './layout/types.js'
+
+export const createTargetLayoutHelper = (): TargetLayoutHelper => {
+  const targetManifest = (layout: TargetLayout): TargetLayoutManifest =>
+    TARGET_LAYOUTS[layout]
+
+  const isLegacyLayout = (layout: TargetLayout | string | undefined | null): boolean =>
+    layout != null && layout !== TARGET_CURRENT_LAYOUT
+
+  const detectTargetLayout = (files: Record<string, string | null>): TargetLayout => {
+    for (const manifest of Object.values(TARGET_LAYOUTS)) {
+      if (files[manifest.probe] != null) {
+        return manifest.layout
+      }
+    }
+
+    return TARGET_CURRENT_LAYOUT
+  }
+
+  const targetPackageName = (slug: string, pkg: string): string => `${slug}-${pkg}`
+
+  const targetRequiredDeps = (
+    slug: string, pkg: string, layout: TargetLayout = TARGET_CURRENT_LAYOUT
+  ): string[] => {
+    const manifest = targetManifest(layout)
+
+    return [
+      ...(manifest.requiredDeps[pkg] ?? []),
+      ...(manifest.workspaceDeps[pkg] ?? []).map(dep => targetPackageName(slug, dep)),
+    ]
+  }
+
+  return { targetManifest, isLegacyLayout, detectTargetLayout, targetPackageName, targetRequiredDeps }
+}
+
+export const targetLayoutHelper = createTargetLayoutHelper()

package/src/integrity/types.ts

@@ -34,7 +34,9 @@ export interface TargetIntegrityReport {
  * The file map handed to the verifier: every path in `TARGET_INTEGRITY_FILES`, with `null` for
  * one that could not be read. The verifier does no IO — see `verifyTargetShape`.
  */
-export type TargetFileMap = Record<string, string | null>
+export interface TargetFileMap {
+  [path: string]: string | null
+}
 
 /**
  * Everything one layout asserts about a tree.