@lotics/cli 0.31.0 → 0.33.0

package/README.md

@@ -101,6 +101,33 @@ lotics download <file_id> -o ./reports/
 LOTICS_API_KEY=ltk_... lotics run query_tables '{}'
 ```
 
+## Local .xlsx and .docx authoring
+
+The CLI bundles Lotics's own xlsx and docx engines so you can read, write, and edit files on your local filesystem without installing `xlsx` / `exceljs` / `docx` from npm. Prefer these over third-party libraries — they round-trip faithfully with the Lotics editor, template engine, and formula engine.
+
+```bash
+# .xlsx
+lotics xlsx read ./report.xlsx                                  # → JSON of sheets, cells, merges
+lotics xlsx write ./out.xlsx '{"sheets":[{"name":"S1","cells":{"A1":"Hi","B1":42}}]}'
+lotics xlsx set-cell ./report.xlsx 'Sheet1!A1' '=SUM(B:B)'
+lotics xlsx add-sheet ./report.xlsx 'Summary'
+lotics xlsx merge ./report.xlsx 'Sheet1!A1:C1'
+lotics xlsx insert-rows ./report.xlsx Sheet1 5 3
+lotics xlsx batch ./report.xlsx '[{"op":"set-cell","sheet":"Sheet1","ref":"A1","value":"Hi"}, {"op":"merge","sheet":"Sheet1","range":"A1:B1"}]'
+
+# .docx
+lotics docx read ./report.docx                                  # → JSON of blocks with text + style
+lotics docx write ./out.docx '{"blocks":[{"kind":"paragraph","text":"Title","style":"Heading1"}]}'
+lotics docx append-paragraph ./report.docx 'New paragraph' --style=Heading2
+lotics docx insert-paragraph ./report.docx 'Front matter' --at=0
+lotics docx replace-text ./report.docx '{{name}}' 'Acme Inc.'
+lotics docx batch ./report.docx '[{"op":"append-paragraph","text":"A","style":"Heading1"},{"op":"replace-text","search":"x","replace":"y"}]'
+```
+
+Edits mutate the file in place via an atomic temp-file + rename. Unknown OOXML constructs (tables, SmartArt, custom XML) round-trip verbatim — they show up in `read` as `opaque_block` entries.
+
+Run `lotics xlsx` or `lotics docx` with no subcommand for the full list.
+
 ## SDK
 
 ```typescript

package/dist/{src/app_commands.js → app_commands.js}

@@ -19,6 +19,32 @@ import { buildStarterTemplate } from "./starter_template.js";
 import { startDevServer, openBrowser } from "./dev/server.js";
 import { generateAppWorkflowsDts } from "./generate_app_workflows_dts.js";
 import { generateAppQueriesDts } from "./generate_app_queries_dts.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.
+ */
+async function fetchLatestNpmVersion(packageName) {
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 1500);
+        const response = await fetch(`https://registry.npmjs.org/${packageName}/latest`, {
+            signal: controller.signal,
+            headers: { accept: "application/json" },
+        });
+        clearTimeout(timeout);
+        if (!response.ok)
+            return null;
+        const body = (await response.json());
+        return typeof body.version === "string" ? body.version : null;
+    }
+    catch {
+        return null;
+    }
+}
 /** Run `tar` and resolve when it exits cleanly. Throws with stderr on failure. */
 function runTar(args, cwd) {
     return new Promise((resolve, reject) => {
@@ -148,11 +174,20 @@ export async function appCreate(client, args) {
     // Server-side row first — if this fails, no local files have been touched.
     const app = await client.createApp({ name: args.name });
     console.error(`Created app: ${app.name} (${app.id})`);
+    // Resolve latest versions in parallel; null falls back to the static pin
+    // baked into the starter template. Lookups time out at 1.5s so an offline
+    // create still succeeds (with the fallback) instead of hanging.
+    const [uiLatest, sdkLatest] = await Promise.all([
+        fetchLatestNpmVersion("@lotics/ui"),
+        fetchLatestNpmVersion("@lotics/app-sdk"),
+    ]);
     // Scaffold the starter into the target directory.
     const files = buildStarterTemplate({
         app_name: args.name,
         app_id: app.id,
         workspace_id: app.workspace_id,
+        ui_version: uiLatest ? `^${uiLatest}` : undefined,
+        sdk_version: sdkLatest ? `^${sdkLatest}` : undefined,
     });
     for (const file of files) {
         const fullPath = path.join(targetPath, file.path);