@lotics/cli 0.70.0 → 0.73.0

package/README.md

@@ -195,6 +195,44 @@ lotics ui link card --remove               # finalize: PR + publish, then drop t
 
 `app codegen` reads `package.json#lotics.queries` to decide which tables to put in `app_fields.ts`; widen the set with `package.json#lotics.codegen.tables` (an array of `tbl_…` ids) for tables the app only writes via workflows.
 
+## App packages
+
+A maintained, versioned app library: author once, install into many workspaces, upgrade per-workspace. Any org authors its own packages (publishing is owner-org-only); Lotics-backed packages carry the `official` badge. See `docs/app_packages.md` for the model.
+
+```bash
+# Author (any org admin; the package is owned by your org)
+lotics package new my-crm                  # scaffold project + contract.json
+lotics package publish -m "v2: adds deals" # build + publish an immutable version
+
+# Dev loop against a dev workspace (created with: lotics workspace create <name> --dev)
+lotics package dev --workspace wsp_dev     # scaffold-sync + run the app dev server
+lotics package sync --workspace wsp_dev    # migrate the dev installation only
+lotics package reset --workspace wsp_dev   # DEV-ONLY: drop scaffolded tables, re-scaffold clean
+
+# Operate installations (workspace admin)
+lotics package install apg_... --version 2 # scaffold + materialize + deploy + pin
+lotics package doctor app_...              # version pin vs latest + drift + local edits (exit 1 on findings)
+lotics package rebind-role app_... <alias> <grp_id>  # re-point a package role at another group (re-materializes)
+lotics package upgrade app_...             # preview, then apply (additive; overlay preserved)
+lotics package fleet-upgrade apg_...       # upgrade EVERY org installation (clean ones apply; findings skip, exit 1)
+lotics package upgrade app_... --resolve fields.deal.stage=recreate   # resolve reported drift
+lotics package upgrade app_... --resolve queries.tasks=keep           # consent for a local edit (or =revert)
+lotics package eject app_...               # one-way: sever the package link
+lotics workspace doctor                    # dangling schema references across the workspace (exit 1 on findings)
+
+# Promote an EXISTING bespoke app to a package (build it in a real workspace first,
+# distribute once it proves itself — no re-authoring)
+lotics package extract app_...             # → draft project: contract + binding + templates
+                                           #   prints a findings report; always writes the draft,
+                                           #   exits 1 on error findings (fix them, publish re-validates)
+cd <slug-of-app-name>                      # review contract.json aliases
+lotics package publish -m "v1"             # publish the reviewed project
+lotics package adopt app_...               # bind the package onto the origin app (same workspace);
+                                           #   verifies the binding is faithful, then pins installation #1
+```
+
+Extract writes `.lotics/adopt_binding.json` (the origin pin, excluded from published bundles); `adopt` reads it back and refuses a pin recorded for a different app. After promotion the package project is the master — iterate contract-first (`package dev`/`sync` → `publish`), never extract again.
+
 ## SDK
 
 ```typescript

package/dist/app_commands.d.ts

@@ -86,6 +86,10 @@ export declare function writeWorkflowFile(projectDir: string, alias: string, sou
  * real source, not bookkeeping, and must not be silently eaten.
  */
 export declare function stripWorkflowHeader(content: string): string;
+/** Run `tar` and resolve when it exits cleanly. Throws with stderr on failure. */
+export declare function runTar(args: string[], cwd: string): Promise<void>;
+/** Run `npm` (run/install/etc.) inheriting stdio so the user sees progress. */
+export declare function runNpm(args: string[], cwd: string): Promise<void>;
 /**
  * Heal a pre-existing app's `tsconfig.json` so its generated types load and its
  * `npm run typecheck` stays honest. Idempotent, run on every pull / codegen /

package/dist/app_commands.js

@@ -258,7 +258,7 @@ async function fetchWorkflowGlobals(client, projectDir, app_id, alias) {
     }
 }
 /** Run `tar` and resolve when it exits cleanly. Throws with stderr on failure. */
-function runTar(args, cwd) {
+export function runTar(args, cwd) {
     return new Promise((resolve, reject) => {
         const proc = spawn("tar", args, { cwd, stdio: ["ignore", "ignore", "pipe"] });
         let stderr = "";
@@ -275,7 +275,7 @@ function runTar(args, cwd) {
     });
 }
 /** Run `npm` (run/install/etc.) inheriting stdio so the user sees progress. */
-function runNpm(args, cwd) {
+export function runNpm(args, cwd) {
     return new Promise((resolve, reject) => {
         const proc = spawn("npm", args, { cwd, stdio: "inherit", env: ipv4ChildEnv(process.env) });
         proc.on("error", reject);

package/dist/args.d.ts

@@ -30,12 +30,29 @@ export declare function parseArgs(argv: string[]): {
         message?: string;
         local: boolean;
         all: boolean;
+        /** `--dev`: mark a workspace as an app-package dev workspace (`workspace create`). */
+        dev: boolean;
         /** `--yes` (alias `-y`): confirm a destructive command (e.g. `workspace delete`) non-interactively. */
         yes: boolean;
         /** `--print-created` (alias `--report-effects`): print the honest post-run side-effect harvest. */
         printCreated: boolean;
         /** `--cleanup`: also delete the harvested created records (records only). */
         cleanup: boolean;
+        /**
+         * `--version <n>`: a package version number (`lotics package install … --version 2`).
+         * Distinct from the boolean `version` flag below: `--version` followed by an
+         * integer captures the number; a bare `--version` (or `-v`) prints the CLI
+         * version. No other command takes a numeric value after `--version`, so the
+         * peek is unambiguous.
+         */
+        packageVersion?: string;
+        /**
+         * `--resolve <key>=recreate|revert|keep|<id>` (repeatable): upgrade
+         * resolutions — drift entries (`<namespace.alias>`) take `recreate` or an
+         * existing id; modified-core entries (`<kind>.<alias>`) take `revert` or
+         * `keep`.
+         */
+        resolve: string[];
         version: boolean;
         help: boolean;
     };

package/dist/args.js

@@ -25,9 +25,12 @@ export function parseArgs(argv) {
         message: undefined,
         local: false,
         all: false,
+        dev: false,
         yes: false,
         printCreated: false,
         cleanup: false,
+        packageVersion: undefined,
+        resolve: [],
         version: false,
         help: false,
     };
@@ -78,6 +81,9 @@ export function parseArgs(argv) {
             case "--local":
                 flags.local = true;
                 break;
+            case "--dev":
+                flags.dev = true;
+                break;
             case "--all":
                 flags.all = true;
                 break;
@@ -92,10 +98,37 @@ export function parseArgs(argv) {
             case "--cleanup":
                 flags.cleanup = true;
                 break;
+            case "--resolve": {
+                const value = argv[++i];
+                if (value === undefined || value.startsWith("-")) {
+                    throw new Error("--resolve requires a value: <key>=recreate|revert|keep or <key>=<existing_id> (drift: <namespace.alias>; modified core: <kind>.<alias>).");
+                }
+                flags.resolve.push(value);
+                break;
+            }
             case "--version":
-            case "-v":
-                flags.version = true;
+            case "-v": {
+                // Inside a `package` command, `--version` carries a value (the
+                // package version to install) and the value is REQUIRED — a bare or
+                // malformed `--version` here must never fall back to the CLI-version
+                // early-exit boolean, which would print the CLI version and exit 0
+                // (a provisioning script reads that as a successful install). The
+                // value is captured raw; the consuming command validates
+                // integer-ness with a loud error. Outside `package`, this is the
+                // CLI-version boolean.
+                const next = argv[i + 1];
+                if (command === "package") {
+                    if (next === undefined || next.startsWith("-")) {
+                        throw new Error("--version requires a version number for package commands (e.g. --version 2).");
+                    }
+                    flags.packageVersion = next;
+                    i++;
+                }
+                else {
+                    flags.version = true;
+                }
                 break;
+            }
             case "--help":
             case "-h":
                 flags.help = true;

package/dist/args.test.js

@@ -23,6 +23,49 @@ describe("parseArgs", () => {
         const r = parseArgs(["app", "deploy"]);
         expect(r.flags.message).toBeUndefined();
     });
+    it("captures --version <int> as packageVersion, not the boolean version flag", () => {
+        const r = parseArgs(["package", "install", "apg_123", "--version", "2"]);
+        expect(r.command).toBe("package");
+        expect(r.subcommand).toBe("install");
+        expect(r.toolArgs).toBe("apg_123");
+        expect(r.flags.packageVersion).toBe("2");
+        expect(r.flags.version).toBe(false);
+        expect(r.restArgs).toEqual([]);
+    });
+    it("treats a bare --version as the boolean CLI-version flag", () => {
+        const r = parseArgs(["--version"]);
+        expect(r.flags.version).toBe(true);
+        expect(r.flags.packageVersion).toBeUndefined();
+    });
+    it("treats -v as the boolean CLI-version flag", () => {
+        const r = parseArgs(["-v"]);
+        expect(r.flags.version).toBe(true);
+        expect(r.flags.packageVersion).toBeUndefined();
+    });
+    it("captures a non-integer --version value under package commands for loud command-level validation", () => {
+        const r = parseArgs(["package", "install", "apg_123", "--version", "2.0"]);
+        expect(r.flags.packageVersion).toBe("2.0");
+        expect(r.flags.version).toBe(false);
+    });
+    it("collects repeated --resolve values", () => {
+        const r = parseArgs([
+            "package",
+            "upgrade",
+            "app_1",
+            "--resolve",
+            "fields.deal.stage=recreate",
+            "--resolve",
+            "templates.quote=dtl_abc",
+        ]);
+        expect(r.flags.resolve).toEqual(["fields.deal.stage=recreate", "templates.quote=dtl_abc"]);
+    });
+    it("errors on --resolve without a value", () => {
+        expect(() => parseArgs(["package", "upgrade", "app_1", "--resolve"])).toThrow(/--resolve requires a value/);
+    });
+    it("errors loudly on a bare --version under package commands instead of printing the CLI version", () => {
+        expect(() => parseArgs(["package", "install", "apg_123", "--version"])).toThrow(/requires a version number/);
+        expect(() => parseArgs(["package", "install", "apg_123", "--version", "--json"])).toThrow(/requires a version number/);
+    });
     it("parses --workspace as a value flag", () => {
         const r = parseArgs(["run", "query_tables", "{}", "--workspace", "wsp_123"]);
         expect(r.flags.workspace).toBe("wsp_123");
@@ -63,6 +106,12 @@ describe("parseArgs", () => {
         expect(parseArgs(["app", "workflow", "run", "wf"]).flags.cleanup).toBe(false);
         expect(parseArgs(["app", "workflow", "run", "wf"]).flags.printCreated).toBe(false);
     });
+    it("parses --dev as a boolean flag (default false)", () => {
+        expect(parseArgs(["workspace", "create", "Dev WS", "--dev"]).flags.dev).toBe(true);
+        expect(parseArgs(["workspace", "create", "Dev WS"]).flags.dev).toBe(false);
+        // The boolean flag does not consume the workspace name positional.
+        expect(parseArgs(["workspace", "create", "Dev WS", "--dev"]).toolArgs).toBe("Dev WS");
+    });
     it("parses --yes and -y as the same boolean confirmation flag (default false)", () => {
         expect(parseArgs(["workspace", "delete", "wsp_1", "--yes"]).flags.yes).toBe(true);
         expect(parseArgs(["workspace", "delete", "wsp_1", "-y"]).flags.yes).toBe(true);

package/dist/cli.js

@@ -14,10 +14,12 @@ import { LoticsClient, API_BASE_URL } from "./client.js";
 import { resolveContext, deleteConfig, getConfigPath, loadGlobalConfig, saveGlobalConfig, loadLocalConfig, upsertProfile, removeProfile, setActiveOrg, setSelectedWorkspace, resolveProfileByNameOrId, checkForUpdate, } from "./config.js";
 import { VERSION } from "./version.js";
 import { appCreate, appPull, appDeploy, appDev, appSetSubdomain, appRename, appVersions, appCodegen, appExecuteWorkflow, appWorkflowSet, appWorkflowPull, appWorkflowCheck, appQuerySet, appUiLink, } from "./app_commands.js";
+import { packageInstall, packageEject, packageDoctor, packageUpgrade, parseResolveFlags, packageNew, packageBuild, packagePublish, packageDev, packageSync, packageReset, packageExtract, packageAdopt, packageFleetUpgrade, } from "./package_commands.js";
 import { parseArgs } from "./args.js";
 import { ingestJsonArgs } from "./inputs.js";
 import { runXlsxCommand } from "./xlsx.js";
 import { runDocxCommand } from "./docx.js";
+import { runPreviewCommand } from "./preview.js";
 function printHelp() {
     console.log(`Lotics CLI v${VERSION} — AI agent interface for Lotics
 
