@owlmeans/viable-common 0.0.43 → 0.0.45

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

@@ -1,4 +1,4 @@
-import type { IntegrityRule, TargetLayout } from './consts.js'
+import { type IntegrityRule, TargetLayout } from './consts.js'
 
 /** One reason a tree was refused. */
 export interface IntegrityViolation {
@@ -34,4 +34,39 @@ 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.
+ *
+ * One record per layout rather than a set of parallel constants, because the rules are the same
+ * questions asked of a different package set: a rule that exists for one layout and is forgotten
+ * for the other is a hole that nothing fails on.
+ */
+export interface TargetLayoutManifest {
+  layout: TargetLayout
+  /** Directory holding the workspace packages, relative to the sandbox root. */
+  dir: string
+  /** Package directory names, in build order. */
+  packages: readonly string[]
+  /** The one file whose presence identifies this layout and appears in no other. */
+  probe: string
+  /** Every file the verifier reads for this layout. */
+  files: readonly string[]
+  /** Files no user-facing write may touch in a tree of this layout. */
+  protectedFiles: readonly string[]
+  /** The exact `scripts.build` each package must declare. */
+  buildScripts: Readonly<Record<string, string>>
+  /** Framework dependencies without which a package cannot be the generated app. */
+  requiredDeps: Readonly<Record<string, readonly string[]>>
+  /** The workspace siblings each package must depend on. */
+  workspaceDeps: Readonly<Record<string, readonly string[]>>
+  /** The glob spelling of the root manifest's workspace list. */
+  workspaceGlob: string
+  /** The written-out spelling of the same list. */
+  workspaceEntries: readonly string[]
+  /** Markers proving an entry file is still the framework's entry, keyed by file. */
+  markers: Readonly<Record<string, readonly string[]>>
+}

package/src/integrity/utils.ts

@@ -0,0 +1,21 @@
+import type { TargetLayout } from './consts.js'
+import { targetLayoutHelper } from './layout.js'
+import type { TargetLayoutManifest } from './types.js'
+
+/** @deprecated compat:factory-refactor — use `targetLayoutHelper.targetManifest(…)` */
+export const targetManifest = (layout: TargetLayout): TargetLayoutManifest => targetLayoutHelper.targetManifest(layout)
+
+/** @deprecated compat:factory-refactor — use `targetLayoutHelper.isLegacyLayout(…)` */
+export const isLegacyLayout = (layout: TargetLayout | string | undefined | null): boolean =>
+  targetLayoutHelper.isLegacyLayout(layout)
+
+/** @deprecated compat:factory-refactor — use `targetLayoutHelper.detectTargetLayout(…)` */
+export const detectTargetLayout = (files: Record<string, string | null>): TargetLayout =>
+  targetLayoutHelper.detectTargetLayout(files)
+
+/** @deprecated compat:factory-refactor — use `targetLayoutHelper.targetPackageName(…)` */
+export const targetPackageName = (slug: string, pkg: string): string => targetLayoutHelper.targetPackageName(slug, pkg)
+
+/** @deprecated compat:factory-refactor — use `targetLayoutHelper.targetRequiredDeps(…)` */
+export const targetRequiredDeps = (slug: string, pkg: string, layout?: TargetLayout): string[] =>
+  targetLayoutHelper.targetRequiredDeps(slug, pkg, layout)

package/src/integrity/verify/types.ts

@@ -0,0 +1,26 @@
+import type { TargetFileMap, TargetIntegrityReport } from '../types.js'
+
+/** The integrity verdict on a target tree, and its one-line-per-violation rendering. */
+export interface TargetIntegrityHelper {
+  /**
+   * 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.
+   */
+  verifyTargetShape: (files: TargetFileMap) => TargetIntegrityReport
+  /** One line per violation — what goes into a log, `slot.lastError`, or a build diagnostic. */
+  formatIntegrityReport: (report: TargetIntegrityReport) => string
+}

package/src/integrity/verify.ts

@@ -1,221 +1,215 @@
-import {
-  detectTargetLayout, IntegrityRule, TARGET_FORBIDDEN_SCRIPTS, TARGET_SLUG_PATTERN,
-  targetManifest, targetPackageName, targetRequiredDeps
-} from './consts.js'
+import { IntegrityRule, TARGET_FORBIDDEN_SCRIPTS, TARGET_SLUG_PATTERN } from './consts.js'
+import { targetLayoutHelper } from './layout.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.`
-      })
+import type { TargetIntegrityHelper } from './verify/types.js'
+
+export const createTargetIntegrityHelper = (): TargetIntegrityHelper => {
+  const verifyTargetShape = (files: TargetFileMap): TargetIntegrityReport => {
+    const violations: IntegrityViolation[] = []
+    const layout = targetLayoutHelper.detectTargetLayout(files)
+    const manifest = targetLayoutHelper.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 }
+    // 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()
 
-  function checkRoot(): string | null {
-    const found = readJson('package.json')
-    if (found == null) return null
+    return { ok: violations.length === 0, violations, layout }
 
-    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".'
-      })
-    }
+    function checkRoot(): string | null {
+      const found = readJson('package.json')
+      if (found == null) return null
 
-    // 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(', ')}.`
-      })
-    }
+      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".'
+        })
+      }
 
-    checkScripts('package.json', found)
+      // 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(', ')}.`
+        })
+      }
 
-    return TARGET_SLUG_PATTERN.test(name) ? name : null
-  }
+      checkScripts('package.json', found)
 
-  /**
-   * `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.'
-      })
+      return TARGET_SLUG_PATTERN.test(name) ? name : null
     }
-  }
 
-  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) {
+    /**
+     * `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, rule: IntegrityRule.PackageName,
-          detail: `Package must be named "${expected}", not "${String(found.name)}".`
+          path: 'bunfig.toml', rule: IntegrityRule.InstallConfig,
+          detail: 'bunfig.toml may only declare the hoisted install linker.'
         })
       }
     }
-    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) {
+    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 = targetLayoutHelper.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.RequiredDependency,
-          detail: `Package "${pkg}" must depend on ${dep}.`
+          path, rule: IntegrityRule.ModuleType,
+          detail: `Package "${pkg}" must declare "type": "module".`
         })
       }
-    }
-  }
 
-  /** 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) {
+      const scripts = asRecord(found.scripts)
+      if (scripts.build !== manifest.buildScripts[pkg]) {
+        // The one the platform actually spawns.
         violations.push({
-          path, rule: IntegrityRule.LifecycleScript,
-          detail: `Lifecycle script "${hook}" is not allowed in a target project.`
+          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 targetLayoutHelper.targetRequiredDeps(slug, pkg, layout)) {
+        if (deps[dep] == null) {
+          violations.push({
+            path, rule: IntegrityRule.RequiredDependency,
+            detail: `Package "${pkg}" must depend on ${dep}.`
+          })
+        }
+      }
     }
-  }
 
-  function checkMarkers(): void {
-    for (const [path, markers] of Object.entries(manifest.markers)) {
-      const content = files[path]
-      if (content == null) continue
+    /** 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.`
+          })
+        }
+      }
+    }
 
-      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 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 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.`
-    })
+    function reportUnreadable(path: string): null {
+      violations.push({
+        path, rule: IntegrityRule.Unreadable, detail: `${path} is not a readable JSON object.`
+      })
+
+      return null
+    }
 
-    return null
+    function asRecord(value: unknown): Record<string, string> {
+      return typeof value === 'object' && value !== null
+        ? value as Record<string, string>
+        : {}
+    }
   }
 
-  function asRecord(value: unknown): Record<string, string> {
-    return typeof value === 'object' && value !== null
-      ? value as Record<string, string>
-      : {}
-  }
+  const formatIntegrityReport = (report: TargetIntegrityReport): string =>
+    report.violations.map(violation => `${violation.path}: ${violation.detail}`).join('\n')
+
+  return { verifyTargetShape, formatIntegrityReport }
 }
 
-/** One line per violation — what goes into a log, `slot.lastError`, or a build diagnostic. */
+export const targetIntegrityHelper = createTargetIntegrityHelper()
+
+/** @deprecated compat:factory-refactor — use `targetIntegrityHelper.verifyTargetShape(…)` */
+export const verifyTargetShape = (files: TargetFileMap): TargetIntegrityReport =>
+  targetIntegrityHelper.verifyTargetShape(files)
+
+/** @deprecated compat:factory-refactor — use `targetIntegrityHelper.formatIntegrityReport(…)` */
 export const formatIntegrityReport = (report: TargetIntegrityReport): string =>
-  report.violations.map(violation => `${violation.path}: ${violation.detail}`).join('\n')
+  targetIntegrityHelper.formatIntegrityReport(report)

package/src/intent/consts.ts

@@ -12,6 +12,10 @@
  * read the same declarations, and none of them may reinvent a name the others parse.
  */
 
+import { DISPATCHER } from '@owlmeans/auth'
+import { HOME } from '@owlmeans/context'
+import type { ShallowFlow } from '@owlmeans/flow'
+
 /** Every address of the hand-off. API routes are guest routes; the landing is a screen. */
 export const intent = Object.freeze({
   base: 'viable:manager-api:intent:base',
@@ -64,3 +68,66 @@ export enum IntentFlowStep {
   /** The platform's home screen, where the draft is offered back. */
   Review = 'review',
 }
+
+const payloadMap = { [INTENT_PAYLOAD_REF]: 0 }
+
+/**
+ * The hand-off flow both sides walk.
+ *
+ * `compose` runs on the public site: the prompt is stashed and `handoff` carries the reference to
+ * `land`, whose module is the platform's landing screen — so the site redirects to
+ * `land`'s address with the payload as query. The landing then enters at `land` FRESH (the
+ * reference arrives as `?ref=`, never as a serialized token, which the platform's own sign-in
+ * parses from `?flow=` on every page), and either goes on to `review` (signed in) or parks the flow
+ * with `suspendFlow` at `sign-in`, whose non-explicit way forward is `review` — the home screen —
+ * so whichever sign-in method finishes lands there.
+ *
+ * The steps address CONCRETE entrypoint aliases, never `$`-prefixed references: this flow is never
+ * the live `FlowService` model and nothing here needs `configureFlows`.
+ */
+export const intentFlow: ShallowFlow = {
+  flow: INTENT_FLOW,
+  initialStep: IntentFlowStep.Compose,
+  steps: {
+    [IntentFlowStep.Compose]: {
+      index: 0,
+      step: IntentFlowStep.Compose,
+      service: '',
+      initial: true,
+      payloadMap,
+      transitions: {
+        handoff: { transition: 'handoff', step: IntentFlowStep.Land },
+      },
+    },
+    [IntentFlowStep.Land]: {
+      index: 1,
+      step: IntentFlowStep.Land,
+      service: '',
+      module: intent.landing,
+      initial: true,
+      payloadMap,
+      transitions: {
+        review: { transition: 'review', step: IntentFlowStep.Review },
+        'sign-in': { transition: 'sign-in', step: IntentFlowStep.SignIn, explicit: true },
+      },
+    },
+    [IntentFlowStep.SignIn]: {
+      index: 2,
+      step: IntentFlowStep.SignIn,
+      service: '',
+      module: DISPATCHER,
+      payloadMap,
+      transitions: {
+        next: { transition: 'next', step: IntentFlowStep.Review },
+      },
+    },
+    [IntentFlowStep.Review]: {
+      index: 3,
+      step: IntentFlowStep.Review,
+      service: '',
+      module: HOME,
+      payloadMap,
+      transitions: {},
+    },
+  },
+}