@lotics/cli 0.64.0 → 0.66.0

package/README.md

@@ -181,8 +181,14 @@ lotics app workflow pull                    # rewrite src/workflows/*.ts + globa
 lotics app workflow check                   # typecheck every body locally ([alias] for one)
 lotics app workflow set issueInvoice        # push the edited src/workflows/issueInvoice.ts
 
-# Dev-link @lotics/ui to the monorepo's packages/ui/src for live HMR (monorepo only)
-lotics ui link card                        # edits to packages/ui/src go live
+# Iterate on a named query WITHOUT a deploy: push package.json#lotics.queries.<alias>
+# to apps.queries (server-validated like a deploy). apps.queries is manifest-
+# authoritative, so the next `app deploy` re-syncs it — keep the manifest current.
+lotics app query set openInvoices           # push package.json#lotics.queries.openInvoices
+
+# Dev-link @lotics/ui to packages/ui/src for live HMR (Vite alias; deploy bundles it)
+lotics ui link card                        # monorepo: packages/ui/src found automatically
+lotics ui link card --ui-src /abs/monorepo/packages/ui/src   # external app (e.g. ~/lotics_apps)
 lotics ui link card --remove               # finalize: PR + publish, then drop the alias
 ```
 

package/dist/app_commands.d.ts

@@ -87,16 +87,23 @@ export declare function writeWorkflowFile(projectDir: string, alias: string, sou
  */
 export declare function stripWorkflowHeader(content: string): string;
 /**
- * Add the workflow-body globs to the main `tsconfig.json`'s `exclude` if missing,
- * preserving every other exclude. The starter ships these excludes already, but
- * an app SCAFFOLDED before this CLI release (or one with a hand-written tsconfig)
- * doesn't — and pulling bodies into it would otherwise break its
- * `npm run typecheck`: the bodies pull the app's DOM lib (the server doesn't) and
- * the per-alias ambient globals collide on `trigger`. Idempotent — a second pull
- * is a no-op. Warns exactly what it added. A missing/unparseable tsconfig is a
- * non-fatal warn (the pull itself still succeeds); the author fixes the config.
+ * Heal a pre-existing app's `tsconfig.json` so its generated types load and its
+ * `npm run typecheck` stays honest. Idempotent, run on every pull / codegen /
+ * deploy. Two things the current starter ships but an app SCAFFOLDED before those
+ * releases (or with a hand-written tsconfig) can lack:
+ *
+ *  1. `include`: a bare `.lotics` is rewritten to the recursive `LOTICS_INCLUDE_GLOB`.
+ *     A bare dot-dir is skipped by TypeScript's include-glob walk, so the codegen'd
+ *     `.d.ts` never enter the program — every `useQuery`/`useWorkflow`/`useAgentRun`
+ *     param and result silently falls back to `unknown`.
+ *  2. `exclude`: the workflow-body globs — the bodies use the app's DOM lib (the
+ *     server doesn't) and the per-alias ambient globals collide on `trigger`,
+ *     poisoning typecheck. Checked separately by `lotics app workflow check`.
+ *
+ * A missing / unparseable tsconfig is a non-fatal warn (the caller still succeeds);
+ * the author fixes the config.
  */
-export declare function ensureWorkflowTsconfigExcludes(projectDir: string): void;
+export declare function ensureAppTsconfig(projectDir: string): void;
 /**
  * `lotics app codegen [path]` — regenerate every `.lotics/` artifact from the
  * manifest + workspace schema, WITHOUT a deploy. The `.d.ts` companions are
@@ -296,6 +303,23 @@ export declare function appExecuteWorkflow(client: LoticsClient, args: {
 export declare function appWorkflowSet(client: LoticsClient, args: {
     alias: string;
 }): Promise<void>;
+/**
+ * `lotics app query set <alias>` — push `package.json#lotics.queries.<alias>` to
+ * `apps.queries` through `set_app_query`, WITHOUT a deploy. The deploy-free inner
+ * loop for named queries, parallel to `lotics app workflow set` for workflows.
+ *
+ * The declaration (`{ ast, params? }`) is read from the manifest — the same map
+ * `useQuery` codegen reads and `lotics app deploy` syncs authoritatively. The
+ * server validates it exactly as a deploy does (alias identifier, workspace-only
+ * tables, resolvable fields, declared params). Because `apps.queries` is
+ * manifest-authoritative, the next `lotics app deploy` overwrites this from the
+ * manifest — so keep the manifest as the source of truth; this only skips the
+ * build/upload round-trip while iterating. Errors (unbound alias, validation
+ * failure) print to stderr and exit non-zero.
+ */
+export declare function appQuerySet(client: LoticsClient, args: {
+    alias: string;
+}): Promise<void>;
 /**
  * `lotics app workflow pull` — rewrite every `src/workflows/<alias>.ts` from the
  * server without a full `lotics app pull` (no source archive, no npm install).
@@ -339,4 +363,5 @@ export declare function appUiLink(args: {
     projectDir?: string;
     component: string;
     remove?: boolean;
+    uiSrc?: string;
 }): void;

package/dist/app_commands.js

@@ -64,6 +64,17 @@ const WORKFLOW_GLOBALS_DIR = path.join(".lotics", "workflows");
  * with `/` separators — tsconfig globs are POSIX even on Windows.
  */
 const WORKFLOW_TSCONFIG_EXCLUDES = ["src/workflows", ".lotics/workflows"];
+/**
+ * The include glob that actually loads the generated `.lotics/*.d.ts` companions.
+ * A BARE `.lotics` entry loads NONE of them: TypeScript's include-glob walk skips
+ * dot-directories, so `useQuery` / `useWorkflow` / `useAgentRun` fall back to their
+ * untyped string overloads and every param / input / result silently becomes
+ * `unknown`. The current starter emits the glob (`starter_template.ts`); apps
+ * scaffolded before that fix shipped the bare form and need healing.
+ */
+const LOTICS_INCLUDE_GLOB = ".lotics/**/*";
+/** The bare `.lotics` forms an older starter emitted — all skipped by the glob walk. */
+const STALE_LOTICS_INCLUDES = new Set([".lotics", "./.lotics", ".lotics/"]);
 /**
  * The `async function __workflow(...)` wrapper a workflow body sits inside —
  * the SAME envelope the server compiles the body within at `set_app_workflow`
@@ -304,20 +315,27 @@ function writeAppMeta(projectDir, meta) {
     fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
 }
 /**
- * Add the workflow-body globs to the main `tsconfig.json`'s `exclude` if missing,
- * preserving every other exclude. The starter ships these excludes already, but
- * an app SCAFFOLDED before this CLI release (or one with a hand-written tsconfig)
- * doesn't — and pulling bodies into it would otherwise break its
- * `npm run typecheck`: the bodies pull the app's DOM lib (the server doesn't) and
- * the per-alias ambient globals collide on `trigger`. Idempotent — a second pull
- * is a no-op. Warns exactly what it added. A missing/unparseable tsconfig is a
- * non-fatal warn (the pull itself still succeeds); the author fixes the config.
+ * Heal a pre-existing app's `tsconfig.json` so its generated types load and its
+ * `npm run typecheck` stays honest. Idempotent, run on every pull / codegen /
+ * deploy. Two things the current starter ships but an app SCAFFOLDED before those
+ * releases (or with a hand-written tsconfig) can lack:
+ *
+ *  1. `include`: a bare `.lotics` is rewritten to the recursive `LOTICS_INCLUDE_GLOB`.
+ *     A bare dot-dir is skipped by TypeScript's include-glob walk, so the codegen'd
+ *     `.d.ts` never enter the program — every `useQuery`/`useWorkflow`/`useAgentRun`
+ *     param and result silently falls back to `unknown`.
+ *  2. `exclude`: the workflow-body globs — the bodies use the app's DOM lib (the
+ *     server doesn't) and the per-alias ambient globals collide on `trigger`,
+ *     poisoning typecheck. Checked separately by `lotics app workflow check`.
+ *
+ * A missing / unparseable tsconfig is a non-fatal warn (the caller still succeeds);
+ * the author fixes the config.
  */
-export function ensureWorkflowTsconfigExcludes(projectDir) {
+export function ensureAppTsconfig(projectDir) {
     const tsconfigPath = path.join(projectDir, "tsconfig.json");
     if (!fs.existsSync(tsconfigPath)) {
-        console.error(`⚠ No tsconfig.json at ${projectDir} — could not ensure ${WORKFLOW_TSCONFIG_EXCLUDES.join(", ")} are excluded. ` +
-            `Add them to your tsconfig's "exclude" so npm run typecheck skips the workflow bodies.`);
+        console.error(`⚠ No tsconfig.json at ${projectDir} — could not ensure "include" has "${LOTICS_INCLUDE_GLOB}" ` +
+            `(a bare .lotics loads none of the generated types) or "exclude" has ${WORKFLOW_TSCONFIG_EXCLUDES.join(", ")}.`);
         return;
     }
     let parsed;
@@ -326,30 +344,47 @@ export function ensureWorkflowTsconfigExcludes(projectDir) {
     }
     catch (err) {
         console.error(`⚠ Could not parse tsconfig.json (${err instanceof Error ? err.message : String(err)}) — ` +
-            `add ${WORKFLOW_TSCONFIG_EXCLUDES.join(", ")} to its "exclude" manually so npm run typecheck skips the workflow bodies.`);
+            `ensure "include" has "${LOTICS_INCLUDE_GLOB}" and "exclude" has ${WORKFLOW_TSCONFIG_EXCLUDES.join(", ")} manually.`);
         return;
     }
     if (!parsed || typeof parsed !== "object")
         return;
-    // `exclude` is a TOP-LEVEL tsconfig field — tsc ignores `compilerOptions.exclude`,
-    // so the workflow globs must land at the top level or `npm run typecheck` still
-    // loads the bodies + their colliding per-alias globals.
-    const current = Array.isArray(parsed.exclude) ? parsed.exclude : [];
-    const currentStrings = current.filter((e) => typeof e === "string");
-    const toAdd = WORKFLOW_TSCONFIG_EXCLUDES.filter((g) => !currentStrings.includes(g));
-    if (toAdd.length === 0)
+    const changes = [];
+    // 1. Heal a stale bare `.lotics` include so the generated `.d.ts` actually load
+    //    (a bare dot-dir is invisible to TypeScript's include-glob walk).
+    if (Array.isArray(parsed.include)) {
+        const inc = parsed.include.filter((e) => typeof e === "string");
+        if (inc.some((e) => STALE_LOTICS_INCLUDES.has(e))) {
+            const healed = inc.map((e) => (STALE_LOTICS_INCLUDES.has(e) ? LOTICS_INCLUDE_GLOB : e));
+            parsed.include = healed.filter((e, i) => healed.indexOf(e) === i); // dedupe if the glob was already present
+            changes.push(`rewrote a bare ".lotics" to "${LOTICS_INCLUDE_GLOB}" in "include" (a dot-dir loads zero generated types)`);
+        }
+    }
+    // 2. Ensure the workflow-body excludes. `exclude` is a TOP-LEVEL tsconfig field —
+    //    tsc ignores `compilerOptions.exclude`, so they must land at the top level.
+    const currentEx = Array.isArray(parsed.exclude)
+        ? parsed.exclude.filter((e) => typeof e === "string")
+        : [];
+    const toAdd = WORKFLOW_TSCONFIG_EXCLUDES.filter((g) => !currentEx.includes(g));
+    if (toAdd.length > 0) {
+        parsed.exclude = [...currentEx, ...toAdd];
+        changes.push(`added ${toAdd.join(", ")} to "exclude"`);
+    }
+    if (changes.length === 0)
         return;
-    parsed.exclude = [...currentStrings, ...toAdd];
     fs.writeFileSync(tsconfigPath, JSON.stringify(parsed, null, 2) + "\n");
-    console.error(`Patched tsconfig.json: added ${toAdd.join(", ")} to "exclude" so npm run typecheck skips the workflow bodies ` +
-        `(check them with: lotics app workflow check).`);
+    console.error(`Patched tsconfig.json: ${changes.join("; ")}.`);
 }
 /**
- * Write `.lotics/app_workflows.d.ts` + `.lotics/app_queries.d.ts` from the
- * manifest's `workflows` / `queries` maps. Called from `app create / pull /
- * dev / deploy` so the augmented `AppWorkflows` / `AppQueries` types stay in
- * sync with the manifest. The starter tsconfig.json includes `.lotics/` so
- * tsc + Vite pick the files up automatically.
+ * Write the three `.lotics/app_{workflows,queries,agents}.d.ts` companions from
+ * the manifest's maps, then heal the app's tsconfig so they actually load. Called
+ * from `app create / pull / dev / deploy / codegen`, so the augmented `AppWorkflows`
+ * / `AppQueries` / `AppAgents` types stay in sync with the manifest.
+ *
+ * The heal is at the write boundary on purpose: a `.d.ts` written but not loaded is
+ * useless (a bare `.lotics` include is skipped by TypeScript's include-glob walk and
+ * loads zero of them), so `ensureAppTsconfig` couples "wrote the types" with "the
+ * program can see them" — no caller can do one without the other.
  */
 function writeAppDts(projectDir, manifest) {
     const dotLotics = path.join(projectDir, ".lotics");
@@ -361,6 +396,7 @@ function writeAppDts(projectDir, manifest) {
     ];
     for (const [file, content] of written)
         fs.writeFileSync(file, content);
+    ensureAppTsconfig(projectDir);
     return written.map(([file]) => file);
 }
 /**
@@ -450,10 +486,6 @@ export async function appCodegen(args) {
     // it, so the local typecheck tracks the current workspace schema. Aliases
     // never pulled (no body file yet) are skipped — codegen isn't a pull.
     await refreshWorkflowGlobals(args.client, projectDir, meta.app_id, Object.keys(meta.workflows ?? {}));
-    // Keep the main tsconfig excluding the workflow-body globs (idempotent) so
-    // npm run typecheck never loads the bodies or their colliding per-alias globals.
-    if (Object.keys(meta.workflows ?? {}).length > 0)
-        ensureWorkflowTsconfigExcludes(projectDir);
 }
 /**
  * For each bound alias that already has a local body file, fetch its current
@@ -745,9 +777,6 @@ export async function appPull(client, args) {
         if (written.length > 0) {
             console.error(`Wrote ${written.length} workflow ${written.length === 1 ? "body" : "bodies"} to ${WORKFLOWS_DIR}/ (${written.join(", ")})`);
         }
-        // A pre-existing app's tsconfig may predate the workflow-body excludes; pulling
-        // bodies into it would break its npm run typecheck. Patch it idempotently.
-        ensureWorkflowTsconfigExcludes(targetPath);
     }
     console.error(`Installing npm dependencies...`);
     await runNpm(["install"], targetPath);
@@ -867,9 +896,13 @@ args) {
                 // `capabilities` block turns every capability OFF on the next deploy
                 // (fail-safe; the declaration is the grant).
                 capabilities: meta.capabilities ?? {},
-                // Workflow bindings are NOT a deploy concern — set_app_workflow /
-                // remove_app_workflow own apps.workflows. The manifest's `workflows`
-                // map is a pulled reflection used only for the .d.ts codegen above.
+                // Workflow BINDINGS are NOT a deploy concern — set_app_workflow /
+                // remove_app_workflow own apps.workflows. But the alias KEYS of the
+                // manifest's `workflows` map ARE sent (never the bindings): they record
+                // which aliases this bundle declares, so remove_app_workflow can refuse
+                // to unbind an alias the served version still calls. Drop an alias from
+                // the manifest + redeploy to lift that guard before removing its binding.
+                workflow_aliases: Object.keys(meta.workflows ?? {}),
             });
             writeAppMeta(projectDir, {
                 ...meta,
@@ -1169,6 +1202,37 @@ export async function appWorkflowSet(client, args) {
         console.error(`  result.data schema: ${JSON.stringify(result.outputs)}`);
     }
 }
+/**
+ * `lotics app query set <alias>` — push `package.json#lotics.queries.<alias>` to
+ * `apps.queries` through `set_app_query`, WITHOUT a deploy. The deploy-free inner
+ * loop for named queries, parallel to `lotics app workflow set` for workflows.
+ *
+ * The declaration (`{ ast, params? }`) is read from the manifest — the same map
+ * `useQuery` codegen reads and `lotics app deploy` syncs authoritatively. The
+ * server validates it exactly as a deploy does (alias identifier, workspace-only
+ * tables, resolvable fields, declared params). Because `apps.queries` is
+ * manifest-authoritative, the next `lotics app deploy` overwrites this from the
+ * manifest — so keep the manifest as the source of truth; this only skips the
+ * build/upload round-trip while iterating. Errors (unbound alias, validation
+ * failure) print to stderr and exit non-zero.
+ */
+export async function appQuerySet(client, args) {
+    const projectDir = process.cwd();
+    const meta = readAppMeta(projectDir);
+    const declaration = meta.queries?.[args.alias];
+    if (!declaration) {
+        console.error(`No query "${args.alias}" in package.json#lotics.queries. ` +
+            `Declare it there (alias → { ast, params? }) first.`);
+        process.exit(1);
+    }
+    const res = await client.setAppQuery(meta.app_id, args.alias, declaration);
+    if (res.error) {
+        console.error(`Failed to set query "${args.alias}": ${res.error}`);
+        process.exit(1);
+    }
+    console.error(`Set query "${args.alias}" on ${meta.app_id}. ` +
+        `(apps.queries is manifest-authoritative — the next 'lotics app deploy' re-syncs it.)`);
+}
 /**
  * `lotics app workflow pull` — rewrite every `src/workflows/<alias>.ts` from the
  * server without a full `lotics app pull` (no source archive, no npm install).
@@ -1187,9 +1251,10 @@ export async function appWorkflowPull(client) {
     const written = await writeWorkflowFiles(client, projectDir, meta.app_id, aliases);
     console.error(`Wrote ${written.length} workflow ${written.length === 1 ? "body" : "bodies"} to ${WORKFLOWS_DIR}/` +
         (written.length > 0 ? ` (${written.join(", ")})` : ""));
-    // A pre-existing app's tsconfig may predate the workflow-body excludes; pulling
-    // bodies into it would break its npm run typecheck. Patch it idempotently.
-    ensureWorkflowTsconfigExcludes(projectDir);
+    // This command writes workflow BODIES, not the `.d.ts` — so it doesn't reach
+    // `writeAppDts`'s heal. Heal here so the bodies land excluded and a stale
+    // `.lotics` include doesn't leave the app's other generated types dead.
+    ensureAppTsconfig(projectDir);
 }
 /**
  * `lotics app workflow check [alias]` — local TypeScript type check of the
@@ -1328,11 +1393,18 @@ export function appUiLink(args) {
     if (!fs.existsSync(viteConfigPath)) {
         throw new Error(`No vite.config.ts at ${projectDir}. Run inside a 'lotics app' project directory.`);
     }
-    const uiSrc = findUiSrcDir(projectDir);
-    if (!uiSrc) {
-        throw new Error("Cannot find packages/ui/src by walking up from this directory — `lotics ui link` " +
-            "requires a monorepo checkout. External apps consume @lotics/ui from npm; bump the " +
-            "package version and widen the app's dependency range instead.");
+    // Resolve packages/ui/src. An explicit --ui-src / LOTICS_UI_SRC wins — that's how
+    // an EXTERNAL app (one that consumes @lotics/ui from npm, with no monorepo above
+    // it) links the local kit; otherwise walk up for a monorepo checkout.
+    const explicit = args.uiSrc ?? process.env.LOTICS_UI_SRC;
+    const uiSrc = explicit ? path.resolve(explicit) : findUiSrcDir(projectDir);
+    if (!uiSrc || !fs.existsSync(uiSrc) || !fs.statSync(uiSrc).isDirectory()) {
+        throw new Error(explicit
+            ? `--ui-src / LOTICS_UI_SRC points at '${explicit}', which is not a directory. ` +
+                `Pass the absolute path to the monorepo's packages/ui/src.`
+            : "Cannot find packages/ui/src by walking up from this directory. For an EXTERNAL app " +
+                "(consuming @lotics/ui from npm), pass --ui-src=<abs path to packages/ui/src> or set " +
+                "LOTICS_UI_SRC; inside a monorepo checkout it is found automatically.");
     }
     // Validate the named component exists in src so a typo fails loud (the alias
     // itself stays package-wide — this is the advisory check the spec calls for).
@@ -1373,6 +1445,10 @@ export function appUiLink(args) {
     fs.writeFileSync(viteConfigPath, updated);
     console.error(`Dev-linked @lotics/ui → ${uiSrc} in ${viteConfigPath}.`);
     console.error("Restart `lotics app dev` and rm -rf node_modules/.vite to clear cached modules.");
+    // The app's tsc still resolves @lotics/ui from node_modules (the published .d.ts) —
+    // the kit `src` can't be typechecked in an app because it's RN-Web (uses
+    // react-native-web types the app resolves as base react-native). Typecheck the kit
+    // in packages/ui; the finalize publish restores the app's own typecheck.
     console.error("Finalize: PR the packages/ui change → publish → `lotics ui link <component> --remove` + bump the app's dep.");
 }
 /** Escape a string for literal use inside a RegExp. */