@@ -61,15 +63,12 @@ COMMANDS
   lotics workspace select <id>         Switch to a different workspace
   lotics workspace create <name>       Create a new workspace (admin only)
   lotics workspace delete <id> --yes   Delete a workspace (admin only; soft delete, recoverable)
+  lotics workspace doctor              Report dangling schema references (admin only)
   lotics tools                         List all available tools
   lotics tools <name>                  Show tool description and input schema
   lotics run <tool> '<json>'           Execute a tool
   lotics run <tool> @args.json         Read JSON args from a file (large payloads)
   cat args.json | lotics run <tool>    Read JSON args from stdin (large payloads)
-  lotics upload <file|dir...>          Upload files (directories expand to their immediate files)
-  lotics download <file_id>            Download a file by ID
-  lotics download record <record_id> <field_key>
-                                       Download all files on a record file field
   lotics app create <name> [path]      Create a new custom-code app + scaffold locally
   lotics app pull <app_id> [path]      Bootstrap full local env (source + npm install + types)
   lotics app deploy -m <message>       Build + upload current dir as a new version
@@ -97,6 +96,37 @@ COMMANDS
   lotics app subdomain <new-subdomain> Rename the app's public <slug>.lotics.app address
   lotics app rename "<new name>"       Rename the app's display name (launcher title)
   lotics app dev [path]                Run the app locally with HMR (RPC forwarded to prod)
