@lotics/cli 0.76.1 → 0.86.0

package/dist/starter_template.d.ts

@@ -62,22 +62,3 @@ export declare function buildStarterTemplate(args: {
     /** @lotics/app-sdk version range, e.g. "^0.7.0". Defaults to the fallback pin. */
     sdk_version?: string;
 }): StarterFile[];
-/**
- * Files the PACKAGE scaffold (`lotics package new`) writes IN PLACE OF the shared
- * app starter's versions. The app starter demonstrates in-app routing over static
- * data — the wrong first screen for a package, which is a workspace-agnostic
- * blueprint installed into many workspaces. A package starter must instead exercise
- * the package machinery: the contract-derived `F`/`OPT` surface (from the generated
- * `.lotics/app_fields.ts`, which resolves each alias to THIS installation's concrete
- * id at module load), a named query, and a config knob. So an author begins from a
- * real screen that shows how a binding is read.
- *
- * `packageNew` overlays these onto the `buildStarterTemplate` output by path — the
- * same per-file swap it does for `package.json`. Kept here (next to the app starter)
- * so both stay editable + unit-testable in one place. Scenario-generic: entity
- * `item`, fields name/notes/status(open|done), query `items`, config knob `heading`
- * — matching `starterContract` in `package_commands.ts`.
- */
-export declare function buildPackageStarterOverrides(args: {
-    app_name: string;
-}): StarterFile[];

package/dist/starter_template.js

@@ -748,395 +748,6 @@ See https://lotics.ai/docs/app-sdk for the SDK reference.
         },
     ];
 }
-/**
- * Files the PACKAGE scaffold (`lotics package new`) writes IN PLACE OF the shared
- * app starter's versions. The app starter demonstrates in-app routing over static
- * data — the wrong first screen for a package, which is a workspace-agnostic
- * blueprint installed into many workspaces. A package starter must instead exercise
- * the package machinery: the contract-derived `F`/`OPT` surface (from the generated
- * `.lotics/app_fields.ts`, which resolves each alias to THIS installation's concrete
- * id at module load), a named query, and a config knob. So an author begins from a
- * real screen that shows how a binding is read.
- *
- * `packageNew` overlays these onto the `buildStarterTemplate` output by path — the
- * same per-file swap it does for `package.json`. Kept here (next to the app starter)
- * so both stay editable + unit-testable in one place. Scenario-generic: entity
- * `item`, fields name/notes/status(open|done), query `items`, config knob `heading`
- * — matching `starterContract` in `package_commands.ts`.
- */
-export function buildPackageStarterOverrides(args) {
-    const nameLit = JSON.stringify(args.app_name);
-    return [
-        {
-            // The package App.tsx imports `../.lotics/app_fields` — a DETERMINISTIC
-            // pure function of contract.json (generate_package_fields.ts) — so unlike
-            // the app starter's fully-ignored `.lotics`, it must be committed or the
-            // scaffold's own shipped CI (npm ci → typecheck/test/build on a clean
-            // clone) fails on the missing module. The sync-written `.d.ts` companions
-            // stay ignored: they need a live workspace and their absence only degrades
-            // hooks to untyped overloads, never breaks the build.
-            path: ".gitignore",
-            content: `node_modules
-dist
-*.tsbuildinfo
-.DS_Store
-.lotics/*
-!.lotics/app_fields.ts
-coverage
-`,
-        },
-        {
-            path: "src/App.tsx",
-            content: `import { useMemo, type ReactNode } from "react";
-import { ScrollView, View } from "react-native";
-import { useConfig, useQuery, readSelect, row } from "@lotics/app-sdk";
-import { AppRouter } from "@lotics/app-sdk/router";
-import { Text } from "@lotics/ui/text";
-import { Card } from "@lotics/ui/card";
-import { Button } from "@lotics/ui/button";
-import { OptionBadge } from "@lotics/ui/option_badge";
-import { Skeleton } from "@lotics/ui/skeleton";
-import { EmptyState } from "@lotics/ui/empty_state";
-import { Callout, CalloutTitle, CalloutText, CalloutActions } from "@lotics/ui/callout";
-import { F, OPT } from "../.lotics/app_fields";
-
-// This is a PACKAGE starter — a workspace-agnostic blueprint installed into many
-// workspaces, each binding the contract's aliases to DIFFERENT concrete ids. So a
-// screen never hardcodes a \`fld_…\`/\`opt_…\` id: it addresses a field by contract
-// alias through \`F\` and a select option through \`OPT\`, both from the generated
-// \`.lotics/app_fields.ts\` (which resolves every alias to THIS installation's id at
-// module load from the binding). The aliases come from contract.json — entity
-// \`item\`, fields name/notes/status, options open/done, query \`items\`, config knob
-// \`heading\`. Edit contract.json, then \`lotics package sync\` to regenerate F/OPT.
-
-interface Item {
-  id: string;
-  name: string;
-  notes: string;
-  status: ReturnType<typeof readSelect>[number] | null;
-  done: boolean;
-}
-
-// The \`items\` query is a bare from_entity, so a row is keyed by FIELD id: read a
-// cell as \`r[F.ITEM.<field>]\` and decode it with the SDK's pure readers (\`row.text\`,
-// \`readSelect\`). \`OPT.ITEM.status.done\` is this install's \`opt_…\` id, so comparing
-// the cell's stored option key to it marks a done row.
-function decode(r: Record<string, unknown>): Item {
-  const status = readSelect(r[F.ITEM.status])[0] ?? null;
-  return {
-    id: row.text(r.__source_record_id),
-    name: row.text(r[F.ITEM.name]),
-    notes: row.text(r[F.ITEM.notes]),
-    status,
-    done: status?.key === OPT.ITEM.status.done,
-  };
-}
-
-// Outer <View flex:1> claims the iframe height (index.html sets html/body/#root to
-// 100% + #root is a flex column); the list scrolls beneath the heading. Keep this
-// flex chain plain (not @lotics/ui/stack) so a fill-remaining-space child gets height.
-function Screen({ children }: { children: ReactNode }) {
-  return (
-    <View style={{ flex: 1 }}>
-      <ScrollView contentContainerStyle={{ padding: 24, alignItems: "center" }}>
-        <View style={{ maxWidth: 640, width: "100%", gap: 16 }}>{children}</View>
-      </ScrollView>
-    </View>
-  );
-}
-
-function ItemsScreen() {
-  // \`heading\` is a contract config knob — an installation overrides it and
-  // useConfig() renders the customized value; the literal here is only the fallback.
-  const { config } = useConfig({ heading: ${nameLit} });
-  const itemsQ = useQuery("items");
-  const items = useMemo(() => itemsQ.rows.map(decode), [itemsQ.rows]);
-  // First-load only: a skeleton while the very first fetch is in flight with no rows
-  // yet — never blank already-loaded rows to a spinner on a background refetch.
-  const firstLoad = itemsQ.loading && items.length === 0;
-
-  return (
-    <Screen>
-      <Text size="xxl" weight="semibold" level={1}>
-        {config.heading}
-      </Text>
-
-      {itemsQ.error ? (
-        <Callout tone="error">
-          <CalloutTitle>Couldn't load items</CalloutTitle>
-          <CalloutText>{itemsQ.error}</CalloutText>
-          <CalloutActions>
-            <Button title="Try again" onPress={() => itemsQ.refetch()} />
-          </CalloutActions>
-        </Callout>
-      ) : firstLoad ? (
-        <View style={{ gap: 10 }}>
-          {[0, 1, 2].map((i) => (
-            <Skeleton key={i} height={64} radius={12} />
-          ))}
-        </View>
-      ) : items.length > 0 ? (
-        <View style={{ gap: 10 }}>
-          {items.map((item) => (
-            <Card key={item.id}>
-              <View style={{ flexDirection: "row", alignItems: "center", gap: 12 }}>
-                <View style={{ flex: 1, gap: 2 }}>
-                  <Text weight="medium" color={item.done ? "muted" : undefined}>
-                    {item.name}
-                  </Text>
-                  {item.notes.length > 0 ? (
-                    <Text size="sm" color="muted" numberOfLines={1}>
-                      {item.notes}
-                    </Text>
-                  ) : null}
-                </View>
-                <OptionBadge value={item.status} />
-              </View>
-            </Card>
-          ))}
-        </View>
-      ) : (
-        <EmptyState
-          icon="list-checks"
-          message="No items yet"
-          hint="Rows in this package's table appear here."
-        />
-      )}
-    </Screen>
-  );
-}
-
-const routes = [{ path: "/", element: <ItemsScreen /> }];
-
-export default function App() {
-  return <AppRouter routes={routes} />;
-}
-`,
-        },
-        {
-            path: "src/App.test.tsx",
-            content: `import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
-import { render, screen, cleanup } from "@testing-library/react";
-import App from "./App";
-
-// Mock @lotics/app-sdk — the app's one external boundary (data + RPC + the package
-// binding). \`importOriginal\` keeps the PURE cell readers (\`row\`, \`readSelect\`) real,
-// so mock rows decode exactly like wire rows; only the hooks and getAppBinding are
-// stubbed. The binding ids below are what F.ITEM.* / OPT.ITEM.status.* resolve to;
-// the query rows are keyed by the SAME ids.
-const h = vi.hoisted(() => ({
-  state: {
-    rows: [] as Array<Record<string, unknown>>,
-    loading: false,
-    error: null as string | null,
-  },
-  binding: {
-    fields: { "item.name": "fld_name", "item.notes": "fld_notes", "item.status": "fld_status" },
-    options: { "item.status:open": "opt_open", "item.status:done": "opt_done" },
-    roles: {},
-  },
-}));
-
-vi.mock("@lotics/app-sdk", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("@lotics/app-sdk")>();
-  return {
-    ...actual,
-    getAppBinding: async () => h.binding,
-    useConfig: (defaults: Record<string, unknown>) => ({ config: defaults, loading: false }),
-    useQuery: () => ({
-      rows: h.state.rows,
-      loading: h.state.loading,
-      isValidating: false,
-      error: h.state.error,
-      refetch: () => {},
-    }),
-  };
-});
-
-const rowOf = (id: string, name: string, notes: string, statusKey: string) => ({
-  __source_record_id: id,
-  fld_name: name,
-  fld_notes: notes,
-  fld_status: [{ key: statusKey, label: statusKey === "opt_done" ? "Done" : "Open" }],
-});
-
-beforeEach(() => {
-  h.state.rows = [];
-  h.state.loading = false;
-  h.state.error = null;
-});
-
-// vitest globals are off, so @testing-library/react's automatic afterEach cleanup is
-// never registered — clean up explicitly or renders accumulate across tests and a
-// second render's duplicate matches fail getByText.
-afterEach(cleanup);
-
-describe("App", () => {
-  test("renders the heading and the loaded items with status badges", () => {
-    h.state.rows = [
-      rowOf("1", "First item", "with a note", "opt_open"),
-      rowOf("2", "Second item", "", "opt_done"),
-    ];
-    render(<App />);
-
-    expect(screen.getByText(${nameLit})).toBeTruthy();
-    expect(screen.getByText("First item")).toBeTruthy();
-    expect(screen.getByText("Second item")).toBeTruthy();
-    expect(screen.getByText("with a note")).toBeTruthy();
-    expect(screen.getByText("Open")).toBeTruthy();
-    expect(screen.getByText("Done")).toBeTruthy();
-    expect(screen.queryByText("No items yet")).toBeNull();
-  });
-
-  test("shows the empty state when there are no items", () => {
-    render(<App />);
-    expect(screen.getByText("No items yet")).toBeTruthy();
-  });
-
-  test("does not flash the list or empty state on first load", () => {
-    h.state.loading = true;
-    render(<App />);
-    expect(screen.queryByText("No items yet")).toBeNull();
-  });
-
-  test("surfaces a load error loudly", () => {
-    h.state.error = "Network unreachable";
-    render(<App />);
-    expect(screen.getByText("Couldn't load items")).toBeTruthy();
-    expect(screen.getByText("Network unreachable")).toBeTruthy();
-  });
-});
-`,
-        },
-        {
-            path: "README.md",
-            content: `# ${escapeHtml(args.app_name)}
-
-A Lotics **app package** — a versioned, installable blueprint (a \`contract.json\`
-data model + app source) that installs into many workspaces. Authored locally,
-published and run through the \`lotics package\` CLI. See \`docs/app_packages.md\`.
-
-## Dev loop
-
-\`\`\`bash
-lotics workspace create "${escapeHtml(args.app_name)} dev" --dev   # a throwaway dev workspace
-lotics package dev --workspace <dev_ws>                # sync into it + run the dev server
-# edit contract.json  → re-run \`lotics package sync\` to migrate + re-materialize
-# edit src/*          → hot reload
-\`\`\`
-
-\`sync\` / \`dev\` regenerate \`.lotics/app_fields.ts\` (the runtime \`F\` / \`OPT\` / \`ROLE\`
-surface) from \`contract.json\`, plus the typed \`.lotics/app_{queries,workflows,agents}.d.ts\`
-companions from the live installation — so \`useQuery\` / \`useWorkflow\` stay typed in the
-dev loop.
-
-## Quality
-
-\`\`\`bash
-npm run typecheck
-npm run lint
-npm test
-\`\`\`
-
-## Publish
-
-\`\`\`bash
-lotics package publish -m "v1"        # build + publish an immutable version
-lotics package install <package_id>   # install into any workspace
-\`\`\`
-
-## The app screen
-
-\`src/App.tsx\` reads the contract BY ALIAS through \`F\` / \`OPT\` (from the generated
-\`.lotics/app_fields.ts\`) — never a raw \`fld_…\` / \`opt_…\` id, since every install binds
-different concrete ids. It lists the \`items\` query and renders the \`heading\` config knob.
-\`@lotics/ui\` primitives render via react-native-web (aliased in \`vite.config.ts\`).
-
-## Contract reference
-
-\`contract.json\` is the package's alias-keyed data model
-(schema: \`@lotics/shared/schemas/app_packages\`). Every cross-reference is by **alias**;
-the materializer resolves alias → this workspace's concrete id at install.
-
-### Aliases
-
-- Entity / field / option / role / template / config aliases are lowercase slugs
-  matching \`^[a-z][a-z0-9_]*$\`. A field's fully-qualified key is \`<entity>.<field>\`
-  (e.g. \`item.status\`); a select option's is \`<entity>.<field>:<option>\`
-  (e.g. \`item.status:done\`).
-- Query / workflow / agent aliases are runtime lookup keys (1–200 chars) — the app
-  source invokes them verbatim (\`useQuery("items")\`), so renaming one severs the call.
-
-### Entities & fields
-
-\`\`\`jsonc
-{ "alias": "item", "label": "Item", "fields": [
-  { "alias": "name",   "label": "Name",   "type": "text", "required": true },
-  { "alias": "status", "label": "Status", "type": "select",
-    "options": [ { "alias": "open", "label": "Open", "color": "blue" },
-                 { "alias": "done", "label": "Done", "color": "green" } ] } ] }
-\`\`\`
-
-Field \`type\`: \`text\`, \`number\`, \`date\`, \`boolean\`, \`select\` (+ \`options\`),
-\`select_member\`, \`select_record_link\` (\`target_entity\` = an entity alias), \`files\`,
-\`formula\` (expression references same-entity fields as \`{alias}\`), \`rollup\`, \`lookup\`,
-\`autonumber\`. \`required\` is advisory (app / workflow-layer UX only — the table model
-has no required constraint). Select \`options\` are \`{ alias, label, color }\`.
-
-### Queries
-
-Alias-form AST — the same node kinds as the runtime query engine, except a
-\`from_table\` node carries \`from_entity\` (an entity alias) instead of a \`table_id\`:
-
-\`\`\`jsonc
-{ "alias": "items", "ast": {
-  "kind": "from_table", "from_entity": "item",
-  "sort": [ { "field_key": "name", "order": "asc" } ] } }
-\`\`\`
-
-### Workflows
-
-The sole app-side mutation path. Each workflow has a \`trigger\`, typed \`inputs\` /
-\`outputs\`, and a JS-subset \`body\`.
-
-- Trigger — app-invoked or table-lifecycle:
-  - \`{ "type": "app" }\` — called by alias from the app (\`useWorkflow("<alias>")\`).
-  - \`{ "type": "entity_lifecycle", "entity": "<entity>", "event": "<event>" }\` — fires
-    on the bound table. \`event\` ∈ \`before_create\`, \`after_create\`, \`before_update\`,
-    \`after_update\`, \`before_delete\`, \`after_delete\`.
-- Typed \`inputs\` (\`text\` / \`number\` / \`date\` / \`member\` / \`select\` / \`record_link\`,
-  plus \`object\` / \`array\`):
-  - \`record_link\` — its \`table_id\` names an **entity alias**.
-  - \`member\` — its \`group\` names a **role alias**.
-  - \`select\` — an option \`value\` in \`entity.field:option\` form binds to that option's
-    id (a plain value is a literal, left as-is).
-- Body **sentinel tokens** — a body addresses package objects by reserved tokens the
-  materializer rewrites to concrete ids at install. Always inside a **string literal**:
-  - \`@@entity:<entity>@@\`
-  - \`@@field:<entity>.<field>@@\`
-  - \`@@option:<entity>.<field>:<option>@@\`
-  - \`@@role:<role>@@\`
-  - \`@@template:<template>@@\`
-
-### Config knobs
-
-Typed customization knobs the app reads via \`useConfig()\`. Each has an \`alias\`,
-\`label\`, \`type\`, and \`default\`:
-
-- \`text\` → a string default; \`boolean\` → a boolean; \`number\` → a number;
-  \`color\` → a palette color token; \`select\` → \`options: [{ value, label }]\` with the
-  \`default\` being one of those \`value\`s.
-
-\`\`\`jsonc
-{ "alias": "heading", "label": "List heading", "type": "text", "default": "Items" }
-\`\`\`
-
-Publish validates the whole contract (alias uniqueness, every cross-reference
-resolves, sentinel tokens name declared objects) before storing the version.
-`,
-        },
-    ];
-}
 function escapeHtml(s) {
     return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }

package/dist/starter_template.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "vitest";
-import { buildStarterTemplate, buildPackageStarterOverrides, STARTER_FALLBACK_SDK_VERSION, STARTER_FALLBACK_UI_VERSION, STARTER_REACT_NATIVE_VERSION, } from "./starter_template.js";
+import { buildStarterTemplate, STARTER_FALLBACK_SDK_VERSION, STARTER_FALLBACK_UI_VERSION, STARTER_REACT_NATIVE_VERSION, } from "./starter_template.js";
 function fileNamed(files, path) {
     const f = files.find((f) => f.path === path);
     if (!f)
@@ -113,71 +113,3 @@ describe("buildStarterTemplate", () => {
         expect(files.find((f) => f.path === "tsconfig.workflows.json")).toBeUndefined();
     });
 });
-describe("buildPackageStarterOverrides", () => {
-    const overrides = buildPackageStarterOverrides({ app_name: "Widget Tracker" });
-    test("overrides exactly the three files packageNew swaps by path", () => {
-        // These paths must line up with buildStarterTemplate's, or the swap is a no-op
-        // (a stray file, or the app version shipped instead of the package one).
-        expect(overrides.map((f) => f.path).sort()).toEqual([".gitignore", "README.md", "src/App.test.tsx", "src/App.tsx"]);
-        const starterPaths = new Set(buildStarterTemplate({ app_name: "Widget Tracker", app_id: "", workspace_id: "" }).map((f) => f.path));
-        for (const f of overrides)
-            expect(starterPaths.has(f.path)).toBe(true);
-    });
-    test("App.tsx exercises the binding: F/OPT, the items query, and the heading config knob", () => {
-        // The whole point of the package starter — a screen that reads the contract by
-        // ALIAS through the generated app_fields, not a static hardcoded demo.
-        const app = fileNamed(overrides, "src/App.tsx");
-        expect(app).toContain('from "../.lotics/app_fields"');
-        expect(app).toContain("F.ITEM.name");
-        expect(app).toContain("OPT.ITEM.status.done");
-        expect(app).toContain('useQuery("items")');
-        expect(app).toContain("useConfig({ heading:");
-        expect(app).toContain("config.heading");
-        // read via the SDK cell readers + rendered through the kit's OptionBadge
-        expect(app).toContain("readSelect(");
-        expect(app).toContain("OptionBadge");
-        // first-load skeleton gated on loading && no rows; a designed empty state
-        expect(app).toContain("itemsQ.loading && items.length === 0");
-        expect(app).toContain("EmptyState");
-        // routed via AppRouter (the shell is kept)
-        expect(app).toContain("<AppRouter routes={routes}");
-        // the config default is the package name
-        expect(app).toContain('useConfig({ heading: "Widget Tracker" })');
-    });
-    test("App.test.tsx registers afterEach(cleanup) and mocks the SDK boundary incl. getAppBinding", () => {
-        // Finding: vitest globals are off, so @testing-library's auto-cleanup never runs.
-        // A multi-render test needs an explicit afterEach(cleanup) or renders accumulate
-        // and a second getByText fails on duplicate matches.
-        const testFile = fileNamed(overrides, "src/App.test.tsx");
-        expect(testFile).toContain("afterEach(cleanup)");
-        expect(testFile).toContain('vi.mock("@lotics/app-sdk"');
-        expect(testFile).toContain("getAppBinding");
-        // the pure readers stay real (importOriginal), so mock rows decode like wire rows
-        expect(testFile).toContain("importOriginal");
-        // asserts outcomes, not calls
-        expect(testFile).toContain("No items yet");
-    });
-    test("README carries a contract reference grounded in the schema", () => {
-        const readme = fileNamed(overrides, "README.md");
-        expect(readme).toContain("## Contract reference");
-        // the two workflow trigger forms
-        expect(readme).toContain('{ "type": "app" }');
-        expect(readme).toContain('"type": "entity_lifecycle"');
-        // the six lifecycle events
-        expect(readme).toContain("before_create");
-        expect(readme).toContain("after_delete");
-        // typed-input alias rules
-        expect(readme).toContain("`table_id` names an **entity alias**");
-        expect(readme).toContain("entity.field:option");
-        // the sentinel-token grammar
-        expect(readme).toContain("@@entity:<entity>@@");
-        expect(readme).toContain("@@field:<entity>.<field>@@");
-        expect(readme).toContain("@@option:<entity>.<field>:<option>@@");
-        expect(readme).toContain("@@role:<role>@@");
-        expect(readme).toContain("@@template:<template>@@");
-        // config knob kinds, and query alias-form AST
-        expect(readme).toContain("from_entity");
-        // fences are single-escaped backticks, not doubled — no stray backslash before ```
-        expect(readme).not.toContain("\\```");
-    });
-});

package/package.json

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