@lotics/cli 0.73.0 → 0.74.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/client.d.ts

@@ -559,6 +559,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

@@ -433,6 +433,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.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

package/dist/src/cli.js

@@ -30012,6 +30012,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 +30558,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 +30778,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 +31286,7 @@ var SUPPORTED_OPS = /* @__PURE__ */ new Set([
   "workflow",
   "members",
   "context",
+  "binding",
   "upload_url",
   "upload_complete",
   "comments.list",
@@ -31334,6 +31344,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 +33363,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 +33566,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 +33593,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 +33693,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 +33727,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 +33799,7 @@ async function syncToDevWorkspace(client, projectDir) {
     );
   }
   assertDevWorkspace(workspace);
+  writePackageAppFields(projectDir);
   const { package_id, version } = await publishVersion(client, projectDir, {
     changelog: "dev sync"
   });
@@ -33950,15 +34075,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 });

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.74.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {