@lotics/cli 0.62.1 → 0.64.0

package/README.md

@@ -156,6 +156,8 @@ Run `lotics xlsx` or `lotics docx` with no subcommand for the full list.
 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
+lotics app versions                        # deploy history: version, when, who, -m message (* = live)
+lotics app versions app_...                # ...for any app, without pulling it first
 
 # Regenerate .lotics/* WITHOUT a deploy: the .d.ts type companions (always) +
 # the runtime app_fields.ts (when authenticated) — F/OPT maps that address

package/dist/app_commands.d.ts

@@ -196,6 +196,17 @@ export declare function appSetSubdomain(client: LoticsClient, args: {
 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
@@ -224,7 +235,7 @@ export declare function undeclaredCapabilities(sourceText: string, declared: Rec
  */
 export declare function appDeploy(client: LoticsClient, args: {
     projectDir?: string;
-    message?: string;
+    message: string;
 }): Promise<void>;
 /**
  * `lotics app dev [path] [--port=5174] [--vite-port=5173]`

package/dist/app_commands.js

@@ -630,6 +630,50 @@ export async function appRename(client, args) {
         throw new Error(res.error);
     console.error(`App renamed: "${args.name}" (${meta.app_id})`);
 }
+/**
+ * `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 async function appVersions(client, args) {
+    const appId = args.app_id ?? readAppMeta(process.cwd()).app_id;
+    const { current_version_id, versions } = await client.listAppVersions(appId, {
+        limit: args.limit,
+    });
+    if (versions.length === 0) {
+        console.error(`No versions found for ${appId}.`);
+        return;
+    }
+    const fmtWhen = (iso) => {
+        const d = new Date(iso);
+        if (Number.isNaN(d.getTime()))
+            return iso;
+        const p = (n) => String(n).padStart(2, "0");
+        return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+    };
+    const rows = versions.map((v) => ({
+        mark: v.id === current_version_id ? "*" : " ",
+        ver: `v${v.version}`,
+        when: fmtWhen(v.created_at),
+        by: v.created_by_name ?? v.created_by ?? "—",
+        status: v.build_status,
+        message: v.message ?? "",
+    }));
+    const colWidth = (key, header) => Math.max(header.length, ...rows.map((r) => r[key].length));
+    const wVer = colWidth("ver", "VER");
+    const wWhen = colWidth("when", "WHEN");
+    const wBy = colWidth("by", "DEPLOYER");
+    const wStatus = colWidth("status", "STATUS");
+    const pad = (s, n) => s.padEnd(n);
+    // Title → stderr (status); the table → stdout (data), so it stays pipeable.
+    console.error(`Deploy history — ${appId} (${versions.length} version${versions.length === 1 ? "" : "s"}, newest first; * = currently served)`);
+    console.log(`  ${pad("VER", wVer)}  ${pad("WHEN", wWhen)}  ${pad("DEPLOYER", wBy)}  ${pad("STATUS", wStatus)}  MESSAGE`);
+    for (const r of rows) {
+        console.log(`${r.mark} ${pad(r.ver, wVer)}  ${pad(r.when, wWhen)}  ${pad(r.by, wBy)}  ${pad(r.status, wStatus)}  ${r.message}`.trimEnd());
+    }
+}
 /**
  * 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
@@ -762,7 +806,11 @@ function readAppSourceText(projectDir) {
  * both archives in R2, creates an app_versions row, and atomically advances
  * the app's current_version pointer.
  */
-export async function appDeploy(client, args) {
+export async function appDeploy(client, 
+// `message` is required — each deploy is a version row read back by
+// `lotics app versions`; a blank message loses the audit trail. The CLI
+// enforces non-empty at the dispatch; the type enforces it for every caller.
+args) {
     const projectDir = path.resolve(args.projectDir ?? process.cwd());
     const meta = readAppMeta(projectDir);
     // Pre-flight (GAP-29): a capability the code calls but the manifest doesn't

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, appWorkflowSet, appWorkflowPull, appExecuteWorkflow, writeWorkflowFile, writeWorkflowGlobals, stripWorkflowHeader, FALLBACK_ENVELOPE_PREFIX, FALLBACK_ENVELOPE_SUFFIX, } from "./app_commands.js";
+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";
 /**
  * `appPull` reads workflows from the live App row (server response), NOT from
  * the manifest embedded in the extracted source archive. The frozen archive
@@ -724,3 +724,68 @@ describe("ensureWorkflowTsconfigExcludes", () => {
         expect(fs.readFileSync(tsconfigPath(), "utf-8")).toBe("{ not json,, }");
     });
 });
+describe("appVersions", () => {
+    let logLines;
+    let errLines;
+    beforeEach(() => {
+        logLines = [];
+        errLines = [];
+        vi.spyOn(console, "log").mockImplementation((...args) => {
+            logLines.push(String(args[0]));
+        });
+        vi.spyOn(console, "error").mockImplementation((...args) => {
+            errLines.push(String(args[0]));
+        });
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    const clientWith = (payload) => ({ listAppVersions: vi.fn().mockResolvedValue(payload) });
+    it("renders history newest-first, marks the current version, and prefers the deployer name", async () => {
+        const client = clientWith({
+            current_version_id: "apv_2",
+            versions: [
+                {
+                    id: "apv_2",
+                    version: 2,
+                    message: "add receipt gate",
+                    build_status: "success",
+                    bundle_size_bytes: 1234,
+                    created_at: "2026-06-24T03:04:41Z",
+                    created_by: "mem_a",
+                    created_by_name: "Minh Vu",
+                },
+                {
+                    id: "apv_1",
+                    version: 1,
+                    message: "initial deploy",
+                    build_status: "success",
+                    bundle_size_bytes: 1000,
+                    created_at: "2026-06-23T08:00:00Z",
+                    created_by: "mem_b",
+                    created_by_name: null,
+                },
+            ],
+        });
+        // Explicit app_id → no manifest/package.json in cwd required.
+        await appVersions(client, { app_id: "app_x" });
+        // One header row + one row per version, all on stdout.
+        expect(logLines.length).toBe(3);
+        const v2Row = logLines.find((l) => l.includes("v2"));
+        const v1Row = logLines.find((l) => l.includes("v1"));
+        // Currently-served version is marked with `*`; the other is not.
+        expect(v2Row.startsWith("*")).toBe(true);
+        expect(v1Row.startsWith("*")).toBe(false);
+        // Messages render; the deployer name is preferred, falling back to the id.
+        expect(v2Row).toContain("add receipt gate");
+        expect(v2Row).toContain("Minh Vu");
+        expect(v1Row).toContain("initial deploy");
+        expect(v1Row).toContain("mem_b");
+    });
+    it("reports an empty history to stderr without printing a table", async () => {
+        const client = clientWith({ current_version_id: null, versions: [] });
+        await appVersions(client, { app_id: "app_empty" });
+        expect(logLines).toEqual([]);
+        expect(errLines.join("\n")).toContain("No versions found");
+    });
+});

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, appCodegen, appExecuteWorkflow, appWorkflowSet, appWorkflowPull, appWorkflowCheck, appUiLink, } from "./app_commands.js";
+import { appCreate, appPull, appDeploy, appDev, appSetSubdomain, appRename, appVersions, appCodegen, appExecuteWorkflow, appWorkflowSet, appWorkflowPull, appWorkflowCheck, appUiLink, } from "./app_commands.js";
 import { parseArgs } from "./args.js";
 import { ingestJsonArgs } from "./inputs.js";
 import { runXlsxCommand } from "./xlsx.js";
@@ -71,9 +71,13 @@ COMMANDS
                                        Download all files on a record file field
   lotics app create <name> [path]      Create a new custom-code app + scaffold locally
   lotics app pull <app_id> [path]      Bootstrap full local env (source + npm install + types)
-  lotics app deploy [-m <message>]     Build + upload current dir as a new version
+  lotics app deploy -m <message>       Build + upload current dir as a new version
+                                       (-m is required — it's the version's audit trail)
                                        (code + queries only — workflow bindings are
                                        managed by set_app_workflow / remove_app_workflow)
+  lotics app versions [app_id]         Show deploy history newest-first (version,
+                                       timestamp, deployer, build status, -m message;
+                                       * marks the currently served version)
   lotics app codegen [path]            Regenerate .lotics/* (types + field/option ids)
                                        from the manifest + workspace schema — no deploy
   lotics app workflow run <alias> '<json>'  Execute a bound app workflow end-to-end
@@ -595,7 +599,8 @@ async function main() {
         console.error("Usage:");
         console.error("  lotics app create <name> [path]      Scaffold a new app locally");
         console.error("  lotics app pull <app_id> [path]      Pull an existing app for local editing");
-        console.error("  lotics app deploy [-m <message>]     Build + upload the current directory");
+        console.error("  lotics app deploy -m <message>       Build + upload the current directory (-m required)");
+        console.error("  lotics app versions [app_id]         Show deploy history (version, when, who, message)");
         console.error("  lotics app codegen [path]            Regenerate .lotics/* (types + field ids) — no deploy");
         console.error("  lotics app workflow run <alias> '<json>'  Execute a bound app workflow end-to-end");
         console.error("  lotics app workflow set <alias>           Push the edited src/workflows/<alias>.ts body");
@@ -725,7 +730,14 @@ async function main() {
         }
         if (subcommand === "deploy") {
             // The message is either `-m <message>` or a bare positional arg after `deploy`.
-            const message = flags.message ?? toolArgs;
+            // Required: every deploy is a version row, and `lotics app versions` reads
+            // the message back — a blank one makes the deploy history useless.
+            const message = (flags.message ?? toolArgs)?.trim();
+            if (!message) {
+                console.error('Usage: lotics app deploy -m "<what changed + why>"');
+                console.error("A deploy message is required — it's the version's audit trail (see `lotics app versions`).");
+                process.exit(1);
+            }
             await appDeploy(client, { message });
             return;
         }
@@ -749,6 +761,12 @@ async function main() {
             await appRename(client, { name: newName });
             return;
         }
+        if (subcommand === "versions") {
+            // Optional positional app_id (inspect any app); else read the local manifest.
+            const appId = toolArgs || undefined;
+            await appVersions(client, { app_id: appId });
+            return;
+        }
         if (subcommand === "workflow") {
             // `lotics app workflow <run|set|pull> …` — disambiguated subcommands so an
             // alias can never collide with the verb. `toolArgs` is the verb; `restArgs`

package/dist/client.d.ts

@@ -199,6 +199,23 @@ export declare class LoticsClient {
         build_status: string;
     }>;
     getAppVersionSourceUrl(app_id: string, version_id: string): Promise<string>;
+    /** Deploy history for an app — newest first. Backs `lotics app versions`. */
+    listAppVersions(app_id: string, opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        current_version_id: string | null;
+        versions: Array<{
+            id: string;
+            version: number;
+            message: string | null;
+            build_status: string;
+            bundle_size_bytes: number | null;
+            created_at: string;
+            created_by: string | null;
+            created_by_name: string | null;
+        }>;
+    }>;
     /**
      * Run a named query declared in the app's manifest, scoped to the app's IAM
      * principal. Mirrors POST /v1/apps/{app_id}/query.

package/dist/client.js

@@ -244,6 +244,16 @@ export class LoticsClient {
         const result = await this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/versions/${encodeURIComponent(version_id)}/source`);
         return result.url;
     }
+    /** Deploy history for an app — newest first. Backs `lotics app versions`. */
+    async listAppVersions(app_id, opts) {
+        const qs = new URLSearchParams();
+        if (opts?.limit != null)
+            qs.set("limit", String(opts.limit));
+        if (opts?.offset != null)
+            qs.set("offset", String(opts.offset));
+        const suffix = qs.toString() ? `?${qs.toString()}` : "";
+        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/versions${suffix}`);
+    }
     // ── App iframe RPC endpoints ──────────────────────────────────────────────
     // These mirror the two ops handled by frontend/features/app_ui/app_iframe_host.tsx.
     // The deployed iframe sends postMessage to the parent frontend, which calls

package/dist/src/cli.js

@@ -29803,6 +29803,14 @@ var LoticsClient = class {
     );
     return result.url;
   }
+  /** Deploy history for an app — newest first. Backs `lotics app versions`. */
+  async listAppVersions(app_id, opts) {
+    const qs = new URLSearchParams();
+    if (opts?.limit != null) qs.set("limit", String(opts.limit));
+    if (opts?.offset != null) qs.set("offset", String(opts.offset));
+    const suffix = qs.toString() ? `?${qs.toString()}` : "";
+    return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/versions${suffix}`);
+  }
   // ── App iframe RPC endpoints ──────────────────────────────────────────────
   // These mirror the two ops handled by frontend/features/app_ui/app_iframe_host.tsx.
   // The deployed iframe sends postMessage to the parent frontend, which calls
@@ -32529,6 +32537,47 @@ async function appRename(client, args) {
   if (res.error) throw new Error(res.error);
   console.error(`App renamed: "${args.name}" (${meta.app_id})`);
 }
+async function appVersions(client, args) {
+  const appId = args.app_id ?? readAppMeta(process.cwd()).app_id;
+  const { current_version_id, versions } = await client.listAppVersions(appId, {
+    limit: args.limit
+  });
+  if (versions.length === 0) {
+    console.error(`No versions found for ${appId}.`);
+    return;
+  }
+  const fmtWhen = (iso) => {
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime())) return iso;
+    const p = (n) => String(n).padStart(2, "0");
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+  };
+  const rows = versions.map((v) => ({
+    mark: v.id === current_version_id ? "*" : " ",
+    ver: `v${v.version}`,
+    when: fmtWhen(v.created_at),
+    by: v.created_by_name ?? v.created_by ?? "\u2014",
+    status: v.build_status,
+    message: v.message ?? ""
+  }));
+  const colWidth = (key, header) => Math.max(header.length, ...rows.map((r) => r[key].length));
+  const wVer = colWidth("ver", "VER");
+  const wWhen = colWidth("when", "WHEN");
+  const wBy = colWidth("by", "DEPLOYER");
+  const wStatus = colWidth("status", "STATUS");
+  const pad = (s, n) => s.padEnd(n);
+  console.error(
+    `Deploy history \u2014 ${appId} (${versions.length} version${versions.length === 1 ? "" : "s"}, newest first; * = currently served)`
+  );
+  console.log(
+    `  ${pad("VER", wVer)}  ${pad("WHEN", wWhen)}  ${pad("DEPLOYER", wBy)}  ${pad("STATUS", wStatus)}  MESSAGE`
+  );
+  for (const r of rows) {
+    console.log(
+      `${r.mark} ${pad(r.ver, wVer)}  ${pad(r.when, wWhen)}  ${pad(r.by, wBy)}  ${pad(r.status, wStatus)}  ${r.message}`.trimEnd()
+    );
+  }
+}
 function defaultPullTarget(appId, appName) {
   const cwdPkgPath = path5.join(process.cwd(), "package.json");
   if (fs4.existsSync(cwdPkgPath)) {
@@ -49154,9 +49203,13 @@ COMMANDS
                                        Download all files on a record file field
   lotics app create <name> [path]      Create a new custom-code app + scaffold locally
   lotics app pull <app_id> [path]      Bootstrap full local env (source + npm install + types)
-  lotics app deploy [-m <message>]     Build + upload current dir as a new version
+  lotics app deploy -m <message>       Build + upload current dir as a new version
+                                       (-m is required \u2014 it's the version's audit trail)
                                        (code + queries only \u2014 workflow bindings are
                                        managed by set_app_workflow / remove_app_workflow)
+  lotics app versions [app_id]         Show deploy history newest-first (version,
+                                       timestamp, deployer, build status, -m message;
+                                       * marks the currently served version)
   lotics app codegen [path]            Regenerate .lotics/* (types + field/option ids)
                                        from the manifest + workspace schema \u2014 no deploy
   lotics app workflow run <alias> '<json>'  Execute a bound app workflow end-to-end
@@ -49631,7 +49684,8 @@ async function main() {
     console.error("Usage:");
     console.error("  lotics app create <name> [path]      Scaffold a new app locally");
     console.error("  lotics app pull <app_id> [path]      Pull an existing app for local editing");
-    console.error("  lotics app deploy [-m <message>]     Build + upload the current directory");
+    console.error("  lotics app deploy -m <message>       Build + upload the current directory (-m required)");
+    console.error("  lotics app versions [app_id]         Show deploy history (version, when, who, message)");
     console.error("  lotics app codegen [path]            Regenerate .lotics/* (types + field ids) \u2014 no deploy");
     console.error("  lotics app workflow run <alias> '<json>'  Execute a bound app workflow end-to-end");
     console.error("  lotics app workflow set <alias>           Push the edited src/workflows/<alias>.ts body");
@@ -49754,7 +49808,12 @@ Available workspaces:`);
       return;
     }
     if (subcommand === "deploy") {
-      const message = flags.message ?? toolArgs;
+      const message = (flags.message ?? toolArgs)?.trim();
+      if (!message) {
+        console.error('Usage: lotics app deploy -m "<what changed + why>"');
+        console.error("A deploy message is required \u2014 it's the version's audit trail (see `lotics app versions`).");
+        process.exit(1);
+      }
       await appDeploy(client, { message });
       return;
     }
@@ -49778,6 +49837,11 @@ Available workspaces:`);
       await appRename(client, { name: newName });
       return;
     }
+    if (subcommand === "versions") {
+      const appId = toolArgs || void 0;
+      await appVersions(client, { app_id: appId });
+      return;
+    }
     if (subcommand === "workflow") {
       const action = toolArgs;
       const workflowUsage = () => {

package/package.json

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