@flytedesk/app-kit 0.1.3 → 0.3.0

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,26 @@
+#!/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 { pathToFileURL } from "node:url";
+import { runSyncCli, SyncCliError } from "./sync-engine.js";
+export async function main(argv) {
+    return runSyncCli(argv, { name: "flags", binName: "flags-sync" });
+}
+const isMainModule = process.argv[1] !== undefined &&
+    import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMainModule) {
+    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,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,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC,CAAC;AACpE,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"}

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

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

package/dist/cli/profile-sync.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * profile-sync — the CLI half of @flytedesk/app-kit/profile (DEC-39, DEC-52).
+ *
+ * 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 "profile"
+ * 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";
+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) {
+    main(process.argv.slice(2)).catch((err) => {
+        if (!(err instanceof SyncCliError)) {
+            console.error(err);
+        }
+        process.exitCode = process.exitCode ?? 1;
+    });
+}
+//# sourceMappingURL=profile-sync.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,20 @@
+/**
+ * Everything that differs between `trace-sync` and `profile-sync`. `name` picks out
+ * prisma/fragments/<name>.prisma, prisma/fragments/<name>.meta.json, and every
+ * manifest entry with `fragment: name`; `binName` is only used for log/error message
+ * prefixes and the CLI's own usage string.
+ */
+export interface SyncFragment {
+    /** e.g. "trace" or "profile" — must match the fragment's file basenames and its
+     *  manifest entries' `fragment` field. */
+    name: string;
+    /** e.g. "trace-sync" or "profile-sync" — the bin name this is invoked as. */
+    binName: string;
+}
+export declare class SyncCliError extends Error {
+}
+/**
+ * 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)`.
+ */
+export declare function runSyncCli(argv: string[], fragment: SyncFragment): Promise<void>;

package/dist/cli/sync-engine.js