+  lotics package new <name> [path]     Scaffold a package project (contract + app source)
+  lotics package build [path]          Build the publishable bundle (source + dist)
+  lotics package publish [path]        Publish a new immutable package version
+  lotics package dev [path]            Sync the package into a dev workspace + run the app
+                                       dev server (--workspace <dev_ws> selects it)
+  lotics package sync [path]           Re-sync (additive migrate + materialize) into a dev ws
+  lotics package reset [path]          DEV-ONLY: drop scaffolded tables + re-scaffold clean
+  lotics package install <package> [--version N]
+                                       Install an app package into this workspace
+                                       (scaffolds the data model + deploys + materializes)
+  lotics package upgrade <app_id> [--version N] [--resolve <key>=recreate|revert|keep|<id> ...]
+                                       Preview-then-apply a package upgrade; refuses while
+                                       any drift/modified finding lacks a --resolve, and
+                                       hard-stops on breaking contract changes
+  lotics package doctor [app_id]       Installation health: version pin vs latest, binding
+                                       drift, locally modified core (exit 1 on findings)
+  lotics package rebind-role <app_id> <alias> <grp_id>
+                                       Re-point a package role at a different group
+                                       (re-materializes at the pinned version)
+  lotics package eject <app_id>        Sever an installation's package link
+                                       (re-deploys the pinned source as a bespoke app)
+  lotics package extract <app_id> [path]   Promote a bespoke app to a draft package
+                                       project (contract + binding + templates); always
+                                       writes the draft, exits 1 on error findings
+  lotics package adopt <app_id> [path]     Bind the published package project onto the
+                                       origin app (reads .lotics/adopt_binding.json;
+                                       --version N pins a specific version)
+  lotics package fleet-upgrade <package_id> [--version N]
+                                       Upgrade EVERY installation of the package across
+                                       your org: applies where the preview is clean,
+                                       skips + reports findings (exit 1 unless all current)
   lotics ui link <component> [--ui-src <path>] [--remove]
                                        Dev-link @lotics/ui to packages/ui/src (Vite alias
                                        + tsc paths) for live HMR + typecheck. Monorepo apps
