@lotics/cli 0.57.0 → 0.62.0

package/README.md

@@ -149,6 +149,43 @@ Edits mutate the file in place via an atomic temp-file + rename. Unknown OOXML c
 
 Run `lotics xlsx` or `lotics docx` with no subcommand for the full list.
 
+## Custom-code apps
+
+```bash
+# Scaffold / pull / deploy a Vite+React+TS app project
+lotics app create "Sales Desk"            # scaffold + deploy v1
+lotics app pull app_...                    # bootstrap an existing app locally
+lotics app deploy -m "Add quote drawer"    # build + upload a new version
+
+# Regenerate .lotics/* WITHOUT a deploy: the .d.ts type companions (always) +
+# the runtime app_fields.ts (when authenticated) — F/OPT maps that address
+# fields + select options by stable display-name aliases instead of opaque ids.
+lotics app codegen                         # import { F, OPT } from "../.lotics/app_fields"
+
+# Execute a bound app workflow end-to-end (inputs: inline / @file / stdin)
+lotics app workflow run issueInvoice '{"record_id":"rec_..."}'
+cat inputs.json | lotics app workflow run importRates   # bulk inputs bypass ARG_MAX
+# Honest post-run harvest: created records + a paste-ready cleanup plan + the
+# caveat (external/notification calls can't be auto-undone; sub-workflows may run).
+lotics app workflow run issueInvoice '{...}' --print-created
+lotics app workflow run issueInvoice '{...}' --cleanup   # also deletes created records (NOT a rollback)
+
+# Edit workflow bodies as files. `app pull` writes src/workflows/<alias>.ts (the
+# faithful server source, wrapped + referencing its .lotics/workflows/<alias>.globals.d.ts);
+# edit the body, then push it back through set_app_workflow — the server verifies it
+# (deploy still never authors workflows). Bodies are locally typecheckable with
+# `app workflow check` (one isolated program per alias = the same verdict as `set`):
+lotics app workflow pull                    # rewrite src/workflows/*.ts + globals from the server
+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
+lotics ui link card --remove               # finalize: PR + publish, then drop the alias
+```
+
+`app codegen` reads `package.json#lotics.queries` to decide which tables to put in `app_fields.ts`; widen the set with `package.json#lotics.codegen.tables` (an array of `tbl_…` ids) for tables the app only writes via workflows.
+
 ## SDK
 
 ```typescript

package/dist/app_commands.d.ts

@@ -42,6 +42,74 @@ export type AppAgentDeclaration = {
     inputs?: Record<string, unknown>;
     outputs?: Record<string, unknown>;
 };
+/**
+ * The `async function __workflow(...)` wrapper a workflow body sits inside —
+ * the SAME envelope the server compiles the body within at `set_app_workflow`
+ * verify time (GAP-59). Carried so a body that uses top-level `await` and ends
+ * with `return({...})` typechecks locally exactly as the server checks it. The
+ * server returns the canonical strings (`getAppWorkflowDts`); these are the
+ * offline fallback when the dts fetch fails so the file is still wrapped — a
+ * test pins them equal to the server's, so they can't drift.
+ */
+export declare const FALLBACK_ENVELOPE_PREFIX = "async function __workflow(): Promise<__WorkflowReturn | void> {\n";
+export declare const FALLBACK_ENVELOPE_SUFFIX = "\n}";
+export interface WorkflowEnvelope {
+    prefix: string;
+    suffix: string;
+}
+/**
+ * Write `.lotics/workflows/<alias>.globals.d.ts` = the server-generated ambient
+ * declarations the body typechecks against. Idempotent. Returns the path.
+ */
+export declare function writeWorkflowGlobals(projectDir: string, alias: string, dts: string): string;
+/**
+ * Write `src/workflows/<alias>.ts` = header (triple-slash reference + comments)
+ * + the body wrapped in the `__workflow` envelope. Idempotent (a re-pull
+ * overwrites with the current server body). The raw `source` round-trips on
+ * `set` (the header + wrapper are stripped). Exported for direct unit testing —
+ * the surrounding pull shells out to `tar`/`npm`.
+ */
+export declare function writeWorkflowFile(projectDir: string, alias: string, source: string, envelope?: WorkflowEnvelope): string;
+/**
+ * Strip the CLI bookkeeping back off a workflow body before pushing it: the
+ * triple-slash reference + the `//` header comments + the `export {};` marker +
+ * blank lines, then the `__workflow` envelope (the opening
+ * `async function __workflow(...) {` line and the matching trailing `}`). `set`
+ * sends ONLY the JS-subset body the author edited — the server stays the single
+ * verifier.
+ *
+ * The strip is anchored on the GENERATED bookkeeping, never on "the file happens
+ * to start with comments": the leading comment/marker/blank block is only peeled
+ * when it is immediately followed by the `__workflow` wrapper opener (the exact
+ * shape `writeWorkflowFile` produces). A hand-written, wrapper-LESS body whose
+ * first lines are comments therefore round-trips unchanged — its comments are
+ * real source, not bookkeeping, and must not be silently eaten.
+ */
+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.
+ */
+export declare function ensureWorkflowTsconfigExcludes(projectDir: string): void;
+/**
+ * `lotics app codegen [path]` — regenerate every `.lotics/` artifact from the
+ * manifest + workspace schema, WITHOUT a deploy. The `.d.ts` companions are
+ * always written (synchronous, no network). When a `client` is available, the
+ * runtime `app_fields.ts` is also regenerated from the live schema of the tables
+ * the app's queries reference (+ the allowlist); a network failure is non-fatal
+ * (warn, keep the last-generated file) — so codegen still does useful work
+ * offline, mirroring `app create`'s tolerance of an offline npm registry.
+ */
+export declare function appCodegen(args: {
+    projectDir?: string;
+    client?: LoticsClient;
+}): Promise<void>;
 /**
  * Stamp the post-extraction manifest with server-authoritative meta. Called
  * by `appPull` after the source archive lands on disk.
@@ -106,8 +174,10 @@ export declare function appCreate(client: LoticsClient, args: {
  *   4. Regenerate `.lotics/app_workflows.d.ts` from the live workflows so
  *      `useWorkflow<"alias">` is typed at pull time.
  *   5. Run `npm install`.
- *   6. (TODO) Generate `.lotics/types.ts` with workspace tables augmentation —
- *      pending a `client.getWorkspaceSchema()` endpoint.
+ *
+ * Runtime field/option id aliases (`.lotics/app_fields.ts`) are generated on
+ * demand by `lotics app codegen`, which fetches the workspace schema — pull
+ * leaves it to that command so a schema fetch never blocks the bootstrap.
  */
 /**
  * `lotics app subdomain <new>` — rename the current app's public address.
@@ -126,6 +196,14 @@ export declare function appSetSubdomain(client: LoticsClient, args: {
 export declare function appRename(client: LoticsClient, args: {
     name: string;
 }): Promise<void>;
+/**
+ * Where `lotics app pull <app_id>` lands when given NO explicit path. If the cwd
+ * IS already this app's own project (its manifest `app_id` matches), refresh in
+ * place — the documented `cd <app> && lotics app pull` flow. Otherwise a fresh
+ * clone goes to an `appDirName(name)` subdir. Without this, pulling from inside
+ * the app dropped a stray `./<name>/` subdir instead of refreshing the project.
+ */
+export declare function defaultPullTarget(appId: string, appName: string): string;
 export declare function appPull(client: LoticsClient, args: {
     app_id: string;
     targetPath?: string;
@@ -166,3 +244,88 @@ export declare function appDev(client: LoticsClient, args: {
     port?: number;
     vitePort?: number;
 }): Promise<void>;
+/**
+ * `lotics app workflow run <alias> '<json>'` — execute a bound app workflow
+ * end-to-end against the live workspace. `app_id` comes from the local manifest
+ * (like deploy/dev), the alias must be bound server-side via `set_app_workflow`.
+ *
+ * The full `{ status, message, data, files, side_effects }` JSON prints to
+ * stdout (pipeable / assertable); a one-line human summary goes to stderr. A
+ * `status: "error"` envelope exits non-zero so a script can branch on it — the
+ * transport already normalizes a gateway/timeout failure into the same
+ * `{ status: "error" }` shape, so a failed run is never a thrown HTML body.
+ *
+ * `--print-created` (alias `--report-effects`) renders the honest post-run
+ * harvest (GAP-58): created records grouped by table, a paste-ready
+ * `delete_records` per table, and the mandatory caveat about what cannot be
+ * auto-undone. `--cleanup` (DEFAULT OFF) additionally runs the deletes for the
+ * harvested records ONLY — never files, external integrations, or notifications.
+ * Neither is a rollback; a rollback is structurally impossible here.
+ */
+export declare function appExecuteWorkflow(client: LoticsClient, args: {
+    alias: string;
+    inputs: Record<string, unknown>;
+    printCreated?: boolean;
+    cleanup?: boolean;
+}): Promise<void>;
+/**
+ * `lotics app workflow set <alias>` — push the edited `src/workflows/<alias>.ts`
+ * body to the server through `set_app_workflow` (the single author of
+ * `apps.workflows`). The body is read from disk (header stripped); the typed
+ * `inputs`/`outputs` schemas come from `package.json#lotics.workflows.<alias>`,
+ * so a pulled-then-edited app keeps its declared contract. The server re-verifies
+ * the body and echoes the bound `outputs` (declared, else DERIVED from
+ * `return({ data })`) — the same guarantee as calling `set_app_workflow` by hand,
+ * with no fetch/reconstruct/escape. Errors (missing file, unbound alias, verify
+ * failure) print to stderr and exit non-zero.
+ *
+ * This is a CLI convenience over the existing tool — `lotics app deploy` is still
+ * NOT an author of workflows; the single-author invariant holds.
+ */
+export declare function appWorkflowSet(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).
+ * The alias set + bodies come from the live App row (the same source `app pull`
+ * uses); a legacy alias with no rendered source warns and is skipped.
+ */
+export declare function appWorkflowPull(client: LoticsClient): Promise<void>;
+/**
+ * `lotics app workflow check [alias]` — local TypeScript type check of the
+ * editable workflow bodies, ONE isolated program per bound alias (GAP-59 fix).
+ *
+ * The dedicated `tsconfig.workflows.json` that GAP-59 first shipped compiled ALL
+ * aliases' bodies + per-alias ambient globals into a SINGLE program, so the N
+ * `declare const trigger: AppWorkflowTrigger` declarations (each with THAT
+ * alias's `app_workflow.inputs`) collided — tsc resolved one and every body
+ * checked `trigger.app_workflow.inputs` against the wrong alias. This command
+ * replaces that config: it builds a separate `ts.Program` per alias from exactly
+ * that alias's `{body, globals}` pair (mirroring the SERVER, which verifies one
+ * body at a time), so the ambient `trigger` is unambiguous and the verdict
+ * matches set-time. All aliases run in ONE process.
+ *
+ * `[alias]` checks one alias; omitted, checks every bound alias that has a body
+ * file. Exits non-zero if ANY alias has a type error. A bound alias with no body
+ * file yet (never pulled) is warned and skipped; an alias missing its globals
+ * file is an error (the body can't be checked without its types).
+ */
+export declare function appWorkflowCheck(args: {
+    alias?: string;
+}): Promise<void>;
+/**
+ * `lotics ui link <component> [--remove]` — add or remove the `@lotics/ui`
+ * dev-link alias in the app's `vite.config.ts`, so edits to the monorepo's
+ * `packages/ui/src` go live (HMR) without a publish round-trip. `component` is
+ * advisory only — the alias is package-wide (one subpath regex covers every
+ * import); it's validated to exist under `packages/ui/src` so a typo fails here.
+ *
+ * Idempotent: linking twice is a no-op; `--remove` strips the one inserted
+ * entry and leaves the rest of `resolve.alias` intact.
+ */
+export declare function appUiLink(args: {
+    projectDir?: string;
+    component: string;
+    remove?: boolean;
+}): void;