@flytedesk/app-kit 0.2.0 → 0.3.1

package/dist/cli/flags-sync.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv: string[]): Promise<void>;

package/dist/cli/flags-sync.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * flags-sync — the CLI half of @flytedesk/app-kit/flags (DEC-39).
+ *
+ * A thin wrapper around the generalized sync engine in ./sync-engine.js — see that
+ * file's doc comment for the full subcommand reference (init/diff/apply/status) and
+ * how fragments/migrations/lock files work. This file only supplies the "flags"
+ * fragment name and the "flags-sync" bin name; trace-sync.ts/profile-sync.ts are the
+ * same wrapper for the trace/profile fragments.
+ */
+import { isRunningAsMain, runSyncCli, SyncCliError } from "./sync-engine.js";
+export async function main(argv) {
+    return runSyncCli(argv, { name: "flags", binName: "flags-sync" });
+}
+if (isRunningAsMain(import.meta.url)) {
+    main(process.argv.slice(2)).catch((err) => {
+        if (!(err instanceof SyncCliError)) {
+            console.error(err);
+        }
+        process.exitCode = process.exitCode ?? 1;
+    });
+}
+//# sourceMappingURL=flags-sync.js.map

package/dist/cli/flags-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags-sync.js","sourceRoot":"","sources":["../../src/cli/flags-sync.ts"],"names":[],"mappings":";AACA;;;;;;;;GAQG;AACH,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAE7E,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,IAAc;IACvC,OAAO,UAAU,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC,CAAC;AACpE,CAAC;AAED,IAAI,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;IACrC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QACjD,IAAI,CAAC,CAAC,GAAG,YAAY,YAAY,CAAC,EAAE,CAAC;YACnC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;QACD,OAAO,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/cli/profile-sync.js

@@ -8,14 +8,11 @@
  * fragment name and the "profile-sync" bin name; trace-sync.ts is the same wrapper
  * for the trace fragment.
  */
-import { pathToFileURL } from "node:url";
-import { runSyncCli, SyncCliError } from "./sync-engine.js";
+import { isRunningAsMain, runSyncCli, SyncCliError } from "./sync-engine.js";
 export async function main(argv) {
     return runSyncCli(argv, { name: "profile", binName: "profile-sync" });
 }