@@ -0,0 +1,543 @@
+/**
+ * sync-engine — the shared internals behind `trace-sync` and `profile-sync`
+ * (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 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
+ * `SyncFragment` rather than hardcoded, so a third fragment only ever needs its own
+ * ~15-line wrapper file, not a second copy of this logic.
+ *
+ * Migrations for every fragment live together under prisma/migrations/ and are
+ * tracked in one shared prisma/migrations/manifest.json, disambiguated by each
+ * entry's `fragment` field — `computePending`/`cmdInit`/`cmdApply` below all filter
+ * the manifest down to `entry.fragment === fragment.name` before doing anything, so
+ * e.g. `trace-sync init` only ever touches trace's own migrations, never profile's.
+ *
+ * Subcommands (identical across every fragment):
+ *   <bin> init    copy fragment + migrations in, run `prisma validate` and
+ *                  `prisma db execute`, write the lock file.
+ *   <bin> diff     read-only: compare this package's bundled fragment version /
+ *                  migration manifest against the consumer's lock file and report
+ *                  what's pending. Never applies anything.
+ *   <bin> apply    apply pending migrations + refresh the fragment copy, update the
+ *                  lock file. Does not re-run `prisma validate` against a fresh
+ *                  init — use `init` for first install.
+ *   <bin> status   read-only report: fragment version, applied migrations, and
+ *                  whether the consumer's copy of the fragment has been hand-edited
+ *                  (checksum mismatch).
+ *
+ * This is a real, runnable CLI — it shells out to the consumer's local `prisma` via
+ * `npx` and touches the consumer's real filesystem — not a stub.
+ */
+import { createHash } from "node:crypto";
+import spawn from "cross-spawn";
+import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+export class SyncCliError extends Error {
+}
+function readJson(filePath) {
+    return JSON.parse(readFileSync(filePath, "utf8"));
+}
+function sha256(content) {
+    return `sha256:${createHash("sha256").update(content).digest("hex")}`;
+}
+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
+// ---------------------------------------------------------------------------
+class SyncEngine {
+    fragment;
+    packageRoot;
+    fragmentSrcPath;
+    fragmentMetaPath;
+    migrationsSrcDir;
+    manifestSrcPath;
+    lockFileName;
+    constructor(fragment) {
+        this.fragment = fragment;
+        // Root of the installed @flytedesk/app-kit package (two levels up from
+        // dist/cli/<bin>.js — this file, once built).
+        this.packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+        this.fragmentSrcPath = path.join(this.packageRoot, "prisma", "fragments", `${fragment.name}.prisma`);
+        this.fragmentMetaPath = path.join(this.packageRoot, "prisma", "fragments", `${fragment.name}.meta.json`);
+        this.migrationsSrcDir = path.join(this.packageRoot, "prisma", "migrations");
+        this.manifestSrcPath = path.join(this.migrationsSrcDir, "manifest.json");
+        this.lockFileName = `.app-kit-${fragment.name}.lock.json`;
+    }
+    fail(message) {
+        console.error(`${this.fragment.binName}: ${message}`);
+        process.exitCode = 1;
+        throw new SyncCliError(message);
+    }
+    readFragmentMeta() {
+        return readJson(this.fragmentMetaPath);
+    }
+    /** Every manifest entry for THIS fragment only — see the module doc comment on
+     *  why the manifest is shared across fragments and how entries are disambiguated. */
+    readManifest() {
+        return readJson(this.manifestSrcPath).filter((entry) => entry.fragment === this.fragment.name);
+    }
+    lockFilePath(consumerRoot) {
+        return path.join(consumerRoot, this.lockFileName);
+    }
+    readLockFile(consumerRoot) {
+        const p = this.lockFilePath(consumerRoot);
+        if (!existsSync(p))
+            return null;
+        return readJson(p);
+    }
+    writeLockFile(consumerRoot, lock) {
+        writeFileSync(this.lockFilePath(consumerRoot), `${JSON.stringify(lock, null, 2)}\n`, "utf8");
+    }
+    // -------------------------------------------------------------------------
+    // Locating the consumer's Prisma schema folder via their prisma.config.ts
+    // -------------------------------------------------------------------------
+    static CONSUMER_CONFIG_CANDIDATES = [
+        "prisma.config.ts",
+        "prisma.config.mts",
+        "prisma.config.js",
+        "prisma.config.mjs",
+    ];
+    findConsumerConfigFile(consumerRoot) {
+        for (const candidate of SyncEngine.CONSUMER_CONFIG_CANDIDATES) {
+            const p = path.join(consumerRoot, candidate);
+            if (existsSync(p))
+                return p;
+        }
+        this.fail(`could not find a prisma.config.{ts,mts,js,mjs} in ${consumerRoot}. ` +
+            `${this.fragment.binName} reads this file to find your Prisma schema folder — it does not assume a path.`);
+    }
+    /**
+     * Best-effort read of the consumer's `schema` setting out of their
+     * prisma.config.ts default export. Supports the shapes Prisma's config API has
+     * used: a bare string path (file or folder), or `{ path: string }`. Relies on
+     * Node's native TypeScript type-stripping (unflagged as of the Node 24 baseline
+     * this package requires) to import a .ts file directly — if the consumer's config
+     * uses syntax that isn't erasable (enums, namespaces, parameter properties, etc.)
+     * this import will fail, and that failure is surfaced as-is rather than swallowed.
+     */
+    async loadConsumerSchemaPath(consumerRoot) {
+        const configFile = this.findConsumerConfigFile(consumerRoot);
+        let mod;
+        try {
+            mod = await import(pathToFileURL(configFile).href);
+        }
+        catch (err) {
+            this.fail(`failed to load ${configFile}: ${err.message}\n` +
+                `If this config file uses TypeScript syntax that Node can't type-strip natively ` +
+                `(enums, namespaces, decorators, ...), ${this.fragment.binName} can't import it directly.`);
+        }
+        const config = mod.default ?? mod;
+        const schema = config?.schema;
+        let schemaPath;
+        if (typeof schema === "string") {
+            schemaPath = schema;
+        }
+        else if (schema &&
+            typeof schema === "object" &&
+            typeof schema.path === "string") {
+            schemaPath = schema.path;
+        }
+        if (!schemaPath) {
+            this.fail(`could not find a "schema" path in ${configFile}'s default export. ` +
+                `Expected \`defineConfig({ schema: "prisma/schema" })\` (or a { path } object).`);
+        }
+        return path.resolve(path.dirname(configFile), 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 {
+                kind: "flat-file",
+                file: schemaPath,
+                prismaRoot: path.dirname(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/`. */
+    resolvePrismaRoot(schemaFolder) {
+        return path.basename(schemaFolder) === "schema"
+            ? path.dirname(schemaFolder)
+            : schemaFolder;
+    }
+    // -------------------------------------------------------------------------
+    // Shelling out to the consumer's local `prisma`
+    // -------------------------------------------------------------------------
+    runPrisma(args, cwd) {
+        // On Windows, npx resolves to npx.cmd, a shell script — node:child_process's
+        // spawnSync can't exec it directly (EINVAL) without shell:true, and shell:true
+        // 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",
+        });
+        if (result.error) {
+            this.fail(`failed to run "npx prisma ${args.join(" ")}": ${result.error.message}`);
+        }
+        if (result.status !== 0) {
+            this.fail(`"npx prisma ${args.join(" ")}" exited with code ${result.status}`);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // File copying
+    // -------------------------------------------------------------------------
+    copyFragment(schemaFolder) {
+        mkdirSync(schemaFolder, { recursive: true });
+        copyFileSync(this.fragmentSrcPath, path.join(schemaFolder, `${this.fragment.name}.prisma`));
+    }
+    copyMigration(migrationId, migrationsDestDir) {
+        const srcDir = path.join(this.migrationsSrcDir, migrationId);
+        const destDir = path.join(migrationsDestDir, migrationId);
+        mkdirSync(destDir, { recursive: true });
+        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();
+    }
+    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) {
+        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.extractFragmentBody(readFileSync(this.fragmentSrcPath, "utf8"));
+        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) {
+        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);
+        }
+    }
+    /**
+     * What gets recorded as `fragmentChecksum` in the lock file, and what cmdStatus
+     * recomputes from the consumer's tree to detect hand-edits — computed the same
+     * way installFragment actually wrote it, per layout: the exact fragment file
+     * bytes for the folder/sibling-copy case, or the extracted marker-region body for
+     * the flat-file/merge case (NOT the whole fragment source file, since the
+     * installed region deliberately excludes the fragment file's leading doc
+     * comment — see extractFragmentBody).
+     */
+    computeFragmentChecksum(layout) {
+        if (layout.kind === "folder") {
+            return sha256File(this.fragmentSrcPath);
+        }
+        return sha256(this.extractFragmentBody(readFileSync(this.fragmentSrcPath, "utf8")));
+    }
+    // -------------------------------------------------------------------------
+    // Subcommands
+    // -------------------------------------------------------------------------
+    async cmdInit(consumerRoot) {
+        const bin = this.fragment.binName;
+        const schemaPath = await this.loadConsumerSchemaPath(consumerRoot);
+        const layout = this.classifySchemaLayout(schemaPath);
+        const migrationsDestDir = path.join(layout.prismaRoot, "migrations");
+        this.installFragment(layout);
+        console.log(`${bin}: running "npx prisma validate" against ${consumerRoot}`);
+        this.runPrisma(["validate"], consumerRoot);
+        const manifest = this.readManifest();
+        const appliedMigrations = [];
+        for (const entry of manifest) {
+            console.log(`${bin}: copying migration ${entry.id} into ${migrationsDestDir}`);
+            this.copyMigration(entry.id, migrationsDestDir);
+            const migrationSqlPath = path.join(migrationsDestDir, entry.id, "migration.sql");
+            console.log(`${bin}: applying ${entry.id} via "npx prisma db execute"`);
+            this.runPrisma(
+            // Prisma ORM v7's `db execute` no longer accepts `--schema` at all — the
+            // datasource URL comes only from the consumer's prisma.config.ts now (same
+            // "config file, not CLI flags" migration documented on flytedesk-id's own
+            // prisma.config.ts). Passing --schema here is a hard CLI usage error
+            // ("unknown or unexpected option: --schema") against a real Prisma 7 install,
+            // confirmed while building examples/hello-world.
+            ["db", "execute", "--file", migrationSqlPath], consumerRoot);
+            appliedMigrations.push(entry.id);
+        }
+        const meta = this.readFragmentMeta();
+        this.writeLockFile(consumerRoot, {
+            fragmentVersion: meta.fragmentVersion,
+            fragmentChecksum: this.computeFragmentChecksum(layout),
+            appliedMigrations,
+            lastSyncedAt: new Date().toISOString(),
+        });
+        console.log(`${bin}: wrote ${this.lockFilePath(consumerRoot)}`);
+        console.log(`${bin}: init complete.`);
+    }
+    computePending(consumerRoot) {
+        const lock = this.readLockFile(consumerRoot);
+        if (!lock) {
+            this.fail(`no ${this.lockFileName} found at ${consumerRoot}. Run "${this.fragment.binName} init" first.`);
+        }
+        const meta = this.readFragmentMeta();
+        const manifest = this.readManifest();
+        const applied = new Set(lock.appliedMigrations);
+        const pendingMigrations = manifest.filter((entry) => !applied.has(entry.id));
+        return {
+            fragmentVersionCurrent: meta.fragmentVersion,
+            fragmentVersionInstalled: lock.fragmentVersion,
+            fragmentVersionChanged: meta.fragmentVersion !== lock.fragmentVersion,
+            pendingMigrations,
+        };
+    }
+    cmdDiff(consumerRoot) {
+        const report = this.computePending(consumerRoot);
+        if (report.fragmentVersionChanged) {
+            console.log(`fragment version: ${report.fragmentVersionInstalled} -> ${report.fragmentVersionCurrent} (changed)`);
+        }
+        else {
+            console.log(`fragment version: ${report.fragmentVersionCurrent} (up to date)`);
+        }
+        if (report.pendingMigrations.length === 0) {
+            console.log("migrations: up to date, nothing pending.");
+            return;
+        }
+        console.log(`migrations: ${report.pendingMigrations.length} pending:`);
+        for (const entry of report.pendingMigrations) {
+            console.log(`  - ${entry.id} (introduced in fragment ${entry.introducedInFragmentVersion})`);
+        }
+        console.log(`${this.fragment.binName} diff is read-only. Run "${this.fragment.binName} apply" to apply these.`);
+    }
+    async cmdApply(consumerRoot) {
+        const bin = this.fragment.binName;
+        const report = this.computePending(consumerRoot);
+        const schemaPath = await this.loadConsumerSchemaPath(consumerRoot);
+        const layout = this.classifySchemaLayout(schemaPath);
+        const migrationsDestDir = path.join(layout.prismaRoot, "migrations");
+        this.installFragment(layout);
+        const lock = this.readLockFile(consumerRoot);
+        if (!lock) {
+            this.fail(`no ${this.lockFileName} found at ${consumerRoot}. Run "${bin} init" first.`);
+        }
+        const appliedMigrations = [...lock.appliedMigrations];
+        if (report.pendingMigrations.length === 0) {
+            console.log(`${bin}: no pending migrations to apply.`);
+        }
+        for (const entry of report.pendingMigrations) {
+            console.log(`${bin}: copying migration ${entry.id} into ${migrationsDestDir}`);
+            this.copyMigration(entry.id, migrationsDestDir);
+            const migrationSqlPath = path.join(migrationsDestDir, entry.id, "migration.sql");
+            console.log(`${bin}: applying ${entry.id} via "npx prisma db execute"`);
+            this.runPrisma(
+            // See the matching comment in cmdInit above — Prisma 7's `db execute` has no
+            // --schema flag; the datasource comes from the consumer's prisma.config.ts.
+            ["db", "execute", "--file", migrationSqlPath], consumerRoot);
+            appliedMigrations.push(entry.id);
+        }
+        const meta = this.readFragmentMeta();
+        this.writeLockFile(consumerRoot, {
+            fragmentVersion: meta.fragmentVersion,
+            fragmentChecksum: this.computeFragmentChecksum(layout),
+            appliedMigrations,
+            lastSyncedAt: new Date().toISOString(),
+        });
+        console.log(`${bin}: wrote ${this.lockFilePath(consumerRoot)}`);
+        console.log(`${bin}: apply complete.`);
+    }
+    async cmdStatus(consumerRoot) {
+        const lock = this.readLockFile(consumerRoot);
+        if (!lock) {
+            console.log(`no ${this.lockFileName} found at ${consumerRoot}. Not yet initialized — run "${this.fragment.binName} init".`);
+            return;
+        }
+        console.log(`fragment version (installed):  ${lock.fragmentVersion}`);
+        console.log(`fragment version (package):    ${this.readFragmentMeta().fragmentVersion}`);
+        console.log(`last synced:                   ${lock.lastSyncedAt}`);
+        console.log(`applied migrations (${lock.appliedMigrations.length}):`);
+        for (const id of lock.appliedMigrations) {
+            console.log(`  - ${id}`);
+        }
+        try {
+            const schemaPath = await this.loadConsumerSchemaPath(consumerRoot);
+            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)`;
+            }
+            if (installedChecksum === lock.fragmentChecksum) {
+                console.log("fragment copy:                 unmodified");
+            }
+            else {
+                console.log(`fragment copy:                 CHECKSUM MISMATCH — ${location} has been hand-edited ` +
+                    `(or is out of sync with the lock file)`);
+            }
+        }
+        catch (err) {
+            console.log(`fragment copy:                 could not verify (${err.message})`);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Entry point shared by every fragment's bin wrapper
+// ---------------------------------------------------------------------------
+const SUBCOMMANDS = ["init", "diff", "apply", "status"];
+function isSubcommand(value) {
+    return SUBCOMMANDS.includes(value);
+}
+/**
+ * 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)`.
+ */
+export async function runSyncCli(argv, fragment) {
+    const [subcommand, ...rest] = argv;
+    if (!isSubcommand(subcommand)) {
+        console.error(`usage: ${fragment.binName} <${SUBCOMMANDS.join("|")}>`);
+        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 consumerRoot = process.cwd();
+    const engine = new SyncEngine(fragment);
+    switch (subcommand) {
+        case "init":
+            await engine.cmdInit(consumerRoot);
+            break;
+        case "diff":
+            engine.cmdDiff(consumerRoot);
+            break;
+        case "apply":
+            await engine.cmdApply(consumerRoot);
+            break;
+        case "status":
+            await engine.cmdStatus(consumerRoot);
+            break;
+    }
+}
+//# sourceMappingURL=sync-engine.js.map