@lotics/cli 0.73.0 → 0.75.0

package/dist/app_commands.d.ts

@@ -1,4 +1,13 @@
 import { LoticsClient } from "./client.js";
+/**
+ * Resolve the latest published version of a package from the npm registry.
+ * Returns null on any failure (network error, 404, malformed payload) so
+ * callers can fall back to a static pin rather than crashing `app create`.
+ *
+ * 1.5s timeout — npm registry is fast when reachable; the fallback is fine
+ * the rare times it isn't, and we don't want to block scaffold on a hang.
+ */
+export declare function fetchLatestNpmVersion(packageName: string): Promise<string | null>;
 /**
  * Manifest declaration for one workflow alias:
  *   `"alias": { workflow_id, inputs?: { key: { type, … } }, outputs?: { key: { type, … } } }`

package/dist/app_commands.js

@@ -32,7 +32,7 @@ import { loadProjectTypescript, checkWorkflowBodies, } from "./app_workflow_chec
  * 1.5s timeout — npm registry is fast when reachable; the fallback is fine
  * the rare times it isn't, and we don't want to block scaffold on a hang.
  */
-async function fetchLatestNpmVersion(packageName) {
+export async function fetchLatestNpmVersion(packageName) {
     try {
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), 1500);

package/dist/cli.js

@@ -14,7 +14,7 @@ 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 { packageInstall, packageEject, packageDoctor, packageUpgrade, parseResolveFlags, packageNew, packageBuild, packagePublish, packageDev, packageSync, packageReset, packageExtract, packageAdopt, packageFleetUpgrade, packageYank, } from "./package_commands.js";
 import { parseArgs } from "./args.js";
 import { ingestJsonArgs } from "./inputs.js";
 import { runXlsxCommand } from "./xlsx.js";
@@ -124,6 +124,7 @@ COMMANDS
                                        origin app (reads .lotics/adopt_binding.json;
                                        --version N pins a specific version)
   lotics package fleet-upgrade <package_id> [--version N]
+  lotics package yank <package_id> <version> [--undo]
                                        Upgrade EVERY installation of the package across
                                        your org: applies where the preview is clean,
                                        skips + reports findings (exit 1 unless all current)
@@ -707,6 +708,7 @@ async function main() {
         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)");
+        console.error("  lotics package yank <package_id> <version> [--undo]       Refuse new installs/upgrades of a broken published version (pinned installations keep running)");
         process.exit(1);
     }
     if (command === "run" && !subcommand) {
@@ -736,6 +738,16 @@ async function main() {
     const { client, ctx } = requireClient(flags);
     // lotics workspace / lotics workspace list / lotics workspace select <id>
     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") {
             // The workspace command family runs before the global workspace
             // resolution — doctor needs the same first-workspace fallback every

package/dist/client.d.ts

@@ -287,6 +287,17 @@ export declare class LoticsClient {
      * per-installation consent flow. Backs `lotics package fleet-upgrade`.
      * Admin-only; org-scoped (no workspace header needed).
      */
+    /**
+     * Yank / unyank a published package version — refuses NEW installs/upgrades/
+     * adopts targeting it; pinned installations keep running. Owner-org
+     * admin-only. Backs `lotics package yank`.
+     */
+    yankAppPackageVersion(package_id: string, version: number, yanked: boolean): Promise<{
+        package_id: string;
+        version: number;
+        yanked_at: string | null;
+        latest_version: number;
+    }>;
     fleetUpgradeAppPackage(package_id: string, body: {
         version?: number;
     }): Promise<{
@@ -559,6 +570,12 @@ export declare class LoticsClient {
             image: string | null;
         }>;
     }>;
+    /** A package installation's alias→id maps (fields/options/roles) — the app's runtime F/OPT resolution. */
+    appBinding(app_id: string): Promise<{
+        fields: Record<string, string>;
+        options: Record<string, string>;
+        roles: Record<string, string>;
+    }>;
     /**
      * Resolve the full option set (key, label, color) of a named query's select
      * columns — the picker companion to `appQuery`. Mirrors

package/dist/client.js

@@ -255,6 +255,14 @@ export class LoticsClient {
      * per-installation consent flow. Backs `lotics package fleet-upgrade`.
      * Admin-only; org-scoped (no workspace header needed).
      */
+    /**
+     * Yank / unyank a published package version — refuses NEW installs/upgrades/
+     * adopts targeting it; pinned installations keep running. Owner-org
+     * admin-only. Backs `lotics package yank`.
+     */
+    async yankAppPackageVersion(package_id, version, yanked) {
+        return this.request("POST", `/v1/app-packages/${encodeURIComponent(package_id)}/versions/${version}/yank`, { yanked });
+    }
     async fleetUpgradeAppPackage(package_id, body) {
         return this.request("POST", `/v1/app-packages/${encodeURIComponent(package_id)}/fleet-upgrade`, body);
     }
@@ -433,6 +441,10 @@ export class LoticsClient {
         const qs = group_id ? `?group_id=${encodeURIComponent(group_id)}` : "";
         return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/members${qs}`);
     }
+    /** A package installation's alias→id maps (fields/options/roles) — the app's runtime F/OPT resolution. */
+    async appBinding(app_id) {
+        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/binding`);
+    }
     /**
      * Resolve the full option set (key, label, color) of a named query's select
      * columns — the picker companion to `appQuery`. Mirrors

package/dist/dev/rpc_handler.d.ts

@@ -6,7 +6,7 @@
  * { message }. Same shape as the production iframe-host's error path.
  */
 import { LoticsClient } from "../client.js";
-export type RpcOp = "query" | "field_options" | "workflow" | "members" | "context" | "upload_url" | "upload_complete" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts";
+export type RpcOp = "query" | "field_options" | "workflow" | "members" | "context" | "binding" | "upload_url" | "upload_complete" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts";
 export interface RpcRequest {
     app_id: string;
     op: RpcOp;

package/dist/dev/rpc_handler.js

@@ -11,6 +11,7 @@ const SUPPORTED_OPS = new Set([
     "workflow",
     "members",
     "context",
+    "binding",
     "upload_url",
     "upload_complete",
     "comments.list",
@@ -76,6 +77,8 @@ export async function dispatchRpc(client, body, opts) {
             const p = body.payload;
             return client.appMembers(body.app_id, p?.group);
         }
+        case "binding":
+            return client.appBinding(body.app_id);
         case "upload_url": {
             const p = body.payload;
             if (!p ||

package/dist/generate_app_fields.d.ts

@@ -46,6 +46,8 @@ export interface TableSchema {
  * `upper` uppercases the result (TABLE aliases read as constants).
  */
 export declare function slugifyAlias(name: string, upper: boolean): string;
+/** A property key for an object literal — bare when a valid identifier, else quoted. */
+export declare function propKey(alias: string): string;
 /**
  * Generate the full `.lotics/app_fields.ts` source. `tables` is the resolved
  * workspace schema (the subset the app touches). An empty list yields valid,

package/dist/generate_app_fields.js

@@ -68,7 +68,7 @@ function dedupeAliases(names, upper) {
     });
 }
 /** A property key for an object literal — bare when a valid identifier, else quoted. */
-function propKey(alias) {
+export function propKey(alias) {
     return isValidIdentifier(alias) ? alias : JSON.stringify(alias);
 }
 /** Resolve table + field aliases once, so the `F`/`OPT` maps and the union types agree. */

package/dist/generate_package_fields.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Codegen: emit a RUNTIME `.lotics/app_fields.ts` for a PACKAGE project from
+ * its `contract.json`.
+ *
+ * The bespoke twin (`generate_app_fields.ts`) bakes this workspace's concrete
+ * `fld_…`/`opt_…` ids at authoring time — correct when source and workspace
+ * co-live, fundamentally wrong for a package (one bundle, many workspaces,
+ * different ids in each). A package project instead resolves the SAME `F` /
+ * `OPT` surface at MODULE LOAD from the installation's binding via the SDK's
+ * `getAppBinding()` (the `binding` RPC op), using top-level await — the ESM
+ * graph waits for the binding before any importer evaluates, so
+ * `F.TASKS.title` is a plain string everywhere, including module-top-level
+ * constants. Extracted bespoke sources therefore compile unchanged: same
+ * import path, same shapes, same alias naming (contract aliases derive from
+ * the same display names the bespoke codegen slugifies).
+ *
+ * A missing alias fails LOUD at boot (the binding is adopt/install-verified
+ * complete, so a miss means the generated file is stale relative to the
+ * installed contract version) — never a silent undefined key in a write.
+ *
+ * Requires the app build to target es2022+ (the starter's `build.target`) —
+ * top-level await does not exist below it.
+ */
+/** The subset of a contract this generator reads (structural, not zod-validated —
+ *  publish is the validating boundary; codegen must work on drafts too). */
+export interface PackageContractShape {
+    entities?: Array<{
+        alias: string;
+        fields?: Array<{
+            alias: string;
+            options?: Array<{
+                alias: string;
+            }>;
+        }>;
+    }>;
+    roles?: Array<{
+        alias: string;
+    }>;
+}
+/**
+ * Generate the full package `.lotics/app_fields.ts` source. Valid contract
+ * aliases are slug-grammar (`^[a-z][a-z0-9_]*$`) and emit as bare identifiers
+ * — but this also runs on unvalidated DRAFTS (dev/sync pre-publish), so every
+ * key goes through `propKey`, which quotes anything that isn't a valid
+ * identifier instead of emitting broken TypeScript into a "DO NOT EDIT" file.
+ * Pure; same contract → same bytes.
+ */
+export declare function generatePackageAppFields(contract: PackageContractShape): string;

package/dist/generate_package_fields.js

@@ -0,0 +1,104 @@
+/**
+ * Codegen: emit a RUNTIME `.lotics/app_fields.ts` for a PACKAGE project from
+ * its `contract.json`.
+ *
+ * The bespoke twin (`generate_app_fields.ts`) bakes this workspace's concrete
+ * `fld_…`/`opt_…` ids at authoring time — correct when source and workspace
+ * co-live, fundamentally wrong for a package (one bundle, many workspaces,
+ * different ids in each). A package project instead resolves the SAME `F` /
+ * `OPT` surface at MODULE LOAD from the installation's binding via the SDK's
+ * `getAppBinding()` (the `binding` RPC op), using top-level await — the ESM
+ * graph waits for the binding before any importer evaluates, so
+ * `F.TASKS.title` is a plain string everywhere, including module-top-level
+ * constants. Extracted bespoke sources therefore compile unchanged: same
+ * import path, same shapes, same alias naming (contract aliases derive from
+ * the same display names the bespoke codegen slugifies).
+ *
+ * A missing alias fails LOUD at boot (the binding is adopt/install-verified
+ * complete, so a miss means the generated file is stale relative to the
+ * installed contract version) — never a silent undefined key in a write.
+ *
+ * Requires the app build to target es2022+ (the starter's `build.target`) —
+ * top-level await does not exist below it.
+ */
+import { propKey } from "./generate_app_fields.js";
+const HEADER = `// Auto-generated by 'lotics package new/extract/dev/sync' from contract.json.
+// DO NOT EDIT — regenerated whenever the contract changes.
+//
+// Package apps resolve F/OPT/ROLE at MODULE LOAD from the installation's
+// binding (contract alias → THIS workspace's concrete id) via the SDK's
+// \`binding\` RPC. Top-level await: the module graph waits for the binding
+// before any importer evaluates, so every entry is a plain string.
+import { getAppBinding } from "@lotics/app-sdk";
+
+const binding = await getAppBinding();
+
+function bound(map: Record<string, string>, key: string, kind: string): string {
+  const id = map[key];
+  if (id === undefined) {
+    throw new Error(
+      \`app_fields: \${kind} "\${key}" is not in this installation's binding — \` +
+        \`the generated app_fields.ts is stale relative to the installed contract version.\`,
+    );
+  }
+  return id;
+}
+`;
+/**
+ * Generate the full package `.lotics/app_fields.ts` source. Valid contract
+ * aliases are slug-grammar (`^[a-z][a-z0-9_]*$`) and emit as bare identifiers
+ * — but this also runs on unvalidated DRAFTS (dev/sync pre-publish), so every
+ * key goes through `propKey`, which quotes anything that isn't a valid
+ * identifier instead of emitting broken TypeScript into a "DO NOT EDIT" file.
+ * Pure; same contract → same bytes.
+ */
+export function generatePackageAppFields(contract) {
+    const entities = contract.entities ?? [];
+    const roles = contract.roles ?? [];
+    const fieldBlocks = [];
+    for (const entity of entities) {
+        const lines = (entity.fields ?? []).map((field) => `    ${propKey(field.alias)}: bound(binding.fields, ${JSON.stringify(`${entity.alias}.${field.alias}`)}, "field"),`);
+        if (lines.length === 0)
+            continue;
+        fieldBlocks.push(`  ${propKey(entity.alias.toUpperCase())}: {\n${lines.join("\n")}\n  },`);
+    }
+    const optionBlocks = [];
+    for (const entity of entities) {
+        const perField = [];
+        for (const field of entity.fields ?? []) {
+            const options = field.options ?? [];
+            if (options.length === 0)
+                continue;
+            const lines = options.map((option) => `      ${propKey(option.alias)}: bound(binding.options, ${JSON.stringify(`${entity.alias}.${field.alias}:${option.alias}`)}, "option"),`);
+            perField.push(`    ${propKey(field.alias)}: {\n${lines.join("\n")}\n    },`);
+        }
+        if (perField.length > 0) {
+            optionBlocks.push(`  ${propKey(entity.alias.toUpperCase())}: {\n${perField.join("\n")}\n  },`);
+        }
+    }
+    const fMap = fieldBlocks.length > 0
+        ? `export const F = {\n${fieldBlocks.join("\n")}\n} as const;`
+        : `export const F = {} as const;`;
+    const optMap = optionBlocks.length > 0
+        ? `export const OPT = {\n${optionBlocks.join("\n")}\n} as const;`
+        : `export const OPT = {} as const;`;
+    const roleMap = roles.length > 0
+        ? `export const ROLE = {\n${roles
+            .map((role) => `  ${propKey(role.alias)}: bound(binding.roles, ${JSON.stringify(role.alias)}, "role"),`)
+            .join("\n")}\n} as const;`
+        : `export const ROLE = {} as const;`;
+    return `${HEADER}
+${fMap}
+
+${optMap}
+
+${roleMap}
+
+/** Field-id alias map: \`F[<ENTITY>][<field>]\` is this installation's \`fld_…\` id. */
+export type AppFields = typeof F;
+/** Select-option alias map: \`OPT[<ENTITY>][<field>][<option>]\` is this installation's \`opt_…\` id. */
+export type AppOptions = typeof OPT;
+/** Role alias map: \`ROLE[<role>]\` is this installation's \`grp_…\` id. */
+export type AppRoles = typeof ROLE;
+`;
+}

package/dist/generate_package_fields.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/generate_package_fields.test.js

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import { generatePackageAppFields } from "./generate_package_fields.js";
+const contract = {
+    entities: [
+        {
+            alias: "tasks",
+            fields: [
+                { alias: "title" },
+                {
+                    alias: "status",
+                    options: [{ alias: "to_do" }, { alias: "doing" }, { alias: "done" }],
+                },
+            ],
+        },
+        { alias: "projects", fields: [{ alias: "name" }] },
+    ],
+    roles: [{ alias: "approver" }],
+};
+describe("generatePackageAppFields", () => {
+    it("emits runtime-resolved F/OPT/ROLE keyed by contract aliases", () => {
+        const src = generatePackageAppFields(contract);
+        // Resolves through the SDK binding at module load (top-level await).
+        expect(src).toContain('import { getAppBinding } from "@lotics/app-sdk";');
+        expect(src).toContain("const binding = await getAppBinding();");
+        // F: uppercased entity alias, fully-qualified binding keys.
+        expect(src).toContain('title: bound(binding.fields, "tasks.title", "field")');
+        expect(src).toContain('name: bound(binding.fields, "projects.name", "field")');
+        expect(src).toMatch(/TASKS: \{/);
+        expect(src).toMatch(/PROJECTS: \{/);
+        // OPT: qualified entity.field:opt keys; option-less fields absent.
+        expect(src).toContain('to_do: bound(binding.options, "tasks.status:to_do", "option")');
+        expect(src).toContain('done: bound(binding.options, "tasks.status:done", "option")');
+        expect(src).not.toContain('"tasks.title:');
+        // ROLE map from contract roles.
+        expect(src).toContain('approver: bound(binding.roles, "approver", "role")');
+        // No concrete id in any VALUE position — the module is workspace-agnostic.
+        // (Doc comments legitimately name the id prefixes, so match quoted ids.)
+        expect(src).not.toMatch(/"(fld|opt|tbl|grp)_/);
+    });
+    it("emits valid empty maps for an empty contract", () => {
+        const src = generatePackageAppFields({});
+        expect(src).toContain("export const F = {} as const;");
+        expect(src).toContain("export const OPT = {} as const;");
+        expect(src).toContain("export const ROLE = {} as const;");
+        // Still imports the SDK so the module shape is uniform.
+        expect(src).toContain("const binding = await getAppBinding();");
+    });
+    it("is deterministic — same contract, same bytes", () => {
+        expect(generatePackageAppFields(contract)).toBe(generatePackageAppFields(contract));
+    });
+});

package/dist/package_commands.d.ts

@@ -220,6 +220,17 @@ export declare function packageAdopt(client: LoticsClient, args: {
  * installations are reported per line and the process exits 1 so a release
  * script can gate on "fleet fully current".
  */
+/**
+ * `lotics package yank <package_id> <version> [--undo]` — mark a published
+ * version uninstallable (or restore it). New installs/upgrades/adopts refuse a
+ * yanked version and "latest" skips it; installations already pinned keep
+ * running. Owner-org admin-only.
+ */
+export declare function packageYank(client: LoticsClient, args: {
+    package_id: string;
+    version: number;
+    undo: boolean;
+}): Promise<void>;
 export declare function packageFleetUpgrade(client: LoticsClient, args: {
     package_id: string;
     version?: number;

package/dist/package_commands.js

@@ -25,8 +25,9 @@ import fs from "node:fs";
 import path from "node:path";
 import { tmpdir } from "node:os";
 import "./client.js";
-import { buildStarterTemplate } from "./starter_template.js";
-import { appDirName, runNpm, runTar } from "./app_commands.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";
@@ -160,6 +161,36 @@ export function formatExtractReport(report) {
         .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);
@@ -168,6 +199,21 @@ function readContract(projectDir) {
     }
     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",
@@ -299,10 +345,21 @@ export async function packageNew(args) {
     // 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);
@@ -324,6 +381,7 @@ export async function packageNew(args) {
         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);
@@ -426,6 +484,9 @@ async function syncToDevWorkspace(client, projectDir) {
         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",
     });
@@ -741,10 +802,57 @@ export async function packageExtract(client, args) {
     // 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"));
-    writePackageManifest(targetPath, draftPackageProjectFromApp(appPkgJson, { name: app.name, description: null }));
+    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
@@ -817,6 +925,23 @@ export async function packageAdopt(client, args) {
  * installations are reported per line and the process exits 1 so a release
  * script can gate on "fleet fully current".
  */
+/**
+ * `lotics package yank <package_id> <version> [--undo]` — mark a published
+ * version uninstallable (or restore it). New installs/upgrades/adopts refuse a
+ * yanked version and "latest" skips it; installations already pinned keep
+ * running. Owner-org admin-only.
+ */
+export async function packageYank(client, args) {
+    const result = await client.yankAppPackageVersion(args.package_id, args.version, !args.undo);
+    if (result.yanked_at !== null) {
+        console.error(`Yanked ${result.package_id} v${result.version} (${result.yanked_at}). ` +
+            `New installs/upgrades refuse it; pinned installations keep running.`);
+    }
+    else {
+        console.error(`Restored ${result.package_id} v${result.version} — installable again.`);
+    }
+    console.error(`  Latest installable version: ${result.latest_version === 0 ? "none" : `v${result.latest_version}`}`);
+}
 export async function packageFleetUpgrade(client, args) {
     const result = await client.fleetUpgradeAppPackage(args.package_id, {
         ...(args.version !== undefined ? { version: args.version } : {}),

package/dist/src/cli.js

@@ -29818,6 +29818,18 @@ var LoticsClient = class {
    * per-installation consent flow. Backs `lotics package fleet-upgrade`.
    * Admin-only; org-scoped (no workspace header needed).
    */
+  /**
+   * Yank / unyank a published package version — refuses NEW installs/upgrades/
+   * adopts targeting it; pinned installations keep running. Owner-org
+   * admin-only. Backs `lotics package yank`.
+   */
+  async yankAppPackageVersion(package_id, version, yanked) {
+    return this.request(
+      "POST",
+      `/v1/app-packages/${encodeURIComponent(package_id)}/versions/${version}/yank`,
+      { yanked }
+    );
+  }
   async fleetUpgradeAppPackage(package_id, body) {
     return this.request(
       "POST",
@@ -30012,6 +30024,10 @@ var LoticsClient = class {
     const qs = group_id ? `?group_id=${encodeURIComponent(group_id)}` : "";
     return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/members${qs}`);
   }
+  /** A package installation's alias→id maps (fields/options/roles) — the app's runtime F/OPT resolution. */
+  async appBinding(app_id) {
+    return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/binding`);
+  }
   /**
    * Resolve the full option set (key, label, color) of a named query's select
    * columns — the picker companion to `appQuery`. Mirrors
@@ -30554,7 +30570,7 @@ import { tmpdir } from "node:os";
 
 // src/starter_template.ts
 var STARTER_FALLBACK_UI_VERSION = "6.1.0";
-var STARTER_FALLBACK_SDK_VERSION = "0.40.0";
+var STARTER_FALLBACK_SDK_VERSION = "0.51.0";
 var STARTER_REACT_NATIVE_VERSION = "0.85.3";
 function buildStarterTemplate(args) {
   const uiVersion = args.ui_version ?? `^${STARTER_FALLBACK_UI_VERSION}`;
@@ -30774,6 +30790,11 @@ export default defineConfig({
   build: {
     outDir: "dist",
     sourcemap: true,
+    // Top-level await (package projects' generated .lotics/app_fields.ts
+    // resolves the installation binding at module load) needs es2022 \u2014 Vite's
+    // default 'modules' baseline is es2020 and esbuild hard-fails TLA there.
+    // Dev already transforms at esnext, so this only aligns the prod build.
+    target: "es2022",
   },
   server: {
     // Allow the sandboxed null-origin iframe used by \`lotics app dev\` to
@@ -31277,6 +31298,7 @@ var SUPPORTED_OPS = /* @__PURE__ */ new Set([
   "workflow",
   "members",
   "context",
+  "binding",
   "upload_url",
   "upload_complete",
   "comments.list",
@@ -31334,6 +31356,8 @@ async function dispatchRpc(client, body, opts) {
       const p = body.payload;
       return client.appMembers(body.app_id, p?.group);
     }
+    case "binding":
+      return client.appBinding(body.app_id);
     case "upload_url": {
       const p = body.payload;
       if (!p || typeof p.filename !== "string" || typeof p.mime_type !== "string" || typeof p.file_size !== "number") {
@@ -33351,6 +33375,86 @@ import fs6 from "node:fs";
 import path7 from "node:path";
 import { tmpdir as tmpdir2 } from "node:os";
 
+// src/generate_package_fields.ts
+var HEADER5 = `// Auto-generated by 'lotics package new/extract/dev/sync' from contract.json.
+// DO NOT EDIT \u2014 regenerated whenever the contract changes.
+//
+// Package apps resolve F/OPT/ROLE at MODULE LOAD from the installation's
+// binding (contract alias \u2192 THIS workspace's concrete id) via the SDK's
+// \`binding\` RPC. Top-level await: the module graph waits for the binding
+// before any importer evaluates, so every entry is a plain string.
+import { getAppBinding } from "@lotics/app-sdk";
+
+const binding = await getAppBinding();
+
+function bound(map: Record<string, string>, key: string, kind: string): string {
+  const id = map[key];
+  if (id === undefined) {
+    throw new Error(
+      \`app_fields: \${kind} "\${key}" is not in this installation's binding \u2014 \` +
+        \`the generated app_fields.ts is stale relative to the installed contract version.\`,
+    );
+  }
+  return id;
+}
+`;
+function generatePackageAppFields(contract) {
+  const entities = contract.entities ?? [];
+  const roles = contract.roles ?? [];
+  const fieldBlocks = [];
+  for (const entity of entities) {
+    const lines = (entity.fields ?? []).map(
+      (field) => `    ${propKey(field.alias)}: bound(binding.fields, ${JSON.stringify(`${entity.alias}.${field.alias}`)}, "field"),`
+    );
+    if (lines.length === 0) continue;
+    fieldBlocks.push(`  ${propKey(entity.alias.toUpperCase())}: {
+${lines.join("\n")}
+  },`);
+  }
+  const optionBlocks = [];
+  for (const entity of entities) {
+    const perField = [];
+    for (const field of entity.fields ?? []) {
+      const options = field.options ?? [];
+      if (options.length === 0) continue;
+      const lines = options.map(
+        (option) => `      ${propKey(option.alias)}: bound(binding.options, ${JSON.stringify(`${entity.alias}.${field.alias}:${option.alias}`)}, "option"),`
+      );
+      perField.push(`    ${propKey(field.alias)}: {
+${lines.join("\n")}
+    },`);
+    }
+    if (perField.length > 0) {
+      optionBlocks.push(`  ${propKey(entity.alias.toUpperCase())}: {
+${perField.join("\n")}
+  },`);
+    }
+  }
+  const fMap = fieldBlocks.length > 0 ? `export const F = {
+${fieldBlocks.join("\n")}
+} as const;` : `export const F = {} as const;`;
+  const optMap = optionBlocks.length > 0 ? `export const OPT = {
+${optionBlocks.join("\n")}
+} as const;` : `export const OPT = {} as const;`;
+  const roleMap = roles.length > 0 ? `export const ROLE = {
+${roles.map((role) => `  ${propKey(role.alias)}: bound(binding.roles, ${JSON.stringify(role.alias)}, "role"),`).join("\n")}
+} as const;` : `export const ROLE = {} as const;`;
+  return `${HEADER5}
+${fMap}
+
+${optMap}
+
+${roleMap}
+
+/** Field-id alias map: \`F[<ENTITY>][<field>]\` is this installation's \`fld_\u2026\` id. */
+export type AppFields = typeof F;
+/** Select-option alias map: \`OPT[<ENTITY>][<field>][<option>]\` is this installation's \`opt_\u2026\` id. */
+export type AppOptions = typeof OPT;
+/** Role alias map: \`ROLE[<role>]\` is this installation's \`grp_\u2026\` id. */
+export type AppRoles = typeof ROLE;
+`;
+}
+
 // src/file_command_io.ts
 import fs5 from "node:fs";
 import path6 from "node:path";
@@ -33474,6 +33578,24 @@ function formatExtractReport(report) {
   );
   return { lines, hasError: report.some((f) => f.severity === "error") };
 }
+function dotLoticsDirEnsured(projectDir) {
+  const dir = path7.join(projectDir, ".lotics");
+  fs6.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+function cmpVersions(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i2 = 0; i2 < 3; i2++) {
+    const d = (pa[i2] || 0) - (pb[i2] || 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+}
+function packageSdkRange(sdkLatest) {
+  const version = sdkLatest !== null && cmpVersions(sdkLatest, STARTER_FALLBACK_SDK_VERSION) > 0 ? sdkLatest : STARTER_FALLBACK_SDK_VERSION;
+  return `^${version}`;
+}
 function readContract(projectDir) {
   const contractPath = path7.join(projectDir, CONTRACT_FILE);
   if (!fs6.existsSync(contractPath)) {
@@ -33483,6 +33605,13 @@ function readContract(projectDir) {
   }
   return JSON.parse(fs6.readFileSync(contractPath, "utf-8"));
 }
+function writePackageAppFields(projectDir) {
+  const contract = readContract(projectDir);
+  const dotLotics = path7.join(projectDir, ".lotics");
+  fs6.mkdirSync(dotLotics, { recursive: true });
+  fs6.writeFileSync(path7.join(dotLotics, "app_fields.ts"), generatePackageAppFields(contract));
+  console.error("Wrote .lotics/app_fields.ts (contract-derived, runtime-resolved)");
+}
 var SOURCE_STAGE_EXCLUDES = /* @__PURE__ */ new Set([
   "node_modules",
   "dist",
@@ -33576,10 +33705,16 @@ async function packageNew(args) {
     throw new Error(`Target directory ${targetPath} is not empty.`);
   }
   fs6.mkdirSync(targetPath, { recursive: true });
+  const [uiLatest, sdkLatest] = await Promise.all([
+    fetchLatestNpmVersion("@lotics/ui"),
+    fetchLatestNpmVersion("@lotics/app-sdk")
+  ]);
   const files = buildStarterTemplate({
     app_name: args.name,
     app_id: "",
-    workspace_id: ""
+    workspace_id: "",
+    ui_version: uiLatest ? `^${uiLatest}` : void 0,
+    sdk_version: packageSdkRange(sdkLatest)
   });
   for (const file of files) {
     const fullPath = path7.join(targetPath, file.path);
@@ -33604,6 +33739,7 @@ async function packageNew(args) {
     path7.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);
@@ -33675,6 +33811,7 @@ async function syncToDevWorkspace(client, projectDir) {
     );
   }
   assertDevWorkspace(workspace);
+  writePackageAppFields(projectDir);
   const { package_id, version } = await publishVersion(client, projectDir, {
     changelog: "dev sync"
   });
@@ -33950,15 +34087,42 @@ async function packageExtract(client, args) {
   const appPkgJson = JSON.parse(
     fs6.readFileSync(packageJsonPath(targetPath), "utf-8")
   );
-  writePackageManifest(
-    targetPath,
-    draftPackageProjectFromApp(appPkgJson, { name: app.name, description: null })
-  );
+  const draft = draftPackageProjectFromApp(appPkgJson, { name: app.name, description: null });
+  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);
   fs6.writeFileSync(
     path7.join(targetPath, CONTRACT_FILE),
     JSON.stringify(extracted.contract, null, 2) + "\n"
   );
   console.error(`Wrote ${CONTRACT_FILE}`);
+  writePackageAppFields(targetPath);
+  const starterViteConfig = buildStarterTemplate({
+    app_name: app.name,
+    app_id: "",
+    workspace_id: ""
+  }).find((f) => f.path === "vite.config.ts");
+  if (starterViteConfig === void 0) {
+    throw new Error("starter template is missing vite.config.ts \u2014 cannot refresh the package project");
+  }
+  const viteConfigPath = path7.join(targetPath, "vite.config.ts");
+  const originViteConfig = fs6.existsSync(viteConfigPath) ? fs6.readFileSync(viteConfigPath, "utf-8") : null;
+  fs6.writeFileSync(viteConfigPath, starterViteConfig.content);
+  if (originViteConfig !== null && originViteConfig !== starterViteConfig.content) {
+    const stash = path7.join(dotLoticsDirEnsured(targetPath), "vite.config.origin.ts");
+    fs6.writeFileSync(stash, originViteConfig);
+    console.error(
+      "Refreshed vite.config.ts from the starter (build.target es2022). The origin app's config differed \u2014 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)");
+  }
   for (const tf of extracted.template_files) {
     const dest = path7.join(targetPath, tf.bytes_ref);
     fs6.mkdirSync(path7.dirname(dest), { recursive: true });
@@ -34029,6 +34193,17 @@ async function packageAdopt(client, args) {
   );
   console.error(`  Verify the installation:  lotics package doctor ${app.id}`);
 }
+async function packageYank(client, args) {
+  const result = await client.yankAppPackageVersion(args.package_id, args.version, !args.undo);
+  if (result.yanked_at !== null) {
+    console.error(
+      `Yanked ${result.package_id} v${result.version} (${result.yanked_at}). New installs/upgrades refuse it; pinned installations keep running.`
+    );
+  } else {
+    console.error(`Restored ${result.package_id} v${result.version} \u2014 installable again.`);
+  }
+  console.error(`  Latest installable version: ${result.latest_version === 0 ? "none" : `v${result.latest_version}`}`);
+}
 async function packageFleetUpgrade(client, args) {
   const result = await client.fleetUpgradeAppPackage(args.package_id, {
     ...args.version !== void 0 ? { version: args.version } : {}
@@ -50856,6 +51031,7 @@ COMMANDS
                                        origin app (reads .lotics/adopt_binding.json;
                                        --version N pins a specific version)
   lotics package fleet-upgrade <package_id> [--version N]
+  lotics package yank <package_id> <version> [--undo]
                                        Upgrade EVERY installation of the package across
                                        your org: applies where the preview is clean,
                                        skips + reports findings (exit 1 unless all current)
@@ -51386,6 +51562,7 @@ async function main() {
     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)");
+    console.error("  lotics package yank <package_id> <version> [--undo]       Refuse new installs/upgrades of a broken published version (pinned installations keep running)");
     process.exit(1);
   }
   if (command === "run" && !subcommand) {
@@ -51414,6 +51591,16 @@ 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();

package/dist/starter_template.d.ts

@@ -42,7 +42,7 @@ export interface StarterFile {
  * fall back here when the lookup fails.
  */
 export declare const STARTER_FALLBACK_UI_VERSION = "6.1.0";
-export declare const STARTER_FALLBACK_SDK_VERSION = "0.40.0";
+export declare const STARTER_FALLBACK_SDK_VERSION = "0.51.0";
 /**
  * react-native pin for scaffolded apps. Matches the monorepo frontend's pin so
  * an app deep-typechecks `@lotics/ui`'s `.tsx` source against the SAME RN types

package/dist/starter_template.js

@@ -38,10 +38,11 @@
  * fall back here when the lookup fails.
  */
 export const STARTER_FALLBACK_UI_VERSION = "6.1.0";
-// Must be ≥ the release that added `@lotics/app-sdk/router` (`AppRouter`, used by
-// the scaffolded App.tsx) — an older offline pin won't resolve the subpath and
-// the scaffold won't typecheck.
-export const STARTER_FALLBACK_SDK_VERSION = "0.40.0";
+// Must be ≥ the release that added `getAppBinding` (0.51.0, used by package
+// projects' generated .lotics/app_fields.ts) — and note ^0.x caret ranges never
+// cross a minor, so a stale floor here permanently pins scaffolds below the
+// APIs the generated code imports.
+export const STARTER_FALLBACK_SDK_VERSION = "0.51.0";
 /**
  * react-native pin for scaffolded apps. Matches the monorepo frontend's pin so
  * an app deep-typechecks `@lotics/ui`'s `.tsx` source against the SAME RN types
@@ -267,6 +268,11 @@ export default defineConfig({
   build: {
     outDir: "dist",
     sourcemap: true,
+    // Top-level await (package projects' generated .lotics/app_fields.ts
+    // resolves the installation binding at module load) needs es2022 — Vite's
+    // default 'modules' baseline is es2020 and esbuild hard-fails TLA there.
+    // Dev already transforms at esnext, so this only aligns the prod build.
+    target: "es2022",
   },
   server: {
     // Allow the sandboxed null-origin iframe used by \`lotics app dev\` to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.73.0",
+  "version": "0.75.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {