@lotics/cli 0.88.0 → 0.89.1

package/dist/app_commands.d.ts

@@ -1,401 +0,0 @@
-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, … } } }`
- *
- * When `inputs` is declared, the CLI codegen emits a typed `AppWorkflows[alias]`
- * entry and the server validates payloads against it at execute time. When
- * `outputs` is declared, codegen emits a typed `AppWorkflowResults[alias]` so the
- * app reads a typed `result.data`. Omit either for workflows that take no typed
- * inputs / return no structured data.
- */
-export type AppWorkflowDeclaration = {
-    workflow_id: string;
-    inputs?: Record<string, unknown>;
-    outputs?: Record<string, unknown>;
-};
-/**
- * Manifest declaration for one named query:
- *   `"alias": { ast, params?: { key: { type, … } } }`
- *
- * `ast` is a fixed query AST template; `params` declares the typed value
- * holes (`{{params.<name>}}`) the app fills via `useQuery(alias, params)`.
- * Custom-code apps never send a raw AST — this declaration is the contract.
- */
-export type AppQueryDeclaration = {
-    ast: unknown;
-    params?: Record<string, unknown>;
-};
-/**
- * Manifest declaration for one streaming agent:
- *   `"alias": { instructions, tool_names, model_id, inputs?, outputs? }`
- *
- * A read-only reflection of the live App row (`apps.agents`, owned by
- * `set_app_agent` / `remove_app_agent`), refreshed by `lotics app pull` and used only to codegen
- * `useAgentRun` typings. `inputs`/`outputs` drive the typed call site; the rest
- * is carried for fidelity.
- */
-export type AppAgentDeclaration = {
-    instructions?: string;
-    tool_names?: string[];
-    model_id?: string;
-    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;
-/** Run `tar` and resolve when it exits cleanly. Throws with stderr on failure. */
-export declare function runTar(args: string[], cwd: string): Promise<void>;
-/** Run `npm` (run/install/etc.) inheriting stdio so the user sees progress. */
-export declare function runNpm(args: string[], cwd: string): Promise<void>;
-/**
- * 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 ensureAppTsconfig(projectDir: string): void;
-/**
- * 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.
- */
-export declare function writeAppDts(projectDir: string, manifest: {
-    workflows?: Record<string, AppWorkflowDeclaration>;
-    queries?: Record<string, AppQueryDeclaration>;
-    agents?: Record<string, AppAgentDeclaration>;
-}): string[];
-/**
- * `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 — **branched on whether the app is
- * a package installation** (`getApp().package_id` set): a **linked/published**
- * app emits the BINDING-resolved form (`F`/`OPT`/`ROLE` resolved from the live
- * binding at module load via `getAppBinding()`, so the source stays portable
- * across every install), a **bespoke** app emits the baked form (this
- * workspace's concrete `fld_…`/`opt_…` ids, from the live schema of the tables
- * its 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.
- *
- * Crucially, `workflows` is sourced from `app.workflows` (live DB state),
- * NOT from whatever the extracted archive's package.json contains. The
- * archive's embedded `lotics.workflows` is a frozen snapshot from deploy
- * time and would silently overwrite any agent-authored bindings made via
- * `set_app_workflow` since the last deploy. Exported for direct unit
- * testing — the rest of `appPull` involves shelling out to `tar`/`npm`,
- * which doesn't reward integration coverage.
- */
-export declare function stampPulledManifest(projectDir: string, args: {
-    app_id: string;
-    workspace_id: string;
-    current_version_id: string;
-    version_number: number;
-    workflows: Record<string, AppWorkflowDeclaration>;
-    queries: Record<string, AppQueryDeclaration>;
-    agents: Record<string, AppAgentDeclaration>;
-}): void;
-/**
- * A filesystem-safe SINGLE directory segment from an app's free-form display
- * name, for the default create/pull target. App names may contain "/" (and
- * other path-hostile characters); used verbatim as a directory, a name like
- * "Nhập/Xuất Cont" splits into NESTED folders ("Nhập" → "Xuất Cont") — and a
- * deploy then packages that nested copy into the source archive, so each later
- * pull re-extracts and compounds it. Neutralize path separators + reserved
- * characters to one segment, keeping spaces and unicode so the folder stays
- * recognizable. An explicit `targetPath` still overrides this entirely.
- */
-export declare function appDirName(name: string): string;
-/**
- * `lotics app create <name> [path]`
- *
- * Creates the app server-side, scaffolds a Vite+React+TS project locally
- * from the embedded starter template, runs `npm install` + `npm run build`,
- * then deploys the result as v1. After this returns, `lotics app deploy`
- * works end-to-end on the same directory.
- *
- * Why scaffold + deploy rather than pull-from-server-starter: the deploy
- * pipeline requires a built dist tree, and v1 doesn't run builds server-side.
- * Doing the build locally on first create keeps the platform infrastructure
- * minimal — the starter template is embedded in the CLI binary and bumps
- * with CLI releases. (Server-side build is the v2 path.)
- */
-export declare function appCreate(client: LoticsClient, args: {
-    name: string;
-    targetPath?: string;
-}): Promise<void>;
-/**
- * `lotics app pull <app_id> [path]`
- *
- * Bootstraps a full local dev environment for an existing app:
- *   1. Fetch the current version's source archive from R2 (presigned URL).
- *   2. Extract into the target directory.
- *   3. Stamp package.json's `lotics` field with app_id + version metadata,
- *      and the live `apps.workflows` map from the server (NOT the manifest
- *      embedded in the source archive — that's a frozen snapshot from deploy
- *      time and would silently overwrite any agent-authored bindings made via
- *      `set_app_workflow` since the last deploy).
- *   4. Regenerate `.lotics/app_workflows.d.ts` from the live workflows so
- *      `useWorkflow<"alias">` is typed at pull time.
- *   5. Run `npm install`.
- *
- * 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.
- * The app_id comes from the local `package.json` manifest. The old
- * `<slug>.lotics.app` stops resolving once the change lands.
- */
-export declare function appSetSubdomain(client: LoticsClient, args: {
-    subdomain: string;
-}): Promise<void>;
-/**
- * `lotics app rename <name>` — change the current app's display name (the
- * launcher/title shown in the workspace). The app_id comes from the local
- * `package.json` manifest. Wraps the `update_app` tool — the public address
- * (`lotics app subdomain`) and the code (`lotics app deploy`) are unchanged.
- */
-export declare function appRename(client: LoticsClient, args: {
-    name: string;
-}): Promise<void>;
-/**
- * `lotics app versions [app_id]` — print the app's deploy history, newest
- * first: version number, when, deployer, build status, and the `-m` message.
- * With no `app_id`, reads it from the local `package.json` manifest (run inside
- * the app dir); pass an explicit `app_id` to inspect any app without pulling it.
- * The currently served version is marked with `*`. Admin-only server-side.
- */
-export declare function appVersions(client: LoticsClient, args: {
-    app_id?: string;
-    limit?: number;
-}): 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;
-}): Promise<void>;
-/**
- * Capabilities the source CALLS but the manifest does not DECLARE — each one
- * silently 403s at runtime (GAP-29). Pure over the concatenated source text so
- * it's unit-testable; the deploy warns (non-blocking) on a non-empty result.
- */
-export declare function undeclaredCapabilities(sourceText: string, declared: Record<string, boolean | undefined> | undefined): string[];
-/**
- * `lotics app deploy [-m <message>]`
- *
- * Builds the project locally with `npm run build`, tars source + dist, and
- * uploads to the deploy endpoint. The endpoint validates structure, stores
- * both archives in R2, creates an app_versions row, and atomically advances
- * the app's current_version pointer.
- */
-export declare function appDeploy(client: LoticsClient, args: {
-    projectDir?: string;
-    message: string;
-}): Promise<void>;
-/**
- * `lotics app dev [path] [--port=5174] [--vite-port=5173]`
- *
- * Local dev mode for iframe apps. Spawns Vite + a postMessage RPC forwarder
- * that bridges the iframe's hooks (useQuery, useWorkflow) to api.lotics.ai
- * using the CLI's stored API key. Wrapper
- * iframe matches the production sandbox attributes exactly — null origin,
- * allow-scripts — so prod-equivalent runtime behavior surfaces in dev.
- *
- * Lifecycle: Vite as a child process (HMR over WebSocket), HTTP server on a
- * sibling port serving the wrapper HTML + the /_rpc dispatcher. SIGINT kills
- * both cleanly.
- */
-export declare function appDev(client: LoticsClient, args: {
-    projectDir?: string;
-    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 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).
- * 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;
-    uiSrc?: string;
-}): void;