drivethrough-cli 0.1.11 → 0.1.13

package/dist/main.mjs

@@ -1065,157 +1065,35 @@ var init_universal = __esm({
     "use strict";
     UNIVERSAL_SCHEMA_STATEMENTS = [
       `CREATE TABLE IF NOT EXISTS data (
-  id         TEXT PRIMARY KEY,
-  parent_id  TEXT,
-  type       TEXT,
-  json       TEXT,
-  created_at TEXT
+  seq        INTEGER PRIMARY KEY AUTOINCREMENT,
+  type       TEXT    NOT NULL,
+  parent_seq INTEGER REFERENCES data(seq) ON DELETE CASCADE,
+  json       TEXT    NOT NULL DEFAULT '{}',
+  session    TEXT,
+  token      TEXT,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
 )`,
-      `CREATE INDEX IF NOT EXISTS idx_type   ON data(type)`,
-      // idx_parent is PARTIAL. D1 bills a written row per index touched, so a full
-      // index on parent_id charged every insert for an entry the common case never
-      // reads: most rows are top-level (a form submission with no parent), and
-      // `WHERE parent_id = ?` can only match a non-null value. Excluding NULLs
-      // keeps every query that used it — `type = ?1 AND parent_id = ?2` — on an
-      // index, while top-level inserts stop paying for it.
-      //
-      // The one reader of NULL parents (selectSessionRow's `parent_id IS NULL`
-      // branch) cannot use a partial index, and did not want this one anyway: it
-      // filters on type first, and for the unique_per types it actually runs on,
-      // uniq_session_<type> covers it.
-      //
-      // DROP first, under the old name: databases created before this change
-      // already hold the full index, and `CREATE ... IF NOT EXISTS` would see it
-      // and silently keep it. Renaming makes both statements true no-ops once the
-      // upgrade has happened, so init() stays cheap to re-run.
-      `DROP INDEX IF EXISTS idx_parent`,
-      `CREATE INDEX IF NOT EXISTS idx_parent_present ON data(parent_id) WHERE parent_id IS NOT NULL`
+      // ---- the three shared indexes ---------------------------------------------
+      // `(type)`, NOT `(type, seq)`. Because seq is INTEGER PRIMARY KEY it is the
+      // rowid, and SQLite appends the rowid to every index entry — so an index on
+      // `(type)` is already stored as `type, seq` and the ordering is free. Writing
+      // `(type, seq)` stores the number twice: 1,708 KB against 1,348 KB per
+      // 100,000 rows, for identical behaviour (schema §8).
+      `CREATE INDEX IF NOT EXISTS dt_type ON data(type)`,
+      // PARTIAL, so top-level rows (the common case — a form submission with no
+      // parent) never pay for an index entry `WHERE parent_seq = ?` could not match
+      // anyway.
+      `CREATE INDEX IF NOT EXISTS dt_parent ON data(parent_seq) WHERE parent_seq IS NOT NULL`,
+      // PARTIAL for the same reason, and it is what makes shipping `token` now free
+      // for every row that doesn't use it: 2 billed writes without a token, 3 with
+      // (schema §4).
+      `CREATE UNIQUE INDEX IF NOT EXISTS dt_token ON data(token) WHERE token IS NOT NULL`
     ];
     UNIVERSAL_SCHEMA_SQL = UNIVERSAL_SCHEMA_STATEMENTS.join(";\n") + ";";
   }
 });
 