-const isMainModule = process.argv[1] !== undefined &&
-    import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isMainModule) {
+if (isRunningAsMain(import.meta.url)) {
     main(process.argv.slice(2)).catch((err) => {
         if (!(err instanceof SyncCliError)) {
             console.error(err);

package/dist/cli/profile-sync.js.map

@@ -1 +1 @@
-{"version":3,"file":"profile-sync.js","sourceRoot":"","sources":["../../src/cli/profile-sync.ts"],"names":[],"mappings":";AACA;;;;;;;;GAQG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAE5D,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,IAAc;IACvC,OAAO,UAAU,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,YAAY,GAChB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,SAAS;IAC7B,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAE1D,IAAI,YAAY,EAAE,CAAC;IACjB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QACjD,IAAI,CAAC,CAAC,GAAG,YAAY,YAAY,CAAC,EAAE,CAAC;YACnC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;QACD,OAAO,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"profile-sync.js","sourceRoot":"","sources":["../../src/cli/profile-sync.ts"],"names":[],"mappings":";AACA;;;;;;;;GAQG;AACH,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAE7E,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,IAAc;IACvC,OAAO,UAAU,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC,CAAC;AACxE,CAAC;AAED,IAAI,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;IACrC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QACjD,IAAI,CAAC,CAAC,GAAG,YAAY,YAAY,CAAC,EAAE,CAAC;YACnC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;QACD,OAAO,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/cli/sync-engine.d.ts

@@ -1,3 +1,35 @@
+/**
+ * Whether the module at `moduleUrl` (pass `import.meta.url`) is the one Node was
+ * invoked to run directly — the ESM successor to `require.main === module`, shared
+ * by every bin wrapper (trace-sync.ts/profile-sync.ts/flags-sync.ts) so there's one
+ * fix point instead of three copies of the same check.
+ *
+ * A raw `import.meta.url === pathToFileURL(process.argv[1]).href` string comparison
+ * (the previous check) is NOT reliable: a package manager's bin shim can leave
+ * `argv[1]` pointing at a *symlink* while Node resolves the ESM module id through
+ * that symlink to the real target path for `import.meta.url` — so the two name the
+ * same file but compare unequal. This is not hypothetical: pnpm's
+ * `node_modules/<pkg>` is exactly such a symlink into its content-addressable
+ * store, and it reproduces on Windows for every real invocation path (`pnpm exec
+ * flags-sync init`, an npm-script `"flags-sync init"` run via `pnpm run`, etc.) —
+ * confirmed by instrumenting a real 0.3.0 install: `argv[1]` resolved to
+ * `...\node_modules\@flytedesk\app-kit\dist\cli\flags-sync.js` (the symlinked
+ * path) while `import.meta.url` resolved to
+ * `...\node_modules\.pnpm\@flytedesk+app-kit@0.3.0_.../node_modules\@flytedesk\app-kit\dist\cli\flags-sync.js`
+ * (the real store path). The mismatch meant `main()` was never called at all —
+ * every CLI entrypoint silently no-op'd: exit code 0, no output, nothing written.
+ *
+ * `realpathSync.native` (the real OS `realpath` syscall, not Node's pure-JS
+ * fallback — verified directly: the JS fallback leaves an on-disk casing mismatch
+ * unresolved, e.g. `RealFile.js` vs `realfile.js` compare unequal even though NTFS
+ * treats them as the same file, while `.native` correctly normalizes both to the
+ * same canonical path) resolves both sides to the same canonical filesystem path
+ * first — following symlinks AND normalizing casing — so the comparison is correct
+ * regardless of symlinks, path-separator style, or casing differences between how
+ * a shell/bin-shim sets `argv[1]` and how Node constructs `import.meta.url` for
+ * the same file.
+ */
+export declare function isRunningAsMain(moduleUrl: string): boolean;
 /**
  * Everything that differs between `trace-sync` and `profile-sync`. `name` picks out
  * prisma/fragments/<name>.prisma, prisma/fragments/<name>.meta.json, and every

package/dist/cli/sync-engine.js

@@ -3,12 +3,26 @@
  * (DEC-39, generalized to a second fragment for the profile module).
  *
  * This package never generates its own Prisma Client for any of its fragments.
- * Instead, this engine copies a package fragment (prisma/fragments/<fragment>.prisma)
- * into the *consumer's* own multi-file Prisma schema folder, applies that fragment's
- * raw SQL migrations directly against the consumer's configured datasource, and
- * tracks what's been applied in a lock file (`.app-kit-<fragment>.lock.json`) written
- * at the consumer project root. The consumer's own `prisma generate` then produces
- * one client that includes these models alongside their own.
+ * Instead, this engine installs a package fragment (prisma/fragments/<fragment>.prisma)
+ * into the *consumer's* own Prisma schema, applies that fragment's raw SQL migrations
+ * directly against the consumer's configured datasource, and tracks what's been
+ * applied in a lock file (`.app-kit-<fragment>.lock.json`) written at the consumer
+ * project root. The consumer's own `prisma generate` then produces one client that
+ * includes these models alongside their own.
+ *
+ * A consumer's `prisma.config.ts` `schema` setting points at one of two real layouts
+ * (see classifySchemaLayout below), and this engine handles both:
+ *   - A multi-file schema FOLDER (`schema: "prisma/schema"`, no `.prisma` suffix):
+ *     the fragment is copied as a sibling file, `prisma/schema/<fragment>.prisma`.
+ *   - A flat single-file schema.prisma (`schema: "prisma/schema.prisma"`), which is
+ *     what both real consumers (flytedesk-id, media-planner) actually use: the
+ *     fragment's model(s) are merged directly into that one file, inside a
+ *     delimited, app-kit-owned marker region (see mergeIntoFlatSchema) rather than
+ *     copied as a sibling file — a sibling file next to a flat schema.prisma is never
+ *     read by Prisma, since `schema` names that one file, not a folder. An earlier
+ *     version of this engine always did the sibling-file copy regardless of layout,
+ *     which is why the CLI had never successfully run against a real consumer
+ *     (flytedesk-id's /profile integration had to be pasted in by hand).
  *
  * Both bin commands are thin wrappers around `runSyncCli` (see src/cli/trace-sync.ts
  * and src/cli/profile-sync.ts) — everything fragment-specific is passed in as a
@@ -39,9 +53,53 @@
  */
 import { createHash } from "node:crypto";
 import spawn from "cross-spawn";
-import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync, } from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+/**
+ * Whether the module at `moduleUrl` (pass `import.meta.url`) is the one Node was
+ * invoked to run directly — the ESM successor to `require.main === module`, shared
+ * by every bin wrapper (trace-sync.ts/profile-sync.ts/flags-sync.ts) so there's one
+ * fix point instead of three copies of the same check.
+ *
+ * A raw `import.meta.url === pathToFileURL(process.argv[1]).href` string comparison
+ * (the previous check) is NOT reliable: a package manager's bin shim can leave
+ * `argv[1]` pointing at a *symlink* while Node resolves the ESM module id through
+ * that symlink to the real target path for `import.meta.url` — so the two name the
+ * same file but compare unequal. This is not hypothetical: pnpm's
+ * `node_modules/<pkg>` is exactly such a symlink into its content-addressable
+ * store, and it reproduces on Windows for every real invocation path (`pnpm exec
+ * flags-sync init`, an npm-script `"flags-sync init"` run via `pnpm run`, etc.) —
+ * confirmed by instrumenting a real 0.3.0 install: `argv[1]` resolved to
+ * `...\node_modules\@flytedesk\app-kit\dist\cli\flags-sync.js` (the symlinked
+ * path) while `import.meta.url` resolved to
+ * `...\node_modules\.pnpm\@flytedesk+app-kit@0.3.0_.../node_modules\@flytedesk\app-kit\dist\cli\flags-sync.js`
+ * (the real store path). The mismatch meant `main()` was never called at all —
+ * every CLI entrypoint silently no-op'd: exit code 0, no output, nothing written.
+ *
+ * `realpathSync.native` (the real OS `realpath` syscall, not Node's pure-JS
+ * fallback — verified directly: the JS fallback leaves an on-disk casing mismatch
+ * unresolved, e.g. `RealFile.js` vs `realfile.js` compare unequal even though NTFS
+ * treats them as the same file, while `.native` correctly normalizes both to the
+ * same canonical path) resolves both sides to the same canonical filesystem path
+ * first — following symlinks AND normalizing casing — so the comparison is correct
+ * regardless of symlinks, path-separator style, or casing differences between how
+ * a shell/bin-shim sets `argv[1]` and how Node constructs `import.meta.url` for
+ * the same file.
+ */
+export function isRunningAsMain(moduleUrl) {
+    if (process.argv[1] === undefined)
+        return false;
+    try {
+        return (realpathSync.native(fileURLToPath(moduleUrl)) ===
+            realpathSync.native(process.argv[1]));
+    }
+    catch {
+        // Either path doesn't exist / isn't resolvable (e.g. a REPL or a bundler that
+        // gives import.meta.url a non-file URL) — definitely not "run directly" then.
+        return false;
+    }
+}
 export class SyncCliError extends Error {
 }
 function readJson(filePath) {
@@ -53,6 +111,9 @@ function sha256(content) {
 function sha256File(filePath) {
     return sha256(readFileSync(filePath));
 }
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 // ---------------------------------------------------------------------------
 // Engine: bound to one SyncFragment + the consumer root it's operating on
 // ---------------------------------------------------------------------------
@@ -155,19 +216,31 @@ class SyncEngine {
         }
         return path.resolve(path.dirname(configFile), schemaPath);
     }
-    /** Resolve the folder <fragment>.prisma gets copied into, from the config's
-     *  schema path (which may point at the folder itself, or at a single schema file
-     *  inside it, e.g. "prisma/schema.prisma"). */
-    resolveSchemaFolder(schemaPath) {
+    /**
+     * Classifies the consumer's schema layout from their prisma.config.ts `schema`
+     * path: a path ending in `.prisma` names one specific file — Prisma reads only
+     * that file, so this is the flat single-file layout, and the fragment must be
+     * merged into it directly (mergeIntoFlatSchema). Anything else names a folder —
+     * the multi-file layout — and the fragment is copied in as a sibling file
+     * (copyFragment), same as before.
+     */
+    classifySchemaLayout(schemaPath) {
         if (schemaPath.endsWith(".prisma")) {
-            return path.dirname(schemaPath);
+            return {
+                kind: "flat-file",
+                file: schemaPath,
+                prismaRoot: path.dirname(schemaPath),
+            };
         }
-        return schemaPath;
+        return {
+            kind: "folder",
+            folder: schemaPath,
+            prismaRoot: this.resolvePrismaRoot(schemaPath),
+        };
     }
     /** The conventional "prisma root" a schema folder sits under, used to locate (or
      *  create) the sibling `migrations/` directory. For the common multi-file layout
-     *  `prisma/schema/*.prisma`, that's `prisma/`; for a flat `prisma/schema.prisma`
-     *  layout, `resolveSchemaFolder` already returned `prisma/`, so this is a no-op. */
+     *  `prisma/schema/*.prisma`, that's `prisma/`. */
     resolvePrismaRoot(schemaFolder) {
         return path.basename(schemaFolder) === "schema"
             ? path.dirname(schemaFolder)
@@ -182,7 +255,10 @@ class SyncEngine {
         // with an argument array is an unescaped-concatenation footgun (path arguments
         // here can contain spaces). cross-spawn resolves and correctly quotes .cmd/.bat
         // executables on Windows without going through a shell at all.
-        const result = spawn.sync("npx", ["prisma", ...args], { cwd, stdio: "inherit" });
+        const result = spawn.sync("npx", ["prisma", ...args], {
+            cwd,
+            stdio: "inherit",
+        });
         if (result.error) {
             this.fail(`failed to run "npx prisma ${args.join(" ")}": ${result.error.message}`);
         }
@@ -204,16 +280,221 @@ class SyncEngine {
         cpSync(srcDir, destDir, { recursive: true });
     }
     // -------------------------------------------------------------------------
+    // Flat single-file schema.prisma support
+    // -------------------------------------------------------------------------
+    /**
+     * The portion of a fragment's .prisma source that gets merged into a consumer's
+     * flat schema.prisma — everything from the first `model` declaration onward,
+     * trimmed. Deliberately drops the fragment file's own leading design-rationale
+     * doc comment (see prisma/fragments/profile.prisma / trace.prisma's file
+     * headers): that comment describes the *fragment file itself* ("this file is
+     * copied by <bin> init...", "matching the raw SQL in prisma/migrations/...")
+     * which reads oddly once inlined into someone else's schema.prisma, whereas the
+     * marker region's own header (markerStart) already identifies the block as
+     * app-kit-owned and names which command manages it.
+     */
+    extractFragmentBody(fragmentSource) {
+        const lines = fragmentSource.split(/\r?\n/);
+        const firstModelLine = lines.findIndex((line) => /^model\s+\w+\s*\{/.test(line));
+        const body = firstModelLine === -1
+            ? fragmentSource
+            : lines.slice(firstModelLine).join("\n");
+        return body.trim();
+    }
+    static DATASOURCE_SCHEMAS_RE = /datasource\s+\w+\s*\{[^}]*\bschemas\s*=\s*\[([^\]]*)\]/;
+    /**
+     * The Postgres schema name(s) declared on the consumer's own `datasource` block
+     * (`schemas = [...]`) in a flat schema.prisma's full text. Prisma's multiSchema
+     * feature requires `@@schema(...)` on every single model once this array is
+     * non-empty (P1012 otherwise) — see resolveFragmentBody, which uses this to
+     * decide whether merged-in fragment models need one. Returns `[]` when the
+     * datasource has no `schemas` setting at all (a non-multiSchema consumer).
+     */
+    readConsumerSchemaNames(schemaContent) {
+        const match = schemaContent.match(SyncEngine.DATASOURCE_SCHEMAS_RE);
+        if (!match)
+            return [];
+        return match[1]
+            .split(",")
+            .map((entry) => entry.trim())
+            .filter((entry) => entry.length > 0)
+            .map((entry) => entry.replace(/^["']|["']$/g, ""));
+    }
+    /**
+     * Inserts `@@schema("<name>")` as the last block attribute of every top-level
+     * `model { ... }` in `body`, immediately before its closing brace — the same
+     * position a hand-written model in a multiSchema consumer's own schema.prisma
+     * uses (see FLAT_SCHEMA_FIXTURE in sync-engine.test.ts).
+     *
+     * Relies on this package's own fragment files' formatting convention (verified
+     * against every prisma/fragments/*.prisma file): `model Foo {` always starts at
+     * column 0, and its matching `}` is always alone on its own line at column 0 —
+     * the same convention extractFragmentBody's firstModelLine scan already depends
+     * on. This is deliberately not a general-purpose Prisma parser (it would, for
+     * instance, mis-handle a `{`/`}` inside a string default like flags.prisma's
+     * `@default("{}")` if it tried to brace-count) — it only ever needs to run
+     * against this package's own fragment files, never a consumer's.
+     */
+    injectSchemaAttribute(body, schemaName) {
+        const lines = body.split(/\r?\n/);
+        const out = [];
+        let inModel = false;
+        for (const line of lines) {
+            if (!inModel && /^model\s+\w+\s*\{$/.test(line)) {
+                inModel = true;
+                out.push(line);
+                continue;
+            }
+            if (inModel && line === "}") {
+                out.push(`  @@schema(${JSON.stringify(schemaName)})`);
+                out.push(line);
+                inModel = false;
+                continue;
+            }
+            out.push(line);
+        }
+        return out.join("\n");
+    }
+    /**
+     * Resolves this fragment's exact body text as it should be merged into a
+     * consumer's flat schema.prisma: extractFragmentBody's output, with
+     * `@@schema(...)` injected into every model when the consumer's datasource
+     * declares `schemas = [...]` (multiSchema) — fixing the bug where a merged
+     * fragment had no `@@schema` at all and broke `prisma validate` (P1012:
+     * "This model is missing an @@schema attribute") for every multiSchema consumer,
+     * which is both real consumers (flytedesk-id, media-planner).
+     *
+     * `schemaNameOverride` is the CLI's `--schema-name` flag. When the consumer
+     * declares exactly one schema name, that name is used automatically and the
+     * override (if given) is only validated, not required. When more than one is
+     * declared, this engine has no way to guess which one a given fragment's models
+     * belong to — guessing silently is exactly the class of bug this fixes — so
+     * `--schema-name` becomes required and this fails loudly (via `fail()`,
+     * surfaced to the consumer with the exact flag to pass) rather than picking one.
+     */
+    resolveFragmentBody(schemaFileContent, schemaNameOverride) {
+        const rawBody = this.extractFragmentBody(readFileSync(this.fragmentSrcPath, "utf8"));
+        const declaredSchemas = this.readConsumerSchemaNames(schemaFileContent);
+        if (declaredSchemas.length === 0) {
+            return rawBody;
+        }
+        let schemaName;
+        if (declaredSchemas.length === 1) {
+            schemaName = schemaNameOverride ?? declaredSchemas[0];
+        }
+        else if (schemaNameOverride) {
+            schemaName = schemaNameOverride;
+        }
+        else {
+            this.fail(`the consumer's datasource declares multiple schemas (${declaredSchemas.join(", ")}) via ` +
+                `\`schemas = [...]\`. ${this.fragment.binName} can't guess which one this fragment's model(s) ` +
+                `belong to — pass --schema-name=<name> to disambiguate, e.g. ` +
+                `"${this.fragment.binName} init --schema-name=${declaredSchemas[0]}".`);
+        }
+        if (!declaredSchemas.includes(schemaName)) {
+            this.fail(`--schema-name=${schemaName} is not one of the consumer's declared schemas (${declaredSchemas.join(", ")}).`);
+        }
+        return this.injectSchemaAttribute(rawBody, schemaName);
+    }
+    markerStart() {
+        return `// --- @flytedesk/app-kit:${this.fragment.name} start (managed by ${this.fragment.binName} — do not hand-edit this region) ---`;
+    }
+    markerEnd() {
+        return `// --- @flytedesk/app-kit:${this.fragment.name} end ---`;
+    }
+    /**
+     * Extracts the current content of THIS fragment's own marker region from a flat
+     * schema.prisma's full text, or null if the region isn't present yet. Matching on
+     * this fragment's own name means two different fragments merged into the same
+     * flat file never see or touch each other's regions.
+     *
+     * Exact inverse of the `${start}\n${body}\n${end}` block mergeIntoFlatSchema
+     * writes, so a round trip (write, then extract) returns the same body
+     * byte-for-byte — this is what makes both mergeIntoFlatSchema's own
+     * no-op-if-unchanged check and cmdStatus's checksum comparison correct.
+     */
+    extractInstalledRegion(schemaContent) {
+        const re = new RegExp(`${escapeRegExp(this.markerStart())}\\n([\\s\\S]*?)\\n${escapeRegExp(this.markerEnd())}`);
+        const match = schemaContent.match(re);
+        return match ? match[1] : null;
+    }
+    /**
+     * Merges this fragment's model(s) into a consumer's flat single-file
+     * prisma/schema.prisma, inside a delimited, app-kit-owned marker region — the
+     * flat-file counterpart to copyFragment's sibling-file copy for the multi-file
+     * folder layout.
+     *
+     * Idempotent: running this twice with the same fragment content is a no-op (the
+     * installed region already matches, so the file isn't rewritten at all). Multiple
+     * fragments merged into the same file coexist as separate regions — this only
+     * ever reads or replaces text between ITS OWN start/end marker pair; everything
+     * else in the file (the consumer's own models, datasource/generator blocks,
+     * `schemas = [...]`, other fragments' regions) is left byte-for-byte untouched.
+     */
+    mergeIntoFlatSchema(schemaFilePath, schemaNameOverride) {
+        if (!existsSync(schemaFilePath)) {
+            this.fail(`schema file not found at ${schemaFilePath} (expected a flat single-file prisma/schema.prisma)`);
+        }
+        const original = readFileSync(schemaFilePath, "utf8");
+        const body = this.resolveFragmentBody(original, schemaNameOverride);
+        const existingRegion = this.extractInstalledRegion(original);
+        if (existingRegion === body) {
+            return;
+        }
+        let updated;
+        if (existingRegion !== null) {
+            const re = new RegExp(`${escapeRegExp(this.markerStart())}\\n[\\s\\S]*?\\n${escapeRegExp(this.markerEnd())}`);
+            updated = original.replace(re, `${this.markerStart()}\n${body}\n${this.markerEnd()}`);
+        }
+        else {
+            updated = `${original.replace(/\s*$/, "")}\n\n${this.markerStart()}\n${body}\n${this.markerEnd()}\n`;
+        }
+        writeFileSync(schemaFilePath, updated, "utf8");
+    }
+    /** Installs the fragment for either layout — the one call site cmdInit/cmdApply
+     *  both use, so they can never disagree about which path a given layout takes. */
+    installFragment(layout, schemaNameOverride) {
+        const bin = this.fragment.binName;
+        if (layout.kind === "folder") {
+            console.log(`${bin}: copying ${this.fragment.name}.prisma into ${layout.folder}`);
+            this.copyFragment(layout.folder);
+        }
+        else {
+            console.log(`${bin}: merging ${this.fragment.name} model(s) into ${layout.file} (managed region)`);
+            this.mergeIntoFlatSchema(layout.file, schemaNameOverride);
+        }
+    }
+    /**
+     * What gets recorded as `fragmentChecksum` in the lock file, and what cmdStatus
+     * recomputes from the consumer's tree to detect hand-edits. Must be called AFTER
+     * installFragment has already written to the consumer's tree (both call sites,
+     * cmdInit/cmdApply, satisfy this).
+     *
+     * For the flat-file/merge case this reads the marker region back out of the file
+     * that was just written, rather than re-deriving it from the fragment source —
+     * that keeps this in lockstep with whatever mergeIntoFlatSchema actually wrote
+     * (including any `@@schema(...)` injected by resolveFragmentBody) without
+     * duplicating that resolution logic a second time here.
+     */
+    computeFragmentChecksum(layout) {
+        if (layout.kind === "folder") {
+            return sha256File(this.fragmentSrcPath);
+        }
+        const installed = this.extractInstalledRegion(readFileSync(layout.file, "utf8"));
+        if (installed === null) {
+            this.fail(`internal error: no managed region found in ${layout.file} immediately after installing it`);
+        }
+        return sha256(installed);
+    }
+    // -------------------------------------------------------------------------
     // Subcommands
     // -------------------------------------------------------------------------
-    async cmdInit(consumerRoot) {
+    async cmdInit(consumerRoot, schemaNameOverride) {
         const bin = this.fragment.binName;
         const schemaPath = await this.loadConsumerSchemaPath(consumerRoot);
-        const schemaFolder = this.resolveSchemaFolder(schemaPath);
-        const prismaRoot = this.resolvePrismaRoot(schemaFolder);
-        const migrationsDestDir = path.join(prismaRoot, "migrations");
-        console.log(`${bin}: copying ${this.fragment.name}.prisma into ${schemaFolder}`);
-        this.copyFragment(schemaFolder);
+        const layout = this.classifySchemaLayout(schemaPath);
+        const migrationsDestDir = path.join(layout.prismaRoot, "migrations");
+        this.installFragment(layout, schemaNameOverride);
         console.log(`${bin}: running "npx prisma validate" against ${consumerRoot}`);
         this.runPrisma(["validate"], consumerRoot);
         const manifest = this.readManifest();
@@ -236,7 +517,7 @@ class SyncEngine {
         const meta = this.readFragmentMeta();
         this.writeLockFile(consumerRoot, {
             fragmentVersion: meta.fragmentVersion,
-            fragmentChecksum: sha256File(this.fragmentSrcPath),
+            fragmentChecksum: this.computeFragmentChecksum(layout),
             appliedMigrations,
             lastSyncedAt: new Date().toISOString(),
         });
@@ -277,15 +558,13 @@ class SyncEngine {
         }
         console.log(`${this.fragment.binName} diff is read-only. Run "${this.fragment.binName} apply" to apply these.`);
     }
-    async cmdApply(consumerRoot) {
+    async cmdApply(consumerRoot, schemaNameOverride) {
         const bin = this.fragment.binName;
         const report = this.computePending(consumerRoot);
         const schemaPath = await this.loadConsumerSchemaPath(consumerRoot);
-        const schemaFolder = this.resolveSchemaFolder(schemaPath);
-        const prismaRoot = this.resolvePrismaRoot(schemaFolder);
-        const migrationsDestDir = path.join(prismaRoot, "migrations");
-        console.log(`${bin}: refreshing ${this.fragment.name}.prisma in ${schemaFolder}`);
-        this.copyFragment(schemaFolder);
+        const layout = this.classifySchemaLayout(schemaPath);
+        const migrationsDestDir = path.join(layout.prismaRoot, "migrations");
+        this.installFragment(layout, schemaNameOverride);
         const lock = this.readLockFile(consumerRoot);
         if (!lock) {
             this.fail(`no ${this.lockFileName} found at ${consumerRoot}. Run "${bin} init" first.`);
@@ -308,7 +587,7 @@ class SyncEngine {
         const meta = this.readFragmentMeta();
         this.writeLockFile(consumerRoot, {
             fragmentVersion: meta.fragmentVersion,
-            fragmentChecksum: sha256File(this.fragmentSrcPath),
+            fragmentChecksum: this.computeFragmentChecksum(layout),
             appliedMigrations,
             lastSyncedAt: new Date().toISOString(),
         });
@@ -330,18 +609,36 @@ class SyncEngine {
         }
         try {
             const schemaPath = await this.loadConsumerSchemaPath(consumerRoot);
-            const schemaFolder = this.resolveSchemaFolder(schemaPath);
-            const copiedFragmentPath = path.join(schemaFolder, `${this.fragment.name}.prisma`);
-            if (!existsSync(copiedFragmentPath)) {
-                console.log(`fragment copy:                 MISSING at ${copiedFragmentPath}`);
-                return;
+            const layout = this.classifySchemaLayout(schemaPath);
+            let installedChecksum;
+            let location;
+            if (layout.kind === "folder") {
+                const copiedFragmentPath = path.join(layout.folder, `${this.fragment.name}.prisma`);
+                if (!existsSync(copiedFragmentPath)) {
+                    console.log(`fragment copy:                 MISSING at ${copiedFragmentPath}`);
+                    return;
+                }
+                installedChecksum = sha256File(copiedFragmentPath);
+                location = copiedFragmentPath;
+            }
+            else {
+                if (!existsSync(layout.file)) {
+                    console.log(`fragment copy:                 MISSING — ${layout.file} does not exist`);
+                    return;
+                }
+                const region = this.extractInstalledRegion(readFileSync(layout.file, "utf8"));
+                if (region === null) {
+                    console.log(`fragment copy:                 MISSING — no managed region found in ${layout.file}`);
+                    return;
+                }
+                installedChecksum = sha256(region);
+                location = `${layout.file} (managed region)`;
             }
-            const installedChecksum = sha256File(copiedFragmentPath);
             if (installedChecksum === lock.fragmentChecksum) {
                 console.log("fragment copy:                 unmodified");
             }
             else {
-                console.log(`fragment copy:                 CHECKSUM MISMATCH — ${copiedFragmentPath} has been hand-edited ` +
+                console.log(`fragment copy:                 CHECKSUM MISMATCH — ${location} has been hand-edited ` +
                     `(or is out of sync with the lock file)`);
             }
         }
@@ -357,6 +654,30 @@ const SUBCOMMANDS = ["init", "diff", "apply", "status"];
 function isSubcommand(value) {
     return SUBCOMMANDS.includes(value);
 }
+/**
+ * Parses `--schema-name=<name>` / `--schema-name <name>` out of a subcommand's
+ * trailing args — the flag `resolveFragmentBody` requires when a consumer's flat
+ * schema.prisma declares more than one entry in `schemas = [...]` and this engine
+ * can't guess which one a fragment's models belong to. Only `init`/`apply` use the
+ * result (they're the only subcommands that install the fragment); `diff`/`status`
+ * ignore it since they never write anything.
+ */
+function parseSchemaNameFlag(rest) {
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (arg === "--schema-name") {
+            const value = rest[i + 1];
+            if (value === undefined) {
+                throw new SyncCliError("--schema-name requires a value, e.g. --schema-name=my_schema");
+            }
+            return value;
+        }
+        if (arg.startsWith("--schema-name=")) {
+            return arg.slice("--schema-name=".length);
+        }
+    }
+    return undefined;
+}
 /**
  * Runs one CLI invocation for the given fragment. Called by each bin wrapper
  * (src/cli/trace-sync.ts, src/cli/profile-sync.ts) with `process.argv.slice(2)`.
@@ -364,25 +685,22 @@ function isSubcommand(value) {
 export async function runSyncCli(argv, fragment) {
     const [subcommand, ...rest] = argv;
     if (!isSubcommand(subcommand)) {
-        console.error(`usage: ${fragment.binName} <${SUBCOMMANDS.join("|")}>`);
+        console.error(`usage: ${fragment.binName} <${SUBCOMMANDS.join("|")}> [--schema-name=<name>]`);
         process.exitCode = 1;
         return;
     }
-    // Reserved for a future --cwd override; today every sync CLI always operates on
-    // the directory it's invoked from, which is how `npx <bin> ...` / an npm script in
-    // the consumer's own package.json will run it.
-    void rest;
+    const schemaNameOverride = parseSchemaNameFlag(rest);
     const consumerRoot = process.cwd();
     const engine = new SyncEngine(fragment);
     switch (subcommand) {
         case "init":
-            await engine.cmdInit(consumerRoot);
+            await engine.cmdInit(consumerRoot, schemaNameOverride);
             break;
         case "diff":
             engine.cmdDiff(consumerRoot);
             break;
         case "apply":
-            await engine.cmdApply(consumerRoot);
+            await engine.cmdApply(consumerRoot, schemaNameOverride);
             break;
         case "status":
             await engine.cmdStatus(consumerRoot);