@lotics/cli 0.71.0 → 0.74.0

package/dist/package_commands.js

@@ -0,0 +1,957 @@
+/**
+ * `lotics package *` subcommands — the app-package authoring + dev/test/run loop
+ * (see docs/app_packages.md). An app *package* is a versioned, workspace-agnostic
+ * blueprint Lotics maintains once and installs into many workspaces. This module
+ * implements the full harness:
+ *
+ *   new      scaffold a package project (contract + app source).
+ *   build    build the publishable bundle (source + dist).
+ *   publish  create a new immutable package version from the contract + bundle.
+ *   dev      scaffold-sync the package into a dev workspace (install/upgrade) and
+ *            run the existing app dev server against the resulting installation.
+ *   sync     re-run the scaffold-sync (additive migrate + materialize) without dev.
+ *   reset    DEV-ONLY, hard-gated: drop the scaffolded tables + re-scaffold clean.
+ *   install  materialize a published version into the current workspace.
+ *   eject    sever an installation's package link (last rung of customization).
+ *
+ * The dev loop reuses the *published* path end-to-end: `dev`/`sync` build →
+ * publish a new version → install (first time) or upgrade (subsequent) into the
+ * dev workspace, so the dev installation goes through the exact scaffold +
+ * materialize the real install/upgrade run (no parallel dev-only materializer).
+ * The local installation pin per dev workspace is recorded in the project
+ * manifest so a re-sync upgrades in place.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import "./client.js";
+import { buildStarterTemplate, STARTER_FALLBACK_SDK_VERSION } from "./starter_template.js";
+import { generatePackageAppFields, } from "./generate_package_fields.js";
+import { appDirName, fetchLatestNpmVersion, runNpm, runTar } from "./app_commands.js";
+import { writeFileAtomic } from "./file_command_io.js";
+import { startDevServer, openBrowser } from "./dev/server.js";
+const CONTRACT_FILE = "contract.json";
+/**
+ * The origin pin `lotics package extract` writes and `lotics package adopt`
+ * reads back: `{ app_id, workspace_id, binding }`. Lives under `.lotics/`, which
+ * is in `SOURCE_STAGE_EXCLUDES` — so it never rides along in a published bundle.
+ */
+const ADOPT_BINDING_FILE = "adopt_binding.json";
+function packageJsonPath(projectDir) {
+    return path.join(projectDir, "package.json");
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Read the package project's manifest, failing loud when the dir isn't one. */
+export function readPackageProject(projectDir) {
+    const pkgPath = packageJsonPath(projectDir);
+    if (!fs.existsSync(pkgPath)) {
+        throw new Error(`No package.json in ${projectDir}. Run this inside a package project (lotics package new <name>).`);
+    }
+    const parsed = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+    if (!isPlainObject(parsed))
+        throw new Error(`Malformed package.json in ${projectDir}.`);
+    const lotics = parsed.lotics;
+    const pkg = isPlainObject(lotics) ? lotics.package : undefined;
+    if (!isPlainObject(pkg) || typeof pkg.name !== "string") {
+        throw new Error(`${pkgPath} has no lotics.package manifest — not a package project. Use "lotics package new <name>".`);
+    }
+    const dev = {};
+    if (isPlainObject(pkg.dev)) {
+        for (const [ws, entry] of Object.entries(pkg.dev)) {
+            if (isPlainObject(entry) && typeof entry.app_id === "string" && typeof entry.version === "number") {
+                dev[ws] = { app_id: entry.app_id, version: entry.version };
+            }
+        }
+    }
+    const manifest = {
+        id: typeof pkg.id === "string" ? pkg.id : null,
+        name: pkg.name,
+        description: typeof pkg.description === "string" ? pkg.description : null,
+        version: typeof pkg.version === "number" ? pkg.version : null,
+        dev,
+    };
+    return { pkgJson: parsed, manifest };
+}
+/** Persist an updated manifest back into the project's package.json (atomic write). */
+export function writePackageManifest(projectDir, project) {
+    const next = {
+        ...project.pkgJson,
+        lotics: {
+            ...(isPlainObject(project.pkgJson.lotics) ? project.pkgJson.lotics : {}),
+            package: project.manifest,
+        },
+    };
+    // Atomic write: a torn plain write could corrupt package.json and lose the
+    // stamped registry `package_id` — which would orphan the published package
+    // and create a duplicate on the next publish retry.
+    writeFileAtomic(packageJsonPath(projectDir), new TextEncoder().encode(JSON.stringify(next, null, 2) + "\n"));
+}
+/**
+ * The package.json to ship INSIDE `source.tar.gz`: the on-disk manifest with the
+ * author-local `lotics.package.dev` map stripped. `dev` is the author's private
+ * dev-workspace → installation bookkeeping; it must never reach a consumer (every
+ * install carries the source, and `lotics app pull` ejects it). Returns a
+ * sanitized copy — the on-disk package.json is left untouched. `id`/`name`/
+ * `description`/`version` are the package's stable identity and stay.
+ */
+export function sanitizePackageJsonForSource(pkgJson) {
+    const lotics = isPlainObject(pkgJson.lotics) ? pkgJson.lotics : {};
+    const pkg = isPlainObject(lotics.package) ? lotics.package : {};
+    const { dev: _dev, ...pkgWithoutDev } = pkg;
+    return {
+        ...pkgJson,
+        lotics: { ...lotics, package: pkgWithoutDev },
+    };
+}
+/**
+ * Transform an app project's package.json (the source archive `lotics app pull`
+ * downloads, carrying the `lotics.app_id`/`workspace_id` app manifest) into a
+ * package project's `PackageProjectFile`: the app manifest is stripped ENTIRELY
+ * and a fresh, unpublished `lotics.package` manifest (id/version null) is
+ * grafted. Pure — returns a new value, never mutates the input;
+ * `writePackageManifest` writes it (atomic). The bespoke→package promotion's
+ * manifest inversion.
+ */
+export function draftPackageProjectFromApp(appPkgJson, args) {
+    const { lotics: _appManifest, ...rest } = appPkgJson;
+    return {
+        pkgJson: rest,
+        manifest: { id: null, name: args.name, description: args.description, version: null, dev: {} },
+    };
+}
+/**
+ * Parse + validate `.lotics/adopt_binding.json` against the app being adopted.
+ * REFUSES a pin recorded for a different app: a binding maps ONE workspace's
+ * concrete ids, so replaying it onto another app would bind the wrong objects.
+ * Pure; the CLI never interprets the binding, only round-trips it to the server.
+ */
+export function parseAdoptBindingFile(raw, expectedAppId) {
+    if (!isPlainObject(raw) ||
+        typeof raw.app_id !== "string" ||
+        typeof raw.workspace_id !== "string" ||
+        !isPlainObject(raw.binding)) {
+        throw new Error("Malformed .lotics/adopt_binding.json — expected { app_id, workspace_id, binding }.");
+    }
+    if (raw.app_id !== expectedAppId) {
+        throw new Error(`.lotics/adopt_binding.json records app ${raw.app_id}, but you are adopting ${expectedAppId}. ` +
+            `A binding maps one app's concrete ids and must never be applied to another — ` +
+            `run "lotics package extract ${expectedAppId}" to produce the right pin.`);
+    }
+    // Boundary adapter: the file is untyped JSON; `isPlainObject` proved the shape
+    // and the CLI passes the map straight to the server (the validating authority).
+    return {
+        app_id: raw.app_id,
+        workspace_id: raw.workspace_id,
+        binding: raw.binding,
+    };
+}
+/**
+ * Render an extraction report grouped by severity (errors, then warnings, then
+ * info), one `  [<severity>] <area>: <message>` line each, and classify whether
+ * any `error` finding is present. An `error` ⇒ the draft is not publishable
+ * as-is, so `lotics package extract` exits non-zero. Pure — the command prints
+ * `lines` to stderr and gates on `hasError`.
+ */
+export function formatExtractReport(report) {
+    const order = ["error", "warning", "info"];
+    const lines = order.flatMap((severity) => report
+        .filter((f) => f.severity === severity)
+        .map((f) => `  [${f.severity}] ${f.area}: ${f.message}`));
+    return { lines, hasError: report.some((f) => f.severity === "error") };
+}
+function dotLoticsDirEnsured(projectDir) {
+    const dir = path.join(projectDir, ".lotics");
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+}
+/** Numeric "x.y.z" compare — no semver dep (the CLI has zero runtime deps). */
+function cmpVersions(a, b) {
+    const pa = a.split(".").map(Number);
+    const pb = b.split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        const d = (pa[i] || 0) - (pb[i] || 0);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
+/**
+ * The `@lotics/app-sdk` range a package project needs: the live npm latest,
+ * clamped to never fall below `STARTER_FALLBACK_SDK_VERSION` — the release
+ * that ships `getAppBinding`, which the generated `.lotics/app_fields.ts`
+ * imports. A `^0.x` caret range never crosses a minor, so pinning below the
+ * floor (offline, or npm not yet carrying the release) would permanently
+ * scaffold projects that cannot compile their own generated code.
+ */
+function packageSdkRange(sdkLatest) {
+    const version = sdkLatest !== null && cmpVersions(sdkLatest, STARTER_FALLBACK_SDK_VERSION) > 0
+        ? sdkLatest
+        : STARTER_FALLBACK_SDK_VERSION;
+    return `^${version}`;
+}
+/** Read + JSON-parse the project's contract.json (the alias-keyed declaration). */
+function readContract(projectDir) {
+    const contractPath = path.join(projectDir, CONTRACT_FILE);
+    if (!fs.existsSync(contractPath)) {
+        throw new Error(`No ${CONTRACT_FILE} in ${projectDir}. A package project declares its data model there.`);
+    }
+    return JSON.parse(fs.readFileSync(contractPath, "utf-8"));
+}
+/**
+ * (Re)generate the package project's `.lotics/app_fields.ts` from its
+ * contract.json — the runtime-resolving F/OPT/ROLE surface (see
+ * `generate_package_fields.ts`). Runs on new/extract and on every dev/sync so
+ * contract edits keep the aliases addressable. `.lotics` is in
+ * SOURCE_STAGE_EXCLUDES: the compiled module ships inside `dist/`, and a
+ * post-eject `lotics app pull` regenerates the bespoke (baked) variant.
+ */
+function writePackageAppFields(projectDir) {
+    const contract = readContract(projectDir);
+    const dotLotics = path.join(projectDir, ".lotics");
+    fs.mkdirSync(dotLotics, { recursive: true });
+    fs.writeFileSync(path.join(dotLotics, "app_fields.ts"), generatePackageAppFields(contract));
+    console.error("Wrote .lotics/app_fields.ts (contract-derived, runtime-resolved)");
+}
+/** Top-level project entries that never ship in the source archive. */
+const SOURCE_STAGE_EXCLUDES = new Set([
+    "node_modules",
+    "dist",
+    ".lotics",
+    ".git",
+    "bundle.tar.gz",
+    "package.json",
+]);
+/**
+ * Copy the project's source tree into `sourceStage` with explicit TOP-LEVEL
+ * excludes, writing a sanitized `package.json` in place of the on-disk one.
+ * Deliberately not tar `--exclude` flags: those match at any depth (a nested
+ * `templates/dist/` would be silently dropped) and GNU tar vs bsdtar (macOS)
+ * disagree on `./`-prefixed patterns, which broke the sanitized-package.json
+ * graft on macOS.
+ */
+export function stagePackageSource(projectDir, sourceStage) {
+    const project = readPackageProject(projectDir);
+    fs.mkdirSync(sourceStage, { recursive: true });
+    for (const entry of fs.readdirSync(projectDir)) {
+        if (SOURCE_STAGE_EXCLUDES.has(entry) || entry.endsWith(".tsbuildinfo"))
+            continue;
+        fs.cpSync(path.join(projectDir, entry), path.join(sourceStage, entry), { recursive: true });
+    }
+    fs.writeFileSync(path.join(sourceStage, "package.json"), JSON.stringify(sanitizePackageJsonForSource(project.pkgJson), null, 2) + "\n");
+}
+/**
+ * Build the publishable bundle: `npm run build` (vite → dist/), then a gzipped
+ * tarball carrying `source.tar.gz` (the pullable project tree) + `dist.tar.gz`
+ * (the prebuilt assets) as its two top-level members — the publish↔install
+ * contract the backend's `extractPackageBundle` reads. Returns the bytes.
+ */
+async function buildPackageBundle(projectDir) {
+    console.error("Building...");
+    await runNpm(["run", "build"], projectDir);
+    const distDir = path.join(projectDir, "dist");
+    if (!fs.existsSync(distDir)) {
+        throw new Error(`Build did not produce a dist/ directory in ${projectDir}. ` +
+            `Check that 'npm run build' is configured correctly.`);
+    }
+    // Stage the two member archives in a temp dir, then tar them into the bundle.
+    const stage = fs.mkdtempSync(path.join(tmpdir(), "lotics-pkg-"));
+    const bundlePath = path.join(tmpdir(), `lotics-bundle-${Date.now()}.tar.gz`);
+    try {
+        console.error("Packaging source...");
+        // Stage a copy of the source tree with EXPLICIT top-level excludes, then
+        // tar the stage with no --exclude flags at all. tar exclude patterns are
+        // the wrong tool twice over: they match at ANY depth (a nested
+        // `templates/dist/` would be silently dropped from the bundle), and GNU
+        // tar vs bsdtar (macOS) disagree on whether `./package.json` and
+        // `package.json` are the same pattern — bsdtar strips the leading `./`,
+        // which would also exclude the sanitized package.json grafted below.
+        //
+        // The on-disk package.json carries the author-local `lotics.package.dev`
+        // map; the stage gets a sanitized copy in its place, so that bookkeeping
+        // never ships to a consumer nor lands in an `lotics app pull` eject.
+        const sourceStage = path.join(stage, "source");
+        stagePackageSource(projectDir, sourceStage);
+        await runTar(["-czf", path.join(stage, "source.tar.gz"), "-C", sourceStage, "."], projectDir);
+        console.error("Packaging dist...");
+        await runTar(["-czf", path.join(stage, "dist.tar.gz"), "-C", distDir, "."], projectDir);
+        console.error("Bundling...");
+        await runTar(["-czf", bundlePath, "source.tar.gz", "dist.tar.gz"], stage);
+        return fs.readFileSync(bundlePath);
+    }
+    finally {
+        fs.rmSync(stage, { recursive: true, force: true });
+        if (fs.existsSync(bundlePath))
+            fs.unlinkSync(bundlePath);
+    }
+}
+/** The minimal, valid starting contract a `package new` scaffold ships. */
+export function starterContract(name) {
+    return {
+        entities: [
+            {
+                alias: "item",
+                label: name,
+                description: `Records managed by the ${name} package.`,
+                fields: [
+                    { alias: "name", label: "Name", type: "text", required: true },
+                    { alias: "notes", label: "Notes", type: "text" },
+                    {
+                        alias: "status",
+                        label: "Status",
+                        type: "select",
+                        options: [
+                            { alias: "open", label: "Open", color: "blue" },
+                            { alias: "done", label: "Done", color: "green" },
+                        ],
+                    },
+                ],
+            },
+        ],
+        roles: [],
+        templates: [],
+        queries: [
+            {
+                alias: "items",
+                ast: {
+                    kind: "from_table",
+                    from_entity: "item",
+                    sort: [{ field_key: "name", order: "asc" }],
+                },
+            },
+        ],
+        workflows: [],
+        agents: [],
+        config: [
+            { alias: "heading", label: "List heading", type: "text", default: name },
+        ],
+    };
+}
+/**
+ * `lotics package new <name> [path]` — scaffold a package project. Reuses the
+ * app starter (Vite+React+TS) for the code surface, swaps its app manifest for a
+ * package manifest, and adds a starter `contract.json`. The project publishes
+ * with `lotics package publish` and runs against a dev workspace with
+ * `lotics package dev`.
+ */
+export async function packageNew(args) {
+    const targetPath = path.resolve(args.targetPath ?? appDirName(args.name));
+    if (fs.existsSync(targetPath) && fs.readdirSync(targetPath).length > 0) {
+        throw new Error(`Target directory ${targetPath} is not empty.`);
+    }
+    fs.mkdirSync(targetPath, { recursive: true });
+    // The starter bakes an app manifest (app_id/workspace_id) into package.json;
+    // a package is workspace-agnostic, so those placeholders are replaced with the
+    // package manifest below. The rest of the starter (config, src, tests) is the
+    // package's code surface verbatim.
+    // Resolve the live @lotics/ui + @lotics/app-sdk versions like `app create`
+    // does — the generated .lotics/app_fields.ts imports `getAppBinding`, and a
+    // ^0.x caret range never crosses a minor, so a stale starter fallback would
+    // permanently pin the project below the API it needs (offline still works
+    // off STARTER_FALLBACK_*, kept ≥ that floor).
+    const [uiLatest, sdkLatest] = await Promise.all([
+        fetchLatestNpmVersion("@lotics/ui"),
+        fetchLatestNpmVersion("@lotics/app-sdk"),
+    ]);
+    const files = buildStarterTemplate({
+        app_name: args.name,
+        app_id: "",
+        workspace_id: "",
+        ui_version: uiLatest ? `^${uiLatest}` : undefined,
+        sdk_version: packageSdkRange(sdkLatest),
+    });
+    for (const file of files) {
+        const fullPath = path.join(targetPath, file.path);
+        if (file.path === "package.json") {
+            const pkg = JSON.parse(file.content);
+            const manifest = {
+                id: null,
+                name: args.name,
+                description: null,
+                version: null,
+                dev: {},
+            };
+            pkg.lotics = { package: manifest };
+            fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+            fs.writeFileSync(fullPath, JSON.stringify(pkg, null, 2) + "\n");
+            continue;
+        }
+        fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+        fs.writeFileSync(fullPath, file.content);
+    }
+    fs.writeFileSync(path.join(targetPath, CONTRACT_FILE), JSON.stringify(starterContract(args.name), null, 2) + "\n");
+    writePackageAppFields(targetPath);
+    console.error(`Scaffolded ${files.length + 1} files into ${targetPath}`);
+    console.error("Installing npm dependencies...");
+    await runNpm(["install"], targetPath);
+    console.error(`\nReady. Next steps:`);
+    console.error(`  cd ${path.relative(process.cwd(), targetPath) || "."}`);
+    console.error(`  # edit contract.json + src/App.tsx, then run it against a dev workspace:`);
+    console.error(`  lotics workspace create "<name> dev" --dev`);
+    console.error(`  lotics package dev --workspace <dev_ws>`);
+}
+/**
+ * `lotics package build [path]` — build the publishable bundle and write it to
+ * `bundle.tar.gz` in the project. Mostly a local sanity check / CI artifact;
+ * `publish` and `dev`/`sync` build the bundle in memory directly.
+ */
+export async function packageBuild(args) {
+    const projectDir = path.resolve(args.projectDir ?? process.cwd());
+    readPackageProject(projectDir); // assert it's a package project
+    const bundle = await buildPackageBundle(projectDir);
+    const out = path.join(projectDir, "bundle.tar.gz");
+    fs.writeFileSync(out, bundle);
+    console.error(`Built ${out} (${(bundle.byteLength / 1024).toFixed(1)} KB)`);
+}
+/**
+ * Build + publish a new immutable package version from the project's contract +
+ * bundle. Creates the registry package on first publish (stamping its id into
+ * the manifest), then publishes the next monotonic version. Returns the new
+ * version number and the resolved package id.
+ */
+async function publishVersion(client, projectDir, opts) {
+    const project = readPackageProject(projectDir);
+    const contract = readContract(projectDir);
+    let packageId = project.manifest.id;
+    if (packageId === null) {
+        const pkg = await client.createAppPackage({
+            name: project.manifest.name,
+            description: project.manifest.description,
+        });
+        packageId = pkg.id;
+        project.manifest.id = packageId;
+        writePackageManifest(projectDir, project);
+        console.error(`Created package ${pkg.name} (${pkg.id}).`);
+    }
+    const bundle = await buildPackageBundle(projectDir);
+    console.error("Publishing version...");
+    const version = await client.publishAppPackageVersion(packageId, {
+        contract,
+        bundle,
+        changelog: opts.changelog ?? null,
+    });
+    project.manifest.version = version.version;
+    writePackageManifest(projectDir, project);
+    return { package_id: packageId, version: version.version };
+}
+/**
+ * `lotics package publish [path] [-m <changelog>]` — publish a new version.
+ */
+export async function packagePublish(client, args) {
+    const projectDir = path.resolve(args.projectDir ?? process.cwd());
+    const { package_id, version } = await publishVersion(client, projectDir, {
+        changelog: args.changelog,
+    });
+    console.error(`Published ${package_id} v${version}.`);
+    console.error(`  Install it:  lotics package install ${package_id} --version ${version}`);
+}
+/**
+ * Fail loud unless `workspace` is a throwaway dev workspace. The dev/sync
+ * scaffold path publishes a new version and scaffold-installs package tables into
+ * the resolved workspace, so the target MUST be a dev workspace — this mirrors
+ * the server-side `package reset` gate so a forgotten `--workspace` (prod
+ * selected) can never scaffold package tables into prod. Fails closed: an absent
+ * `is_dev` (a server that doesn't yet serialize it) is treated as non-dev.
+ */
+export function assertDevWorkspace(workspace) {
+    if (workspace.is_dev === true)
+        return;
+    throw new Error(`Workspace "${workspace.name}" (${workspace.id}) is not a dev workspace. ` +
+        `"lotics package dev"/"sync" scaffold package tables into the target workspace, so it must be a throwaway dev workspace. ` +
+        `Create one with "lotics workspace create <name> --dev" and pass --workspace <dev_ws>.`);
+}
+/**
+ * Scaffold-sync the local package into the dev workspace: publish the current
+ * contract + bundle as a new version, then install it (first time) or upgrade
+ * the recorded installation (subsequent runs) so the dev workspace goes through
+ * the exact scaffold + materialize the real install/upgrade run. Records the
+ * installation pin per dev workspace in the manifest. Returns the dev
+ * installation's app id + name.
+ */
+async function syncToDevWorkspace(client, projectDir) {
+    const devWorkspaceId = client.getWorkspaceId();
+    if (!devWorkspaceId) {
+        throw new Error("No dev workspace selected. Pass --workspace <dev_ws> (a workspace created with --dev).");
+    }
+    // Guard BEFORE publishing: dev/sync scaffold-installs package tables into the
+    // resolved workspace, so it must be a throwaway dev workspace — a developer who
+    // forgot --workspace with prod selected would otherwise scaffold into prod.
+    // Mirrors the server-side `package reset` gate (which refuses any non-`is_dev`
+    // workspace).
+    const workspace = await client.getWorkspaceInfo(devWorkspaceId);
+    if (!workspace) {
+        throw new Error(`Workspace ${devWorkspaceId} is not accessible with these credentials. Pass --workspace <dev_ws> (a workspace created with --dev).`);
+    }
+    assertDevWorkspace(workspace);
+    // Contract may have been edited since the last sync — regenerate the
+    // runtime F/OPT/ROLE surface before the build that publishVersion runs.
+    writePackageAppFields(projectDir);
+    const { package_id, version } = await publishVersion(client, projectDir, {
+        changelog: "dev sync",
+    });
+    // Re-read after publish (publishVersion may have stamped the package id).
+    const project = readPackageProject(projectDir);
+    const existing = project.manifest.dev[devWorkspaceId];
+    let appId;
+    if (existing) {
+        console.error(`Upgrading dev installation ${existing.app_id} → v${version}...`);
+        const app = await client.upgradeAppPackage(existing.app_id, { version });
+        appId = app.id;
+    }
+    else {
+        console.error(`Installing ${package_id} v${version} into dev workspace ${devWorkspaceId}...`);
+        const app = await client.installAppPackage(package_id, { version });
+        appId = app.id;
+    }
+    project.manifest.dev[devWorkspaceId] = { app_id: appId, version };
+    writePackageManifest(projectDir, project);
+    const installed = await client.getApp(appId);
+    return { app_id: appId, app_name: installed.name, workspace_id: devWorkspaceId, version };
+}
+/**
+ * `lotics package sync [path]` — re-run the scaffold-sync into the dev workspace
+ * (the continuous loop: edit contract → sync additively migrates + re-materializes).
+ */
+export async function packageSync(client, args) {
+    const projectDir = path.resolve(args.projectDir ?? process.cwd());
+    const result = await syncToDevWorkspace(client, projectDir);
+    console.error(`Synced ${result.app_name} v${result.version} → ${result.app_id} (workspace ${result.workspace_id}).`);
+}
+/**
+ * `lotics package dev [path] [--workspace <dev_ws>] [--view-as <member>]` —
+ * scaffold-sync the package into the dev workspace, then run the existing app
+ * dev server against the resulting installation (HMR over the local source, RPC
+ * forwarded to the live installation). The inner loop: edit contract → re-run to
+ * sync; edit code → hot reload.
+ */
+export async function packageDev(client, args) {
+    const projectDir = path.resolve(args.projectDir ?? process.cwd());
+    const synced = await syncToDevWorkspace(client, projectDir);
+    const handle = await startDevServer({
+        projectDir,
+        app_id: synced.app_id,
+        app_name: synced.app_name,
+        workspace_id: synced.workspace_id,
+        api_url: client.baseUrl,
+        port: args.port,
+        vitePort: args.vitePort,
+        client,
+    });
+    await handle.ready;
+    const url = `http://localhost:${handle.port}`;
+    console.error(`\n  lotics package dev`);
+    console.error(`  package:   ${synced.app_name} (dev installation ${synced.app_id} v${synced.version})`);
+    console.error(`  workspace: ${synced.workspace_id} (dev)`);
+    if (client.viewAsMemberId) {
+        console.error(`  view as:   ${client.viewAsMemberId}`);
+    }
+    console.error(`  vite:      http://localhost:${handle.vitePort}/`);
+    console.error(`  open:      ${url}`);
+    console.error(`  rpc:       ${client.baseUrl} (via Bearer API key)\n`);
+    console.error(`  Edit contract.json then re-run "lotics package dev" / "lotics package sync" to migrate.`);
+    console.error(`  Ctrl-C to stop.\n`);
+    openBrowser(url);
+    await new Promise((resolve) => {
+        const onSig = () => {
+            process.off("SIGINT", onSig);
+            process.off("SIGTERM", onSig);
+            resolve();
+        };
+        process.on("SIGINT", onSig);
+        process.on("SIGTERM", onSig);
+    });
+    console.error("\nStopping…");
+    await handle.stop();
+}
+/**
+ * `lotics package reset [path]` — DEV-ONLY, hard-gated. Drops the dev
+ * installation's package-owned scaffolded tables and re-scaffolds them clean. The
+ * backend refuses any workspace not flagged as a dev workspace, so this can never
+ * erase a real workspace's data. The dev installation is resolved from the
+ * project manifest's pin for the selected workspace.
+ */
+export async function packageReset(client, args) {
+    const projectDir = path.resolve(args.projectDir ?? process.cwd());
+    const devWorkspaceId = client.getWorkspaceId();
+    if (!devWorkspaceId) {
+        throw new Error("No dev workspace selected. Pass --workspace <dev_ws> (a workspace created with --dev).");
+    }
+    const { manifest } = readPackageProject(projectDir);
+    const pin = manifest.dev[devWorkspaceId];
+    if (!pin) {
+        throw new Error(`No dev installation recorded for workspace ${devWorkspaceId}. Run "lotics package dev --workspace ${devWorkspaceId}" first.`);
+    }
+    console.error(`Resetting dev installation ${pin.app_id} in workspace ${devWorkspaceId}...`);
+    const app = await client.resetAppPackage(pin.app_id);
+    console.error(`Reset ${app.name} → ${app.id}. The scaffolded tables were dropped and re-created clean.`);
+}
+/**
+ * Resolve the installation to operate on: an explicit app id wins; otherwise
+ * fall back to the project manifest's dev pin for the selected workspace (the
+ * same resolution `package reset` uses).
+ */
+function resolveInstallationAppId(client, explicit) {
+    if (explicit)
+        return explicit;
+    const workspaceId = client.getWorkspaceId();
+    if (!workspaceId) {
+        throw new Error("Pass an app id (lotics package doctor <app_id>) or select a workspace.");
+    }
+    let manifest;
+    try {
+        ({ manifest } = readPackageProject(path.resolve(process.cwd())));
+    }
+    catch {
+        // CLI usage boundary: translate "this directory isn't a package project"
+        // into the action the caller actually needs.
+        throw new Error("No app id given and the current directory is not a package project. " +
+            "Pass one explicitly: lotics package doctor <app_id>.");
+    }
+    const pin = manifest.dev[workspaceId];
+    if (!pin) {
+        throw new Error(`No app id given and no dev installation recorded for workspace ${workspaceId}. ` +
+            "Pass one explicitly: lotics package doctor <app_id>.");
+    }
+    return pin.app_id;
+}
+/**
+ * Parse repeated `--resolve <key>=<value>` flags. Drift entries
+ * (`<namespace>.<alias>`) take `recreate` or an existing id; modified
+ * artifacts (`<kind>.<alias>`) take `revert` or `keep`. Any other value is a
+ * bind_to id; the server validates value-kind against what the key resolves.
+ */
+export function parseResolveFlags(resolve) {
+    const resolutions = {};
+    for (const entry of resolve) {
+        const eq = entry.indexOf("=");
+        if (eq <= 0 || eq === entry.length - 1) {
+            throw new Error(`Invalid --resolve "${entry}" — expected <key>=recreate|revert|keep or <key>=<existing_id>.`);
+        }
+        const key = entry.slice(0, eq);
+        const value = entry.slice(eq + 1);
+        resolutions[key] =
+            value === "recreate" || value === "revert" || value === "keep" ? value : { bind_to: value };
+    }
+    return resolutions;
+}
+/**
+ * Health check: version pin vs. registry latest + binding drift. Exits
+ * non-zero when drift is found so scripts can gate on it.
+ */
+export async function packageDoctor(client, args) {
+    const app_id = resolveInstallationAppId(client, args.app_id);
+    const health = await client.getAppPackageHealth(app_id);
+    console.error(`${health.package_name} — installation ${health.app_id}`);
+    console.error(`  Installed: v${health.installed_version}   Latest: v${health.latest_version}` +
+        (health.update_available ? "   → update available" : ""));
+    if (health.drift.length === 0) {
+        console.error("  Binding: healthy — every bound alias resolves.");
+    }
+    else {
+        console.error(`  Binding drift (${health.drift.length}):`);
+        for (const d of health.drift) {
+            console.error(`    - ${d.namespace}.${d.alias} → ${d.id} (missing from the workspace)`);
+        }
+        console.error(`  Resolve while upgrading:\n    lotics package upgrade ${app_id}` +
+            ` --resolve <namespace.alias>=recreate   (or =<existing_id> to re-point)`);
+        process.exitCode = 1;
+    }
+    if (health.modified.length === 0) {
+        console.error("  Package artifacts: pristine — no local edits an upgrade would revert.");
+    }
+    else {
+        console.error(`  Locally modified package artifacts (${health.modified.length}):`);
+        for (const m of health.modified) {
+            console.error(`    - ${m.kind}.${m.alias} (an upgrade overwrites this unless kept)`);
+        }
+        console.error(`  Consent while upgrading:\n    lotics package upgrade ${app_id}` +
+            ` --resolve <kind.alias>=revert   (or =keep to retain the edit)`);
+        process.exitCode = 1;
+    }
+    if (health.update_available) {
+        console.error(`  Upgrade: lotics package upgrade ${app_id}`);
+    }
+}
+/**
+ * Preview-then-apply upgrade. Prints the additive plan + informational
+ * removals; refuses (exit 1, with the exact --resolve syntax) while any
+ * binding drift lacks a resolution.
+ */
+export async function packageUpgrade(client, args) {
+    const preview = await client.previewAppPackageUpgrade(args.app_id, {
+        ...(args.version !== undefined ? { version: args.version } : {}),
+    });
+    console.error(`Upgrade v${preview.from_version} → v${preview.to_version}` +
+        (preview.changelog ? ` — ${preview.changelog}` : ""));
+    const summarize = (sets) => Object.entries(sets)
+        .filter(([, entries]) => entries.length > 0)
+        .map(([kind, entries]) => `${entries.length} ${kind}`)
+        .join(", ");
+    const added = summarize(preview.diff.added);
+    const removed = summarize(preview.diff.removed);
+    if (added)
+        console.error(`  Adds: ${added}`);
+    if (removed)
+        console.error(`  Unbinds (workspace data kept): ${removed}`);
+    // Breaking contract changes are NOT resolvable via --resolve — scaffold would
+    // refuse them on a bound alias, and there is no in-flow remediation. Report
+    // every entry and the only two real remedies, then hard-stop.
+    if (preview.diff.breaking.length > 0) {
+        console.error("  Breaking contract changes — NOT resolvable via --resolve (a bound alias's shape changed):");
+        for (const b of preview.diff.breaking) {
+            console.error(`    - ${b.entity}.${b.alias} (${b.kind}): ${b.from} → ${b.to}`);
+        }
+        console.error("  There is no in-flow resolution for this class. The package author must publish a version\n" +
+            "  that keeps these aliases' shape stable, or eject this app (severing the package link)\n" +
+            `  before making the change:  lotics package eject ${args.app_id}`);
+        process.exit(1);
+    }
+    const unresolvedDrift = preview.drift.filter((d) => args.resolutions[`${d.namespace}.${d.alias}`] === undefined);
+    const unresolvedModified = preview.modified.filter((m) => args.resolutions[`${m.kind}.${m.alias}`] === undefined);
+    if (unresolvedDrift.length > 0 || unresolvedModified.length > 0) {
+        if (unresolvedDrift.length > 0) {
+            console.error("  Binding drift must be resolved before upgrading:");
+            for (const d of unresolvedDrift) {
+                console.error(`    --resolve ${d.namespace}.${d.alias}=recreate   (or =<existing_id> to re-point; was ${d.id})`);
+            }
+        }
+        if (unresolvedModified.length > 0) {
+            console.error("  Locally modified package artifacts need consent before upgrading:");
+            for (const m of unresolvedModified) {
+                console.error(`    --resolve ${m.kind}.${m.alias}=revert   (overwrite the local edit; or =keep to retain it)`);
+            }
+        }
+        process.exit(1);
+    }
+    const app = await client.upgradeAppPackage(args.app_id, {
+        ...(args.version !== undefined ? { version: args.version } : {}),
+        ...(Object.keys(args.resolutions).length > 0 ? { resolutions: args.resolutions } : {}),
+    });
+    console.error(`Upgraded ${app.name} → v${app.package_version} (${app.id}).`);
+}
+export async function packageInstall(client, args) {
+    // Surface the trust badge at the consent point: installing materializes the
+    // package's workflows/agents under YOUR authority, so say whose package it is.
+    const pkg = await client.getAppPackage(args.package_id);
+    console.error(pkg.is_official
+        ? `Installing ${pkg.name} — official Lotics package...`
+        : `Installing ${pkg.name} — third-party package (runs under your authority once installed)...`);
+    const app = await client.installAppPackage(args.package_id, {
+        ...(args.version !== undefined ? { version: args.version } : {}),
+    });
+    const versionLabel = app.package_version !== null ? `v${app.package_version}` : "(unknown version)";
+    console.error(`Installed ${app.name} ${versionLabel} → ${app.id} (workspace ${app.workspace_id}).`);
+    console.error("  The data model, queries, workflows, and agents are live.");
+    console.error("  Pull it for local editing:  lotics app pull " + app.id);
+}
+export async function packageEject(client, args) {
+    const app = await client.ejectAppPackage(args.app_id);
+    console.error(`Ejected ${app.name} → ${app.id} (workspace ${app.workspace_id}).`);
+    console.error("  The package link is severed — it's now a normal bespoke app and can no longer be upgraded.");
+    console.error("  Its data model, queries, workflows, and templates are unchanged.");
+    console.error("  Pull the pinned source for local editing:  lotics app pull " + app.id);
+}
+/**
+ * `lotics package extract <app_id> [path]` — promote a bespoke app to a DRAFT
+ * package project (docs/app_packages.md § Promotion). Calls the extract read,
+ * prints the findings report grouped by severity, then ALWAYS emits the draft
+ * project (a broken contract is still the reviewable starting point): the app's
+ * current source archive (same mechanics as `lotics app pull`) with the app
+ * manifest swapped for an unpublished package manifest, `contract.json`, the
+ * file-backed templates staged at their `bytes_ref` paths, and
+ * `.lotics/adopt_binding.json` (the origin pin the `adopt` step reads back).
+ * Exits non-zero when any `error` finding exists — the draft is written, but
+ * publish re-validates and nothing should ship unreviewed.
+ */
+export async function packageExtract(client, args) {
+    const app = await client.getApp(args.app_id);
+    if (!app.current_version_id) {
+        throw new Error(`App ${app.id} has no deployed version — extract stages its source archive, so deploy it first.`);
+    }
+    const extracted = await client.extractAppPackage(args.app_id);
+    const { lines, hasError } = formatExtractReport(extracted.report);
+    if (lines.length > 0) {
+        console.error(`Extraction report (${extracted.report.length}):`);
+        for (const line of lines)
+            console.error(line);
+    }
+    else {
+        console.error("Extraction report: no findings.");
+    }
+    const targetPath = path.resolve(args.targetPath ?? appDirName(app.name));
+    if (fs.existsSync(targetPath) && fs.readdirSync(targetPath).length > 0) {
+        throw new Error(`Target directory ${targetPath} is not empty.`);
+    }
+    fs.mkdirSync(targetPath, { recursive: true });
+    // Pull the app's current source archive — same mechanics as `lotics app pull`
+    // (getAppVersion → presigned source URL → download → untar into the project).
+    const version = await client.getAppVersion(app.id, app.current_version_id);
+    const sourceUrl = await client.getAppVersionSourceUrl(app.id, version.id);
+    const tmpFile = path.join(tmpdir(), `lotics-extract-${app.id}-${Date.now()}.tar.gz`);
+    console.error("Downloading source archive...");
+    await client.downloadFile(sourceUrl, tmpFile);
+    try {
+        console.error(`Extracting to ${targetPath}...`);
+        await runTar(["-xzf", tmpFile, "-C", targetPath], targetPath);
+    }
+    finally {
+        if (fs.existsSync(tmpFile))
+            fs.unlinkSync(tmpFile);
+    }
+    // Swap the app manifest (lotics.app_id/workspace_id) for a fresh, unpublished
+    // package manifest — atomic write via the existing manifest writer.
+    const appPkgJson = JSON.parse(fs.readFileSync(packageJsonPath(targetPath), "utf-8"));
+    const draft = draftPackageProjectFromApp(appPkgJson, { name: app.name, description: null });
+    // The origin app's package.json rides in the source archive with ITS OWN
+    // @lotics/app-sdk range — raise it to the getAppBinding floor the generated
+    // .lotics/app_fields.ts needs (never lower an already-newer range).
+    const deps = isPlainObject(draft.pkgJson.dependencies) ? draft.pkgJson.dependencies : {};
+    const originRange = typeof deps["@lotics/app-sdk"] === "string" ? deps["@lotics/app-sdk"] : null;
+    const originFloor = originRange?.replace(/^[\^~]/, "") ?? null;
+    if (originFloor === null || cmpVersions(originFloor, STARTER_FALLBACK_SDK_VERSION) < 0) {
+        const raised = packageSdkRange(await fetchLatestNpmVersion("@lotics/app-sdk"));
+        draft.pkgJson.dependencies = { ...deps, "@lotics/app-sdk": raised };
+        console.error(`Raised @lotics/app-sdk to ${raised} (generated app_fields needs getAppBinding)`);
+    }
+    writePackageManifest(targetPath, draft);
+    // The alias-keyed draft contract — the reviewable master. Pretty + trailing newline.
+    fs.writeFileSync(path.join(targetPath, CONTRACT_FILE), JSON.stringify(extracted.contract, null, 2) + "\n");
+    console.error(`Wrote ${CONTRACT_FILE}`);
+    // The origin's baked `.lotics/app_fields.ts` (concrete ids) never travels —
+    // regenerate it contract-derived so `F`/`OPT` resolve per-install at runtime
+    // and the extracted source compiles unchanged.
+    writePackageAppFields(targetPath);
+    // vite.config.ts is starter-owned machinery — refresh it wholesale so the
+    // package project carries the current starter config (notably
+    // `build.target: "es2022"`, which the generated app_fields' top-level await
+    // requires). Origin-side dev customizations (e.g. `lotics ui link` aliases)
+    // don't belong in a package.
+    const starterViteConfig = buildStarterTemplate({
+        app_name: app.name,
+        app_id: "",
+        workspace_id: "",
+    }).find((f) => f.path === "vite.config.ts");
+    if (starterViteConfig === undefined) {
+        throw new Error("starter template is missing vite.config.ts — cannot refresh the package project");
+    }
+    const viteConfigPath = path.join(targetPath, "vite.config.ts");
+    const originViteConfig = fs.existsSync(viteConfigPath)
+        ? fs.readFileSync(viteConfigPath, "utf-8")
+        : null;
+    fs.writeFileSync(viteConfigPath, starterViteConfig.content);
+    if (originViteConfig !== null && originViteConfig !== starterViteConfig.content) {
+        // The origin may carry legitimate customizations (optimizeDeps entries,
+        // plugins) beyond the dev-links that must not ship — never destroy them
+        // silently: stash the original for manual re-application.
+        const stash = path.join(dotLoticsDirEnsured(targetPath), "vite.config.origin.ts");
+        fs.writeFileSync(stash, originViteConfig);
+        console.error("Refreshed vite.config.ts from the starter (build.target es2022). The origin app's config " +
+            "differed — its original was saved to .lotics/vite.config.origin.ts; re-apply any " +
+            "custom optimizeDeps/plugins entries you still need (never dev-link aliases).");
+    }
+    else {
+        console.error("Refreshed vite.config.ts from the starter (build.target es2022)");
+    }
+    // Stage each file-backed template at the `bytes_ref` the contract references.
+    // The download lands in the target dir (fresh, so no name collision) under the
+    // file's own name; rename it to the exact `bytes_ref` basename the contract
+    // points at. Processed sequentially so a prior rename frees the name.
+    for (const tf of extracted.template_files) {
+        const dest = path.join(targetPath, tf.bytes_ref);
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        const { path: downloaded } = await client.downloadFileById(tf.file_id, path.dirname(dest));
+        if (path.resolve(downloaded) !== path.resolve(dest))
+            fs.renameSync(downloaded, dest);
+        console.error(`Wrote ${tf.bytes_ref}`);
+    }
+    // The origin pin the `adopt` step reads back. `.lotics` is in
+    // SOURCE_STAGE_EXCLUDES, so this never ships in a published bundle.
+    const dotLotics = path.join(targetPath, ".lotics");
+    fs.mkdirSync(dotLotics, { recursive: true });
+    fs.writeFileSync(path.join(dotLotics, ADOPT_BINDING_FILE), JSON.stringify({ app_id: app.id, workspace_id: app.workspace_id, binding: extracted.binding }, null, 2) + "\n");
+    console.error(`Wrote .lotics/${ADOPT_BINDING_FILE}`);
+    console.error("Installing npm dependencies...");
+    await runNpm(["install"], targetPath);
+    if (hasError) {
+        console.error("\nExtraction produced error findings — the draft is written but NOT publishable as-is.");
+        console.error("Fix the reported items above, then publish (which re-validates the contract).");
+        process.exitCode = 1;
+        return;
+    }
+    console.error("\nDraft package project written. Next steps:");
+    console.error(`  cd ${path.relative(process.cwd(), targetPath) || "."}`);
+    console.error("  # review the aliases in contract.json, then:");
+    console.error(`  lotics package publish -m "v1"`);
+    console.error(`  lotics package adopt ${app.id}   (from this project, same workspace)`);
+}
+/**
+ * `lotics package adopt <app_id> [path]` — bind the published package project
+ * onto the origin app (docs/app_packages.md § Promotion). Reads the project
+ * manifest (must be published — refuses otherwise), resolves the version
+ * (`--version N` else the manifest's), and reads `.lotics/adopt_binding.json`,
+ * REFUSING a pin recorded for a different app. On success the app becomes
+ * installation #1 and is upgradeable again; a server ConflictError (naming the
+ * unfaithful aliases) surfaces verbatim.
+ */
+export async function packageAdopt(client, args) {
+    const projectDir = path.resolve(args.projectDir ?? process.cwd());
+    const { manifest } = readPackageProject(projectDir);
+    if (manifest.id === null) {
+        throw new Error("This package project has never been published (no package id). Publish first:\n  lotics package publish");
+    }
+    const version = args.version ?? manifest.version;
+    if (version === null) {
+        throw new Error("No version to adopt — publish this project first (lotics package publish) or pass --version N.");
+    }
+    const bindingPath = path.join(projectDir, ".lotics", ADOPT_BINDING_FILE);
+    if (!fs.existsSync(bindingPath)) {
+        throw new Error(`No .lotics/${ADOPT_BINDING_FILE} in ${projectDir}. Adopt binds the origin app that ` +
+            `"lotics package extract" recorded — run extract to produce this project.`);
+    }
+    const pin = parseAdoptBindingFile(JSON.parse(fs.readFileSync(bindingPath, "utf-8")), args.app_id);
+    const app = await client.adoptAppPackage(args.app_id, {
+        package_id: manifest.id,
+        version,
+        binding: pin.binding,
+    });
+    console.error(`Adopted ${app.name} → installation of ${app.package_id} v${app.package_version}.`);
+    console.error(`  Verify the installation:  lotics package doctor ${app.id}`);
+}
+/**
+ * `lotics package fleet-upgrade <package_id> [--version N]` — bring every
+ * installation of the package across the caller's org to the target version.
+ * Hands-off applies only where the preview is clean; skipped/failed
+ * installations are reported per line and the process exits 1 so a release
+ * script can gate on "fleet fully current".
+ */
+export async function packageFleetUpgrade(client, args) {
+    const result = await client.fleetUpgradeAppPackage(args.package_id, {
+        ...(args.version !== undefined ? { version: args.version } : {}),
+    });
+    console.error(`Fleet upgrade of ${result.package_id} → v${result.target_version}:`);
+    if (result.installations.length === 0) {
+        console.error("  No installations of this package in your organization.");
+        return;
+    }
+    const counts = { upgraded: 0, up_to_date: 0, skipped: 0, failed: 0 };
+    for (const inst of result.installations) {
+        counts[inst.outcome]++;
+        const from = inst.from_version === null ? "?" : `v${inst.from_version}`;
+        const line = `  [${inst.outcome}] ${inst.workspace_name} — ${inst.app_name} (${from} → v${result.target_version})`;
+        if (inst.outcome === "skipped" && inst.blockers) {
+            console.error(`${line}: breaking=${inst.blockers.breaking} drift=${inst.blockers.drift} modified=${inst.blockers.modified}`);
+            console.error(`      resolve via:  lotics package upgrade ${inst.app_id} --version ${result.target_version} ...`);
+        }
+        else if (inst.message) {
+            console.error(`${line}: ${inst.message}`);
+        }
+        else {
+            console.error(line);
+        }
+    }
+    console.error(`Done: ${counts.upgraded} upgraded, ${counts.up_to_date} already current, ${counts.skipped} skipped, ${counts.failed} failed.`);
+    if (counts.skipped > 0 || counts.failed > 0) {
+        process.exitCode = 1;
+    }
+}