@helipod/admin 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,126 @@
+import { JSONValue, ValidatorJSON } from '@helipod/values';
+import { MigrationDump } from '@helipod/docstore';
+import { EmbeddedRuntime } from '@helipod/runtime-embedded';
+import { RegisteredFunction, LogSink, IndexCatalog, LogFilter, ExecutionLogEntry } from '@helipod/executor';
+import { ComparisonOp } from '@helipod/query-engine';
+
+/** A fresh url-safe admin key (192 bits of entropy). */
+declare function generateAdminKey(): string;
+/** Constant-time comparison; false for a missing or wrong-length key. */
+declare function verifyAdminKey(expected: string, presented: string | undefined): boolean;
+
+interface FilterCond {
+    field: string;
+    op: ComparisonOp;
+    value: JSONValue;
+}
+/** Privileged, subscribable table browser. Reads any full-named table via cursor paginate + filters. */
+declare const browseTableModule: RegisteredFunction;
+
+type SchemaJsonLike = {
+    tables: Record<string, {
+        indexes: {
+            indexDescriptor: string;
+        }[];
+        shardKey?: string | null;
+        documentType?: ValidatorJSON;
+    }>;
+};
+type ManifestLike = {
+    path: string;
+    functions: {
+        name: string;
+        type: string;
+    }[];
+}[];
+interface AdminDeps {
+    runtime: EmbeddedRuntime;
+    schemaJson: SchemaJsonLike;
+    tableNumbers: Record<string, number>;
+    manifest: ManifestLike;
+    logSink: LogSink;
+    /** Optional — when provided, component tables (not in schemaJson) are enumerated. */
+    catalog?: IndexCatalog;
+}
+interface TableInfo {
+    name: string;
+    indexes: string[];
+    shardKey?: string;
+    documentCount: number;
+}
+interface TableDataPage {
+    documents: JSONValue[];
+    nextCursor: string | null;
+    hasMore: boolean;
+    scanCapped: boolean;
+}
+declare class AdminApi {
+    private readonly deps;
+    constructor(deps: AdminDeps);
+    private tableId;
+    listTables(): Promise<TableInfo[]>;
+    getTableData(table: string, opts?: {
+        cursor?: string | null;
+        pageSize?: number;
+        filter?: FilterCond[];
+    }): Promise<TableDataPage>;
+    listFunctions(): {
+        path: string;
+        kind: string;
+    }[];
+    queryLogs(filter?: LogFilter): ExecutionLogEntry[];
+    runFunction(path: string, args: JSONValue): Promise<{
+        value: JSONValue;
+        committed: boolean;
+    }>;
+    patchDocument(id: string, fields: Record<string, JSONValue>): Promise<JSONValue>;
+    deleteDocument(id: string): Promise<void>;
+    createDocument(table: string, fields: Record<string, JSONValue>): Promise<JSONValue>;
+    /** Swap the schema/tableNumbers/manifest the data browser + validation read — after a live deploy. */
+    setSchema(schemaJson: AdminDeps["schemaJson"], tableNumbers: Record<string, number>, manifest: AdminDeps["manifest"]): void;
+    /** The live schema + tableNumbers — a deploy diffs its new schema against this. */
+    getSchema(): {
+        schemaJson: AdminDeps["schemaJson"];
+        tableNumbers: Record<string, number>;
+    };
+    /**
+     * Export this deployment's full current materialized state to a portable {@link MigrationDump}
+     * (every live document + every current index row + the table-number map). Reachable via
+     * `GET /_admin/export` on BOTH the container `serve` path AND the Cloudflare DO host (both funnel
+     * `/_admin/*` through the same handler). Uses the store's `dumpCurrentState()` primitive — the same
+     * one the R2 snapshot mechanism uses — so ids and `_creationTime` round-trip verbatim.
+     */
+    exportDump(): Promise<MigrationDump>;
+    /**
+     * Import a {@link MigrationDump} into this deployment. Runs the table-number collision guard FIRST
+     * (refuses a dump whose numbers would serve rows under the wrong table), applies the rows via the
+     * store's `write(..., "Overwrite")` overlay, then advances the runtime's timestamp oracle to the
+     * new high-water mark — without which a freshly-booted runtime keeps reading at `ts <= 0` and sees
+     * nothing. Intended for a FRESH target deployment (see `applyDumpToStore`'s note on merge semantics).
+     */
+    importDump(dumpJson: string | unknown): Promise<{
+        ok: true;
+        imported: {
+            documents: number;
+            indexUpdates: number;
+        };
+    }>;
+}
+
+/** Built-in privileged mutations the admin API invokes by id. Registered under `_system:*`. */
+declare function systemModules(): Record<string, RegisteredFunction>;
+
+interface AdminRequest {
+    method: string;
+    path: string;
+    query: Record<string, string>;
+    body?: string;
+    authorization?: string;
+}
+interface AdminResponse {
+    status: number;
+    body: JSONValue;
+}
+declare function handleAdminRequest(api: AdminApi, adminKey: string, req: AdminRequest): Promise<AdminResponse>;
+
+export { AdminApi, type AdminDeps, type AdminRequest, type AdminResponse, type FilterCond, type ManifestLike, type SchemaJsonLike, type TableDataPage, type TableInfo, browseTableModule, generateAdminKey, handleAdminRequest, systemModules, verifyAdminKey };

package/dist/index.js