@@ -107,6 +137,12 @@ COMMANDS
   lotics docx <subcommand> ...         Read/write/edit .docx files on your local filesystem
                                        (uses the bundled Lotics OOXML engine; preserves
                                        tables, images, and unknown markup verbatim)
+  lotics file upload <file|dir...>     Upload files (alias: lotics upload)
+  lotics file download <file_id>       Download a file by ID (alias: lotics download)
+  lotics file download record <record_id> <field_key>
+                                       Download all files on a record file field
+  lotics file preview <file> [-o png]  Render a .docx/.xlsx to a PNG (frontend engines;
+                                       needs a Chrome/Chromium on the machine)
 
 FLAGS
   --json             Full JSON output (default is human-readable text)
@@ -119,6 +155,8 @@ FLAGS
                      is_current_member / row-scoping resolve to them (also
                      LOTICS_VIEW_AS env; admin key only; writes stay yours)
   --local            Pin the current directory (lotics org use / auth api-key)
+  --dev              (lotics workspace create) Mark a throwaway app-package dev
+                     workspace — required for "lotics package reset"
   --all              (lotics auth logout) Remove every saved credential
   --version          Show version
 
@@ -392,7 +430,22 @@ function resolveUploadPaths(rawPaths) {
     return result;
 }
 async function main() {
-    const { command, subcommand, toolArgs, restArgs, flags } = parseArgs(process.argv.slice(2));
+    const parsed = parseArgs(process.argv.slice(2));
+    const { restArgs, flags } = parsed;
+    let { command, subcommand, toolArgs } = parsed;
+    // `file` is a thin noun-group over the file verbs: `lotics file <upload|download|preview>
+    // <args…>` strips the prefix and re-dispatches to the same handlers as the top-level
+    // verbs (which stay as aliases). Positional shift only — flags are untouched, and
+    // `download record <id> <field>` still works as `file download record <id> <field>`.
+    if (command === "file") {
+        if (!subcommand) {
+            printHelp();
+            return;
+        }
+        command = subcommand;
+        subcommand = toolArgs;
+        toolArgs = restArgs.shift();
+    }
     if (flags.help || (!command && !flags.version)) {
         printHelp();
         return;
@@ -494,6 +547,10 @@ async function main() {
         await runDocxCommand(subcommand, toolArgs, restArgs);
         return;
     }
+    if (command === "preview") {
+        await runPreviewCommand(subcommand, flags);
+        return;
+    }
     // --- lotics ui link <component> [--remove] — local vite.config edit, no auth ---
     if (command === "ui") {
         if (subcommand === "link") {
@@ -514,6 +571,20 @@ async function main() {
         console.error("Usage: lotics ui link <component> [--ui-src <abs path>] [--remove]");
         process.exit(1);
     }
+    // --- lotics package new / build — local scaffold + build, no auth required ---
+    if (command === "package" && subcommand === "new") {
+        const name = toolArgs;
+        if (!name) {
+            console.error("Usage: lotics package new <name> [path]");
+            process.exit(1);
+        }
+        await packageNew({ name, targetPath: restArgs[0] });
+        return;
+    }
+    if (command === "package" && subcommand === "build") {
+        await packageBuild({ projectDir: toolArgs });
+        return;
+    }
     // --- lotics app workflow check [alias] — local typecheck, no auth, no network ---
     // Reads src/workflows/*.ts + .lotics/workflows/*.globals.d.ts and the app's own
     // typescript; builds one isolated program per alias. Handled before the auth
@@ -596,7 +667,7 @@ async function main() {
         return;
     }
     // --- Validate command before auth ---
-    if (command !== "tools" && command !== "upload" && command !== "run" && command !== "download" && command !== "workspace" && command !== "app") {
+    if (command !== "tools" && command !== "upload" && command !== "run" && command !== "download" && command !== "workspace" && command !== "app" && command !== "package") {
         console.error(`Unknown command: ${command}`);
         console.error('Run "lotics --help" for usage.');
         process.exit(1);
@@ -620,6 +691,24 @@ async function main() {
         console.error("  lotics app dev [path]                Run the app locally with HMR + RPC forwarding");
         process.exit(1);
     }
+    if (command === "package" && !subcommand) {
+        console.error("Usage:");
+        console.error("  lotics package new <name> [path]                 Scaffold a package project (contract + app source)");
+        console.error("  lotics package build [path]                      Build the publishable bundle (source + dist)");
+        console.error("  lotics package publish [path] [-m <changelog>]   Publish a new immutable package version");
+        console.error("  lotics package dev [path] [--workspace <ws>]     Sync into a dev workspace + run the app dev server");
+        console.error("  lotics package sync [path] [--workspace <ws>]    Re-sync (additive migrate + materialize) into a dev workspace");
+        console.error("  lotics package reset [path] [--workspace <ws>]   DEV-ONLY: drop scaffolded tables + re-scaffold clean");
+        console.error("  lotics package install <package> [--version N]   Install a package into this workspace");
+        console.error("  lotics package upgrade <app_id> [--version N] [--resolve ns.alias=recreate|<id>]   Preview + apply an upgrade");
+        console.error("  lotics package doctor [app_id]                   Health: version pin vs latest + binding drift");
+        console.error("  lotics package rebind-role <app_id> <alias> <grp_id>   Re-point a package role at another group");
+        console.error("  lotics package eject <app_id>                    Sever an installation's package link");
+        console.error("  lotics package extract <app_id> [path]           Promote a bespoke app to a draft package project");
+        console.error("  lotics package adopt <app_id> [path]             Bind the published project onto the origin app");
+        console.error("  lotics package fleet-upgrade <package_id> [--version N]   Upgrade every org installation (clean ones apply; findings skip)");
+        process.exit(1);
+    }
     if (command === "run" && !subcommand) {
         console.error("Usage: lotics run <tool> '<json_args>'\n" +
             "       lotics run <tool> @args.json   (read args from a file — for large payloads)\n" +
@@ -647,6 +736,24 @@ async function main() {
     const { client, ctx } = requireClient(flags);
     // lotics workspace / lotics workspace list / lotics workspace select <id>
     if (command === "workspace") {
+        if (subcommand === "doctor") {
+            // The workspace command family runs before the global workspace
+            // resolution — doctor needs the same first-workspace fallback every
+            // data command gets.
+            await resolveWorkspace(client, ctx);
+            const dangling = await client.getWorkspaceDanglingReferences();
+            if (dangling.length === 0) {
+                console.error("Workspace references: healthy — every referenced schema id resolves.");
+                return;
+            }
+            console.error(`Dangling schema references (${dangling.length}):`);
+            for (const d of dangling) {
+                console.error(`  - ${d.referent.kind} "${d.referent.name}" (${d.referent.id}) → ${d.namespace} ${d.id} (missing)`);
+            }
+            console.error("Each referent points at schema that no longer exists — edit or archive it, or recreate the missing schema.");
+            process.exitCode = 1;
+            return;
+        }
         const workspaces = await client.listWorkspaces();
         const currentWorkspaceId = ctx.workspaceId;
         if (subcommand === "select") {
@@ -673,11 +780,11 @@ async function main() {
         if (subcommand === "create") {
             const name = toolArgs;
             if (!name) {
-                console.error('Usage: lotics workspace create <name> [--timezone <tz>]');
+                console.error('Usage: lotics workspace create <name> [--timezone <tz>] [--dev]');
                 process.exit(1);
             }
             const timezone = flags.timezone;
-            const created = await client.createWorkspace({ name, timezone });
+            const created = await client.createWorkspace({ name, timezone, is_dev: flags.dev || undefined });
             setSelectedWorkspace(created.id);
             client.setWorkspaceId(created.id);
             if (flags.json) {
@@ -746,6 +853,153 @@ async function main() {
     }
     // Ensure workspace is resolved for all remaining commands
     await resolveWorkspace(client, ctx);
+    // lotics package install <package> [--version N]
+    if (command === "package") {
+        if (subcommand === "install") {
+            const packageId = toolArgs;
+            if (!packageId) {
+                console.error("Usage: lotics package install <package> [--version N]");
+                process.exit(1);
+            }
+            let version;
+            if (flags.packageVersion !== undefined) {
+                version = Number(flags.packageVersion);
+                if (!Number.isInteger(version) || version <= 0) {
+                    console.error(`Invalid --version "${flags.packageVersion}" — expected a positive integer.`);
+                    process.exit(1);
+                }
+            }
+            await packageInstall(client, { package_id: packageId, version });
+            return;
+        }
+        if (subcommand === "eject") {
+            const appId = toolArgs;
+            if (!appId) {
+                console.error("Usage: lotics package eject <app_id>");
+                process.exit(1);
+            }
+            await packageEject(client, { app_id: appId });
+            return;
+        }
+        if (subcommand === "extract") {
+            const appId = toolArgs;
+            if (!appId) {
+                console.error("Usage: lotics package extract <app_id> [path]");
+                console.error("Promotes a bespoke app to a draft package project (contract + binding + templates).");
+                process.exit(1);
+            }
+            await packageExtract(client, { app_id: appId, targetPath: restArgs[0] });
+            return;
+        }
+        if (subcommand === "adopt") {
+            const appId = toolArgs;
+            if (!appId) {
+                console.error("Usage: lotics package adopt <app_id> [path]");
+                console.error("Binds the published package project (this dir, or [path]) onto the origin app.");
+                process.exit(1);
+            }
+            let version;
+            if (flags.packageVersion !== undefined) {
+                version = Number(flags.packageVersion);
+                if (!Number.isInteger(version) || version <= 0) {
+                    console.error(`Invalid --version "${flags.packageVersion}" — expected a positive integer.`);
+                    process.exit(1);
+                }
+            }
+            await packageAdopt(client, { app_id: appId, version, projectDir: restArgs[0] });
+            return;
+        }
+        if (subcommand === "fleet-upgrade") {
+            const packageId = toolArgs;
+            if (!packageId) {
+                console.error("Usage: lotics package fleet-upgrade <package_id> [--version N]");
+                process.exit(1);
+            }
+            let version;
+            if (flags.packageVersion !== undefined) {
+                version = Number(flags.packageVersion);
+                if (!Number.isInteger(version) || version <= 0) {
+                    console.error(`Invalid --version "${flags.packageVersion}" — expected a positive integer.`);
+                    process.exit(1);
+                }
+            }
+            await packageFleetUpgrade(client, { package_id: packageId, version });
+            return;
+        }
+        if (subcommand === "doctor") {
+            await packageDoctor(client, { app_id: toolArgs });
+            return;
+        }
+        if (subcommand === "rebind-role") {
+            const appId = toolArgs;
+            const [roleAlias, groupId] = restArgs;
+            if (!appId || !roleAlias || !groupId) {
+                console.error("Usage: lotics package rebind-role <app_id> <role_alias> <grp_id>");
+                process.exit(1);
+            }
+            const result = await client.rebindAppPackageRole(appId, {
+                role_alias: roleAlias,
+                group_id: groupId,
+            });
+            console.error(`Rebound role "${result.role_alias}" → ${result.group_id}` +
+                (result.previous_group_id ? ` (was ${result.previous_group_id})` : "") +
+                ". Package workflows/agents were re-materialized against the new group.");
+            return;
+        }
+        if (subcommand === "upgrade") {
+            const appId = toolArgs;
+            if (!appId) {
+                console.error("Usage: lotics package upgrade <app_id> [--version N] [--resolve <namespace.alias>=recreate|<id> ...]");
+                process.exit(1);
+            }
+            let version;
+            if (flags.packageVersion !== undefined) {
+                version = Number(flags.packageVersion);
+                if (!Number.isInteger(version) || version <= 0) {
+                    console.error(`Invalid --version "${flags.packageVersion}" — expected a positive integer.`);
+                    process.exit(1);
+                }
+            }
+            await packageUpgrade(client, {
+                app_id: appId,
+                version,
+                resolutions: parseResolveFlags(flags.resolve),
+            });
+            return;
+        }
+        if (subcommand === "publish") {
+            await packagePublish(client, { projectDir: toolArgs, changelog: flags.message });
+            return;
+        }
+        if (subcommand === "sync") {
+            await packageSync(client, { projectDir: toolArgs });
+            return;
+        }
+        if (subcommand === "reset") {
+            await packageReset(client, { projectDir: toolArgs });
+            return;
+        }
+        if (subcommand === "dev") {
+            // First positional is an optional project path; --port / --vite-port
+            // override the wrapper / Vite ports (same shape as `lotics app dev`).
+            const projectDir = toolArgs;
+            let port;
+            let vitePort;
+            for (const a of restArgs) {
+                const portMatch = /^--port=(\d+)$/.exec(a);
+                const vitePortMatch = /^--vite-port=(\d+)$/.exec(a);
+                if (portMatch)
+                    port = Number(portMatch[1]);
+                else if (vitePortMatch)
+                    vitePort = Number(vitePortMatch[1]);
+            }
+            await packageDev(client, { projectDir, port, vitePort });
+            return;
+        }
+        console.error(`Unknown package subcommand: ${subcommand}`);
+        console.error("Run 'lotics package' for usage.");
+        process.exit(1);
+    }
     // lotics app create / pull / deploy
     if (command === "app") {
         if (subcommand === "create") {