@warmhub/cli 0.44.0 → 0.44.1

package/dist/wh.js

@@ -19358,7 +19358,7 @@ function findSystemComponent(componentId) {
 // ../../packages/sdk-ts/package.json
 var package_default = {
   name: "@warmhub/sdk-ts",
-  version: "0.43.0",
+  version: "0.44.0",
   private: false,
   type: "module",
   homepage: "https://docs.warmhub.ai",
@@ -20547,6 +20547,18 @@ class WarmHubClient {
       } catch (error) {
         throw toWarmHubError(error);
       }
+    },
+    index: {
+      describe: async (orgName, repoName) => {
+        try {
+          return await this.trpc.repo.index.describe.query({
+            orgName,
+            repoName
+          });
+        } catch (error) {
+          throw toWarmHubError(error);
+        }
+      }
     }
   };
   shape = {
@@ -20869,7 +20881,8 @@ class WarmHubClient {
           cursor: opts?.cursor,
           componentId: opts?.componentId,
           excludeComponents: opts?.excludeComponents,
-          excludeInfraShapes: opts?.excludeInfraShapes
+          excludeInfraShapes: opts?.excludeInfraShapes,
+          where: opts?.where
         });
       } catch (error) {
         throw toWarmHubError(error);
@@ -21002,7 +21015,8 @@ class WarmHubClient {
           depth: opts?.depth,
           resolveCollections: opts?.resolveCollections,
           limit: opts?.limit,
-          cursor: opts?.cursor
+          cursor: opts?.cursor,
+          where: opts?.where
         });
       } catch (error) {
         throw toWarmHubError(error);
@@ -21031,7 +21045,8 @@ class WarmHubClient {
           cursor: opts?.cursor,
           componentId: opts?.componentId,
           excludeComponents: opts?.excludeComponents,
-          excludeInfraShapes: opts?.excludeInfraShapes
+          excludeInfraShapes: opts?.excludeInfraShapes,
+          where: opts?.where
         });
       } catch (error) {
         throw toWarmHubError(error);
@@ -21082,7 +21097,8 @@ class WarmHubClient {
           resolveCollections: opts?.resolveCollections,
           componentId: opts?.componentId,
           excludeComponents: opts?.excludeComponents,
-          excludeInfraShapes: opts?.excludeInfraShapes
+          excludeInfraShapes: opts?.excludeInfraShapes,
+          where: opts?.where
         });
       } catch (error) {
         throw toWarmHubError(error);
@@ -21120,7 +21136,8 @@ class WarmHubClient {
         dataMode: opts?.dataMode,
         limit: opts?.limit,
         cursor: opts?.cursor,
-        includeRetracted: opts?.includeRetracted
+        includeRetracted: opts?.includeRetracted,
+        where: opts?.where
       }), onUpdate);
     },
     thingHistory: async (orgName, repoName, opts, onUpdate) => {
@@ -21624,6 +21641,9 @@ function conflictHint(message) {
   }
   return "Resolve the conflicting existing state and try again.";
 }
+function isFieldIndexErrorCode(code) {
+  return code === "FIELD_INDEX_UNAVAILABLE" || code === "FIELD_NOT_INDEXABLE" || code === "FIELD_TYPE_AMBIGUOUS";
+}
 function toCliError(err) {
   if (err instanceof CliError)
     return err;
@@ -21635,6 +21655,9 @@ function toCliError(err) {
       const hint = err.hint ?? unauthenticatedHint(err.message);
       return new CliError(3 /* Config */, "AUTH", err.message, err, hint);
     }
+    if (isFieldIndexErrorCode(err.code)) {
+      return new CliError(err.code === "FIELD_NOT_INDEXABLE" ? 2 /* UserInput */ : 4 /* Backend */, err.code, err.message, err, err.hint);
+    }
     if ((err.code === "CONFLICT" || err.code === "ARCHIVED") && err.status === undefined) {
       return new CliError(2 /* UserInput */, "CONFLICT", err.message, err, err.hint ?? conflictHint(err.message));
     }
@@ -21738,6 +21761,30 @@ function generateSuggestions(code, message, context) {
       });
     }
   }
