@vyuhlabs/dxkit 2.21.2 → 2.22.0

package/dist/analyzers/flow/setup.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Flow setup — the detection + apply behind folding `flow init` into `init`.
+ *
+ * `init` runs `detectFlowTopology` to decide whether a repo even HAS a UI→API
+ * surface worth gating (if not, the init wizard stays silent — zero burden).
+ * When it does, init surfaces the two learnings this module computes — the
+ * dominant host-helper to strip, and any multiple backend services — as confirm
+ * prompts, then `applyFlowSetup` writes the resulting config (`.dxkit/policy.json:flow`
+ * plus `.dxkit/workspace.json` when participants are named).
+ *
+ * Detection reuses the same `gatherFlowModel` the gate runs (Rule 2 — one
+ * extractor); it never re-parses source itself. Fail-open throughout — an error
+ * degrades to "no flow detected", which the caller treats as "don't ask".
+ */
+import { type FlowGateMode } from './config';
+import { type WorkspaceParticipant } from '../../workspace';
+import type { ClientCall, RouteEndpoint } from './extract';
+/** Which halves of the UI→API contract this repo contains. */
+export type FlowTopology = 'monorepo' | 'consumer-only' | 'provider-only' | 'none';
+export interface FlowDetection {
+    /** monorepo (both sides) · consumer-only (calls, no routes) · provider-only
+     *  (routes, no calls) · none (nothing to gate — stay silent). */
+    readonly topology: FlowTopology;
+    readonly callCount: number;
+    readonly routeCount: number;
+    /** Calls that already bind to a served route — the healthy baseline. */
+    readonly resolvedCount: number;
+    /** Dominant host-helper prefix(es) across client calls — the strip-prefix the
+     *  setup offers so a call like `${Config.api()}/x` matches a served `/x`. */
+    readonly suggestedStripPrefixes: readonly string[];
+    /** Distinct top-level directories that serve routes — a best-effort
+     *  multi-service hint (robust multi-repo splitting is M4.3's `flow publish`). */
+    readonly detectedServices: readonly string[];
+}
+/**
+ * Detect the repo's flow topology by running the shared extractor. Returns
+ * `topology: 'none'` (and the caller stays silent) when no flow-capable pack is
+ * active, when extraction finds nothing, or on any error.
+ */
+export declare function detectFlowTopology(cwd: string): Promise<FlowDetection>;
+/**
+ * The prefix of a raw client URL that is NOT part of the route path — an
+ * absolute `scheme://host`, or a leading `${...}` base-URL helper template. A
+ * relative URL (`/articles`) has no host prefix. This is exactly what a
+ * strip-prefix removes so a templated call matches a served route.
+ */
+export declare function hostPrefixOf(rawUrl: string): string | null;
+/** Host-helper prefixes ranked by frequency across calls, most common first.
+ *  Empty when calls are all relative (nothing to strip). */
+export declare function dominantHostPrefixes(calls: readonly ClientCall[]): string[];
+/** Distinct top-level directories that contain served routes — a coarse
+ *  multi-service signal. Returns [] when routes live under one top-level dir
+ *  (a single service). Deeper (nested / multi-repo) service splitting is
+ *  M4.3's concern; here we only surface the obvious top-level split. */
+export declare function servicesFromRoutes(routes: readonly RouteEndpoint[]): string[];
+/** The confirmed setup a caller applies after the init prompts. */
+export interface FlowSetupDecision {
+    readonly mode: FlowGateMode;
+    readonly stripUrlPrefixes: readonly string[];
+    /** Named participants → written to workspace.json (the multi-service /
+     *  cross-repo case). Omitted for a single-service monorepo. */
+    readonly participants?: readonly WorkspaceParticipant[];
+}
+/**
+ * Apply a confirmed flow setup: write `flow.mode` (+ strip prefixes) into
+ * `.dxkit/policy.json` via the canonical writer, and — when participants are
+ * named — `.dxkit/workspace.json`. Returns the repo-relative paths written (for
+ * the init summary). Never throws on an already-current policy (idempotent).
+ */
+export declare function applyFlowSetup(cwd: string, decision: FlowSetupDecision): string[];
+//# sourceMappingURL=setup.d.ts.map