@@ -0,0 +1,229 @@
+// src/auth.ts
+import { randomBytes, timingSafeEqual } from "crypto";
+function generateAdminKey() {
+  return randomBytes(24).toString("base64url");
+}
+function verifyAdminKey(expected, presented) {
+  if (presented === void 0) return false;
+  const a = Buffer.from(expected);
+  const b = Buffer.from(presented);
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
+
+// src/admin-api.ts
+import { encodeStorageTableId } from "@helipod/id-codec";
+import { convexToJson } from "@helipod/values";
+import {
+  applyDumpToStore,
+  exportDumpFromStore,
+  parseDump
+} from "@helipod/docstore";
+var AdminApi = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  deps;
+  tableId(table) {
+    const n = this.deps.tableNumbers[table];
+    if (n === void 0) throw new Error(`unknown table: ${table}`);
+    return encodeStorageTableId(n);
+  }
+  async listTables() {
+    const out = [];
+    for (const name of Object.keys(this.deps.tableNumbers).sort()) {
+      const schemaDef = this.deps.schemaJson.tables[name];
+      let indexes;
+      let shardKey;
+      if (schemaDef) {
+        indexes = schemaDef.indexes.map((i) => i.indexDescriptor);
+        shardKey = schemaDef.shardKey ?? void 0;
+      } else {
+        indexes = this.deps.catalog ? this.deps.catalog.indexesForTable(name).map((spec) => spec.index) : [];
+        shardKey = void 0;
+      }
+      out.push({
+        name,
+        indexes,
+        shardKey,
+        documentCount: await this.deps.runtime.store.count(this.tableId(name))
+      });
+    }
+    return out;
+  }
+  async getTableData(table, opts = {}) {
+    const args = { table, cursor: opts.cursor ?? null };
+    if (opts.pageSize !== void 0) args.pageSize = opts.pageSize;
+    if (opts.filter !== void 0) args.filter = opts.filter;
+    const r = await this.deps.runtime.runAdmin("_admin:browseTable", args);
+    return r.value;
+  }
+  listFunctions() {
+    return this.deps.manifest.flatMap(
+      (m) => m.functions.map((f) => ({ path: `${m.path}:${f.name}`, kind: f.type }))
+    );
+  }
+  queryLogs(filter) {
+    return this.deps.logSink.query(filter);
+  }
+  async runFunction(path, args) {
+    const r = await this.deps.runtime.run(path, args);
+    return { value: convexToJson(r.value), committed: r.committed };
+  }
+  async patchDocument(id, fields) {
+    const r = await this.deps.runtime.runSystem("_system:patchDocument", { id, fields });
+    return convexToJson(r.value);
+  }
+  async deleteDocument(id) {
+    await this.deps.runtime.runSystem("_system:deleteDocument", { id });
+  }
+  async createDocument(table, fields) {
+    const r = await this.deps.runtime.runSystem("_system:insertDocument", { table, fields });
+    return convexToJson(r.value);
+  }
+  /** Swap the schema/tableNumbers/manifest the data browser + validation read — after a live deploy. */
+  setSchema(schemaJson, tableNumbers, manifest) {
+    this.deps.schemaJson = schemaJson;
+    this.deps.tableNumbers = tableNumbers;
+    this.deps.manifest = manifest;
+  }
+  /** The live schema + tableNumbers — a deploy diffs its new schema against this. */
+  getSchema() {
+    return { schemaJson: this.deps.schemaJson, tableNumbers: this.deps.tableNumbers };
+  }
+  // ── Data migration (Slice 5 — portable ⇄ DO-native) ───────────────────────────────────────────
+  /**
+   * Export this deployment's full current materialized state to a portable {@link MigrationDump}
+   * (every live document + every current index row + the table-number map). Reachable via
+   * `GET /_admin/export` on BOTH the container `serve` path AND the Cloudflare DO host (both funnel
+   * `/_admin/*` through the same handler). Uses the store's `dumpCurrentState()` primitive — the same
+   * one the R2 snapshot mechanism uses — so ids and `_creationTime` round-trip verbatim.
+   */
+  async exportDump() {
+    const deploymentId = await this.deps.runtime.store.getGlobal("fleet:deploymentId");
+    return exportDumpFromStore(this.deps.runtime.store, { tableNumbers: this.deps.tableNumbers, deploymentId });
+  }
+  /**
+   * Import a {@link MigrationDump} into this deployment. Runs the table-number collision guard FIRST
+   * (refuses a dump whose numbers would serve rows under the wrong table), applies the rows via the
+   * store's `write(..., "Overwrite")` overlay, then advances the runtime's timestamp oracle to the
+   * new high-water mark — without which a freshly-booted runtime keeps reading at `ts <= 0` and sees
+   * nothing. Intended for a FRESH target deployment (see `applyDumpToStore`'s note on merge semantics).
+   */
+  async importDump(dumpJson) {
+    const dump = parseDump(dumpJson);
+    const imported = await applyDumpToStore(
+      this.deps.runtime.store,
+      dump,
+      this.deps.tableNumbers
+    );
+    this.deps.runtime.observeTimestamp(await this.deps.runtime.store.maxTimestamp());
+    return { ok: true, imported };
+  }
+};
+
+// src/browse.ts
+import { query } from "@helipod/executor";
+import { convexToJson as convexToJson2 } from "@helipod/values";
+var MAX_SCAN = 1e3;
+var PAGE_SIZE = 50;
+var browseTableModule = query(async (ctx, args) => {
+  const b = ctx.db.query(args.table, "by_creation");
+  for (const c of args.filter ?? []) b.where(c.op, c.field, c.value);
+  const res = await b.paginate({ cursor: args.cursor ?? null, pageSize: args.pageSize ?? PAGE_SIZE, maxScan: MAX_SCAN });
+  return {
+    documents: res.page.map((d) => convexToJson2(d)),
+    nextCursor: res.nextCursor,
+    hasMore: res.hasMore,
+    scanCapped: res.scanCapped
+  };
+});
+
+// src/system-functions.ts
+import { mutation } from "@helipod/executor";
+import { DocumentNotFoundError } from "@helipod/errors";
+function systemModules() {
+  return {
+    "_system:patchDocument": mutation(async (ctx, args) => {
+      const existing = await ctx.db.get(args.id);
+      if (!existing) throw new DocumentNotFoundError(`cannot edit missing document ${args.id}`);
+      await ctx.db.replace(args.id, args.fields);
+      return await ctx.db.get(args.id);
+    }),
+    "_system:deleteDocument": mutation(async (ctx, args) => {
+      await ctx.db.delete(args.id);
+      return null;
+    }),
+    "_system:insertDocument": mutation(async (ctx, args) => {
+      const id = await ctx.db.insert(args.table, args.fields);
+      return await ctx.db.get(id);
+    })
+  };
+}
+
+// src/router.ts
+function bearer(authorization) {
+  if (!authorization) return void 0;
+  const m = /^Bearer (.+)$/.exec(authorization);
+  return m ? m[1] : void 0;
+}
+async function handleAdminRequest(api, adminKey, req) {
+  if (!verifyAdminKey(adminKey, bearer(req.authorization))) {
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  const parts = req.path.split("/").filter(Boolean);
+  const seg = parts.slice(1);
+  try {
+    if (req.method === "GET" && seg.length === 1 && seg[0] === "tables") {
+      return { status: 200, body: await api.listTables() };
+    }
+    if (req.method === "GET" && seg.length === 3 && seg[0] === "tables" && seg[2] === "data") {
+      const cursor = req.query.cursor ?? null;
+      const pageSize = req.query.pageSize ? Number(req.query.pageSize) : void 0;
+      const data = await api.getTableData(decodeURIComponent(seg[1]), { cursor, pageSize });
+      return { status: 200, body: data };
+    }
+    if (req.method === "GET" && seg.length === 1 && seg[0] === "functions") {
+      return { status: 200, body: api.listFunctions() };
+    }
+    if (req.method === "POST" && seg.length === 1 && seg[0] === "run") {
+      const { path, args } = JSON.parse(req.body ?? "{}");
+      if (!path) return { status: 400, body: { error: "missing path" } };
+      return { status: 200, body: await api.runFunction(path, args ?? {}) };
+    }
+    if (req.method === "GET" && seg.length === 1 && seg[0] === "logs") {
+      const since = req.query.since ? Number(req.query.since) : void 0;
+      return { status: 200, body: api.queryLogs({ since }) };
+    }
+    if (req.method === "PATCH" && seg.length === 4 && seg[0] === "tables" && seg[2] === "docs") {
+      const fields = JSON.parse(req.body ?? "{}");
+      return { status: 200, body: await api.patchDocument(seg[3], fields) };
+    }
+    if (req.method === "DELETE" && seg.length === 4 && seg[0] === "tables" && seg[2] === "docs") {
+      await api.deleteDocument(seg[3]);
+      return { status: 200, body: { ok: true } };
+    }
+    if (req.method === "POST" && seg.length === 3 && seg[0] === "tables" && seg[2] === "docs") {
+      const fields = JSON.parse(req.body ?? "{}");
+      return { status: 200, body: await api.createDocument(decodeURIComponent(seg[1]), fields) };
+    }
+    if (req.method === "GET" && seg.length === 1 && seg[0] === "export") {
+      return { status: 200, body: await api.exportDump() };
+    }
+    if (req.method === "POST" && seg.length === 1 && seg[0] === "import") {
+      return { status: 200, body: await api.importDump(req.body ?? "") };
+    }
+    return { status: 404, body: { error: "not found" } };
+  } catch (e) {
+    return { status: 400, body: { error: e instanceof Error ? e.message : String(e) } };
+  }
+}
+export {
+  AdminApi,
+  browseTableModule,
+  generateAdminKey,
+  handleAdminRequest,
+  systemModules,
+  verifyAdminKey
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/auth.ts","../src/admin-api.ts","../src/browse.ts","../src/system-functions.ts","../src/router.ts"],"sourcesContent":["// packages/admin/src/auth.ts\nimport { randomBytes, timingSafeEqual } from \"node:crypto\";\n\n/** A fresh url-safe admin key (192 bits of entropy). */\nexport function generateAdminKey(): string {\n  return randomBytes(24).toString(\"base64url\");\n}\n\n/** Constant-time comparison; false for a missing or wrong-length key. */\nexport function verifyAdminKey(expected: string, presented: string | undefined): boolean {\n  if (presented === undefined) return false;\n  const a = Buffer.from(expected);\n  const b = Buffer.from(presented);\n  if (a.length !== b.length) return false;\n  return timingSafeEqual(a, b);\n}\n","import { encodeStorageTableId } from \"@helipod/id-codec\";\nimport { convexToJson, type JSONValue, type Value, type ValidatorJSON } from \"@helipod/values\";\nimport {\n  applyDumpToStore,\n  exportDumpFromStore,\n  parseDump,\n  type ImportableDocStore,\n  type MigrationDump,\n} from \"@helipod/docstore\";\nimport type { EmbeddedRuntime } from \"@helipod/runtime-embedded\";\nimport type { ExecutionLogEntry, IndexCatalog, LogFilter, LogSink } from \"@helipod/executor\";\nimport type { FilterCond } from \"./browse\";\n\nexport type SchemaJsonLike = {\n  tables: Record<\n    string,\n    {\n      indexes: { indexDescriptor: string }[];\n      shardKey?: string | null;\n      // The real schema always sets this (see SchemaDefinitionJSON in @helipod/values); optional\n      // here only because callers that build a SchemaJsonLike by hand (tests, component tables with\n      // no app-level schema entry) don't always carry it. `helipod deploy`'s schema diff reads it\n      // off the live `AdminApi.getSchema()` snapshot — see DeployDeps[\"current\"] in deploy-apply.ts.\n      documentType?: ValidatorJSON;\n    }\n  >;\n};\nexport type ManifestLike = { path: string; functions: { name: string; type: string }[] }[];\n\nexport interface AdminDeps {\n  runtime: EmbeddedRuntime;\n  schemaJson: SchemaJsonLike;\n  tableNumbers: Record<string, number>;\n  manifest: ManifestLike;\n  logSink: LogSink;\n  /** Optional — when provided, component tables (not in schemaJson) are enumerated. */\n  catalog?: IndexCatalog;\n}\n\nexport interface TableInfo {\n  name: string;\n  indexes: string[];\n  shardKey?: string;\n  documentCount: number;\n}\n\nexport interface TableDataPage {\n  documents: JSONValue[];\n  nextCursor: string | null;\n  hasMore: boolean;\n  scanCapped: boolean;\n}\n\nexport class AdminApi {\n  constructor(private readonly deps: AdminDeps) {}\n\n  private tableId(table: string): string {\n    const n = this.deps.tableNumbers[table];\n    if (n === undefined) throw new Error(`unknown table: ${table}`);\n    return encodeStorageTableId(n);\n  }\n\n  async listTables(): Promise<TableInfo[]> {\n    const out: TableInfo[] = [];\n    for (const name of Object.keys(this.deps.tableNumbers).sort()) {\n      const schemaDef = this.deps.schemaJson.tables[name];\n      let indexes: string[];\n      let shardKey: string | undefined;\n      if (schemaDef) {\n        // App table — use the schema definition.\n        indexes = schemaDef.indexes.map((i) => i.indexDescriptor);\n        shardKey = schemaDef.shardKey ?? undefined;\n      } else {\n        // Component table — derive index info from the catalog.\n        indexes = this.deps.catalog\n          ? this.deps.catalog.indexesForTable(name).map((spec) => spec.index)\n          : [];\n        shardKey = undefined;\n      }\n      out.push({\n        name,\n        indexes,\n        shardKey,\n        documentCount: await this.deps.runtime.store.count(this.tableId(name)),\n      });\n    }\n    return out;\n  }\n\n  async getTableData(\n    table: string,\n    opts: { cursor?: string | null; pageSize?: number; filter?: FilterCond[] } = {},\n  ): Promise<TableDataPage> {\n    const args: Record<string, unknown> = { table, cursor: opts.cursor ?? null };\n    if (opts.pageSize !== undefined) args.pageSize = opts.pageSize;\n    if (opts.filter !== undefined) args.filter = opts.filter;\n    const r = await this.deps.runtime.runAdmin(\"_admin:browseTable\", args as JSONValue);\n    return r.value as TableDataPage;\n  }\n\n  listFunctions(): { path: string; kind: string }[] {\n    return this.deps.manifest.flatMap((m) =>\n      m.functions.map((f) => ({ path: `${m.path}:${f.name}`, kind: f.type })),\n    );\n  }\n\n  queryLogs(filter?: LogFilter): ExecutionLogEntry[] {\n    return this.deps.logSink.query(filter);\n  }\n\n  async runFunction(path: string, args: JSONValue): Promise<{ value: JSONValue; committed: boolean }> {\n    const r = await this.deps.runtime.run(path, args);\n    return { value: convexToJson(r.value as Value), committed: r.committed };\n  }\n\n  async patchDocument(id: string, fields: Record<string, JSONValue>): Promise<JSONValue> {\n    const r = await this.deps.runtime.runSystem(\"_system:patchDocument\", { id, fields });\n    return convexToJson(r.value as Value);\n  }\n\n  async deleteDocument(id: string): Promise<void> {\n    await this.deps.runtime.runSystem(\"_system:deleteDocument\", { id });\n  }\n\n  async createDocument(table: string, fields: Record<string, JSONValue>): Promise<JSONValue> {\n    const r = await this.deps.runtime.runSystem(\"_system:insertDocument\", { table, fields });\n    return convexToJson(r.value as Value);\n  }\n\n  /** Swap the schema/tableNumbers/manifest the data browser + validation read — after a live deploy. */\n  setSchema(schemaJson: AdminDeps[\"schemaJson\"], tableNumbers: Record<string, number>, manifest: AdminDeps[\"manifest\"]): void {\n    this.deps.schemaJson = schemaJson;\n    this.deps.tableNumbers = tableNumbers;\n    this.deps.manifest = manifest;\n  }\n\n  /** The live schema + tableNumbers — a deploy diffs its new schema against this. */\n  getSchema(): { schemaJson: AdminDeps[\"schemaJson\"]; tableNumbers: Record<string, number> } {\n    return { schemaJson: this.deps.schemaJson, tableNumbers: this.deps.tableNumbers };\n  }\n\n  // ── Data migration (Slice 5 — portable ⇄ DO-native) ───────────────────────────────────────────\n\n  /**\n   * Export this deployment's full current materialized state to a portable {@link MigrationDump}\n   * (every live document + every current index row + the table-number map). Reachable via\n   * `GET /_admin/export` on BOTH the container `serve` path AND the Cloudflare DO host (both funnel\n   * `/_admin/*` through the same handler). Uses the store's `dumpCurrentState()` primitive — the same\n   * one the R2 snapshot mechanism uses — so ids and `_creationTime` round-trip verbatim.\n   */\n  async exportDump(): Promise<MigrationDump> {\n    const deploymentId = (await this.deps.runtime.store.getGlobal(\"fleet:deploymentId\")) as string | null;\n    return exportDumpFromStore(this.deps.runtime.store, { tableNumbers: this.deps.tableNumbers, deploymentId });\n  }\n\n  /**\n   * Import a {@link MigrationDump} into this deployment. Runs the table-number collision guard FIRST\n   * (refuses a dump whose numbers would serve rows under the wrong table), applies the rows via the\n   * store's `write(..., \"Overwrite\")` overlay, then advances the runtime's timestamp oracle to the\n   * new high-water mark — without which a freshly-booted runtime keeps reading at `ts <= 0` and sees\n   * nothing. Intended for a FRESH target deployment (see `applyDumpToStore`'s note on merge semantics).\n   */\n  async importDump(dumpJson: string | unknown): Promise<{ ok: true; imported: { documents: number; indexUpdates: number } }> {\n    const dump = parseDump(dumpJson);\n    const imported = await applyDumpToStore(\n      this.deps.runtime.store as unknown as ImportableDocStore,\n      dump,\n      this.deps.tableNumbers,\n    );\n    // Re-floor the read/write snapshot at the imported high-water mark (the same seeding a boot does).\n    this.deps.runtime.observeTimestamp(await this.deps.runtime.store.maxTimestamp());\n    return { ok: true, imported };\n  }\n}\n","import { query, type RegisteredFunction } from \"@helipod/executor\";\nimport { convexToJson, type JSONValue, type Value } from \"@helipod/values\";\nimport type { ComparisonOp } from \"@helipod/query-engine\";\n\nexport interface FilterCond { field: string; op: ComparisonOp; value: JSONValue }\nconst MAX_SCAN = 1000;\nconst PAGE_SIZE = 50;\n\n/** Privileged, subscribable table browser. Reads any full-named table via cursor paginate + filters. */\nexport const browseTableModule: RegisteredFunction = query(async (ctx, args: {\n  table: string; cursor?: string | null; pageSize?: number; filter?: FilterCond[];\n}) => {\n  const b = (ctx as unknown as { db: { query(t: string, i: string): { where(op: ComparisonOp, f: string, v: Value): unknown; paginate(o: { cursor?: string | null; pageSize: number; maxScan: number }): Promise<{ page: unknown[]; nextCursor: string | null; hasMore: boolean; scanCapped: boolean }> } } })\n    .db.query(args.table, \"by_creation\");\n  for (const c of args.filter ?? []) (b as { where(op: ComparisonOp, f: string, v: Value): unknown }).where(c.op, c.field, c.value as Value);\n  const res = await (b as { paginate(o: { cursor?: string | null; pageSize: number; maxScan: number }): Promise<{ page: unknown[]; nextCursor: string | null; hasMore: boolean; scanCapped: boolean }> })\n    .paginate({ cursor: args.cursor ?? null, pageSize: args.pageSize ?? PAGE_SIZE, maxScan: MAX_SCAN });\n  return {\n    documents: (res.page as Value[]).map((d) => convexToJson(d)),\n    nextCursor: res.nextCursor, hasMore: res.hasMore, scanCapped: res.scanCapped,\n  } as JSONValue;\n});\n","import { mutation, type RegisteredFunction } from \"@helipod/executor\";\nimport { DocumentNotFoundError } from \"@helipod/errors\";\n\n/** Built-in privileged mutations the admin API invokes by id. Registered under `_system:*`. */\nexport function systemModules(): Record<string, RegisteredFunction> {\n  return {\n    \"_system:patchDocument\": mutation(async (ctx, args: { id: string; fields: Record<string, unknown> }) => {\n      const existing = await ctx.db.get(args.id);\n      if (!existing) throw new DocumentNotFoundError(`cannot edit missing document ${args.id}`);\n      // Whole-document replace: the dashboard editor submits the full (user-field) document, so a\n      // field removed in the editor is actually removed. _id/_creationTime are preserved by the kernel.\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      await ctx.db.replace(args.id, args.fields as any);\n      return await ctx.db.get(args.id);\n    }),\n    \"_system:deleteDocument\": mutation(async (ctx, args: { id: string }) => {\n      await ctx.db.delete(args.id);\n      return null;\n    }),\n    \"_system:insertDocument\": mutation(async (ctx, args: { table: string; fields: Record<string, unknown> }) => {\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      const id = await ctx.db.insert(args.table, args.fields as any);\n      return await ctx.db.get(id);\n    }),\n  };\n}\n","// packages/admin/src/router.ts\nimport type { JSONValue } from \"@helipod/values\";\nimport { verifyAdminKey } from \"./auth\";\nimport type { AdminApi } from \"./admin-api\";\n\nexport interface AdminRequest {\n  method: string;\n  path: string;\n  query: Record<string, string>;\n  body?: string;\n  authorization?: string;\n}\nexport interface AdminResponse {\n  status: number;\n  body: JSONValue;\n}\n\nfunction bearer(authorization?: string): string | undefined {\n  if (!authorization) return undefined;\n  const m = /^Bearer (.+)$/.exec(authorization);\n  return m ? m[1] : undefined;\n}\n\nexport async function handleAdminRequest(api: AdminApi, adminKey: string, req: AdminRequest): Promise<AdminResponse> {\n  if (!verifyAdminKey(adminKey, bearer(req.authorization))) {\n    return { status: 401, body: { error: \"unauthorized\" } };\n  }\n  const parts = req.path.split(\"/\").filter(Boolean); // [\"_admin\", ...]\n  const seg = parts.slice(1); // drop \"_admin\"\n\n  try {\n    if (req.method === \"GET\" && seg.length === 1 && seg[0] === \"tables\") {\n      return { status: 200, body: (await api.listTables()) as unknown as JSONValue };\n    }\n    if (req.method === \"GET\" && seg.length === 3 && seg[0] === \"tables\" && seg[2] === \"data\") {\n      const cursor = req.query.cursor ?? null;\n      const pageSize = req.query.pageSize ? Number(req.query.pageSize) : undefined;\n      const data = await api.getTableData(decodeURIComponent(seg[1]!), { cursor, pageSize });\n      return { status: 200, body: data as unknown as JSONValue };\n    }\n    if (req.method === \"GET\" && seg.length === 1 && seg[0] === \"functions\") {\n      return { status: 200, body: api.listFunctions() as unknown as JSONValue };\n    }\n    if (req.method === \"POST\" && seg.length === 1 && seg[0] === \"run\") {\n      const { path, args } = JSON.parse(req.body ?? \"{}\") as { path?: string; args?: JSONValue };\n      if (!path) return { status: 400, body: { error: \"missing path\" } };\n      return { status: 200, body: (await api.runFunction(path, args ?? {})) as unknown as JSONValue };\n    }\n    if (req.method === \"GET\" && seg.length === 1 && seg[0] === \"logs\") {\n      const since = req.query.since ? Number(req.query.since) : undefined;\n      return { status: 200, body: api.queryLogs({ since }) as unknown as JSONValue };\n    }\n    if (req.method === \"PATCH\" && seg.length === 4 && seg[0] === \"tables\" && seg[2] === \"docs\") {\n      const fields = JSON.parse(req.body ?? \"{}\") as Record<string, JSONValue>;\n      return { status: 200, body: await api.patchDocument(seg[3]!, fields) };\n    }\n    if (req.method === \"DELETE\" && seg.length === 4 && seg[0] === \"tables\" && seg[2] === \"docs\") {\n      await api.deleteDocument(seg[3]!);\n      return { status: 200, body: { ok: true } };\n    }\n    if (req.method === \"POST\" && seg.length === 3 && seg[0] === \"tables\" && seg[2] === \"docs\") {\n      const fields = JSON.parse(req.body ?? \"{}\") as Record<string, JSONValue>;\n      return { status: 200, body: await api.createDocument(decodeURIComponent(seg[1]!), fields) };\n    }\n    // Data migration (Slice 5) — export/import the app's full materialized state. Works on both the\n    // container `serve` path and the Cloudflare DO host (both route `/_admin/*` through here). The DO's\n    // store is writable only from inside the DO, and this runs inside it.\n    if (req.method === \"GET\" && seg.length === 1 && seg[0] === \"export\") {\n      return { status: 200, body: (await api.exportDump()) as unknown as JSONValue };\n    }\n    if (req.method === \"POST\" && seg.length === 1 && seg[0] === \"import\") {\n      return { status: 200, body: (await api.importDump(req.body ?? \"\")) as unknown as JSONValue };\n    }\n    return { status: 404, body: { error: \"not found\" } };\n  } catch (e) {\n    return { status: 400, body: { error: e instanceof Error ? e.message : String(e) } };\n  }\n}\n"],"mappings":";AACA,SAAS,aAAa,uBAAuB;AAGtC,SAAS,mBAA2B;AACzC,SAAO,YAAY,EAAE,EAAE,SAAS,WAAW;AAC7C;AAGO,SAAS,eAAe,UAAkB,WAAwC;AACvF,MAAI,cAAc,OAAW,QAAO;AACpC,QAAM,IAAI,OAAO,KAAK,QAAQ;AAC9B,QAAM,IAAI,OAAO,KAAK,SAAS;AAC/B,MAAI,EAAE,WAAW,EAAE,OAAQ,QAAO;AAClC,SAAO,gBAAgB,GAAG,CAAC;AAC7B;;;ACfA,SAAS,4BAA4B;AACrC,SAAS,oBAAoE;AAC7E;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OAGK;AA6CA,IAAM,WAAN,MAAe;AAAA,EACpB,YAA6B,MAAiB;AAAjB;AAAA,EAAkB;AAAA,EAAlB;AAAA,EAErB,QAAQ,OAAuB;AACrC,UAAM,IAAI,KAAK,KAAK,aAAa,KAAK;AACtC,QAAI,MAAM,OAAW,OAAM,IAAI,MAAM,kBAAkB,KAAK,EAAE;AAC9D,WAAO,qBAAqB,CAAC;AAAA,EAC/B;AAAA,EAEA,MAAM,aAAmC;AACvC,UAAM,MAAmB,CAAC;AAC1B,eAAW,QAAQ,OAAO,KAAK,KAAK,KAAK,YAAY,EAAE,KAAK,GAAG;AAC7D,YAAM,YAAY,KAAK,KAAK,WAAW,OAAO,IAAI;AAClD,UAAI;AACJ,UAAI;AACJ,UAAI,WAAW;AAEb,kBAAU,UAAU,QAAQ,IAAI,CAAC,MAAM,EAAE,eAAe;AACxD,mBAAW,UAAU,YAAY;AAAA,MACnC,OAAO;AAEL,kBAAU,KAAK,KAAK,UAChB,KAAK,KAAK,QAAQ,gBAAgB,IAAI,EAAE,IAAI,CAAC,SAAS,KAAK,KAAK,IAChE,CAAC;AACL,mBAAW;AAAA,MACb;AACA,UAAI,KAAK;AAAA,QACP;AAAA,QACA;AAAA,QACA;AAAA,QACA,eAAe,MAAM,KAAK,KAAK,QAAQ,MAAM,MAAM,KAAK,QAAQ,IAAI,CAAC;AAAA,MACvE,CAAC;AAAA,IACH;AACA,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,aACJ,OACA,OAA6E,CAAC,GACtD;AACxB,UAAM,OAAgC,EAAE,OAAO,QAAQ,KAAK,UAAU,KAAK;AAC3E,QAAI,KAAK,aAAa,OAAW,MAAK,WAAW,KAAK;AACtD,QAAI,KAAK,WAAW,OAAW,MAAK,SAAS,KAAK;AAClD,UAAM,IAAI,MAAM,KAAK,KAAK,QAAQ,SAAS,sBAAsB,IAAiB;AAClF,WAAO,EAAE;AAAA,EACX;AAAA,EAEA,gBAAkD;AAChD,WAAO,KAAK,KAAK,SAAS;AAAA,MAAQ,CAAC,MACjC,EAAE,UAAU,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,EAAE,IAAI,IAAI,EAAE,IAAI,IAAI,MAAM,EAAE,KAAK,EAAE;AAAA,IACxE;AAAA,EACF;AAAA,EAEA,UAAU,QAAyC;AACjD,WAAO,KAAK,KAAK,QAAQ,MAAM,MAAM;AAAA,EACvC;AAAA,EAEA,MAAM,YAAY,MAAc,MAAoE;AAClG,UAAM,IAAI,MAAM,KAAK,KAAK,QAAQ,IAAI,MAAM,IAAI;AAChD,WAAO,EAAE,OAAO,aAAa,EAAE,KAAc,GAAG,WAAW,EAAE,UAAU;AAAA,EACzE;AAAA,EAEA,MAAM,cAAc,IAAY,QAAuD;AACrF,UAAM,IAAI,MAAM,KAAK,KAAK,QAAQ,UAAU,yBAAyB,EAAE,IAAI,OAAO,CAAC;AACnF,WAAO,aAAa,EAAE,KAAc;AAAA,EACtC;AAAA,EAEA,MAAM,eAAe,IAA2B;AAC9C,UAAM,KAAK,KAAK,QAAQ,UAAU,0BAA0B,EAAE,GAAG,CAAC;AAAA,EACpE;AAAA,EAEA,MAAM,eAAe,OAAe,QAAuD;AACzF,UAAM,IAAI,MAAM,KAAK,KAAK,QAAQ,UAAU,0BAA0B,EAAE,OAAO,OAAO,CAAC;AACvF,WAAO,aAAa,EAAE,KAAc;AAAA,EACtC;AAAA;AAAA,EAGA,UAAU,YAAqC,cAAsC,UAAuC;AAC1H,SAAK,KAAK,aAAa;AACvB,SAAK,KAAK,eAAe;AACzB,SAAK,KAAK,WAAW;AAAA,EACvB;AAAA;AAAA,EAGA,YAA2F;AACzF,WAAO,EAAE,YAAY,KAAK,KAAK,YAAY,cAAc,KAAK,KAAK,aAAa;AAAA,EAClF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,MAAM,aAAqC;AACzC,UAAM,eAAgB,MAAM,KAAK,KAAK,QAAQ,MAAM,UAAU,oBAAoB;AAClF,WAAO,oBAAoB,KAAK,KAAK,QAAQ,OAAO,EAAE,cAAc,KAAK,KAAK,cAAc,aAAa,CAAC;AAAA,EAC5G;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,MAAM,WAAW,UAA0G;AACzH,UAAM,OAAO,UAAU,QAAQ;AAC/B,UAAM,WAAW,MAAM;AAAA,MACrB,KAAK,KAAK,QAAQ;AAAA,MAClB;AAAA,MACA,KAAK,KAAK;AAAA,IACZ;AAEA,SAAK,KAAK,QAAQ,iBAAiB,MAAM,KAAK,KAAK,QAAQ,MAAM,aAAa,CAAC;AAC/E,WAAO,EAAE,IAAI,MAAM,SAAS;AAAA,EAC9B;AACF;;;AC7KA,SAAS,aAAsC;AAC/C,SAAS,gBAAAA,qBAAgD;AAIzD,IAAM,WAAW;AACjB,IAAM,YAAY;AAGX,IAAM,oBAAwC,MAAM,OAAO,KAAK,SAEjE;AACJ,QAAM,IAAK,IACR,GAAG,MAAM,KAAK,OAAO,aAAa;AACrC,aAAW,KAAK,KAAK,UAAU,CAAC,EAAG,CAAC,EAAgE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAc;AACzI,QAAM,MAAM,MAAO,EAChB,SAAS,EAAE,QAAQ,KAAK,UAAU,MAAM,UAAU,KAAK,YAAY,WAAW,SAAS,SAAS,CAAC;AACpG,SAAO;AAAA,IACL,WAAY,IAAI,KAAiB,IAAI,CAAC,MAAMA,cAAa,CAAC,CAAC;AAAA,IAC3D,YAAY,IAAI;AAAA,IAAY,SAAS,IAAI;AAAA,IAAS,YAAY,IAAI;AAAA,EACpE;AACF,CAAC;;;ACrBD,SAAS,gBAAyC;AAClD,SAAS,6BAA6B;AAG/B,SAAS,gBAAoD;AAClE,SAAO;AAAA,IACL,yBAAyB,SAAS,OAAO,KAAK,SAA0D;AACtG,YAAM,WAAW,MAAM,IAAI,GAAG,IAAI,KAAK,EAAE;AACzC,UAAI,CAAC,SAAU,OAAM,IAAI,sBAAsB,gCAAgC,KAAK,EAAE,EAAE;AAIxF,YAAM,IAAI,GAAG,QAAQ,KAAK,IAAI,KAAK,MAAa;AAChD,aAAO,MAAM,IAAI,GAAG,IAAI,KAAK,EAAE;AAAA,IACjC,CAAC;AAAA,IACD,0BAA0B,SAAS,OAAO,KAAK,SAAyB;AACtE,YAAM,IAAI,GAAG,OAAO,KAAK,EAAE;AAC3B,aAAO;AAAA,IACT,CAAC;AAAA,IACD,0BAA0B,SAAS,OAAO,KAAK,SAA6D;AAE1G,YAAM,KAAK,MAAM,IAAI,GAAG,OAAO,KAAK,OAAO,KAAK,MAAa;AAC7D,aAAO,MAAM,IAAI,GAAG,IAAI,EAAE;AAAA,IAC5B,CAAC;AAAA,EACH;AACF;;;ACRA,SAAS,OAAO,eAA4C;AAC1D,MAAI,CAAC,cAAe,QAAO;AAC3B,QAAM,IAAI,gBAAgB,KAAK,aAAa;AAC5C,SAAO,IAAI,EAAE,CAAC,IAAI;AACpB;AAEA,eAAsB,mBAAmB,KAAe,UAAkB,KAA2C;AACnH,MAAI,CAAC,eAAe,UAAU,OAAO,IAAI,aAAa,CAAC,GAAG;AACxD,WAAO,EAAE,QAAQ,KAAK,MAAM,EAAE,OAAO,eAAe,EAAE;AAAA,EACxD;AACA,QAAM,QAAQ,IAAI,KAAK,MAAM,GAAG,EAAE,OAAO,OAAO;AAChD,QAAM,MAAM,MAAM,MAAM,CAAC;AAEzB,MAAI;AACF,QAAI,IAAI,WAAW,SAAS,IAAI,WAAW,KAAK,IAAI,CAAC,MAAM,UAAU;AACnE,aAAO,EAAE,QAAQ,KAAK,MAAO,MAAM,IAAI,WAAW,EAA2B;AAAA,IAC/E;AACA,QAAI,IAAI,WAAW,SAAS,IAAI,WAAW,KAAK,IAAI,CAAC,MAAM,YAAY,IAAI,CAAC,MAAM,QAAQ;AACxF,YAAM,SAAS,IAAI,MAAM,UAAU;AACnC,YAAM,WAAW,IAAI,MAAM,WAAW,OAAO,IAAI,MAAM,QAAQ,IAAI;AACnE,YAAM,OAAO,MAAM,IAAI,aAAa,mBAAmB,IAAI,CAAC,CAAE,GAAG,EAAE,QAAQ,SAAS,CAAC;AACrF,aAAO,EAAE,QAAQ,KAAK,MAAM,KAA6B;AAAA,IAC3D;AACA,QAAI,IAAI,WAAW,SAAS,IAAI,WAAW,KAAK,IAAI,CAAC,MAAM,aAAa;AACtE,aAAO,EAAE,QAAQ,KAAK,MAAM,IAAI,cAAc,EAA0B;AAAA,IAC1E;AACA,QAAI,IAAI,WAAW,UAAU,IAAI,WAAW,KAAK,IAAI,CAAC,MAAM,OAAO;AACjE,YAAM,EAAE,MAAM,KAAK,IAAI,KAAK,MAAM,IAAI,QAAQ,IAAI;AAClD,UAAI,CAAC,KAAM,QAAO,EAAE,QAAQ,KAAK,MAAM,EAAE,OAAO,eAAe,EAAE;AACjE,aAAO,EAAE,QAAQ,KAAK,MAAO,MAAM,IAAI,YAAY,MAAM,QAAQ,CAAC,CAAC,EAA2B;AAAA,IAChG;AACA,QAAI,IAAI,WAAW,SAAS,IAAI,WAAW,KAAK,IAAI,CAAC,MAAM,QAAQ;AACjE,YAAM,QAAQ,IAAI,MAAM,QAAQ,OAAO,IAAI,MAAM,KAAK,IAAI;AAC1D,aAAO,EAAE,QAAQ,KAAK,MAAM,IAAI,UAAU,EAAE,MAAM,CAAC,EAA0B;AAAA,IAC/E;AACA,QAAI,IAAI,WAAW,WAAW,IAAI,WAAW,KAAK,IAAI,CAAC,MAAM,YAAY,IAAI,CAAC,MAAM,QAAQ;AAC1F,YAAM,SAAS,KAAK,MAAM,IAAI,QAAQ,IAAI;AAC1C,aAAO,EAAE,QAAQ,KAAK,MAAM,MAAM,IAAI,cAAc,IAAI,CAAC,GAAI,MAAM,EAAE;AAAA,IACvE;AACA,QAAI,IAAI,WAAW,YAAY,IAAI,WAAW,KAAK,IAAI,CAAC,MAAM,YAAY,IAAI,CAAC,MAAM,QAAQ;AAC3F,YAAM,IAAI,eAAe,IAAI,CAAC,CAAE;AAChC,aAAO,EAAE,QAAQ,KAAK,MAAM,EAAE,IAAI,KAAK,EAAE;AAAA,IAC3C;AACA,QAAI,IAAI,WAAW,UAAU,IAAI,WAAW,KAAK,IAAI,CAAC,MAAM,YAAY,IAAI,CAAC,MAAM,QAAQ;AACzF,YAAM,SAAS,KAAK,MAAM,IAAI,QAAQ,IAAI;AAC1C,aAAO,EAAE,QAAQ,KAAK,MAAM,MAAM,IAAI,eAAe,mBAAmB,IAAI,CAAC,CAAE,GAAG,MAAM,EAAE;AAAA,IAC5F;AAIA,QAAI,IAAI,WAAW,SAAS,IAAI,WAAW,KAAK,IAAI,CAAC,MAAM,UAAU;AACnE,aAAO,EAAE,QAAQ,KAAK,MAAO,MAAM,IAAI,WAAW,EAA2B;AAAA,IAC/E;AACA,QAAI,IAAI,WAAW,UAAU,IAAI,WAAW,KAAK,IAAI,CAAC,MAAM,UAAU;AACpE,aAAO,EAAE,QAAQ,KAAK,MAAO,MAAM,IAAI,WAAW,IAAI,QAAQ,EAAE,EAA2B;AAAA,IAC7F;AACA,WAAO,EAAE,QAAQ,KAAK,MAAM,EAAE,OAAO,YAAY,EAAE;AAAA,EACrD,SAAS,GAAG;AACV,WAAO,EAAE,QAAQ,KAAK,MAAM,EAAE,OAAO,aAAa,QAAQ,EAAE,UAAU,OAAO,CAAC,EAAE,EAAE;AAAA,EACpF;AACF;","names":["convexToJson"]}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@helipod/admin",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@helipod/docstore": "0.1.0",
+    "@helipod/errors": "0.1.0",
+    "@helipod/executor": "0.1.0",
+    "@helipod/id-codec": "0.1.0",
+    "@helipod/query-engine": "0.1.0",
+    "@helipod/runtime-embedded": "0.1.0",
+    "@helipod/values": "0.1.0"
+  },
+  "devDependencies": {
+    "@helipod/component": "0.1.0",
+    "@helipod/docstore-sqlite": "0.1.0",
+    "@helipod/query-engine": "0.1.0",
+    "@types/node": "^22.10.5",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "FSL-1.1-Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/helipod-sh/helipod.git",
+    "directory": "packages/admin"
+  },
+  "homepage": "https://github.com/helipod-sh/helipod"
+}