+  if (code === "FIELD_NOT_INDEXABLE") {
+    suggestions.push({
+      action: "Inspect indexed field state for the repo",
+      command: "wh repo describe --indexed-fields"
+    });
+    suggestions.push({
+      action: "Use a shape-declared, indexable scalar field in --where"
+    });
+  }
+  if (code === "FIELD_INDEX_UNAVAILABLE") {
+    suggestions.push({
+      action: "Retry after the field index finishes building"
+    });
+    suggestions.push({
+      action: "Inspect indexed field state for the repo",
+      command: "wh repo describe --indexed-fields"
+    });
+  }
+  if (code === "FIELD_TYPE_AMBIGUOUS") {
+    suggestions.push({
+      action: "Inspect indexed field state for heterogeneous field types",
+      command: "wh repo describe --indexed-fields"
+    });
+  }
   if (code === "AUTH") {
     suggestions.push({
       action: "Re-authenticate",
@@ -21771,6 +21818,11 @@ function shouldLogToErrorTier(err) {
     case "AUTH":
     case "UNKNOWN":
       return true;
+    case "FIELD_NOT_INDEXABLE":
+      return false;
+    case "FIELD_INDEX_UNAVAILABLE":
+    case "FIELD_TYPE_AMBIGUOUS":
+      return true;
     case "BACKEND": {
       const status = err.cause?.status;
       if (typeof status === "number" && status >= 400 && status < 500) {
@@ -24533,10 +24585,64 @@ async function readContentInput(filePath, inline, stdinStream) {
 function usageError(usage, example) {
   throw new CliError(2 /* UserInput */, "USER_INPUT", usage, undefined, `Example: ${example}`);
 }
+var WHERE_USAGE_HINT = 'Example: --where state=NC --where "employees>=100" --where "state?"';
+function requireWhereFieldPath(raw, fieldPath) {
+  const normalized = fieldPath.trim();
+  if (!normalized) {
+    throw new CliError(2 /* UserInput */, "USER_INPUT", `Malformed --where predicate: "${raw}". Field path cannot be empty.`, undefined, WHERE_USAGE_HINT);
+  }
+  return normalized;
+}
+function parseWhereFlag(raw) {
+  const opMatch = raw.match(/^(.+?)\s*(>=|<=|!=|=|>|<)\s*(.*)$/);
+  if (opMatch) {
+    const fieldPath = requireWhereFieldPath(raw, opMatch[1]);
+    const opStr = opMatch[2];
+    const rhsStr = (opMatch[3] ?? "").trim();
+    const op = opStr === "=" ? "eq" : opStr === "!=" ? "ne" : opStr === ">=" ? "gte" : opStr === "<=" ? "lte" : opStr === ">" ? "gt" : "lt";
+    const rhs = coerceValue(rhsStr);
+    return { fieldPath, op, rhs };
+  }
+  const inMatch = raw.match(/^(.+?)\s+in:\[(.*)?\]$/);
+  if (inMatch) {
+    const fieldPath = requireWhereFieldPath(raw, inMatch[1]);
+    const valueStr = inMatch[2] ?? "";
+    if (valueStr.trim() === "") {
+      throw new CliError(2 /* UserInput */, "USER_INPUT", `Invalid --where "${raw}": in:[] requires at least one value`, undefined, 'Example: --where "state in:[NC,VA]"');
+    }
+    const rhs = valueStr.split(",").map((v) => coerceValue(v.trim()));
+    if (rhs.length > MAX_WHERE_IN_VALUES) {
+      throw new CliError(2 /* UserInput */, "USER_INPUT", `Invalid --where "${raw}": in:[...] supports at most ${MAX_WHERE_IN_VALUES} values`, undefined, `Split the query into smaller batches of at most ${MAX_WHERE_IN_VALUES} values.`);
+    }
+    return { fieldPath, op: "in", rhs };
+  }
+  const prefixMatch = raw.match(/^(.+?)~(.+)$/);
+  if (prefixMatch) {
+    const fieldPath = requireWhereFieldPath(raw, prefixMatch[1]);
+    const rhs = coerceValue(prefixMatch[2].replace(/\*$/, ""));
+    return { fieldPath, op: "prefix", rhs };
+  }
+  if (raw.endsWith("?")) {
+    const fieldPath = requireWhereFieldPath(raw, raw.slice(0, -1));
+    return { fieldPath, op: "exists" };
+  }
+  throw new CliError(2 /* UserInput */, "USER_INPUT", `Malformed --where predicate: "${raw}". Supported operators: =, !=, >, >=, <, <=, ~, in:[...], ?`, undefined, WHERE_USAGE_HINT);
+}
+function coerceValue(s) {
+  if (s.startsWith('"') && s.endsWith('"') || s.startsWith("'") && s.endsWith("'")) {
+    return s.slice(1, -1);
+  }
+  if (s === "true")
+    return true;
+  if (s === "false")
+    return false;
+  return s;
+}
 var DEFAULT_PAGE_LIMIT = 50;
 var DEFAULT_SEARCH_LIMIT = 25;
 var MAX_PAGE_LIMIT = 500;
 var AUTO_PAGE_LIMIT = MAX_PAGE_LIMIT;
+var MAX_WHERE_IN_VALUES = 1000;
 async function handleCount(ctx, org, repo, opts) {
   const result = await ctx.client.thing.count(org, repo, opts);
   writeOutput(ctx, result, () => ctx.out(`${result.count}`));
@@ -24778,6 +24884,10 @@ var headFlags = {
   }),
   "exclude-components": flag.boolean({
     description: "Exclude component-owned things from results"
+  }),
+  where: flag.string({
+    multiple: true,
+    description: `Field-value WHERE predicate (repeatable). Syntax: field=val, field>=val, field~prefix*, field in:[a,b] (max ${MAX_WHERE_IN_VALUES} values), field? (exists). Predicates are served by the typed field index; unservable fields return a machine-readable field-index error instead of scanning JSONB bodies.`
   })
 };
 var handleHead = async (ctx, { flags, args }) => {
@@ -24790,6 +24900,8 @@ var handleHead = async (ctx, { flags, args }) => {
   const match = flags.match;
   const count = flags.count;
   const includeRetracted = flags["include-retracted"];
+  const whereRaw = flags.where ?? [];
+  const where = whereRaw.map(parseWhereFlag);
   if (count) {
     if (cursor || all || limit || ctx.liveMode) {
       usageError("Usage: wh thing list --count [--shape SHAPE] [--kind KIND] [--match PATTERN]", "wh thing list --shape Player --count");
@@ -24804,7 +24916,8 @@ var handleHead = async (ctx, { flags, args }) => {
       includeRetracted,
       componentId: componentId2,
       excludeComponents: strictExclude2,
-      excludeInfraShapes: !strictExclude2 && !shape
+      excludeInfraShapes: !strictExclude2 && !shape,
+      where: where.length > 0 ? where : undefined
     });
   }
   if (cursor && !limit) {
@@ -24830,7 +24943,8 @@ var handleHead = async (ctx, { flags, args }) => {
     cursor,
     componentId,
     excludeComponents,
-    excludeInfraShapes
+    excludeInfraShapes,
+    where: where.length > 0 ? where : undefined
   };
   if (ctx.liveMode) {
     await runLive({
@@ -24860,7 +24974,8 @@ var handleHead = async (ctx, { flags, args }) => {
     cursor,
     componentId,
     excludeComponents,
-    excludeInfraShapes
+    excludeInfraShapes,
+    where: where.length > 0 ? where : undefined
   }) : await ctx.client.thing.head(org, repo, {
     shape,
     kind,
@@ -24870,7 +24985,8 @@ var handleHead = async (ctx, { flags, args }) => {
     cursor,
     componentId,
     excludeComponents,
-    excludeInfraShapes
+    excludeInfraShapes,
+    where: where.length > 0 ? where : undefined
   });
   writeOutput(ctx, result, () => renderHead(ctx.out, ctx.colors, ctx.chars, result, org, repo, shape, kind));
 };
@@ -24887,7 +25003,8 @@ async function fetchAllHeadPages(ctx, org, repo, opts) {
       cursor,
       componentId: opts.componentId,
       excludeComponents: opts.excludeComponents,
-      excludeInfraShapes: opts.excludeInfraShapes
+      excludeInfraShapes: opts.excludeInfraShapes,
+      where: opts.where
     });
     items.push(...page.items ?? []);
     if (!page.nextCursor)
@@ -25333,6 +25450,10 @@ var queryFlags = {
   }),
   "exclude-components": flag.boolean({
     description: "Exclude component-owned things from results"
+  }),
+  where: flag.string({
+    multiple: true,
+    description: `Field-value WHERE predicate (repeatable). Syntax: field=val, field>=val, field~prefix*, field in:[a,b] (max ${MAX_WHERE_IN_VALUES} values), field? (exists). Predicates are served by the typed field index; unservable fields return a machine-readable field-index error instead of scanning JSONB bodies.`
   })
 };
 var handleQuery = async (ctx, { flags }) => {
@@ -25354,6 +25475,8 @@ var handleQuery = async (ctx, { flags }) => {
   const excludeComponents = strictExclude;
   const excludeInfraShapes = !strictExclude && !hasShape;
   const c = ctx.colors;
+  const whereRaw = flags.where ?? [];
+  const where = whereRaw.map(parseWhereFlag);
   if (count) {
     if (cursor || all || limit || ctx.liveMode) {
       usageError("Usage: wh thing query --count [--shape SHAPE] [--about WREF] [--kind KIND] [--match PATTERN]", "wh thing query --kind assertion --about Player/alice --count");
@@ -25367,7 +25490,8 @@ var handleQuery = async (ctx, { flags }) => {
       resolveCollections,
       componentId,
       excludeComponents,
-      excludeInfraShapes
+      excludeInfraShapes,
+      where: where.length > 0 ? where : undefined
     });
   }
   if (cursor && !limit) {
@@ -25389,7 +25513,8 @@ var handleQuery = async (ctx, { flags }) => {
     cursor,
     componentId,
     excludeComponents,
-    excludeInfraShapes
+    excludeInfraShapes,
+    where: where.length > 0 ? where : undefined
   };
   if (ctx.liveMode) {
     await runLive({
@@ -25421,7 +25546,8 @@ var handleQuery = async (ctx, { flags }) => {
     cursor,
     componentId,
     excludeComponents,
-    excludeInfraShapes
+    excludeInfraShapes,
+    where: where.length > 0 ? where : undefined
   }) : await ctx.client.thing.query(org, repo, {
     shape,
     about,
@@ -25433,7 +25559,8 @@ var handleQuery = async (ctx, { flags }) => {
     cursor,
     componentId,
     excludeComponents,
-    excludeInfraShapes
+    excludeInfraShapes,
+    where: where.length > 0 ? where : undefined
   });
   writeOutput(ctx, result, () => renderQueryResults(ctx.out, c, result));
 };
@@ -25452,7 +25579,8 @@ async function fetchAllQueryPages(ctx, org, repo, opts) {
       cursor,
       componentId: opts.componentId,
       excludeComponents: opts.excludeComponents,
-      excludeInfraShapes: opts.excludeInfraShapes
+      excludeInfraShapes: opts.excludeInfraShapes,
+      where: opts.where
     });
     items.push(...page.items ?? []);
     if (!page.nextCursor)
@@ -33437,20 +33565,36 @@ var handleUpdate3 = async (ctx, { args, flags }) => {
     ctx.out(`${c.green}Updated${c.reset} ${c.cyan}${orgName}/${repoName}${c.reset} description`);
   });
 };
-var handleDescribe = async (ctx, { args }) => {
+var describeFlags = {
+  "indexed-fields": flag.boolean({
+    description: "Show typed field index state (building, ready, failed) for each shape"
+  })
+};
+var handleDescribe = async (ctx, { args, flags }) => {
   const repoRef = args[0];
   const { org, repo } = parseOrgRepo(repoRef, ctx.config);
   const c = ctx.colors;
-  const [repoInfo, shapesPage, stats] = await Promise.all([
+  const showIndexedFields = flags["indexed-fields"] === true;
+  const [repoInfo, shapesPage, stats, indexedFields] = await Promise.all([
     ctx.client.repo.get(org, repo),
     ctx.client.shape.list(org, repo),
-    ctx.client.repo.getStats(org, repo)
+    ctx.client.repo.getStats(org, repo),
+    showIndexedFields ? ctx.client.repo.index.describe(org, repo) : null
   ]);
   const shapes = shapesPage.items;
   const byShape = Object.fromEntries([
     ...shapes.map((shape) => shape.name).filter((name) => typeof name === "string").map((name) => [name, 0]),
     ...Object.entries(stats.byShape)
   ]);
+  function stripShapeThingId(bucket) {
+    return bucket.map(({ shapeThingId: _omit, ...rest }) => rest);
+  }
+  const indexedFieldsPublic = indexedFields ? {
+    building: stripShapeThingId(indexedFields.building),
+    ready: stripShapeThingId(indexedFields.ready),
+    failed: stripShapeThingId(indexedFields.failed),
+    other: stripShapeThingId(indexedFields.other)
+  } : null;
   const payload = {
     org,
     repo,
@@ -33470,7 +33614,8 @@ var handleDescribe = async (ctx, { args }) => {
         description: typeof data?.description === "string" ? data.description : null,
         fields: Object.fromEntries(Object.entries(fields).map(([k, v]) => [k, displayFieldEntry(v)]))
       };
-    })
+    }),
+    ...indexedFieldsPublic ? { indexedFields: indexedFieldsPublic } : {}
   };
   writeOutput(ctx, payload, () => {
     ctx.out(`${c.bold}${org}/${repo}${c.reset}`);
@@ -33521,6 +33666,52 @@ var handleDescribe = async (ctx, { args }) => {
       }
       ctx.out("");
     }
+    if (indexedFieldsPublic) {
+      const allEntries = [
+        ...indexedFieldsPublic.building,
+        ...indexedFieldsPublic.ready,
+        ...indexedFieldsPublic.failed,
+        ...indexedFieldsPublic.other
+      ];
+      if (allEntries.length === 0) {
+        ctx.out(`${c.bold}Indexed Fields${c.reset}  ${c.dim}none${c.reset}`);
+      } else {
+        ctx.out(`${c.bold}Indexed Fields${c.reset} (${allEntries.length})`);
+        ctx.out("");
+        const stateColor = (state) => {
+          switch (state) {
+            case "ready":
+              return c.green;
+            case "building":
+              return c.yellow;
+            case "failed":
+              return c.red;
+            default:
+              return c.dim;
+          }
+        };
+        const maxShape = allEntries.reduce((m, e) => Math.max(m, e.shapeName.length), 0);
+        const maxField = allEntries.reduce((m, e) => Math.max(m, e.fieldPath.length), 0);
+        const maxState = allEntries.reduce((m, e) => Math.max(m, e.state.length), 0);
+        for (const entry of allEntries) {
+          const shapeLabel = entry.shapeName.padEnd(maxShape);
+          const fieldLabel = entry.fieldPath.padEnd(maxField);
+          const stateLabel = entry.state.padEnd(maxState);
+          const sc = stateColor(entry.state);
+          let line = `  ${c.cyan}${shapeLabel}${c.reset}  ${c.dim}${fieldLabel}${c.reset}  ${sc}${stateLabel}${c.reset}`;
+          if (entry.state === "building" && entry.backfillTotal != null && entry.backfillTotal > 0) {
+            const pct = Math.round(entry.backfillDone / entry.backfillTotal * 100);
+            line += `  ${c.dim}${entry.backfillDone}/${entry.backfillTotal} (${pct}%)${c.reset}`;
+          } else if (entry.state === "building") {
+            line += `  ${c.dim}${entry.backfillDone} rows${c.reset}`;
+          } else if (entry.state === "failed" && entry.failureReason) {
+            line += `  ${c.dim}${entry.failureReason}${c.reset}`;
+          }
+          ctx.out(line);
+        }
+        ctx.out("");
+      }
+    }
   });
 };
 var confirmFlags2 = {
@@ -33790,7 +33981,12 @@ var REPO_DOMAIN = defineDomain({
       prime: true,
       summary: "Describe repo schema: shapes, fields, and inline descriptions",
       args: "[org/repo]",
-      examples: ["wh repo describe", "wh repo describe acme/world"],
+      flags: describeFlags,
+      examples: [
+        "wh repo describe",
+        "wh repo describe acme/world",
+        "wh repo describe acme/world --indexed-fields"
+      ],
       handler: handleDescribe
     },
     visibility: {
@@ -35860,7 +36056,7 @@ function resolveLogLevel(flags, env) {
 // package.json
 var package_default3 = {
   name: "@warmhub/cli",
-  version: "0.44.0",
+  version: "0.44.1",
   private: false,
   type: "module",
   homepage: "https://docs.warmhub.ai",
@@ -36805,4 +37001,4 @@ if (!updateCheckSuppressedByArgv && shouldRunUpdateCheck(updateEligibility)) {
 var interceptedExitCode = await maybeHandleComponentShellBoundary(dispatchArgv);
 process.exitCode = interceptedExitCode === undefined ? await runCli(dispatchArgv, { version: package_default3.version }) : interceptedExitCode;
 
-//# debugId=2257A8F0A0546F4F64756E2164756E21
+//# debugId=8244220EBED83FEF64756E2164756E21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warmhub/cli",
-  "version": "0.44.0",
+  "version": "0.44.1",
   "private": false,
   "type": "module",
   "homepage": "https://docs.warmhub.ai",