package/dist/app_commands.test.js

@@ -2,7 +2,7 @@ import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
 import fs from "node:fs";
 import path from "node:path";
 import { tmpdir } from "node:os";
-import { stampPulledManifest, undeclaredCapabilities, appDirName, defaultPullTarget, ensureWorkflowTsconfigExcludes, appCodegen, appUiLink, appVersions, appWorkflowSet, appWorkflowPull, appExecuteWorkflow, writeWorkflowFile, writeWorkflowGlobals, stripWorkflowHeader, FALLBACK_ENVELOPE_PREFIX, FALLBACK_ENVELOPE_SUFFIX, } from "./app_commands.js";
+import { stampPulledManifest, undeclaredCapabilities, appDirName, defaultPullTarget, ensureAppTsconfig, appCodegen, appUiLink, appVersions, appWorkflowSet, appWorkflowPull, appExecuteWorkflow, writeWorkflowFile, writeWorkflowGlobals, stripWorkflowHeader, FALLBACK_ENVELOPE_PREFIX, FALLBACK_ENVELOPE_SUFFIX, } from "./app_commands.js";
 /**
  * `appPull` reads workflows from the live App row (server response), NOT from
  * the manifest embedded in the extracted source archive. The frozen archive
@@ -208,8 +208,9 @@ describe("appCodegen (.d.ts-only path)", () => {
 });
 /**
  * `appUiLink` edits the app's vite.config.ts resolve.alias to dev-link
- * @lotics/ui at the monorepo's packages/ui/src. It fails loud outside a
- * monorepo, validates the component exists, and insert/remove is idempotent.
+ * @lotics/ui at packages/ui/src — auto-found in a monorepo checkout, or given
+ * explicitly via --ui-src for an external app. It validates the src + component,
+ * fails loud when neither resolves, and insert/remove is idempotent.
  */
 describe("appUiLink", () => {
     let root;
@@ -264,16 +265,30 @@ describe("appUiLink", () => {
     it("fails loud when the named component does not exist in packages/ui/src", () => {
         expect(() => appUiLink({ projectDir: appDir, component: "nonexistent" })).toThrow(/nonexistent/);
     });
-    it("fails loud when there is no monorepo packages/ui/src above the project", () => {
+    it("fails loud when there is no packages/ui/src and no --ui-src override", () => {
         const lonely = fs.mkdtempSync(path.join(tmpdir(), "lotics-lonely-app-"));
         fs.writeFileSync(path.join(lonely, "vite.config.ts"), "export default { resolve: { alias: [] } };");
         try {
-            expect(() => appUiLink({ projectDir: lonely, component: "card" })).toThrow(/monorepo checkout/);
+            expect(() => appUiLink({ projectDir: lonely, component: "card" })).toThrow(/--ui-src/);
         }
         finally {
             fs.rmSync(lonely, { recursive: true, force: true });
         }
     });
+    it("links an EXTERNAL app (no monorepo above) via an explicit --ui-src", () => {
+        const ext = fs.mkdtempSync(path.join(tmpdir(), "lotics-external-app-"));
+        fs.writeFileSync(path.join(ext, "vite.config.ts"), "export default { resolve: { alias: [] } };");
+        try {
+            appUiLink({ projectDir: ext, component: "card", uiSrc });
+            expect(fs.readFileSync(path.join(ext, "vite.config.ts"), "utf-8")).toContain(uiSrc);
+        }
+        finally {
+            fs.rmSync(ext, { recursive: true, force: true });
+        }
+    });
+    it("fails loud when --ui-src is not a directory", () => {
+        expect(() => appUiLink({ projectDir: appDir, component: "card", uiSrc: path.join(root, "nope") })).toThrow(/not a directory/);
+    });
 });
 /**
  * The workflow body files are how AA-1 Option B becomes "open a file → edit →
@@ -680,7 +695,7 @@ describe("defaultPullTarget", () => {
         expect(defaultPullTarget("app_X", "Sales Tracker")).toBe("Sales Tracker");
     });
 });
-describe("ensureWorkflowTsconfigExcludes", () => {
+describe("ensureAppTsconfig", () => {
     let dir;
     beforeEach(() => {
         dir = fs.mkdtempSync(path.join(tmpdir(), "lotics-tsconfig-"));
@@ -692,37 +707,60 @@ describe("ensureWorkflowTsconfigExcludes", () => {
     const read = () => JSON.parse(fs.readFileSync(tsconfigPath(), "utf-8"));
     it("adds both workflow globs to the TOP-LEVEL exclude", () => {
         fs.writeFileSync(tsconfigPath(), JSON.stringify({ compilerOptions: {}, exclude: ["node_modules"] }));
-        ensureWorkflowTsconfigExcludes(dir);
+        ensureAppTsconfig(dir);
         expect(read().exclude).toEqual(["node_modules", "src/workflows", ".lotics/workflows"]);
     });
     it("writes TOP-LEVEL even when a compilerOptions.exclude exists (tsc ignores the nested key)", () => {
         fs.writeFileSync(tsconfigPath(), JSON.stringify({ compilerOptions: { exclude: ["x"] } }));
-        ensureWorkflowTsconfigExcludes(dir);
+        ensureAppTsconfig(dir);
         const cfg = read();
         expect(cfg.exclude).toEqual(["src/workflows", ".lotics/workflows"]);
         expect(cfg.compilerOptions.exclude).toEqual(["x"]); // left untouched (and tsc-ignored)
     });
     it("preserves pre-existing top-level excludes", () => {
         fs.writeFileSync(tsconfigPath(), JSON.stringify({ exclude: ["node_modules", "dist"] }));
-        ensureWorkflowTsconfigExcludes(dir);
+        ensureAppTsconfig(dir);
         expect(read().exclude).toEqual(["node_modules", "dist", "src/workflows", ".lotics/workflows"]);
     });
     it("is idempotent — a second call writes nothing new", () => {
         fs.writeFileSync(tsconfigPath(), JSON.stringify({ exclude: ["node_modules"] }));
-        ensureWorkflowTsconfigExcludes(dir);
+        ensureAppTsconfig(dir);
         const afterFirst = fs.readFileSync(tsconfigPath(), "utf-8");
-        ensureWorkflowTsconfigExcludes(dir);
+        ensureAppTsconfig(dir);
         expect(fs.readFileSync(tsconfigPath(), "utf-8")).toBe(afterFirst);
     });
     it("warns + does not throw or create a file when there is no tsconfig", () => {
-        expect(() => ensureWorkflowTsconfigExcludes(dir)).not.toThrow();
+        expect(() => ensureAppTsconfig(dir)).not.toThrow();
         expect(fs.existsSync(tsconfigPath())).toBe(false);
     });
     it("warns + does not throw on an unparseable tsconfig (left as-is)", () => {
         fs.writeFileSync(tsconfigPath(), "{ not json,, }");
-        expect(() => ensureWorkflowTsconfigExcludes(dir)).not.toThrow();
+        expect(() => ensureAppTsconfig(dir)).not.toThrow();
         expect(fs.readFileSync(tsconfigPath(), "utf-8")).toBe("{ not json,, }");
     });
+    it("rewrites a bare .lotics include to the glob (a dot-dir loads zero generated types)", () => {
+        fs.writeFileSync(tsconfigPath(), JSON.stringify({ include: ["src", ".lotics"], exclude: ["node_modules"] }));
+        ensureAppTsconfig(dir);
+        expect(read().include).toEqual(["src", ".lotics/**/*"]);
+    });
+    it("leaves an already-correct .lotics/**/* include untouched (idempotent)", () => {
+        fs.writeFileSync(tsconfigPath(), JSON.stringify({ include: ["src", ".lotics/**/*"], exclude: ["node_modules", "src/workflows", ".lotics/workflows"] }));
+        const before = fs.readFileSync(tsconfigPath(), "utf-8");
+        ensureAppTsconfig(dir);
+        expect(fs.readFileSync(tsconfigPath(), "utf-8")).toBe(before);
+    });
+    it("dedupes when both a bare .lotics and the glob are present", () => {
+        fs.writeFileSync(tsconfigPath(), JSON.stringify({ include: [".lotics", ".lotics/**/*", "src"] }));
+        ensureAppTsconfig(dir);
+        expect(read().include).toEqual([".lotics/**/*", "src"]);
+    });
+    it("heals the include AND adds the excludes in a single write", () => {
+        fs.writeFileSync(tsconfigPath(), JSON.stringify({ include: ["src", ".lotics"], exclude: ["node_modules"] }));
+        ensureAppTsconfig(dir);
+        const cfg = read();
+        expect(cfg.include).toEqual(["src", ".lotics/**/*"]);
+        expect(cfg.exclude).toEqual(["node_modules", "src/workflows", ".lotics/workflows"]);
+    });
 });
 describe("appVersions", () => {
     let logLines;

package/dist/args.d.ts

@@ -23,6 +23,8 @@ export declare function parseArgs(argv: string[]): {
         apiKey?: string;
         workspace?: string;
         viewAs?: string;
+        /** `--ui-src <path>`: absolute packages/ui/src for `ui link` in an external app. */
+        uiSrc?: string;
         name?: string;
         timezone?: string;
         message?: string;

package/dist/args.js

@@ -19,6 +19,7 @@ export function parseArgs(argv) {
         apiKey: undefined,
         workspace: undefined,
         viewAs: undefined,
+        uiSrc: undefined,
         name: undefined,
         timezone: undefined,
         message: undefined,
@@ -60,6 +61,9 @@ export function parseArgs(argv) {
             case "--view-as":
                 flags.viewAs = argv[++i];
                 break;
+            case "--ui-src":
+                flags.uiSrc = argv[++i];
+                break;
             case "--name":
                 flags.name = argv[++i];
                 break;

package/dist/cli.js

@@ -13,7 +13,7 @@ net.setDefaultAutoSelectFamilyAttemptTimeout(2000);
 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, appUiLink, } from "./app_commands.js";
+import { appCreate, appPull, appDeploy, appDev, appSetSubdomain, appRename, appVersions, appCodegen, appExecuteWorkflow, appWorkflowSet, appWorkflowPull, appWorkflowCheck, appQuerySet, appUiLink, } from "./app_commands.js";
 import { parseArgs } from "./args.js";
 import { ingestJsonArgs } from "./inputs.js";
 import { runXlsxCommand } from "./xlsx.js";
@@ -90,11 +90,16 @@ COMMANDS
   lotics app workflow pull             Rewrite src/workflows/*.ts from the server
   lotics app workflow check [alias]    Typecheck src/workflows bodies locally (one
                                        isolated program per alias; the app's own tsc)
+  lotics app query set <alias>         Push package.json#lotics.queries.<alias> to
+                                       apps.queries via set_app_query (no deploy;
+                                       re-synced by the next deploy from the manifest)
   lotics app subdomain <new-subdomain> Rename the app's public <slug>.lotics.app address
   lotics app rename "<new name>"       Rename the app's display name (launcher title)
   lotics app dev [path]                Run the app locally with HMR (RPC forwarded to prod)
-  lotics ui link <component> [--remove] Dev-link @lotics/ui to the monorepo's
-                                       packages/ui/src for live HMR (monorepo only)
+  lotics ui link <component> [--ui-src <path>] [--remove]
+                                       Dev-link @lotics/ui to packages/ui/src (Vite alias
+                                       + tsc paths) for live HMR + typecheck. Monorepo apps
+                                       auto-find it; external apps pass --ui-src / LOTICS_UI_SRC
   lotics xlsx <subcommand> ...         Read/write/edit .xlsx files on your local filesystem
                                        (uses the bundled Lotics xlsx engine; prefer over
                                        npm xlsx/exceljs for round-trip fidelity)
@@ -493,17 +498,19 @@ async function main() {
         if (subcommand === "link") {
             const component = toolArgs;
             if (!component) {
-                console.error("Usage: lotics ui link <component> [--remove]");
-                console.error("Dev-links @lotics/ui to the monorepo's packages/ui/src for live HMR.");
+                console.error("Usage: lotics ui link <component> [--ui-src <abs path>] [--remove]");
+                console.error("Dev-links @lotics/ui to packages/ui/src (Vite + tsc) for live HMR + typecheck.");
+                console.error("Monorepo apps find packages/ui/src automatically; external apps pass --ui-src / LOTICS_UI_SRC.");
                 process.exit(1);
             }
             // `--remove` isn't a value-taking flag, so the parser leaves it as a
-            // trailing positional (the component took `toolArgs`).
-            appUiLink({ component, remove: restArgs.includes("--remove") });
+            // trailing positional (the component took `toolArgs`); `--ui-src` IS a
+            // value flag (flags.uiSrc), falling back to LOTICS_UI_SRC inside appUiLink.
+            appUiLink({ component, uiSrc: flags.uiSrc, remove: restArgs.includes("--remove") });
             return;
         }
         console.error(`Unknown ui subcommand: ${subcommand ?? "(none)"}`);
-        console.error("Usage: lotics ui link <component> [--remove]");
+        console.error("Usage: lotics ui link <component> [--ui-src <abs path>] [--remove]");
         process.exit(1);
     }
     // --- lotics app workflow check [alias] — local typecheck, no auth, no network ---
@@ -606,6 +613,7 @@ async function main() {
         console.error("  lotics app workflow set <alias>           Push the edited src/workflows/<alias>.ts body");
         console.error("  lotics app workflow pull                  Rewrite src/workflows/*.ts from the server");
         console.error("  lotics app workflow check [alias]         Typecheck src/workflows bodies locally");
+        console.error("  lotics app query set <alias>              Push lotics.queries.<alias> to apps.queries (no deploy)");
         console.error("  lotics app subdomain <new-subdomain> Rename the app's public <slug>.lotics.app address");
         console.error("  lotics app rename \"<new name>\"        Rename the app's display name (launcher title)");
         console.error("  lotics app dev [path]                Run the app locally with HMR + RPC forwarding");
@@ -826,6 +834,25 @@ async function main() {
             }
             workflowUsage();
         }
+        if (subcommand === "query") {
+            // `lotics app query set <alias>` — push package.json#lotics.queries.<alias>
+            // to apps.queries via set_app_query, no deploy. `toolArgs` is the verb;
+            // `restArgs` carries the alias.
+            const action = toolArgs;
+            if (action === "set") {
+                const alias = restArgs[0];
+                if (!alias) {
+                    console.error("Usage: lotics app query set <alias>");
+                    console.error("Pushes package.json#lotics.queries.<alias> to apps.queries via set_app_query (no deploy).");
+                    process.exit(1);
+                }
+                await appQuerySet(client, { alias });
+                return;
+            }
+            console.error("Usage:");
+            console.error("  lotics app query set <alias>   Push package.json#lotics.queries.<alias> to apps.queries (no deploy)");
+            process.exit(1);
+        }
         if (subcommand === "dev") {
             // First positional is an optional project path (defaults to cwd).
             // --port and --vite-port can override the wrapper / Vite ports.

package/dist/client.d.ts

@@ -277,6 +277,18 @@ export declare class LoticsClient {
         name?: string;
         description?: string;
     }): Promise<ToolExecuteResult>;
+    /**
+     * Bind (create or replace) an app query by alias via the `set_app_query` tool
+     * — the deploy-free authoring path for `apps.queries`, parallel to
+     * `setAppWorkflow`. `declaration` is the `{ ast, params? }` from
+     * `package.json#lotics.queries.<alias>`. The server validates it exactly as a
+     * deploy validates the manifest. Note: `apps.queries` is manifest-authoritative,
+     * so the next `lotics app deploy` overwrites this from the manifest.
+     */
+    setAppQuery(app_id: string, alias: string, declaration: {
+        ast: unknown;
+        params?: Record<string, unknown>;
+    }): Promise<ToolExecuteResult>;
     /**
      * Fetch one app workflow's faithful source + bound input/output schemas via
      * `get_app_workflow`. `source` is the JS-subset body re-rendered from the
@@ -375,6 +387,14 @@ export declare class LoticsClient {
         capabilities?: {
             comments?: boolean;
         };
+        /**
+         * The manifest's `lotics.workflows` KEYS — the workflow aliases the deployed
+         * code declares (NOT the bindings; `set_app_workflow` / `remove_app_workflow`
+         * own `apps.workflows`). Recorded on the new version so `remove_app_workflow`
+         * refuses to unbind an alias the served version still calls. Always sent
+         * (empty array when none declared).
+         */
+        workflow_aliases?: string[];
     }): Promise<{
         version_id: string;
         version_number: number;