package/dist/analyzers/flow/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../src/analyzers/flow/setup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAkB,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE3D,8DAA8D;AAC9D,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,eAAe,GAAG,eAAe,GAAG,MAAM,CAAC;AAEnF,MAAM,WAAW,aAAa;IAC5B;qEACiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wEAAwE;IACxE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;iFAC6E;IAC7E,QAAQ,CAAC,sBAAsB,EAAE,SAAS,MAAM,EAAE,CAAC;IACnD;qFACiF;IACjF,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AAWD;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAmC5E;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAU1D;AAED;4DAC4D;AAC5D,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,EAAE,CAO3E;AAED;;;wEAGwE;AACxE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,EAAE,CAO7E;AAED,mEAAmE;AACnE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C;mEAC+D;IAC/D,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;CACzD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,GAAG,MAAM,EAAE,CAcjF"}

package/dist/analyzers/flow/setup.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * Flow setup — the detection + apply behind folding `flow init` into `init`.
+ *
+ * `init` runs `detectFlowTopology` to decide whether a repo even HAS a UI→API
+ * surface worth gating (if not, the init wizard stays silent — zero burden).
+ * When it does, init surfaces the two learnings this module computes — the
+ * dominant host-helper to strip, and any multiple backend services — as confirm
+ * prompts, then `applyFlowSetup` writes the resulting config (`.dxkit/policy.json:flow`
+ * plus `.dxkit/workspace.json` when participants are named).
+ *
+ * Detection reuses the same `gatherFlowModel` the gate runs (Rule 2 — one
+ * extractor); it never re-parses source itself. Fail-open throughout — an error
+ * degrades to "no flow detected", which the caller treats as "don't ask".
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectFlowTopology = detectFlowTopology;
+exports.hostPrefixOf = hostPrefixOf;
+exports.dominantHostPrefixes = dominantHostPrefixes;
+exports.servicesFromRoutes = servicesFromRoutes;
+exports.applyFlowSetup = applyFlowSetup;
+const languages_1 = require("../../languages");
+const gather_1 = require("./gather");
+const model_1 = require("./model");
+const config_1 = require("./config");
+const workspace_1 = require("../../workspace");
+const NONE = {
+    topology: 'none',
+    callCount: 0,
+    routeCount: 0,
+    resolvedCount: 0,
+    suggestedStripPrefixes: [],
+    detectedServices: [],
+};
+/**
+ * Detect the repo's flow topology by running the shared extractor. Returns
+ * `topology: 'none'` (and the caller stays silent) when no flow-capable pack is
+ * active, when extraction finds nothing, or on any error.
+ */
+async function detectFlowTopology(cwd) {
+    // Cheap gate first: if no active pack extracts flow, don't even run the
+    // extractor (keeps `init --yes` on a non-flow repo fast).
+    if ((0, languages_1.allFlowSourceExtensions)((0, languages_1.detectActiveLanguages)(cwd)).length === 0)
+        return NONE;
+    let model;
+    try {
+        model = await (0, gather_1.gatherFlowModel)({ roots: [cwd] });
+    }
+    catch {
+        return NONE;
+    }
+    const callCount = model.calls.length;
+    const routeCount = model.routes.length;
+    if (callCount === 0 && routeCount === 0)
+        return NONE;
+    const resolvedCount = model.bindings.filter((b) => b.route !== null && !(0, model_1.isPlaceholderOnlyPath)(b.route.path)).length;
+    const topology = callCount > 0 && routeCount > 0
+        ? 'monorepo'
+        : callCount > 0
+            ? 'consumer-only'
+            : 'provider-only';
+    return {
+        topology,
+        callCount,
+        routeCount,
+        resolvedCount,
+        suggestedStripPrefixes: dominantHostPrefixes(model.calls),
+        detectedServices: servicesFromRoutes(model.routes),
+    };
+}
+/**
+ * The prefix of a raw client URL that is NOT part of the route path — an
+ * absolute `scheme://host`, or a leading `${...}` base-URL helper template. A
+ * relative URL (`/articles`) has no host prefix. This is exactly what a
+ * strip-prefix removes so a templated call matches a served route.
+ */
+function hostPrefixOf(rawUrl) {
+    // A template-literal URL is captured WITH its backticks (`${Config.api()}/x`);
+    // strip a leading one so the `${...}` head is at the string start. A plain
+    // string literal is captured without quotes, so this is a no-op for it.
+    const s = rawUrl.replace(/^`/, '');
+    const abs = /^(https?:\/\/[^/`]+)/.exec(s);
+    if (abs)
+        return abs[1];
+    const tmpl = /^(\$\{[^}]+\})/.exec(s);
+    if (tmpl)
+        return tmpl[1];
+    return null;
+}
+/** Host-helper prefixes ranked by frequency across calls, most common first.
+ *  Empty when calls are all relative (nothing to strip). */
+function dominantHostPrefixes(calls) {
+    const counts = new Map();
+    for (const c of calls) {
+        const p = hostPrefixOf(c.rawUrl);
+        if (p)
+            counts.set(p, (counts.get(p) ?? 0) + 1);
+    }
+    return [...counts.entries()].sort((a, b) => b[1] - a[1]).map(([p]) => p);
+}
+/** Distinct top-level directories that contain served routes — a coarse
+ *  multi-service signal. Returns [] when routes live under one top-level dir
+ *  (a single service). Deeper (nested / multi-repo) service splitting is
+ *  M4.3's concern; here we only surface the obvious top-level split. */
+function servicesFromRoutes(routes) {
+    const dirs = new Set();
+    for (const r of routes) {
+        const top = r.file.split(/[/\\]/)[0];
+        if (top && top !== r.file)
+            dirs.add(top); // skip files at repo root (no dir)
+    }
+    return dirs.size >= 2 ? [...dirs].sort() : [];
+}
+/**
+ * Apply a confirmed flow setup: write `flow.mode` (+ strip prefixes) into
+ * `.dxkit/policy.json` via the canonical writer, and — when participants are
+ * named — `.dxkit/workspace.json`. Returns the repo-relative paths written (for
+ * the init summary). Never throws on an already-current policy (idempotent).
+ */
+function applyFlowSetup(cwd, decision) {
+    const written = [];
+    const changed = (0, config_1.writeFlowPolicy)(cwd, {
+        mode: decision.mode,
+        ...(decision.stripUrlPrefixes.length
+            ? { stripUrlPrefixes: [...decision.stripUrlPrefixes] }
+            : {}),
+    });
+    if (changed)
+        written.push('.dxkit/policy.json');
+    if (decision.participants && decision.participants.length > 0) {
+        (0, workspace_1.writeWorkspace)(cwd, { participants: [...decision.participants], external: [] });
+        written.push('.dxkit/workspace.json');
+    }
+    return written;
+}
+//# sourceMappingURL=setup.js.map

package/dist/analyzers/flow/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../../src/analyzers/flow/setup.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;AA0CH,gDAmCC;AAQD,oCAUC;AAID,oDAOC;AAMD,gDAOC;AAiBD,wCAcC;AApJD,+CAAiF;AACjF,qCAA2C;AAC3C,mCAAgD;AAChD,qCAA8D;AAC9D,+CAA4E;AAsB5E,MAAM,IAAI,GAAkB;IAC1B,QAAQ,EAAE,MAAM;IAChB,SAAS,EAAE,CAAC;IACZ,UAAU,EAAE,CAAC;IACb,aAAa,EAAE,CAAC;IAChB,sBAAsB,EAAE,EAAE;IAC1B,gBAAgB,EAAE,EAAE;CACrB,CAAC;AAEF;;;;GAIG;AACI,KAAK,UAAU,kBAAkB,CAAC,GAAW;IAClD,wEAAwE;IACxE,0DAA0D;IAC1D,IAAI,IAAA,mCAAuB,EAAC,IAAA,iCAAqB,EAAC,GAAG,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAElF,IAAI,KAAK,CAAC;IACV,IAAI,CAAC;QACH,KAAK,GAAG,MAAM,IAAA,wBAAe,EAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC;IACrC,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;IACvC,IAAI,SAAS,KAAK,CAAC,IAAI,UAAU,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAErD,MAAM,aAAa,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CACzC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,IAAI,IAAI,CAAC,IAAA,6BAAqB,EAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAChE,CAAC,MAAM,CAAC;IAET,MAAM,QAAQ,GACZ,SAAS,GAAG,CAAC,IAAI,UAAU,GAAG,CAAC;QAC7B,CAAC,CAAC,UAAU;QACZ,CAAC,CAAC,SAAS,GAAG,CAAC;YACb,CAAC,CAAC,eAAe;YACjB,CAAC,CAAC,eAAe,CAAC;IAExB,OAAO;QACL,QAAQ;QACR,SAAS;QACT,UAAU;QACV,aAAa;QACb,sBAAsB,EAAE,oBAAoB,CAAC,KAAK,CAAC,KAAK,CAAC;QACzD,gBAAgB,EAAE,kBAAkB,CAAC,KAAK,CAAC,MAAM,CAAC;KACnD,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAgB,YAAY,CAAC,MAAc;IACzC,+EAA+E;IAC/E,2EAA2E;IAC3E,wEAAwE;IACxE,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACnC,MAAM,GAAG,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC3C,IAAI,GAAG;QAAE,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC;IACvB,MAAM,IAAI,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACtC,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC;IACzB,OAAO,IAAI,CAAC;AACd,CAAC;AAED;4DAC4D;AAC5D,SAAgB,oBAAoB,CAAC,KAA4B;IAC/D,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,MAAM,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACjC,IAAI,CAAC;YAAE,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,CAAC,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;AAC3E,CAAC;AAED;;;wEAGwE;AACxE,SAAgB,kBAAkB,CAAC,MAAgC;IACjE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QACrC,IAAI,GAAG,IAAI,GAAG,KAAK,CAAC,CAAC,IAAI;YAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,mCAAmC;IAC/E,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAChD,CAAC;AAWD;;;;;GAKG;AACH,SAAgB,cAAc,CAAC,GAAW,EAAE,QAA2B;IACrE,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,OAAO,GAAG,IAAA,wBAAe,EAAC,GAAG,EAAE;QACnC,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,GAAG,CAAC,QAAQ,CAAC,gBAAgB,CAAC,MAAM;YAClC,CAAC,CAAC,EAAE,gBAAgB,EAAE,CAAC,GAAG,QAAQ,CAAC,gBAAgB,CAAC,EAAE;YACtD,CAAC,CAAC,EAAE,CAAC;KACR,CAAC,CAAC;IACH,IAAI,OAAO;QAAE,OAAO,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;IAChD,IAAI,QAAQ,CAAC,YAAY,IAAI,QAAQ,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9D,IAAA,0BAAc,EAAC,GAAG,EAAE,EAAE,YAAY,EAAE,CAAC,GAAG,QAAQ,CAAC,YAAY,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC;QAChF,OAAO,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAuSA,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAq8DvD"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AA4SA,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAo/DvD"}

package/dist/cli.js

@@ -39,6 +39,7 @@ const vendored_advisor_1 = require("./analyzers/tools/vendored-advisor");
 const detect_1 = require("./detect");
 const generator_1 = require("./generator");
 const prompts_1 = require("./prompts");
+const setup_1 = require("./analyzers/flow/setup");
 const update_1 = require("./update");
 const doctor_1 = require("./doctor");
 const constants_1 = require("./constants");
@@ -247,6 +248,10 @@ function printUsage() {
                               CLAUDE.md, preserving your content). Implies dxkit skills.
     --loop-preset <p>         Loop blocking posture: security-only (default) or
                               full-debt. Only meaningful with --claude-loop.
+    --flow                    Set up the UI→API integration gate (warn posture),
+                              no prompt. Auto-offered interactively when init
+                              detects a UI→API surface.
+    --no-flow                 Skip flow setup even when a UI→API surface is detected.
     --detect                  Auto-detect stack, minimal prompts
     --yes                     Accept all defaults, no prompts
     --force                   Overwrite existing files (incl. existing hooks/
@@ -349,6 +354,10 @@ async function run(argv) {
             // loop pack: register the Stop-gate hook + CLAUDE.md loop norm
             'claude-loop': { type: 'boolean', default: false },
             'loop-preset': { type: 'string' },
+            // flow setup (folded into init; no standalone `flow init`).
+            // --flow forces it on (warn posture); --no-flow suppresses it.
+            flow: { type: 'boolean', default: false },
+            'no-flow': { type: 'boolean', default: false },
             // setup-branch-protection flags
             branch: { type: 'string' },
             'require-reviews': { type: 'string' },
@@ -465,9 +474,11 @@ async function run(argv) {
             // via flags but bundled under --full).
             // --claude-loop implies the dxkit skills so the dxkit-loop skill (and
             // its siblings) land — the loop is most useful when the user can ask
-            // Claude to explain a block / switch presets conversationally.
+            // Claude to explain a block / switch presets conversationally. --flow
+            // does the same for the dxkit-flow skill: setting up the integration gate
+            // is most useful when Claude can then diagnose + repair a break with it.
             const wantClaudeLoop = !!values['claude-loop'];
-            const wantDxkitAgents = !!values.full || !!values['with-dxkit-agents'] || wantClaudeLoop;
+            const wantDxkitAgents = !!values.full || !!values['with-dxkit-agents'] || wantClaudeLoop || !!values.flow;
             const result = await (0, generator_1.generate)(cwd, config, finalMode, !!values.force, !!values['no-scan'], wantDxkitAgents);
             // Phase Ship installers (additive). `--full` implies every flag
             // so a one-command setup gets the full 2.5.0 ship surface.
@@ -560,6 +571,37 @@ async function run(argv) {
                     result: (0, ship_installers_1.installCiDeepSastRefresh)(cwd, { force: !!values.force }),
                 });
             }
+            // Flow setup — folded into `init` (there is no standalone `flow init`).
+            // Detect a UI→API surface; if there is none, stay silent (zero burden on
+            // a library / CLI / data repo). Otherwise prompt for the gate posture
+            // (interactive, with a description of each) or take the gentle `warn`
+            // default (--flow / --yes / non-TTY). --no-flow suppresses it entirely.
+            if (!values['no-flow']) {
+                const detection = await (0, setup_1.detectFlowTopology)(cwd);
+                if (detection.topology !== 'none') {
+                    // Non-TTY without an explicit answer can't prompt — fall to the
+                    // default rather than hang (mirrors how --yes is handled).
+                    const flowYes = promptOpts.yes || !process.stdin.isTTY;
+                    const decision = await (0, prompts_1.promptFlowSetup)(detection, {
+                        yes: flowYes,
+                        forceOn: !!values.flow,
+                    });
+                    const written = (0, setup_1.applyFlowSetup)(cwd, decision);
+                    shipResults.push({
+                        label: 'Flow integration gate',
+                        result: {
+                            installed: written,
+                            skipped: [],
+                            sidecars: [],
+                            notes: [
+                                `Flow gate posture: ${decision.mode} ` +
+                                    `(${detection.callCount} call(s) → ${detection.routeCount} route(s)). ` +
+                                    `Change it in .dxkit/policy.json:flow.mode.`,
+                            ],
+                        },
+                    });
+                }
+            }
             // dxkit must resolve project-locally so every installed self-invocation
             // surface (Stop hook, context-hook, pre-push + CI guardrail) can run a
             // pinned dxkit instead of 404-ing. The set of surfaces that imply this
@@ -865,12 +907,20 @@ async function run(argv) {
                 await runFlowRefresh({ cwd, frontend, backend, specs, json: !!values.json });
                 break;
             }
+            // `flow publish` → the multi-repo handshake: union every workspace
+            // participant's served routes into this repo's served.json.
+            if (subCommand === 'publish') {
+                const { runFlowPublish } = await Promise.resolve().then(() => __importStar(require('./flow-cli')));
+                await runFlowPublish({ cwd, frontend, backend, specs, json: !!values.json });
+                break;
+            }
             logger.fail(`Unknown flow subcommand: ${subCommand}`);
             logger.info('Usage:');
             logger.info('  vyuh-dxkit flow [map] [--frontend <dir>] [--backend <dir>] [--specs <a,b>]');
             logger.info('  vyuh-dxkit flow trace "<METHOD> <path>"');
             logger.info('  vyuh-dxkit flow extract [--out <dir>]');
             logger.info('  vyuh-dxkit flow refresh');
+            logger.info('  vyuh-dxkit flow publish   (multi-repo: union participants’ served routes)');
             process.exit(1);
             break;
         }