-// ../schema/src/names.ts
-var RESERVED_NAMES, RESERVED;
-var init_names = __esm({
-  "../schema/src/names.ts"() {
-    "use strict";
-    RESERVED_NAMES = [
-      // platform & infrastructure
-      "drivethrough",
-      "drivethru",
-      "www",
-      "mail",
-      "smtp",
-      "imap",
-      "ftp",
-      "ns1",
-      "ns2",
-      "api",
-      "cdn",
-      "static",
-      "assets",
-      "status",
-      "docs",
-      "blog",
-      "dev",
-      "app",
-      // auth & account impersonation
-      "login",
-      "logout",
-      "signin",
-      "signup",
-      "auth",
-      "authorize",
-      "oauth",
-      "sso",
-      "secure",
-      "security",
-      "verify",
-      "verification",
-      "activate",
-      "session",
-      "account",
-      "accounts",
-      "admin",
-      "administrator",
-      "root",
-      "password",
-      "passwords",
-      "billing",
-      "payment",
-      "payments",
-      "invoice",
-      "checkout",
-      "wallet",
-      "support",
-      "help",
-      "helpdesk",
-      "service",
-      "official",
-      "update",
-      "updates",
-      "recover",
-      "recovery",
-      "reset",
-      "unlock",
-      "confirm",
-      "settings",
-      // high-value brand impersonation targets
-      "google",
-      "gmail",
-      "youtube",
-      "apple",
-      "icloud",
-      "itunes",
-      "microsoft",
-      "outlook",
-      "office365",
-      "windows",
-      "amazon",
-      "aws",
-      "paypal",
-      "venmo",
-      "stripe",
-      "visa",
-      "mastercard",
-      "amex",
-      "chase",
-      "wellsfargo",
-      "bankofamerica",
-      "citibank",
-      "hsbc",
-      "barclays",
-      "coinbase",
-      "binance",
-      "kraken",
-      "metamask",
-      "facebook",
-      "instagram",
-      "whatsapp",
-      "meta",
-      "twitter",
-      "netflix",
-      "spotify",
-      "dropbox",
-      "github",
-      "gitlab",
-      "slack",
-      "zoom",
-      "linkedin",
-      "tiktok",
-      "cloudflare",
-      "usps",
-      "ups",
-      "fedex",
-      "dhl",
-      "irs",
-      "gov"
-    ];
-    RESERVED = new Set(RESERVED_NAMES);
-  }
-});
-
 // ../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/helpers/util.js
 var util, objectUtil, ZodParsedType, getParsedType;
 var init_util = __esm({
@@ -5322,6 +5200,151 @@ var init_zod = __esm({
   }
 });
 
+// ../schema/src/query.ts
+var QueryBy, TypeQuery, QueryConfig;
+var init_query = __esm({
+  "../schema/src/query.ts"() {
+    "use strict";
+    init_zod();
+    init_universal();
+    QueryBy = external_exports.object({
+      filter: external_exports.array(external_exports.string().min(1)).min(1),
+      /** Omitted means newest-first, which the appended rowid gives for free. */
+      sort: external_exports.string().min(1).optional()
+    }).strict();
+    TypeQuery = external_exports.object({
+      /** One entry per field you want to filter, range or sort on. */
+      fields: external_exports.array(external_exports.string().min(1)).default([]),
+      /** One entry per COMBINATION: filter+sort, or two filters at once. */
+      by: external_exports.array(QueryBy).default([]),
+      /** The fields full-text search looks in. */
+      search: external_exports.array(external_exports.string().min(1)).default([])
+    }).strict();
+    QueryConfig = external_exports.record(TypeQuery);
+  }
+});
+
+// ../schema/src/names.ts
+var RESERVED_NAMES, RESERVED;
+var init_names = __esm({
+  "../schema/src/names.ts"() {
+    "use strict";
+    RESERVED_NAMES = [
+      // platform & infrastructure
+      "drivethrough",
+      "drivethru",
+      "www",
+      "mail",
+      "smtp",
+      "imap",
+      "ftp",
+      "ns1",
+      "ns2",
+      "api",
+      "cdn",
+      "static",
+      "assets",
+      "status",
+      "docs",
+      "blog",
+      "dev",
+      "app",
+      // auth & account impersonation
+      "login",
+      "logout",
+      "signin",
+      "signup",
+      "auth",
+      "authorize",
+      "oauth",
+      "sso",
+      "secure",
+      "security",
+      "verify",
+      "verification",
+      "activate",
+      "session",
+      "account",
+      "accounts",
+      "admin",
+      "administrator",
+      "root",
+      "password",
+      "passwords",
+      "billing",
+      "payment",
+      "payments",
+      "invoice",
+      "checkout",
+      "wallet",
+      "support",
+      "help",
+      "helpdesk",
+      "service",
+      "official",
+      "update",
+      "updates",
+      "recover",
+      "recovery",
+      "reset",
+      "unlock",
+      "confirm",
+      "settings",
+      // high-value brand impersonation targets
+      "google",
+      "gmail",
+      "youtube",
+      "apple",
+      "icloud",
+      "itunes",
+      "microsoft",
+      "outlook",
+      "office365",
+      "windows",
+      "amazon",
+      "aws",
+      "paypal",
+      "venmo",
+      "stripe",
+      "visa",
+      "mastercard",
+      "amex",
+      "chase",
+      "wellsfargo",
+      "bankofamerica",
+      "citibank",
+      "hsbc",
+      "barclays",
+      "coinbase",
+      "binance",
+      "kraken",
+      "metamask",
+      "facebook",
+      "instagram",
+      "whatsapp",
+      "meta",
+      "twitter",
+      "netflix",
+      "spotify",
+      "dropbox",
+      "github",
+      "gitlab",
+      "slack",
+      "zoom",
+      "linkedin",
+      "tiktok",
+      "cloudflare",
+      "usps",
+      "ups",
+      "fedex",
+      "dhl",
+      "irs",
+      "gov"
+    ];
+    RESERVED = new Set(RESERVED_NAMES);
+  }
+});
+
 // ../schema/src/site-config.ts
 function parseSiteConfig(input) {
   const result = SiteConfig.safeParse(input);
@@ -5334,11 +5357,12 @@ function parseSiteConfig(input) {
   }
   return { ok: true, config: result.data };
 }
-var FieldSpec, RateLimit, TYPE_NAME, TypeConfig, IndexDecl, SiteConfig;
+var FieldSpec, RateLimit, TYPE_NAME, TypeConfig, SiteConfig;
 var init_site_config = __esm({
   "../schema/src/site-config.ts"() {
     "use strict";
     init_zod();
+    init_query();
     FieldSpec = external_exports.enum(["string", "string?", "number", "number?", "boolean", "boolean?"]);
     RateLimit = external_exports.string().regex(/^\d+\/(minute|hour|day)$/, 'rate_limit must look like "5/hour"');
     TYPE_NAME = external_exports.string().regex(/^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$/, "type names are lowercase letters, numbers, hyphens and underscores").max(64);
@@ -5364,10 +5388,6 @@ var init_site_config = __esm({
       parent_types: external_exports.array(external_exports.string().min(1)).optional(),
       rate_limit: RateLimit.optional()
     }).strict();
-    IndexDecl = external_exports.object({
-      type: external_exports.string().min(1),
-      path: external_exports.string().regex(/^\$(\.[A-Za-z0-9_]+)+$/, 'index paths are scalar JSON paths like "$.date"')
-    }).strict();
     SiteConfig = external_exports.object({
       /** Sitename: lowercase alphanumeric + hyphens, unique per user. */
       site: external_exports.string().regex(/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/, "site is lowercase letters, numbers and hyphens").optional(),
@@ -5378,7 +5398,12 @@ var init_site_config = __esm({
       // cannot be parameterised. Keeping them to this alphabet is what makes that
       // interpolation safe, rather than relying on escaping at each use.
       types: external_exports.record(TYPE_NAME, TypeConfig).default({}),
-      indexes: external_exports.array(IndexDecl).default([]),
+      /**
+       * What each type's pages will filter, sort and search on. One entry is one
+       * index is one extra billed write per row of that type; an undeclared query
+       * is refused rather than allowed to scan (query surface §1, §4).
+       */
+      query: QueryConfig.default({}),
       /** Pro (§3): additive custom-schema SQL applied to the site database. */
       schema: external_exports.string().max(2e4).optional()
     }).strict();
@@ -5397,6 +5422,7 @@ var init_src = __esm({
   "../schema/src/index.ts"() {
     "use strict";
     init_universal();
+    init_query();
     init_names();
     init_site_config();
     init_bundle();
@@ -24327,59 +24353,81 @@ function registerTools(server, ctx) {
     "query_db",
     {
       title: "Query site database",
-      description: "Read the site's database as its owner (read-only \u2014 writes go through write_db): list the types present with row counts, list rows of a type, or fetch one row by id. Every row is {id, parent_id, type, json, created_at} \u2014 json is the document. Owner access skips visitor-side permission checks.",
+      description: 'Read the site\'s database as its owner (read-only \u2014 writes go through write_db). Same query surface the site\'s own pages use, so what works here works there. Every row is {seq, type, parent_seq, json, created_at, updated_at}: `seq` is the row number and its permanent identity (never reused, even after a delete), `json` is the document. Newest-first is the default and always free. Filtering, sorting and search need a matching entry in the site\'s "query" block in drivethrough.json \u2014 an undeclared query is refused with the exact line to add. As the owner you get a bounded 5,000-row scan instead of a refusal, marked "partial": true, so you can look at data you have not modelled yet; a visitor page gets the refusal.',
       annotations: { readOnlyHint: true, openWorldHint: false },
       inputSchema: {
         site: external_exports.string().describe("Site name or id"),
-        action: external_exports.enum(["types", "list", "get"]).describe("types = row counts per type; list = rows of a type; get = one row by id"),
+        action: external_exports.enum(["types", "list", "get"]).describe("types = row counts per type; list = rows of a type; get = one row by seq"),
         type: external_exports.string().optional().describe("Row type \u2014 required for list"),
-        id: external_exports.string().optional().describe("Row id \u2014 required for get"),
-        parent_id: external_exports.string().optional().describe("list: return only rows whose parent is this row id"),
+        seq: external_exports.number().int().optional().describe("Row number \u2014 required for get"),
+        filter: external_exports.record(external_exports.unknown()).optional().describe(
+          'list: exact matches, and ranges. Exact: {"genre": "thriller"}. Range: {"year": {"gte": 1990, "lte": 1999}} (also gt, lt). Each field must be listed in query.<type>.fields in drivethrough.json; filtering on two fields at once, or filtering while sorting by a third, additionally needs an entry in query.<type>.by. A range only works when sort names the same field.'
+        ),
+        sort: external_exports.string().optional().describe(
+          'list: a declared field, "-" for descending \u2014 e.g. "-year". Omit for newest-first, which needs no declaration. "created_at" and "-created_at" are always available and always free. Sorting by a field returns only rows that have it.'
+        ),
+        search: external_exports.string().optional().describe(
+          "list: full-text search over the fields in query.<type>.search. Combines with exact `filter` values, but NOT with `sort` (results are ranked by relevance) and NOT with a range. Paged by `offset` up to 1000, never by `cursor`."
+        ),
+        parent_seq: external_exports.number().int().optional().describe("list: only rows whose parent is this row number"),
         limit: external_exports.number().int().optional().describe("list: max rows (default 100, cap 500)"),
-        offset: external_exports.number().int().optional().describe("list: rows to skip, for pagination")
+        cursor: external_exports.string().optional().describe(
+          "list: the next page. Take next_cursor from the previous response and pass it back unchanged. Flat cost at any depth \u2014 this is how you read past the first 1,000 rows."
+        ),
+        offset: external_exports.number().int().optional().describe(
+          "list: rows to skip, for numbered pages. Capped at 1000 because offset walks past every row it skips; past that use cursor."
+        ),
+        count: external_exports.boolean().optional().describe(
+          'list: include a result count, counted up to 1,000 and then reported as {"count": 1000, "count_capped": true}. Costs an extra pass \u2014 ask for it only when you are showing the number.'
+        )
       }
     },
-    async ({
-      site,
-      action,
-      type,
-      id,
-      parent_id,
-      limit,
-      offset
-    }) => {
+    async (args) => {
+      const { site, action, type, seq } = args;
       try {
         switch (action) {
           case "types":
             return ok(await ctx.api.request("GET", `${sitePath(site)}/data/types`));
           case "list": {
-            if (parent_id !== void 0 && parent_id === "") {
+            if (!type) {
               throw new ToolApiError(422, {
                 error: {
-                  code: "parent_filter_unsupported",
-                  message: "Filtering to rows WITHOUT a parent isn't supported \u2014 `parent_id` must be a row id.",
-                  next: "List the type without parent_id and select the parent_id === null rows from the result."
+                  code: "missing_type",
+                  message: 'query_db action "list" needs `type`.',
+                  next: 'See what types exist with action "types".'
                 }
               });
             }
-            const params = new URLSearchParams();
-            if (type) params.set("type", type);
-            if (parent_id !== void 0) params.set("parent", parent_id);
-            if (limit !== void 0) params.set("limit", String(limit));
-            if (offset !== void 0) params.set("offset", String(offset));
+            const params = new URLSearchParams({ type });
+            for (const [field, value] of Object.entries(args.filter ?? {})) {
+              if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+                for (const [op, bound] of Object.entries(value)) {
+                  params.set(`filter.${field}.${op}`, String(bound));
+                }
+              } else {
+                params.set(`filter.${field}`, String(value));
+              }
+            }
+            if (args.sort) params.set("sort", args.sort);
+            if (args.search) params.set("search", args.search);
+            if (args.parent_seq !== void 0) params.set("parent", String(args.parent_seq));
+            if (args.limit !== void 0) params.set("limit", String(args.limit));
+            if (args.cursor) params.set("cursor", args.cursor);
+            if (args.offset !== void 0) params.set("offset", String(args.offset));
+            if (args.count) params.set("count", "1");
             return ok(await ctx.api.request("GET", `${sitePath(site)}/data?${params}`));
           }
           case "get": {
-            if (!id) {
+            if (seq === void 0) {
               throw new ToolApiError(422, {
                 error: {
-                  code: "missing_id",
-                  message: 'query_db action "get" needs `id`.',
-                  next: 'Find row ids with action "list".'
+                  code: "missing_seq",
+                  message: 'query_db action "get" needs `seq` \u2014 the row number.',
+                  next: 'Row numbers come back with every row from action "list".'
                 }
               });
             }
-            return ok(await ctx.api.request("GET", `${sitePath(site)}/data?id=${encodeURIComponent(id)}`));
+            return ok(await ctx.api.request("GET", `${sitePath(site)}/data?seq=${encodeURIComponent(String(seq))}`));
           }
         }
       } catch (error2) {
@@ -24391,18 +24439,24 @@ function registerTools(server, ctx) {
     "write_db",
     {
       title: "Write site database",
-      description: "Write to the site's database as its owner: insert, update, or delete rows (reads go through query_db). To change a few fields of a row, `update` with `merge` \u2014 only the fields that change, no fetch needed. Reserve `json` (wholesale replacement) for rewriting the whole document. Writes are validated against the types declared in the site's drivethrough.json (unknown types and mismatched fields are rejected); pass validate: false only for a deliberate migration. Deleted and overwritten rows are gone for good \u2014 there is no version history for data, so read a row (query_db) before destructive rewrites you might need to undo. Daily write quotas apply.",
+      description: "Write to the site's database as its owner: insert one row, import many, update, or delete (reads go through query_db). Rows are addressed by `seq`, the row number query_db returns. To change a few fields of a row, `update` with `merge` \u2014 only the fields that change, no fetch needed. Reserve `json` (wholesale replacement) for rewriting the whole document. To load a catalogue, use `rows` for a handful and `rows_url` for thousands \u2014 never loop insert, and never try to emit 100,000 rows yourself. Writes are validated against the types declared in the site's drivethrough.json (unknown types and mismatched fields are rejected, and a bulk import is checked in full BEFORE the first row is written, so it is all-or-nothing); pass validate: false only for a deliberate migration. Deleted and overwritten rows are gone for good \u2014 there is no version history for data, so read a row (query_db) before destructive rewrites you might need to undo. Deleting a row also deletes its children. Every write counts against the account's monthly write allowance, and an import larger than what remains is refused before anything is written.",
       annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
       inputSchema: {
         site: external_exports.string().describe("Site name or id"),
         action: external_exports.enum(["insert", "update", "delete"]).describe("What to do with the row"),
         type: external_exports.string().optional().describe("Row type \u2014 required for insert"),
-        id: external_exports.string().optional().describe("Row id \u2014 required for update and delete"),
-        parent_id: external_exports.string().nullable().optional().describe("Parent row id to set on insert/update (null clears it)"),
-        json: external_exports.record(external_exports.unknown()).optional().describe("The row's full document \u2014 required for insert; a wholesale replacement on update (prefer `merge`)"),
+        seq: external_exports.number().int().optional().describe("Row number \u2014 required for update and delete"),
+        parent_seq: external_exports.number().int().nullable().optional().describe("Parent row NUMBER to set on insert/update (null clears it). The parent must exist."),
+        json: external_exports.record(external_exports.unknown()).optional().describe("The row's full document \u2014 for a single insert; a wholesale replacement on update (prefer `merge`)"),
         merge: external_exports.record(external_exports.unknown()).optional().describe(
           "update: change only these fields, merged into the row's existing document (RFC 7386: nested objects merge, null deletes a field). The cheap way to update \u2014 no fetch-modify-resend."
         ),
+        rows: external_exports.array(external_exports.record(external_exports.unknown())).optional().describe(
+          "insert: MANY documents at once, batched into multi-row statements server-side. Use this instead of looping insert \u2014 one row per call costs 50% more in billed writes and one HTTP round trip each. Answers {inserted, writes_charged, first_seq, last_seq} rather than the rows themselves. Up to a few thousand rows; past that use rows_url. One import carries at most 100,000 rows."
+        ),
+        rows_url: external_exports.string().optional().describe(
+          "insert: a public https URL the platform fetches server-side, the same way deploy_site {path, source_url} fetches an image. NDJSON (one JSON object per line), CSV with a header row, or a JSON array. This is how a large catalogue gets loaded at all \u2014 you never hold the data. `created_at` is always the moment the platform wrote the row and is never read from the file; a row's own date is an ordinary declared field. Answers {inserted, writes_charged, first_seq, last_seq}. At most 100,000 rows per import \u2014 split a bigger file and import the parts."
+        ),
         validate: external_exports.boolean().optional().describe("insert/update: set false to bypass declared-type validation \u2014 only for deliberate migrations")
       }
     },
@@ -24410,24 +24464,26 @@ function registerTools(server, ctx) {
       site,
       action,
       type,
-      id,
-      parent_id,
+      seq,
+      parent_seq,
       json,
       merge: merge2,
+      rows,
+      rows_url,
       validate: validate2
     }) => {
       try {
-        const needId = () => {
-          if (!id) {
+        const needSeq = () => {
+          if (seq === void 0) {
             throw new ToolApiError(422, {
               error: {
-                code: "missing_id",
-                message: `write_db action "${action}" needs \`id\`.`,
-                next: 'Find row ids with query_db action "list".'
+                code: "missing_seq",
+                message: `write_db action "${action}" needs \`seq\` \u2014 the row number.`,
+                next: 'Row numbers come back with every row from query_db action "list".'
               }
             });
           }
-          return id;
+          return seq;
         };
         switch (action) {
           case "insert": {
@@ -24435,8 +24491,8 @@ function registerTools(server, ctx) {
               throw new ToolApiError(422, {
                 error: {
                   code: "merge_not_for_insert",
-                  message: "`merge` applies to update only \u2014 insert takes the row's full document in `json`.",
-                  next: "Pass the document as `json`."
+                  message: "`merge` applies to update only \u2014 insert takes the row's document in `json`.",
+                  next: "Pass one document as `json`, many as `rows`, or a file as `rows_url`."
                 }
               });
             }
@@ -24449,18 +24505,40 @@ function registerTools(server, ctx) {
                 }
               });
             }
+            if (rows !== void 0 || rows_url !== void 0) {
+              if (json !== void 0) {
+                throw new ToolApiError(422, {
+                  error: {
+                    code: "ambiguous_bulk_write",
+                    message: "Pass `json` for one row, or `rows`/`rows_url` for many \u2014 not both.",
+                    next: "Drop `json` and put that document in `rows` alongside the others."
+                  }
+                });
+              }
+              return ok(
+                await ctx.api.request("POST", `${sitePath(site)}/data`, {
+                  body: {
+                    type,
+                    ...parent_seq !== void 0 ? { parent_seq } : {},
+                    ...rows !== void 0 ? { rows } : {},
+                    ...rows_url !== void 0 ? { rows_url } : {},
+                    ...validate2 !== void 0 ? { validate: validate2 } : {}
+                  }
+                })
+              );
+            }
             if (json === void 0) {
               throw new ToolApiError(422, {
                 error: {
                   code: "missing_json",
                   message: 'write_db action "insert" needs `json` \u2014 the row\'s document.',
-                  next: "Pass json: {} explicitly if the row is deliberately empty."
+                  next: "Pass json: {} explicitly if the row is deliberately empty, or use `rows` to insert many at once."
                 }
               });
             }
             return ok(
               await ctx.api.request("POST", `${sitePath(site)}/data`, {
-                body: { type, parent_id, json, ...validate2 !== void 0 ? { validate: validate2 } : {} }
+                body: { type, parent_seq, json, ...validate2 !== void 0 ? { validate: validate2 } : {} }
               })
             );
           }
@@ -24475,10 +24553,10 @@ function registerTools(server, ctx) {
               });
             }
             return ok(
-              await ctx.api.request("PATCH", `${sitePath(site)}/data/${encodeURIComponent(needId())}`, {
+              await ctx.api.request("PATCH", `${sitePath(site)}/data/${encodeURIComponent(String(needSeq()))}`, {
                 body: {
                   ...type !== void 0 ? { type } : {},
-                  ...parent_id !== void 0 ? { parent_id } : {},
+                  ...parent_seq !== void 0 ? { parent_seq } : {},
                   ...json !== void 0 ? { json } : {},
                   ...merge2 !== void 0 ? { merge: merge2 } : {},
                   ...validate2 !== void 0 ? { validate: validate2 } : {}
@@ -24486,7 +24564,9 @@ function registerTools(server, ctx) {
               })
             );
           case "delete":
-            return ok(await ctx.api.request("DELETE", `${sitePath(site)}/data/${encodeURIComponent(needId())}`));
+            return ok(
+              await ctx.api.request("DELETE", `${sitePath(site)}/data/${encodeURIComponent(String(needSeq()))}`)
+            );
         }
       } catch (error2) {
         return toolError(error2);
@@ -24676,6 +24756,7 @@ Work token-efficiently \u2014 generated output is your scarcest resource:
 - EDIT, don't resend: change existing files with edit_site (exact find/replace). Never re-emit a whole file to change a small part. Use deploy_site mode "patch" for new files or wholesale rewrites \u2014 unchanged files carry forward automatically.
 - REFERENCE, don't inline: never base64-encode a file \u2014 not by hand, not in code, and never as a data: URI in HTML. To ship an image or other binary asset, pick the route by where the bytes live: already at a public URL \u2192 deploy_site {path, source_url}, fetched server-side; a local file (the user's, or a chat attachment already in your runtime) \u2192 create_upload returns a link the user opens in their browser to drag files in; when they say done, call create_upload {session} for the upload_ids, then deploy_site {path, upload_id}. (Only when this server itself runs on the user's machine \u2014 the CLI \u2014 is there a \`directory\` parameter to deploy instead, binaries riding along; your own sandbox is not that machine, and files you generate there deploy fine as \`content\`.) To move or duplicate an ALREADY-DEPLOYED file, {path, from_path} copies it server-side \u2014 never re-upload unchanged bytes, and once an upload_id exists, reference it rather than inlining the same bytes again. Inline base64 content is capped at 1 MB and exists only for tiny pasted assets like a favicon.
 - MERGE, don't replace: to change a few fields of a database row, write_db update with \`merge\` (null deletes a field). No need to fetch the row first.
+- DECLARE queries, don't scan: a page that filters, sorts or searches its data needs a \`query\` block in drivethrough.json. An undeclared query is REFUSED at request time with the exact line to add \u2014 follow it rather than working around it. Newest-first needs no declaration and is always free.
 - UNDO by version, never by inverse edits: every deploy is a numbered version the platform keeps. When the user wants a change undone, call revert_site \u2014 it restores the exact bytes of any prior version in one call and proves it. Reconstructing old content from memory with edit_site is how sites end up in a state that is neither old nor new.
 - LOOK at what shipped: you have no browser, but preview_site returns a real rendered screenshot of any version \u2014 your only way to see visual results. Use it after layout/style/animation work, or to eyeball an old version before reverting.
 - DON'T overwrite unseen work: when you already know the deployed version (an earlier get_site or deploy in THIS conversation), pass it to deploy_site as \`base_version\` \u2014 if the site moved past it (another session deployed), the deploy is refused with a summary of what changed instead of clobbering it. Never make an extra call just to learn the version; omit it instead. edit_site guards itself. On a \`remote_changes\` refusal, read what changed (get_site {history: true}), fold it in, then redeploy with the current version.
@@ -24697,6 +24778,47 @@ RECIPE \u2014 public form that saves to the site's database (RSVPs, leads, guest
 5. Anonymous visitors only reach a public site (set_privacy) or a shared one \u2014 on a private site the form works for invited viewers.
 6. Verify \u2014 you have no browser, so the deploy response is your feedback loop: it returns \`warnings\` when an anonymously-writable type has no Turnstile widget on any page, and when a page fetches a type its visitors aren't allowed to read (the fetch 403s inside THEIR browser; the page looks perfect to you because you're the owner). Never report success while a warning stands. Then have the user submit once and query_db {action: "list", type: "lead"} to show the row landed. (Local dev accepts any turnstile_token \u2014 the test secret always passes \u2014 so there a scripted POST to /api/data proves the whole path.)
 
+RECIPE \u2014 a searchable, filterable list (catalogue, directory, archive)
+1. Declare the type and its fields in drivethrough.json.
+2. Declare the queries the page will make:
+     "query": { "movie": { "fields": ["genre", "year"],
+                           "by":     [{"filter": ["genre"], "sort": "year"}],
+                           "search": ["title", "director"] } }
+   - "fields": one entry per field you filter, range or sort on.
+   - "by": one entry per COMBINATION \u2014 filtering on one field while sorting by
+     another, or filtering on two at once. Omit "sort" for newest-first.
+   - "search": the fields full-text search looks in.
+   One entry = one index = one extra billed write per row of that type. Declare
+   only what a page actually uses; newest-first needs no declaration. Every
+   field named here must also exist in that type's "fields", or the deploy fails.
+3. Deploy. The response carries \`query_plan\`: the indexes built, the cost per
+   insert in billed writes, and \u2014 when a declaration is added to a type that
+   already has rows \u2014 what re-indexing them will cost. Turning search on for
+   existing rows runs in the BACKGROUND: searches work immediately and return
+   \`"search_status": "building"\` until it finishes. It never blocks the deploy.
+4. Load the data:
+     write_db {action: "insert", type: "movie", rows: [ ... ]}          a handful
+     write_db {action: "insert", type: "movie", rows_url: "https://\u2026/movies.ndjson"}   thousands
+   Never loop single inserts \u2014 it costs 50% more and one round trip per row.
+   An import bigger than the month's remaining write allowance is refused
+   BEFORE anything is written, so a catalogue is never half-loaded.
+5. Fetch from the page, same origin:
+     /api/data?type=movie&filter.genre=thriller&sort=-year&limit=50
+     /api/data?type=movie&filter.year.gte=1990&filter.year.lte=1999&sort=-year
+     /api/data?type=movie&search=crimson
+   The response is {items, next_cursor}. Pass next_cursor back as &cursor=\u2026 for
+   the next page \u2014 flat cost at any depth. &offset= works too but is capped at
+   1000. &count=1 adds a count, capped at 1,000 with "count_capped": true.
+   Each item is {seq, type, parent_seq, json, created_at, updated_at}.
+6. What is REFUSED, so you don't guess: filtering or sorting on an undeclared
+   field; a combination with no "by" entry; a range not sorted by that same
+   field; search together with sort= or with a range; a cursor from a different
+   query; offset past 1000. Every refusal names the file, the key and the value
+   to add \u2014 follow it.
+7. Verify: you have no browser, so read the deploy \`warnings\`. They name a page
+   whose query the config doesn't declare (it will render empty for visitors),
+   and a declaration no page uses (pure cost on every insert).
+
 Custom domains (paid plans): manage_domain attaches a domain the user already owns. After attaching, check_domain {action: "connect"} looks up one-click setup at their registrar (relay the URL when offered, else the exact DNS records from attach), and check_domain {action: "status"} polls until "active" \u2014 DNS seen, then TLS issued.`;
   }
 });
@@ -26799,11 +26921,11 @@ function isJsonMode(args) {
 function isInteractive(args) {
   return !isJsonMode(args) && !args.yes && process.stdout.isTTY === true && process.env.CI !== "true";
 }
-function emit(args, data, human) {
+function emit(args, data, human2) {
   if (isJsonMode(args)) {
     process.stdout.write(JSON.stringify({ ok: true, ...data }, null, 2) + "\n");
   } else {
-    human();
+    human2();
   }
 }
 function fail(args, error2) {
@@ -27371,9 +27493,14 @@ var listCommand = defineCommand({
   args: {
     site: { type: "positional", description: "Site name", required: true },
     type: { type: "positional", description: "Row type", required: true },
-    parent: { type: "string", description: "Only rows under this parent id" },
+    parent: { type: "string", description: "Only rows under this parent row number" },
+    filter: { type: "string", description: "Declared exact match, e.g. --filter genre=thriller (repeatable)" },
+    sort: { type: "string", description: 'A declared field; "-" for descending, e.g. -year' },
+    search: { type: "string", description: "Full-text search over the declared search fields" },
     limit: { type: "string", description: "Max rows (default 100, cap 500)" },
-    offset: { type: "string", description: "Rows to skip (pagination)" },
+    cursor: { type: "string", description: "next_cursor from the previous page" },
+    offset: { type: "string", description: "Rows to skip (numbered pages, capped at 1000)" },
+    count: { type: "boolean", description: "Include a result count (capped at 1,000)" },
     json: { type: "boolean", description: "Machine-readable output" }
   },
   async run({ args }) {
@@ -27381,8 +27508,16 @@ var listCommand = defineCommand({
     try {
       const params = new URLSearchParams({ type: args.type });
       if (args.parent) params.set("parent", args.parent);
+      for (const raw of [].concat(args.filter ?? [])) {
+        const eq = raw.indexOf("=");
+        if (eq > 0) params.set(`filter.${raw.slice(0, eq)}`, raw.slice(eq + 1));
+      }
+      if (args.sort) params.set("sort", args.sort);
+      if (args.search) params.set("search", args.search);
       if (args.limit) params.set("limit", args.limit);
+      if (args.cursor) params.set("cursor", args.cursor);
       if (args.offset) params.set("offset", args.offset);
+      if (args.count) params.set("count", "1");
       const res = await api("GET", `/v1/sites/${args.site}/data?${params}`);
       emit(jsonArgs, { ...res }, () => {
         if (res.items.length === 0) {
@@ -27390,8 +27525,16 @@ var listCommand = defineCommand({
           return;
         }
         for (const row of res.items) {
-          M2.message(`  ${row.id}  ${JSON.stringify(row.json)}`);
+          M2.message(`  ${row.seq}  ${JSON.stringify(row.json)}`);
+        }
+        if (res.count !== void 0) {
+          M2.message(`  ${res.count}${res.count_capped ? "+" : ""} total`);
         }
+        if (res.search_status === "building") {
+          M2.warn("Search is still indexing existing rows \u2014 these are the ones indexed so far.");
+        }
+        if (res.partial) M2.warn(`Partial result \u2014 this query isn't declared. ${res.declare ?? ""}`);
+        if (res.next_cursor) M2.message(`  next: --cursor ${res.next_cursor}`);
       });
     } catch (error2) {
       fail(jsonArgs, error2);
@@ -27399,10 +27542,10 @@ var listCommand = defineCommand({
   }
 });
 var getCommand = defineCommand({
-  meta: { name: "get", description: "Fetch one row by id" },
+  meta: { name: "get", description: "Fetch one row by its row number" },
   args: {
     site: { type: "positional", description: "Site name", required: true },
-    id: { type: "positional", description: "Row id", required: true },
+    seq: { type: "positional", description: "Row number (seq)", required: true },
     json: { type: "boolean", description: "Machine-readable output" }
   },
   async run({ args }) {
@@ -27410,7 +27553,7 @@ var getCommand = defineCommand({
     try {
       const res = await api(
         "GET",
-        `/v1/sites/${args.site}/data?id=${encodeURIComponent(args.id)}`
+        `/v1/sites/${args.site}/data?seq=${encodeURIComponent(args.seq)}`
       );
       emit(jsonArgs, { item: res.items[0] }, () => {
         M2.message(JSON.stringify(res.items[0], null, 2));
@@ -27659,27 +27802,44 @@ var collaboratorsCommand = defineCommand({
 
 // src/commands/usage.ts
 init_api();
+function human(value, unit) {
+  if (unit === "bytes") {
+    if (value >= 1024 ** 3) return `${(value / 1024 ** 3).toFixed(2)} GB`;
+    return `${(value / 1024 ** 2).toFixed(1)} MB`;
+  }
+  return value.toLocaleString("en-US");
+}
 var usageCommand = defineCommand({
-  meta: { name: "usage", description: "Show a site's storage, writes, and index suggestions" },
+  meta: { name: "usage", description: "Show this month's usage against your plan's limits" },
   args: {
-    site: { type: "positional", description: "Site name", required: true },
+    site: { type: "positional", description: "Site name (omit for the account rollup)", required: false },
     json: { type: "boolean", description: "Machine-readable output" }
   },
   async run({ args }) {
     const jsonArgs = { json: args.json };
     try {
+      if (!args.site) {
+        const usage2 = await api("GET", `/v1/usage`);
+        emit(jsonArgs, { ...usage2 }, () => {
+          M2.message(`Plan: ${usage2.plan} \u2014 resets ${new Date(usage2.period.resets_at).toDateString()}`);
+          for (const meter of usage2.meters) {
+            const line = `${meter.label.padEnd(18)} ${human(meter.used, meter.unit)} / ${human(meter.limit, meter.unit)} (${meter.percent}%)${meter.lagged ? " ~" : ""}`;
+            if (meter.state === "over") M2.error(line);
+            else if (meter.state === "warn") M2.warn(line);
+            else M2.message(line);
+          }
+        });
+        return;
+      }
       const usage = await api("GET", `/v1/sites/${args.site}/usage`);
       emit(jsonArgs, { ...usage }, () => {
-        M2.message(`Storage:    ${(usage.storage_bytes / 1024 / 1024).toFixed(2)} MB`);
+        M2.message(`Storage:      ${(usage.storage_bytes / 1024 / 1024).toFixed(2)} MB`);
         M2.message(`Writes today: ${usage.d1_writes_today}`);
-        M2.message(`Rows read today: ${usage.rows_read_today}`);
-        if (usage.index_suggestions.length) {
-          M2.warn("Index suggestions (add to drivethrough.json \u2192 indexes):");
-          for (const s2 of usage.index_suggestions) {
-            M2.message(`  { "type": "${s2.type}", "path": "${s2.path}" } \u2014 ${s2.reason}`);
-          }
-        } else {
-          M2.success("No index suggestions \u2014 your queries are index-friendly.");
+        M2.message(
+          `Database:     ${usage.db_size_bytes === null ? "unknown" : `${(usage.db_size_bytes / 1024 / 1024).toFixed(2)} MB`} of ${(usage.db_cap_bytes / 1024 / 1024).toFixed(0)} MB`
+        );
+        if (usage.query_indexes.length) {
+          M2.message(`Query indexes: ${usage.query_indexes.join(", ")}`);
         }
       });
     } catch (error2) {
@@ -27769,15 +27929,115 @@ Declare data types the site collects. The platform owns the write path.
   \`"read": "public"\` explicitly to publish submissions, e.g. a public guestbook.
 - \`unique_per: "session"\`: the row edits itself (an RSVP updates, never duplicates).
 - \`notify: "owner-email"\`: the owner gets an email on each entry (leads/RSVPs).
-- \`indexes\`: [{ "type": "event", "path": "$.date" }] for larger datasets.
 
 Deploying a drivethrough.json with types auto-provisions the site's database.
 
+## Filtering, sorting and searching \u2014 the \`query\` block
+
+**A query is either declared, or it is refused.** There is no third state where
+a visitor's dropdown quietly scans the whole table, because a page whose cost
+grows with the table is a page that gets slower as the site gets more popular.
+
+\`\`\`json
+{
+  "types": {
+    "movie": {
+      "write": "owner", "read": "public",
+      "fields": { "title": "string", "genre": "string", "year": "number", "director": "string" }
+    }
+  },
+  "query": {
+    "movie": {
+      "fields": ["genre", "year"],
+      "by":     [{ "filter": ["genre"], "sort": "year" }],
+      "search": ["title", "director"]
+    }
+  }
+}
+\`\`\`
+
+Three keys, and they are the whole model:
+- \`fields\` \u2014 one entry per field you filter, range or sort on.
+- \`by\` \u2014 one entry per COMBINATION: filtering on one field while sorting by
+  another, or filtering on two at once. Omit \`sort\` for newest-first.
+- \`search\` \u2014 the fields full-text search looks in.
+
+One entry = one index = one extra billed write on every row of that type, so
+declare only what a page actually uses. Every field named under \`query\` must
+also exist in that type's \`fields\`, or the deploy fails. An insert may cost at
+most 8 billed writes per type (2 base + up to 5 shapes + search).
+
+**Newest-first needs no declaration and is always free** \u2014 \`sort=-created_at\`
+(the default) and \`sort=created_at\` are served by an index every site already
+has. A document's own date (a post's publish date, an event's start) is an
+ordinary field you declare like any other; it is content, not bookkeeping.
+
+The deploy response carries \`query_plan\`: the indexes built, the cost per
+insert, and \u2014 when you add a declaration to a type that already has rows \u2014 what
+re-indexing them will cost, before it happens.
+
 ## Client-side data access
 Static pages call the same-origin Data API \u2014 no SDK required:
-- \`POST /api/data\` with JSON \`{type, json: {\u2026fields}, turnstile_token?}\`
+- \`POST /api/data\` with JSON \`{type, json: {\u2026fields}, parent_seq?, turnstile_token?}\`
   inserts (turnstile_token only for anonymous writes \u2014 wiring above).
-- \`GET /api/data?type=X\` \u2192 \`{items}\` lists the rows the caller may read.
+- \`GET /api/data?type=X\` \u2192 \`{items, next_cursor}\` lists the rows the caller
+  may read. Each item is \`{seq, type, parent_seq, json, created_at, updated_at}\`.
+  \`seq\` is the row number and its permanent identity \u2014 never reused, so a URL
+  like \`/movie/402\` can never come back pointing at a different row.
+
+Everything a page can ask for, in full:
+\`\`\`
+GET /api/data
+  ?type=movie                     required \u2014 which kind of row
+  &filter.genre=thriller          exact match on a declared field
+  &filter.year.gte=1990           range: .gte .lte .gt .lt
+  &search=crimson midnight        full-text over declared search fields
+  &sort=-year                     declared field; "-" means descending
+  &limit=50                       1\u2013500, default 100
+  &cursor=eyJ2IjoxLCJzIjo\u2026        next page (next_cursor from the last response)
+  &offset=200                     0\u20131000 only; past that, use cursor
+  &count=1                        include a count, capped at 1,000
+  &parent=41                      only rows whose parent is this row
+\`\`\`
+
+**Pagination:** pass \`next_cursor\` back as \`&cursor=\u2026\` \u2014 flat cost at any
+depth, which is how a page reads past its first 1,000 rows. \`offset\` is a
+convenience for numbered pages ("page 3") and is capped at 1000, because it
+walks past every row it skips.
+
+**Search** is ranked by relevance, so it does NOT combine with \`sort=\` or with
+a range, and it pages by \`offset\` (up to 1000) rather than by cursor. It does
+combine with exact \`filter\` values. While a newly-declared search is still
+indexing existing rows, responses carry \`"search_status": "building"\` \u2014 show
+the results you got, not an empty state.
+
+**What gets refused, so you don't guess:** filtering or sorting on a field not
+in \`query.<type>.fields\`; a combination with no \`by\` entry; a range not sorted
+by that same field; \`search\` with \`sort\` or with a range; a cursor from a
+different query; \`offset\` past 1000. Every refusal is
+\`{error: {code, message, next}}\` and \`next\` names the file, the key and the
+value to add \u2014 follow it rather than working around it.
+
+## Loading a lot of data
+Never loop single inserts: one row per call costs 50% more in billed writes and
+one HTTP round trip each.
+- A handful to a few thousand rows: \`write_db {action: "insert", type, rows: [...]}\`
+  \u2014 batched into ~250-row statements server-side.
+- Thousands and up: \`write_db {action: "insert", type, rows_url: "https://\u2026/movies.ndjson"}\`
+  \u2014 the platform fetches and parses it server-side (NDJSON, CSV with a header
+  row, or a JSON array), so you never have to hold or emit the data. This is the
+  only way a large catalogue gets loaded at all.
+
+\`created_at\` is always the moment the platform wrote the row and is never read
+from an import \u2014 that is what keeps free newest-first ordering honest. A row's
+own date is an ordinary declared field.
+
+Writes count against the account's monthly allowance (5,000 / 50,000 / 250,000
+on Free / Personal / Pro), owner writes included, and so do index rebuilds and
+search backfills. An import bigger than what remains is refused **before the
+first row is written** \u2014 the error names all three ways out: import fewer rows,
+wait for the reset date it gives you, or upgrade. A half-loaded catalogue is a
+bug, not a degraded success, so this never partially succeeds.
 A typed helper ships in the starter template and keeps it legible:
 \`\`\`ts
 import { data } from "./lib/data";           // ships in the starter template
@@ -27798,13 +28058,17 @@ continue in a later session:
 - \`drivethrough files <site> --json\` \u2014 the deployed version's manifest and
   file contents (or one file: \`drivethrough files <site> /index.html\`).
 - \`drivethrough data types <site>\` / \`data list <site> <type>\` /
-  \`data get <site> <id>\` \u2014 inspect the site's database rows.
+  \`data get <site> <seq>\` \u2014 inspect the site's database rows.
 - MCP: \`get_site\` and \`query_db\` do the same. Reads and writes are separate
-  tools: \`query_db\` lists types, lists rows, and fetches one row; \`write_db\`
-  inserts, updates, and deletes. Writes are validated against the site's
-  declared types \u2014 pass \`validate: false\` only for deliberate migrations \u2014
-  and update with \`merge\` to change a few fields without resending the
-  document.
+  tools: \`query_db\` lists types, lists rows (with the same \`filter\`, \`sort\`,
+  \`search\`, \`cursor\` and \`count\` the pages use), and fetches one row by
+  \`seq\`; \`write_db\` inserts, imports, updates, and deletes. Writes are
+  validated against the site's declared types \u2014 pass \`validate: false\` only for
+  deliberate migrations \u2014 and update with \`merge\` to change a few fields
+  without resending the document. As the owner, a query the config doesn't
+  declare gives you a bounded 5,000-row scan marked \`"partial": true\` instead
+  of a refusal, so you can explore data you haven't modelled \u2014 but a visitor
+  page gets the refusal, so declare it before shipping the page.
 - Locate before you read: \`get_site\` with \`find\` searches the deployed text
   files and returns byte-exact matching lines; \`manifest_only\` lists files
   without contents. Read whole files only when you truly need them.
@@ -27903,12 +28167,20 @@ This project deploys to Drivethrough. Use the \`drivethrough\` CLI (alias \`dt\`
   so a deploy over unseen remote changes is refused (409 remote_changes) \u2014
   sync down and redeploy; \`--force\` overwrites (revert can restore).
 - Sites are private by default; share with \`drivethrough share <site>\`.
-- Declare data behavior in \`drivethrough.json\` (types, fields, write policy).
+- Declare data behavior in \`drivethrough.json\`: \`types\` (fields, write/read
+  policy) and \`query\` (what pages filter, sort and search on). A query the
+  config doesn't declare is REFUSED at request time with the exact line to add;
+  newest-first needs no declaration. One query entry = one index = one extra
+  billed write per row.
+- Load data with \`write_db {rows: [...]}\` or \`{rows_url: "https://\u2026"}\` \u2014 never
+  a loop of single inserts. An import over the month's remaining write allowance
+  is refused before anything is written.
 - Read back what's live: \`drivethrough files <site> --json\` (deployed bundle)
-  and \`drivethrough data types|list|get\` (database rows). Inspection only \u2014
+  and \`drivethrough data types|list|get\` (database rows, addressed by \`seq\`). Inspection only \u2014
   this repo wins AFTER sync-down; never overwrite repo \`src/\` with read-back
   content (the deployed bundle is built output). Sync, edit here, rebuild,
   redeploy.
+- Check this month's usage against every limit: \`drivethrough usage --json\`.
 - Every command supports \`--json\` and non-interactive mode.
 - Full guide: run \`drivethrough agent-setup --skill\` for SKILL.md.
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drivethrough-cli",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Agent-first hosting CLI. Say what you want. Stay in the car.",
   "type": "module",
   "license": "MIT",