@lotics/cli 0.75.0 → 0.76.0

package/dist/src/cli.js

@@ -29775,6 +29775,33 @@ var LoticsClient = class {
       body
     );
   }
+  /**
+   * Uninstall a package installation (backs `lotics package uninstall`). Does
+   * everything DELETE does plus archives the installation's lifecycle
+   * artifacts; with `archive_tables` it also archives the scaffolded entity
+   * tables — refused server-side unless this installation created them
+   * (provenance) and nothing else references them. Admin-only.
+   */
+  async uninstallAppPackage(app_id, body) {
+    return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/uninstall`, body);
+  }
+  /**
+   * Partial-merge a package installation's config (backs `lotics package config
+   * --set`). Only the provided keys change; validated against the installed
+   * contract. Returns the full effective config. Admin-only.
+   */
+  async updateAppPackageConfig(app_id, body) {
+    return this.request("PATCH", `/v1/apps/${encodeURIComponent(app_id)}/package-config`, body);
+  }
+  /**
+   * Retire (or `undo` un-retire) a registry package (backs `lotics package
+   * retire`). Retiring refuses NEW installs and hides the package from
+   * non-owning orgs; existing installations keep working and may still upgrade.
+   * Owner-org admin-only.
+   */
+  async retireAppPackage(package_id, body) {
+    return this.request("POST", `/v1/app-packages/${encodeURIComponent(package_id)}/retire`, body);
+  }
   /**
    * Eject an installation from its package — re-deploy the pinned version's
    * source as a workspace-owned app version, then sever the package link
@@ -29854,6 +29881,10 @@ var LoticsClient = class {
   async getAppPackage(package_id) {
     return this.request("GET", `/v1/app-packages/${encodeURIComponent(package_id)}`);
   }
+  /** Version history newest-first (no contract payloads) — backs `lotics package show`. Admin-only. */
+  async listAppPackageVersions(package_id) {
+    return this.request("GET", `/v1/app-packages/${encodeURIComponent(package_id)}/versions`);
+  }
   /**
    * Publish a new immutable package version — multipart upload of the alias-keyed
    * contract (JSON) + the prebuilt code bundle (a gzipped tarball carrying
@@ -29870,6 +29901,7 @@ var LoticsClient = class {
       "bundle.tar.gz"
     );
     if (args.changelog) formData.append("changelog", args.changelog);
+    if (args.channel) formData.append("channel", args.channel);
     const url = `${this.baseUrl}/v1/app-packages/${encodeURIComponent(package_id)}/versions`;
     const response = await fetch(url, {
       method: "POST",
@@ -31270,6 +31302,379 @@ See https://lotics.ai/docs/app-sdk for the SDK reference.
     }
   ];
 }
+function buildPackageStarterOverrides(args) {
+  const nameLit = JSON.stringify(args.app_name);
+  return [
+    {
+      // The package App.tsx imports `../.lotics/app_fields` — a DETERMINISTIC
+      // pure function of contract.json (generate_package_fields.ts) — so unlike
+      // the app starter's fully-ignored `.lotics`, it must be committed or the
+      // scaffold's own shipped CI (npm ci → typecheck/test/build on a clean
+      // clone) fails on the missing module. The sync-written `.d.ts` companions
+      // stay ignored: they need a live workspace and their absence only degrades
+      // hooks to untyped overloads, never breaks the build.
+      path: ".gitignore",
+      content: `node_modules
+dist
+*.tsbuildinfo
+.DS_Store
+.lotics/*
+!.lotics/app_fields.ts
+coverage
+`
+    },
+    {
+      path: "src/App.tsx",
+      content: `import { useMemo, type ReactNode } from "react";
+import { ScrollView, View } from "react-native";
+import { useConfig, useQuery, readSelect, row } from "@lotics/app-sdk";
+import { AppRouter } from "@lotics/app-sdk/router";
+import { Text } from "@lotics/ui/text";
+import { Card } from "@lotics/ui/card";
+import { Button } from "@lotics/ui/button";
+import { OptionBadge } from "@lotics/ui/option_badge";
+import { Skeleton } from "@lotics/ui/skeleton";
+import { EmptyState } from "@lotics/ui/empty_state";
+import { Callout, CalloutTitle, CalloutText, CalloutActions } from "@lotics/ui/callout";
+import { F, OPT } from "../.lotics/app_fields";
+
+// This is a PACKAGE starter \u2014 a workspace-agnostic blueprint installed into many
+// workspaces, each binding the contract's aliases to DIFFERENT concrete ids. So a
+// screen never hardcodes a \`fld_\u2026\`/\`opt_\u2026\` id: it addresses a field by contract
+// alias through \`F\` and a select option through \`OPT\`, both from the generated
+// \`.lotics/app_fields.ts\` (which resolves every alias to THIS installation's id at
+// module load from the binding). The aliases come from contract.json \u2014 entity
+// \`item\`, fields name/notes/status, options open/done, query \`items\`, config knob
+// \`heading\`. Edit contract.json, then \`lotics package sync\` to regenerate F/OPT.
+
+interface Item {
+  id: string;
+  name: string;
+  notes: string;
+  status: ReturnType<typeof readSelect>[number] | null;
+  done: boolean;
+}
+
+// The \`items\` query is a bare from_entity, so a row is keyed by FIELD id: read a
+// cell as \`r[F.ITEM.<field>]\` and decode it with the SDK's pure readers (\`row.text\`,
+// \`readSelect\`). \`OPT.ITEM.status.done\` is this install's \`opt_\u2026\` id, so comparing
+// the cell's stored option key to it marks a done row.
+function decode(r: Record<string, unknown>): Item {
+  const status = readSelect(r[F.ITEM.status])[0] ?? null;
+  return {
+    id: row.text(r.__source_record_id),
+    name: row.text(r[F.ITEM.name]),
+    notes: row.text(r[F.ITEM.notes]),
+    status,
+    done: status?.key === OPT.ITEM.status.done,
+  };
+}
+
+// Outer <View flex:1> claims the iframe height (index.html sets html/body/#root to
+// 100% + #root is a flex column); the list scrolls beneath the heading. Keep this
+// flex chain plain (not @lotics/ui/stack) so a fill-remaining-space child gets height.
+function Screen({ children }: { children: ReactNode }) {
+  return (
+    <View style={{ flex: 1 }}>
+      <ScrollView contentContainerStyle={{ padding: 24, alignItems: "center" }}>
+        <View style={{ maxWidth: 640, width: "100%", gap: 16 }}>{children}</View>
+      </ScrollView>
+    </View>
+  );
+}
+
+function ItemsScreen() {
+  // \`heading\` is a contract config knob \u2014 an installation overrides it and
+  // useConfig() renders the customized value; the literal here is only the fallback.
+  const { config } = useConfig({ heading: ${nameLit} });
+  const itemsQ = useQuery("items");
+  const items = useMemo(() => itemsQ.rows.map(decode), [itemsQ.rows]);
+  // First-load only: a skeleton while the very first fetch is in flight with no rows
+  // yet \u2014 never blank already-loaded rows to a spinner on a background refetch.
+  const firstLoad = itemsQ.loading && items.length === 0;
+
+  return (
+    <Screen>
+      <Text size="xxl" weight="semibold" level={1}>
+        {config.heading}
+      </Text>
+
+      {itemsQ.error ? (
+        <Callout tone="error">
+          <CalloutTitle>Couldn't load items</CalloutTitle>
+          <CalloutText>{itemsQ.error}</CalloutText>
+          <CalloutActions>
+            <Button title="Try again" onPress={() => itemsQ.refetch()} />
+          </CalloutActions>
+        </Callout>
+      ) : firstLoad ? (
+        <View style={{ gap: 10 }}>
+          {[0, 1, 2].map((i) => (
+            <Skeleton key={i} height={64} radius={12} />
+          ))}
+        </View>
+      ) : items.length > 0 ? (
+        <View style={{ gap: 10 }}>
+          {items.map((item) => (
+            <Card key={item.id}>
+              <View style={{ flexDirection: "row", alignItems: "center", gap: 12 }}>
+                <View style={{ flex: 1, gap: 2 }}>
+                  <Text weight="medium" color={item.done ? "muted" : undefined}>
+                    {item.name}
+                  </Text>
+                  {item.notes.length > 0 ? (
+                    <Text size="sm" color="muted" numberOfLines={1}>
+                      {item.notes}
+                    </Text>
+                  ) : null}
+                </View>
+                <OptionBadge value={item.status} />
+              </View>
+            </Card>
+          ))}
+        </View>
+      ) : (
+        <EmptyState
+          icon="list-checks"
+          message="No items yet"
+          hint="Rows in this package's table appear here."
+        />
+      )}
+    </Screen>
+  );
+}
+
+const routes = [{ path: "/", element: <ItemsScreen /> }];
+
+export default function App() {
+  return <AppRouter routes={routes} />;
+}
+`
+    },
+    {
+      path: "src/App.test.tsx",
+      content: `import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
+import { render, screen, cleanup } from "@testing-library/react";
+import App from "./App";
+
+// Mock @lotics/app-sdk \u2014 the app's one external boundary (data + RPC + the package
+// binding). \`importOriginal\` keeps the PURE cell readers (\`row\`, \`readSelect\`) real,
+// so mock rows decode exactly like wire rows; only the hooks and getAppBinding are
+// stubbed. The binding ids below are what F.ITEM.* / OPT.ITEM.status.* resolve to;
+// the query rows are keyed by the SAME ids.
+const h = vi.hoisted(() => ({
+  state: {
+    rows: [] as Array<Record<string, unknown>>,
+    loading: false,
+    error: null as string | null,
+  },
+  binding: {
+    fields: { "item.name": "fld_name", "item.notes": "fld_notes", "item.status": "fld_status" },
+    options: { "item.status:open": "opt_open", "item.status:done": "opt_done" },
+    roles: {},
+  },
+}));
+
+vi.mock("@lotics/app-sdk", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@lotics/app-sdk")>();
+  return {
+    ...actual,
+    getAppBinding: async () => h.binding,
+    useConfig: (defaults: Record<string, unknown>) => ({ config: defaults, loading: false }),
+    useQuery: () => ({
+      rows: h.state.rows,
+      loading: h.state.loading,
+      isValidating: false,
+      error: h.state.error,
+      refetch: () => {},
+    }),
+  };
+});
+
+const rowOf = (id: string, name: string, notes: string, statusKey: string) => ({
+  __source_record_id: id,
+  fld_name: name,
+  fld_notes: notes,
+  fld_status: [{ key: statusKey, label: statusKey === "opt_done" ? "Done" : "Open" }],
+});
+
+beforeEach(() => {
+  h.state.rows = [];
+  h.state.loading = false;
+  h.state.error = null;
+});
+
+// vitest globals are off, so @testing-library/react's automatic afterEach cleanup is
+// never registered \u2014 clean up explicitly or renders accumulate across tests and a
+// second render's duplicate matches fail getByText.
+afterEach(cleanup);
+
+describe("App", () => {
+  test("renders the heading and the loaded items with status badges", () => {
+    h.state.rows = [
+      rowOf("1", "First item", "with a note", "opt_open"),
+      rowOf("2", "Second item", "", "opt_done"),
+    ];
+    render(<App />);
+
+    expect(screen.getByText(${nameLit})).toBeTruthy();
+    expect(screen.getByText("First item")).toBeTruthy();
+    expect(screen.getByText("Second item")).toBeTruthy();
+    expect(screen.getByText("with a note")).toBeTruthy();
+    expect(screen.getByText("Open")).toBeTruthy();
+    expect(screen.getByText("Done")).toBeTruthy();
+    expect(screen.queryByText("No items yet")).toBeNull();
+  });
+
+  test("shows the empty state when there are no items", () => {
+    render(<App />);
+    expect(screen.getByText("No items yet")).toBeTruthy();
+  });
+
+  test("does not flash the list or empty state on first load", () => {
+    h.state.loading = true;
+    render(<App />);
+    expect(screen.queryByText("No items yet")).toBeNull();
+  });
+
+  test("surfaces a load error loudly", () => {
+    h.state.error = "Network unreachable";
+    render(<App />);
+    expect(screen.getByText("Couldn't load items")).toBeTruthy();
+    expect(screen.getByText("Network unreachable")).toBeTruthy();
+  });
+});
+`
+    },
+    {
+      path: "README.md",
+      content: `# ${escapeHtml(args.app_name)}
+
+A Lotics **app package** \u2014 a versioned, installable blueprint (a \`contract.json\`
+data model + app source) that installs into many workspaces. Authored locally,
+published and run through the \`lotics package\` CLI. See \`docs/app_packages.md\`.
+
+## Dev loop
+
+\`\`\`bash
+lotics workspace create "${escapeHtml(args.app_name)} dev" --dev   # a throwaway dev workspace
+lotics package dev --workspace <dev_ws>                # sync into it + run the dev server
+# edit contract.json  \u2192 re-run \`lotics package sync\` to migrate + re-materialize
+# edit src/*          \u2192 hot reload
+\`\`\`
+
+\`sync\` / \`dev\` regenerate \`.lotics/app_fields.ts\` (the runtime \`F\` / \`OPT\` / \`ROLE\`
+surface) from \`contract.json\`, plus the typed \`.lotics/app_{queries,workflows,agents}.d.ts\`
+companions from the live installation \u2014 so \`useQuery\` / \`useWorkflow\` stay typed in the
+dev loop.
+
+## Quality
+
+\`\`\`bash
+npm run typecheck
+npm run lint
+npm test
+\`\`\`
+
+## Publish
+
+\`\`\`bash
+lotics package publish -m "v1"        # build + publish an immutable version
+lotics package install <package_id>   # install into any workspace
+\`\`\`
+
+## The app screen
+
+\`src/App.tsx\` reads the contract BY ALIAS through \`F\` / \`OPT\` (from the generated
+\`.lotics/app_fields.ts\`) \u2014 never a raw \`fld_\u2026\` / \`opt_\u2026\` id, since every install binds
+different concrete ids. It lists the \`items\` query and renders the \`heading\` config knob.
+\`@lotics/ui\` primitives render via react-native-web (aliased in \`vite.config.ts\`).
+
+## Contract reference
+
+\`contract.json\` is the package's alias-keyed data model
+(schema: \`@lotics/shared/schemas/app_packages\`). Every cross-reference is by **alias**;
+the materializer resolves alias \u2192 this workspace's concrete id at install.
+
+### Aliases
+
+- Entity / field / option / role / template / config aliases are lowercase slugs
+  matching \`^[a-z][a-z0-9_]*$\`. A field's fully-qualified key is \`<entity>.<field>\`
+  (e.g. \`item.status\`); a select option's is \`<entity>.<field>:<option>\`
+  (e.g. \`item.status:done\`).
+- Query / workflow / agent aliases are runtime lookup keys (1\u2013200 chars) \u2014 the app
+  source invokes them verbatim (\`useQuery("items")\`), so renaming one severs the call.
+
+### Entities & fields
+
+\`\`\`jsonc
+{ "alias": "item", "label": "Item", "fields": [
+  { "alias": "name",   "label": "Name",   "type": "text", "required": true },
+  { "alias": "status", "label": "Status", "type": "select",
+    "options": [ { "alias": "open", "label": "Open", "color": "blue" },
+                 { "alias": "done", "label": "Done", "color": "green" } ] } ] }
+\`\`\`
+
+Field \`type\`: \`text\`, \`number\`, \`date\`, \`boolean\`, \`select\` (+ \`options\`),
+\`select_member\`, \`select_record_link\` (\`target_entity\` = an entity alias), \`files\`,
+\`formula\` (expression references same-entity fields as \`{alias}\`), \`rollup\`, \`lookup\`,
+\`autonumber\`. \`required\` is advisory (app / workflow-layer UX only \u2014 the table model
+has no required constraint). Select \`options\` are \`{ alias, label, color }\`.
+
+### Queries
+
+Alias-form AST \u2014 the same node kinds as the runtime query engine, except a
+\`from_table\` node carries \`from_entity\` (an entity alias) instead of a \`table_id\`:
+
+\`\`\`jsonc
+{ "alias": "items", "ast": {
+  "kind": "from_table", "from_entity": "item",
+  "sort": [ { "field_key": "name", "order": "asc" } ] } }
+\`\`\`
+
+### Workflows
+
+The sole app-side mutation path. Each workflow has a \`trigger\`, typed \`inputs\` /
+\`outputs\`, and a JS-subset \`body\`.
+
+- Trigger \u2014 app-invoked or table-lifecycle:
+  - \`{ "type": "app" }\` \u2014 called by alias from the app (\`useWorkflow("<alias>")\`).
+  - \`{ "type": "entity_lifecycle", "entity": "<entity>", "event": "<event>" }\` \u2014 fires
+    on the bound table. \`event\` \u2208 \`before_create\`, \`after_create\`, \`before_update\`,
+    \`after_update\`, \`before_delete\`, \`after_delete\`.
+- Typed \`inputs\` (\`text\` / \`number\` / \`date\` / \`member\` / \`select\` / \`record_link\`,
+  plus \`object\` / \`array\`):
+  - \`record_link\` \u2014 its \`table_id\` names an **entity alias**.
+  - \`member\` \u2014 its \`group\` names a **role alias**.
+  - \`select\` \u2014 an option \`value\` in \`entity.field:option\` form binds to that option's
+    id (a plain value is a literal, left as-is).
+- Body **sentinel tokens** \u2014 a body addresses package objects by reserved tokens the
+  materializer rewrites to concrete ids at install. Always inside a **string literal**:
+  - \`@@entity:<entity>@@\`
+  - \`@@field:<entity>.<field>@@\`
+  - \`@@option:<entity>.<field>:<option>@@\`
+  - \`@@role:<role>@@\`
+  - \`@@template:<template>@@\`
+
+### Config knobs
+
+Typed customization knobs the app reads via \`useConfig()\`. Each has an \`alias\`,
+\`label\`, \`type\`, and \`default\`:
+
+- \`text\` \u2192 a string default; \`boolean\` \u2192 a boolean; \`number\` \u2192 a number;
+  \`color\` \u2192 a palette color token; \`select\` \u2192 \`options: [{ value, label }]\` with the
+  \`default\` being one of those \`value\`s.
+
+\`\`\`jsonc
+{ "alias": "heading", "label": "List heading", "type": "text", "default": "Items" }
+\`\`\`
+
+Publish validates the whole contract (alias uniqueness, every cross-reference
+resolves, sentinel tokens name declared objects) before storing the version.
+`
+    }
+  ];
+}
 function escapeHtml(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
@@ -33716,6 +34121,9 @@ async function packageNew(args) {
     ui_version: uiLatest ? `^${uiLatest}` : void 0,
     sdk_version: packageSdkRange(sdkLatest)
   });
+  const overrides = new Map(
+    buildPackageStarterOverrides({ app_name: args.name }).map((f) => [f.path, f.content])
+  );
   for (const file of files) {
     const fullPath = path7.join(targetPath, file.path);
     if (file.path === "package.json") {
@@ -33733,7 +34141,7 @@ async function packageNew(args) {
       continue;
     }
     fs6.mkdirSync(path7.dirname(fullPath), { recursive: true });
-    fs6.writeFileSync(fullPath, file.content);
+    fs6.writeFileSync(fullPath, overrides.get(file.path) ?? file.content);
   }
   fs6.writeFileSync(
     path7.join(targetPath, CONTRACT_FILE),
@@ -33777,7 +34185,8 @@ async function publishVersion(client, projectDir, opts) {
   const version = await client.publishAppPackageVersion(packageId, {
     contract,
     bundle,
-    changelog: opts.changelog ?? null
+    changelog: opts.changelog ?? null,
+    channel: opts.channel ?? "release"
   });
   project.manifest.version = version.version;
   writePackageManifest(projectDir, project);
@@ -33813,7 +34222,8 @@ async function syncToDevWorkspace(client, projectDir) {
   assertDevWorkspace(workspace);
   writePackageAppFields(projectDir);
   const { package_id, version } = await publishVersion(client, projectDir, {
-    changelog: "dev sync"
+    changelog: "dev sync",
+    channel: "dev"
   });
   const project = readPackageProject(projectDir);
   const existing = project.manifest.dev[devWorkspaceId];
@@ -33830,6 +34240,11 @@ async function syncToDevWorkspace(client, projectDir) {
   project.manifest.dev[devWorkspaceId] = { app_id: appId, version };
   writePackageManifest(projectDir, project);
   const installed = await client.getApp(appId);
+  writeAppDts(projectDir, {
+    workflows: installed.workflows ?? void 0,
+    queries: installed.queries ?? void 0,
+    agents: installed.agents ?? void 0
+  });
   return { app_id: appId, app_name: installed.name, workspace_id: devWorkspaceId, version };
 }
 async function packageSync(client, args) {
@@ -34031,13 +34446,37 @@ async function packageUpgrade(client, args) {
   });
   console.error(`Upgraded ${app.name} \u2192 v${app.package_version} (${app.id}).`);
 }
-async function packageInstall(client, args) {
+function trustBadge(pkg2) {
+  if (pkg2.is_official) return "official Lotics package";
+  if (pkg2.owned_by_caller === true) return "your organization's package";
+  return "third-party package (runs under your authority once installed)";
+}
+async function packageShow(client, args) {
   const pkg2 = await client.getAppPackage(args.package_id);
+  const { versions } = await client.listAppPackageVersions(args.package_id);
+  console.error(`${pkg2.name} (${pkg2.id}) \u2014 ${trustBadge(pkg2)}`);
+  if (pkg2.description) console.error(`  ${pkg2.description}`);
+  if (pkg2.retired_at) console.error(`  RETIRED ${pkg2.retired_at}`);
   console.error(
-    pkg2.is_official ? `Installing ${pkg2.name} \u2014 official Lotics package...` : `Installing ${pkg2.name} \u2014 third-party package (runs under your authority once installed)...`
+    `  latest installable: ${pkg2.latest_version > 0 ? `v${pkg2.latest_version}` : "none"}`
   );
+  console.error("");
+  for (const v of versions) {
+    const marks = [
+      v.version === pkg2.latest_version ? "*" : " ",
+      v.channel === "dev" ? "dev" : "   ",
+      v.yanked_at ? "YANKED" : "      "
+    ].join(" ");
+    console.log(`${marks} v${v.version}  ${v.created_at}  ${v.changelog ?? ""}`.trimEnd());
+  }
+  if (versions.length === 0) console.error("  (no published versions)");
+}
+async function packageInstall(client, args) {
+  const pkg2 = await client.getAppPackage(args.package_id);
+  console.error(`Installing ${pkg2.name} \u2014 ${trustBadge(pkg2)}...`);
   const app = await client.installAppPackage(args.package_id, {
-    ...args.version !== void 0 ? { version: args.version } : {}
+    ...args.version !== void 0 ? { version: args.version } : {},
+    ...args.config !== void 0 ? { config: args.config } : {}
   });
   const versionLabel = app.package_version !== null ? `v${app.package_version}` : "(unknown version)";
   console.error(
@@ -34053,6 +34492,104 @@ async function packageEject(client, args) {
   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);
 }
+function parseConfigAssignment(entry, flag, knownType) {
+  const eq = entry.indexOf("=");
+  if (eq <= 0 || eq === entry.length - 1) {
+    throw new Error(`Invalid ${flag} "${entry}" \u2014 expected key=value.`);
+  }
+  const key = entry.slice(0, eq);
+  const raw = entry.slice(eq + 1);
+  if (knownType === "number") {
+    const n = Number(raw);
+    if (!Number.isFinite(n)) throw new Error(`Config key "${key}" is a number knob \u2014 "${raw}" is not numeric.`);
+    return { key, value: n };
+  }
+  if (knownType === "boolean") {
+    if (raw !== "true" && raw !== "false") {
+      throw new Error(`Config key "${key}" is a boolean knob \u2014 expected true or false, got "${raw}".`);
+    }
+    return { key, value: raw === "true" };
+  }
+  if (knownType === "string") return { key, value: raw };
+  if (raw === "true" || raw === "false") return { key, value: raw === "true" };
+  if (/^-?\d+(\.\d+)?$/.test(raw)) return { key, value: Number(raw) };
+  return { key, value: raw };
+}
+function parseInstallConfigFlags(config) {
+  const out = {};
+  for (const entry of config) {
+    const { key, value } = parseConfigAssignment(entry, "--config");
+    out[key] = value;
+  }
+  return out;
+}
+async function packageConfig(client, args) {
+  const app = await client.getApp(args.app_id);
+  if (!app.package_id) {
+    throw new Error(`App ${args.app_id} is not a package installation \u2014 it has no config.`);
+  }
+  const current = app.config ?? {};
+  if (args.sets.length === 0) {
+    const keys2 = Object.keys(current).sort();
+    if (keys2.length === 0) {
+      console.error(`${app.name} (${app.id}) \u2014 no config knobs.`);
+      return;
+    }
+    console.error(`${app.name} (${app.id}) config:`);
+    for (const key of keys2) console.log(`  ${key} = ${JSON.stringify(current[key])}`);
+    return;
+  }
+  const overrides = {};
+  for (const entry of args.sets) {
+    const key = entry.slice(0, Math.max(0, entry.indexOf("=")));
+    const knownType = typeof current[key];
+    const { value } = parseConfigAssignment(
+      entry,
+      "--set",
+      knownType === "number" || knownType === "boolean" || knownType === "string" ? knownType : void 0
+    );
+    overrides[key] = value;
+  }
+  const { config } = await client.updateAppPackageConfig(args.app_id, { config: overrides });
+  console.error(`Updated config for ${app.name} (${app.id}):`);
+  for (const key of Object.keys(config).sort()) {
+    const marker = key in overrides ? " *" : "";
+    console.log(`  ${key} = ${JSON.stringify(config[key])}${marker}`);
+  }
+}
+async function packageUninstall(client, args) {
+  const app = await client.getApp(args.app_id);
+  if (!app.package_id) {
+    throw new Error(
+      `App ${args.app_id} is not a package installation \u2014 use the app delete flow for a bespoke app.`
+    );
+  }
+  const lifecycleCount = Object.keys(app.binding?.workflows ?? {}).length;
+  const boundCount = Object.keys(app.workflows ?? {}).length;
+  const tableCount = Object.keys(app.binding?.entities ?? {}).length;
+  console.error(`Uninstalling ${app.name} (${app.id}):`);
+  console.error(`  Archives ${boundCount + lifecycleCount} workflow(s) (${boundCount} app, ${lifecycleCount} lifecycle).`);
+  console.error(
+    args.archive_tables ? `  Archives ${tableCount} scaffolded table(s) \u2014 refused if they were adopted or are still referenced.` : `  Leaves the data model (${tableCount} table(s)) intact. Pass --archive-tables to also archive them.`
+  );
+  const result = await client.uninstallAppPackage(args.app_id, {
+    archive_tables: args.archive_tables
+  });
+  console.error(`Uninstalled ${app.name} (${app.id}).`);
+  if (result.archived_table_ids.length > 0) {
+    console.error(`  Archived tables: ${result.archived_table_ids.join(", ")}`);
+  }
+}
+async function packageRetire(client, args) {
+  const pkg2 = await client.retireAppPackage(args.package_id, { undo: args.undo });
+  if (pkg2.retired_at !== null) {
+    console.error(
+      `Retired ${pkg2.name} (${pkg2.id}). New installs refuse it and it is hidden from other orgs; existing installations keep working and may still upgrade.`
+    );
+  } else {
+    console.error(`Un-retired ${pkg2.name} (${pkg2.id}) \u2014 installable again.`);
+  }
+}
 async function packageExtract(client, args) {
   const app = await client.getApp(args.app_id);
   if (!app.current_version_id) {
@@ -34261,6 +34798,10 @@ function parseArgs(argv) {
     cleanup: false,
     packageVersion: void 0,
     resolve: [],
+    config: [],
+    set: [],
+    archiveTables: false,
+    undo: false,
     version: false,
     help: false
   };
@@ -34338,6 +34879,28 @@ function parseArgs(argv) {
         flags.resolve.push(value);
         break;
       }
+      case "--config": {
+        const value = argv[++i2];
+        if (value === void 0 || value.startsWith("-")) {
+          throw new Error("--config requires a value: key=value (repeatable).");
+        }
+        flags.config.push(value);
+        break;
+      }
+      case "--set": {
+        const value = argv[++i2];
+        if (value === void 0 || value.startsWith("-")) {
+          throw new Error("--set requires a value: key=value (repeatable).");
+        }
+        flags.set.push(value);
+        break;
+      }
+      case "--archive-tables":
+        flags.archiveTables = true;
+        break;
+      case "--undo":
+        flags.undo = true;
+        break;
       case "--version":
       case "-v": {
         const next = argv[i2 + 1];
@@ -51010,9 +51573,18 @@ COMMANDS
                                        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]
+  lotics package install <package> [--version N] [--config key=value ...]
                                        Install an app package into this workspace
                                        (scaffolds the data model + deploys + materializes)
+  lotics package uninstall <app_id> [--archive-tables]
+                                       Remove an installation (archives artifacts; with the
+                                       flag also archives the scaffolded tables it created)
+  lotics package config <app_id> [--set key=value ...]
+                                       Show or edit an installation's config knobs
+  lotics package show <package_id>     Registry metadata + version history
+  lotics package retire <package_id> [--undo]
+                                       Retire a package (refuse new installs, hide from other
+                                       orgs); existing installations keep working + upgrade
   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
@@ -51554,7 +52126,11 @@ async function main() {
     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 install <package> [--version N] [--config key=value ...]   Install a package into this workspace");
+    console.error("  lotics package uninstall <app_id> [--archive-tables]   Remove an installation (opt-in table archival)");
+    console.error("  lotics package config <app_id> [--set key=value ...]   Show or edit an installation's config knobs");
+    console.error("  lotics package show <package_id>                 Registry metadata + version history (channel, yank, changelog)");
+    console.error("  lotics package retire <package_id> [--undo]      Retire a package (refuse new installs; installs keep working)");
     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");
@@ -51591,16 +52167,6 @@ async function main() {
   }
   const { client, ctx } = requireClient(flags);
   if (command === "workspace") {
-    if (subcommand === "yank") {
-      const [packageId, versionRaw, maybeUndo] = toolArgs ? toolArgs.split(/\s+/) : [];
-      const version = Number(versionRaw);
-      if (!packageId || !Number.isInteger(version) || version <= 0) {
-        console.error("Usage: lotics package yank <package_id> <version> [--undo]");
-        process.exit(1);
-      }
-      await packageYank(client, { package_id: packageId, version, undo: maybeUndo === "--undo" });
-      return;
-    }
     if (subcommand === "doctor") {
       await resolveWorkspace(client, ctx);
       const dangling = await client.getWorkspaceDanglingReferences();
@@ -51729,7 +52295,48 @@ Available workspaces:`);
           process.exit(1);
         }
       }
-      await packageInstall(client, { package_id: packageId, version });
+      const config = flags.config.length > 0 ? parseInstallConfigFlags(flags.config) : void 0;
+      await packageInstall(client, {
+        package_id: packageId,
+        version,
+        ...config !== void 0 ? { config } : {}
+      });
+      return;
+    }
+    if (subcommand === "uninstall") {
+      const appId = toolArgs;
+      if (!appId) {
+        console.error("Usage: lotics package uninstall <app_id> [--archive-tables]");
+        process.exit(1);
+      }
+      await packageUninstall(client, { app_id: appId, archive_tables: flags.archiveTables });
+      return;
+    }
+    if (subcommand === "config") {
+      const appId = toolArgs;
+      if (!appId) {
+        console.error("Usage: lotics package config <app_id> [--set key=value ...]");
+        process.exit(1);
+      }
+      await packageConfig(client, { app_id: appId, sets: flags.set });
+      return;
+    }
+    if (subcommand === "retire") {
+      const packageId = toolArgs;
+      if (!packageId) {
+        console.error("Usage: lotics package retire <package_id> [--undo]");
+        process.exit(1);
+      }
+      await packageRetire(client, { package_id: packageId, undo: flags.undo });
+      return;
+    }
+    if (subcommand === "show") {
+      const packageId = toolArgs;
+      if (!packageId) {
+        console.error("Usage: lotics package show <package_id>");
+        process.exit(1);
+      }
+      await packageShow(client, { package_id: packageId });
       return;
     }
     if (subcommand === "eject") {
@@ -51769,6 +52376,16 @@ Available workspaces:`);
       await packageAdopt(client, { app_id: appId, version, projectDir: restArgs[0] });
       return;
     }
+    if (subcommand === "yank") {
+      const packageId = toolArgs;
+      const version = Number(restArgs[0]);
+      if (!packageId || !Number.isInteger(version) || version <= 0) {
+        console.error("Usage: lotics package yank <package_id> <version> [--undo]");
+        process.exit(1);
+      }
+      await packageYank(client, { package_id: packageId, version, undo: flags.undo });
+      return;
+    }
     if (subcommand === "fleet-upgrade") {
       const packageId = toolArgs;
       if (!packageId) {