nolo-cli 0.1.31 → 0.1.32

package/cli/tableDataSafety.ts

@@ -0,0 +1,26 @@
+export const TABLE_SCHEMA_WRITE_ACTIONS = new Set(["add-column"]);
+
+export function isTableSchemaWriteAction(action: string): boolean {
+  return TABLE_SCHEMA_WRITE_ACTIONS.has(action.trim());
+}
+
+export function tableSchemaWriteSafetyMessage(action: string): string {
+  return [
+    `Action "${action}" mutates table schema metadata and must be serialized per table.`,
+    "Rerun with --schema-write-ok only after confirming no other agent/script is changing the same table schema.",
+    "Server-side schema CAS/locking is not implemented yet; row-level writes do not need this flag.",
+  ].join(" ");
+}
+
+export function assertTableSchemaWriteAllowed(input: {
+  action: string;
+  allowSchemaWrite: boolean;
+}): void {
+  if (!isTableSchemaWriteAction(input.action)) {
+    return;
+  }
+  if (input.allowSchemaWrite) {
+    return;
+  }
+  throw new Error(tableSchemaWriteSafetyMessage(input.action));
+}

package/cli/tableMetaCommands.ts

@@ -0,0 +1,307 @@
+import { ulid } from "ulid";
+import { getReadableCliDb, type AgentCommandDeps } from "./agentCommandSupport";
+import { readDbRecord } from "./agentRecordHelpers";
+import { parseUserIdFromAuthToken, readOption, resolveAuthToken, resolveServerUrl } from "./cliEnvHelpers";
+import {
+  buildTableAttachedSpaceRecord,
+  parseSpaceIdFromInput,
+  readSpaceRecordWithFallback,
+} from "./spaceMutationHelpers";
+import { writeRemoteRecordsThenCache } from "./pageWriteHelpers";
+
+type ColumnType =
+  | "text"
+  | "number"
+  | "boolean"
+  | "date"
+  | "datetime"
+  | "select"
+  | "multi_select";
+
+type ColumnInput = {
+  id?: string;
+  name: string;
+  label?: string;
+  type?: ColumnType;
+  description?: string;
+  required?: boolean;
+  isPrimary?: boolean;
+  options?: string[];
+};
+
+function usage() {
+  return [
+    "Usage:",
+    "  nolo table meta --name <name> [--table <tableId|metaKey>] [--space <spaceId|spaceKey|spaceUrl>] [--category-id <id>] [--description <text>] [--tags <comma-list>] [--columns <json-array>]",
+    "",
+  ].join("\n");
+}
+
+function parseTableArg(raw?: string) {
+  if (!raw?.trim()) return {};
+  const trimmed = raw.trim();
+  if (trimmed.startsWith("meta-")) {
+    const parts = trimmed.split("-");
+    return {
+      tableId: parts.slice(2).join("-"),
+      dbKey: trimmed,
+    };
+  }
+  return { tableId: trimmed };
+}
+
+function parseTags(raw?: string) {
+  if (!raw) return undefined;
+  const tags = raw
+    .split(",")
+    .map((value) => value.trim())
+    .filter(Boolean);
+  return tags.length > 0 ? tags : undefined;
+}
+
+function defaultColumns(): ColumnInput[] {
+  return [
+    {
+      name: "title",
+      label: "标题",
+      type: "text",
+      description: "这一行记录的主题或名称。",
+      isPrimary: true,
+      required: true,
+    },
+    {
+      name: "note",
+      label: "备注",
+      type: "text",
+      description: "对该条目的补充说明。",
+    },
+  ];
+}
+
+function normalizeColumns(rawColumns?: string, existingColumns?: any[]) {
+  if (!rawColumns) {
+    if (Array.isArray(existingColumns) && existingColumns.length > 0) {
+      return existingColumns;
+    }
+    return defaultColumns().map((column) => ({ ...column, id: ulid() }));
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(rawColumns);
+  } catch (error) {
+    throw new Error(
+      `--columns must be a valid JSON array: ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    );
+  }
+
+  if (!Array.isArray(parsed)) {
+    throw new Error("--columns must be a JSON array.");
+  }
+
+  const seen = new Set<string>();
+  const normalized = parsed
+    .map((value) => {
+      if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+      const column = value as ColumnInput;
+      const name = typeof column.name === "string" ? column.name.trim() : "";
+      if (!name || seen.has(name)) return null;
+      seen.add(name);
+
+      const nextColumn: Record<string, unknown> = {
+        id: typeof column.id === "string" && column.id.trim() ? column.id.trim() : ulid(),
+        name,
+      };
+      if (typeof column.label === "string" && column.label.trim()) nextColumn.label = column.label.trim();
+      if (typeof column.type === "string" && column.type.trim()) nextColumn.type = column.type.trim();
+      if (typeof column.description === "string" && column.description.trim()) {
+        nextColumn.description = column.description.trim();
+      }
+      if (typeof column.required === "boolean") nextColumn.required = column.required;
+      if (typeof column.isPrimary === "boolean") nextColumn.isPrimary = column.isPrimary;
+      if (Array.isArray(column.options)) {
+        const options = column.options
+          .map((option) => (typeof option === "string" ? option.trim() : ""))
+          .filter(Boolean);
+        if (options.length > 0) nextColumn.options = options;
+      }
+      return nextColumn;
+    })
+    .filter(Boolean) as Array<Record<string, unknown>>;
+
+  if (normalized.length === 0) {
+    throw new Error("--columns did not contain any valid columns.");
+  }
+  if (!normalized.some((column) => column.isPrimary === true)) {
+    normalized[0].isPrimary = true;
+  }
+  return normalized;
+}
+
+export async function runTableMetaCommand(
+  args: string[],
+  deps: AgentCommandDeps = {}
+) {
+  const env = deps.env ?? process.env;
+  const output = deps.output ?? process.stdout;
+
+  if (args.includes("--help") || args.includes("-h")) {
+    output.write(`${usage()}\n`);
+    return 0;
+  }
+
+  const rawName = readOption(args, "--name");
+  if (!rawName?.trim()) {
+    output.write(`${usage()}\n`);
+    return 1;
+  }
+
+  const authToken = resolveAuthToken(args, env);
+  const userId = parseUserIdFromAuthToken(authToken);
+  if (!authToken || !userId) {
+    output.write("[nolo] table meta requires an auth token with userId. Run `nolo login`.\n");
+    return 1;
+  }
+
+  const name = rawName.trim();
+  const description = readOption(args, "--description")?.trim() || undefined;
+  const tags = parseTags(readOption(args, "--tags"));
+  const serverUrl = resolveServerUrl(args, env);
+  const db = deps.db ?? await getReadableCliDb(output);
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const fallbackFetchImpl = deps.fallbackFetchImpl;
+
+  try {
+    const parsedTable = parseTableArg(readOption(args, "--table"));
+    const tableId = parsedTable.tableId ?? ulid();
+    const dbKey = parsedTable.dbKey ?? `meta-${userId}-${tableId}`;
+
+    let existingRecord: Record<string, any> | null = null;
+    try {
+      const value = await db.get(dbKey);
+      existingRecord = value && typeof value === "object" ? (value as Record<string, any>) : null;
+    } catch {
+      try {
+        existingRecord = await readDbRecord({
+          authToken,
+          dbKey,
+          fallbackFetchImpl,
+          fetchImpl,
+          serverUrl,
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (parsedTable.dbKey || parsedTable.tableId) {
+          if (!message.includes("404")) {
+            throw error;
+          }
+        }
+      }
+    }
+
+    const columns = normalizeColumns(readOption(args, "--columns"), existingRecord?.columns);
+    const nowIso = new Date().toISOString();
+    const rawSpace = readOption(args, "--space");
+    const spaceId =
+      rawSpace != null
+        ? parseSpaceIdFromInput(rawSpace)
+        : typeof existingRecord?.spaceId === "string" && existingRecord.spaceId
+          ? existingRecord.spaceId
+          : undefined;
+    const explicitCategoryId = readOption(args, "--category-id")?.trim() || undefined;
+    const categoryId =
+      explicitCategoryId ??
+      (typeof existingRecord?.categoryId === "string" && existingRecord.categoryId
+        ? existingRecord.categoryId
+        : undefined);
+
+    let spaceRecord: Record<string, any> | null = null;
+    if (spaceId) {
+      spaceRecord = await readSpaceRecordWithFallback({
+        authToken,
+        db,
+        fallbackFetchImpl,
+        fetchImpl,
+        serverCandidates: [serverUrl],
+        spaceId,
+      });
+      if (categoryId && !spaceRecord?.categories?.[categoryId]) {
+        throw new Error(`space ${spaceId} does not contain category ${categoryId}`);
+      }
+    }
+
+    const nextRecord = {
+      ...(existingRecord ?? {}),
+      dbKey,
+      tenantId: userId,
+      tableId,
+      spaceId: spaceId ?? null,
+      displayName: name,
+      ...(description !== undefined ? { description } : {}),
+      ...(tags !== undefined ? { tags } : existingRecord?.tags ? { tags: existingRecord.tags } : {}),
+      ...(categoryId ? { categoryId } : {}),
+      schemaVersion:
+        typeof existingRecord?.schemaVersion === "number" ? existingRecord.schemaVersion : 1,
+      columns,
+      views: Array.isArray(existingRecord?.views) ? existingRecord.views : [],
+      triggers: Array.isArray(existingRecord?.triggers) ? existingRecord.triggers : [],
+      aiConfig: existingRecord?.aiConfig,
+      createdAt: existingRecord?.createdAt ?? nowIso,
+      updatedAt: nowIso,
+      type: "table",
+    };
+
+    const writeRecords = [{ dbKey, record: nextRecord, serverUrl }];
+
+    if (spaceId && spaceRecord) {
+      const nextSpaceRecord = buildTableAttachedSpaceRecord({
+        categoryId,
+        contentKey: dbKey,
+        existingSpaceRecord: spaceRecord,
+        spaceId,
+        title: name,
+      });
+      writeRecords.push({
+        dbKey: `space-${spaceId}`,
+        record: nextSpaceRecord,
+        serverUrl,
+      });
+    }
+
+    await writeRemoteRecordsThenCache({
+      authToken,
+      db,
+      fallbackFetchImpl,
+      fetchImpl,
+      records: writeRecords,
+      userId,
+    });
+
+    output.write(
+      `${JSON.stringify(
+        {
+          ok: true,
+          action: existingRecord ? "updated" : "created",
+          baseUrl: serverUrl,
+          dbKey,
+          tableId,
+          spaceId: spaceId ?? null,
+          categoryId: categoryId ?? null,
+          table: nextRecord,
+        },
+        null,
+        2
+      )}\n`
+    );
+    return 0;
+  } catch (error) {
+    output.write(
+      `[nolo] table meta failed: ${
+        error instanceof Error ? error.message : String(error)
+      }\n`
+    );
+    return 1;
+  }
+}

package/cli/tableMutationCommands.ts

@@ -0,0 +1,266 @@
+import type { OutputLike } from "./cliIoTypes";
+import {
+  formatOutput,
+  hasFlag,
+  parseJsonOption,
+  parseJwtTenantId,
+  parseOutputMode,
+  parseTableArg,
+  readOption,
+  resolveAuthToken,
+  resolveServerUrl,
+  type EnvLike,
+} from "./tableQueryParsing";
+import { assertTableSchemaWriteAllowed } from "./tableDataSafety";
+
+type TableMutationDeps = {
+  env?: EnvLike;
+  output?: OutputLike;
+  fetchImpl?: typeof fetch;
+};
+
+function usage() {
+  return [
+    "Usage:",
+    "  nolo table data --table <tableId|metaKey> [--tenant-id <userId>] [--action <add-column|add-row|add-rows|update-row|update-rows|delete-row|delete-rows>] [payload flags]",
+    "",
+  ].join("\n");
+}
+
+function resolveRowTarget(raw?: string) {
+  if (!raw?.trim()) return {};
+  const trimmed = raw.trim();
+  if (trimmed.startsWith("row-")) {
+    return { dbKey: trimmed };
+  }
+  return { rowId: trimmed };
+}
+
+async function readTableMeta(args: {
+  authToken: string;
+  dbKey: string;
+  fetchImpl: typeof fetch;
+  serverUrl: string;
+}) {
+  const response = await args.fetchImpl(`${args.serverUrl}/api/v1/db/read/${encodeURIComponent(args.dbKey)}`, {
+    method: "GET",
+    headers: {
+      Authorization: `Bearer ${args.authToken}`,
+    },
+  });
+  const data = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    throw new Error(`failed to read table meta (${response.status}): ${JSON.stringify(data)}`);
+  }
+  return data?.data ?? data;
+}
+
+async function postTableAction(args: {
+  authToken: string;
+  body: Record<string, unknown>;
+  fetchImpl: typeof fetch;
+  path: string;
+  serverUrl: string;
+}) {
+  const response = await args.fetchImpl(`${args.serverUrl}${args.path}`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${args.authToken}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(args.body),
+  });
+  const data = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    throw new Error(`${args.path} failed (${response.status}): ${JSON.stringify(data)}`);
+  }
+  return data?.rawData ?? data;
+}
+
+function buildMutationRequest(args: {
+  action: string;
+  rawArgs: string[];
+  tableId: string;
+  tenantId: string;
+}) {
+  const { action, rawArgs, tableId, tenantId } = args;
+  switch (action) {
+    case "add-column": {
+      const name = readOption(rawArgs, "--name")?.trim();
+      if (!name) throw new Error("--name is required.");
+      const options = parseJsonOption<string[]>(rawArgs, "--options");
+      return {
+        path: "/api/table/add-column",
+        body: {
+          tenantId,
+          tableId,
+          name,
+          ...(readOption(rawArgs, "--label") ? { label: readOption(rawArgs, "--label") } : {}),
+          ...(readOption(rawArgs, "--type") ? { type: readOption(rawArgs, "--type") } : {}),
+          ...(options ? { options } : {}),
+        },
+      };
+    }
+    case "add-row": {
+      const values = parseJsonOption<Record<string, unknown>>(rawArgs, "--values");
+      if (!values || Array.isArray(values)) {
+        throw new Error("--values must be a JSON object.");
+      }
+      return {
+        path: "/api/table/add-row",
+        body: { tenantId, tableId, values },
+      };
+    }
+    case "add-rows": {
+      const rows = parseJsonOption<Array<Record<string, unknown>>>(rawArgs, "--rows");
+      if (!Array.isArray(rows) || rows.length === 0) {
+        throw new Error("--rows must be a non-empty JSON array.");
+      }
+      return {
+        path: "/api/table/add-rows",
+        body: { tenantId, tableId, rows },
+      };
+    }
+    case "update-row": {
+      const target = resolveRowTarget(readOption(rawArgs, "--row"));
+      const changes = parseJsonOption<Record<string, unknown>>(rawArgs, "--changes");
+      if ((!target.rowId && !target.dbKey) || !changes || Array.isArray(changes)) {
+        throw new Error("--row and --changes are required, and --changes must be an object.");
+      }
+      return {
+        path: "/api/table/update-row",
+        body: { tenantId, tableId, ...target, changes },
+      };
+    }
+    case "update-rows": {
+      const updates = parseJsonOption<Array<Record<string, unknown>>>(rawArgs, "--updates");
+      if (!Array.isArray(updates) || updates.length === 0) {
+        throw new Error("--updates must be a non-empty JSON array.");
+      }
+      return {
+        path: "/api/table/update-rows",
+        body: { tenantId, tableId, updates },
+      };
+    }
+    case "delete-row": {
+      const target = resolveRowTarget(readOption(rawArgs, "--row"));
+      if (!target.rowId && !target.dbKey) {
+        throw new Error("--row is required and may be rowId or row dbKey.");
+      }
+      return {
+        path: "/api/table/delete-row",
+        body: { tenantId, tableId, ...target },
+      };
+    }
+    case "delete-rows": {
+      const rowIds = parseJsonOption<string[]>(rawArgs, "--row-ids");
+      const dbKeys = parseJsonOption<string[]>(rawArgs, "--row-dbkeys");
+      if ((!Array.isArray(rowIds) || rowIds.length === 0) && (!Array.isArray(dbKeys) || dbKeys.length === 0)) {
+        throw new Error("--row-ids or --row-dbkeys must provide a non-empty JSON array.");
+      }
+      return {
+        path: "/api/table/delete-rows",
+        body: {
+          tenantId,
+          tableId,
+          ...(Array.isArray(rowIds) && rowIds.length > 0 ? { rowIds } : {}),
+          ...(Array.isArray(dbKeys) && dbKeys.length > 0 ? { dbKeys } : {}),
+        },
+      };
+    }
+    default:
+      throw new Error(`unsupported action: ${action}`);
+  }
+}
+
+export async function runTableDataCommand(args: string[], deps: TableMutationDeps = {}) {
+  const env = deps.env ?? process.env;
+  const output = deps.output ?? process.stdout;
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  if (hasFlag(args, "--help") || hasFlag(args, "-h")) {
+    output.write(usage());
+    return 0;
+  }
+
+  const action = (readOption(args, "--action") || "query").trim();
+  const outputMode = parseOutputMode(readOption(args, "--output"));
+  let tableArg: { tenantId?: string; tableId?: string };
+  try {
+    tableArg = parseTableArg(readOption(args, "--table"));
+    assertTableSchemaWriteAllowed({
+      action,
+      allowSchemaWrite: hasFlag(args, "--schema-write-ok"),
+    });
+  } catch (error) {
+    output.write(`[nolo] table data failed: ${error instanceof Error ? error.message : String(error)}\n`);
+    return 1;
+  }
+
+  const authToken = resolveAuthToken(args, env);
+  const tenantId = readOption(args, "--tenant-id") || tableArg.tenantId || env.USER_ID || parseJwtTenantId(authToken);
+  const tableId = tableArg.tableId;
+  const tableDbKey = tenantId && tableId ? `meta-${tenantId}-${tableId}` : "";
+  if (!authToken) {
+    output.write("[nolo] table data failed: AUTH_TOKEN is required.\n");
+    return 1;
+  }
+  if (!tenantId || !tableId || !tableDbKey) {
+    output.write(usage());
+    return 1;
+  }
+
+  const serverUrl = resolveServerUrl(args, env);
+  try {
+    const tableMeta = await readTableMeta({
+      authToken,
+      dbKey: tableDbKey,
+      fetchImpl,
+      serverUrl,
+    });
+    if (!tableMeta || tableMeta.type !== "table") {
+      throw new Error(`table definition not found: ${tableDbKey}`);
+    }
+
+    const request = buildMutationRequest({
+      action,
+      rawArgs: args,
+      tableId,
+      tenantId,
+    });
+    const result = await postTableAction({
+      authToken,
+      body: request.body,
+      fetchImpl,
+      path: request.path,
+      serverUrl,
+    });
+    const envelope = {
+      ok: true,
+      action,
+      baseUrl: serverUrl,
+      tenantId,
+      tableId,
+      tableDbKey,
+      tableName: tableMeta.displayName ?? null,
+      result,
+    };
+    output.write(`${formatOutput({ envelope, rawData: result, mode: outputMode })}\n`);
+    return 0;
+  } catch (error) {
+    output.write(`[nolo] table data failed: ${error instanceof Error ? error.message : String(error)}\n`);
+    return 1;
+  }
+}
+
+function withAction(action: string) {
+  return (args: string[], deps: TableMutationDeps = {}) =>
+    runTableDataCommand(["--action", action, ...args], deps);
+}
+
+export const runTableAddColumnCommand = withAction("add-column");
+export const runTableAddRowCommand = withAction("add-row");
+export const runTableAddRowsCommand = withAction("add-rows");
+export const runTableUpdateRowCommand = withAction("update-row");
+export const runTableUpdateRowsCommand = withAction("update-rows");
+export const runTableDeleteRowCommand = withAction("delete-row");
+export const runTableDeleteRowsCommand = withAction("delete-rows");

package/cli/tableQueryParsing.ts

@@ -0,0 +1,90 @@
+import {
+  decodeJwtPayload,
+  hasFlag as hasCliFlag,
+  readCliOptionValue,
+  resolveAuthTokenFromArgs,
+  resolveServerUrlFromArgs,
+} from "./cliEnvHelpers";
+import {
+  formatTableDataOutput,
+  parseTableDataOutputMode,
+  type TableDataOutputMode,
+} from "./tableDataOutput";
+
+export type EnvLike = Record<string, string | undefined>;
+export type OutputMode = TableDataOutputMode;
+
+export function readOption(args: string[], flag: string): string {
+  return readCliOptionValue(args, flag);
+}
+
+export function hasFlag(args: string[], flag: string): boolean {
+  return hasCliFlag(args, flag);
+}
+
+export function parseJsonOption<T>(args: string[], flag: string): T | undefined {
+  const raw = readOption(args, flag);
+  if (!raw) return undefined;
+  try {
+    return JSON.parse(raw) as T;
+  } catch (error) {
+    throw new Error(`${flag} must be valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+export function parseJsonOptionAlias<T>(
+  args: string[],
+  primaryFlag: string,
+  aliasFlag: string,
+): T | undefined {
+  const primary = readOption(args, primaryFlag);
+  const alias = readOption(args, aliasFlag);
+  const raw = primary || alias;
+  if (!raw) return undefined;
+  try {
+    return JSON.parse(raw) as T;
+  } catch (error) {
+    const usedFlag = primary ? primaryFlag : aliasFlag;
+    throw new Error(`${usedFlag} must be valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+export function parseOutputMode(raw: string): OutputMode {
+  return parseTableDataOutputMode(raw);
+}
+
+export function parseTableArg(raw: string): { tenantId?: string; tableId?: string } {
+  const trimmed = raw.trim();
+  if (!trimmed) return {};
+  if (!trimmed.startsWith("meta-")) return { tableId: trimmed };
+  const parts = trimmed.split("-");
+  return {
+    tenantId: parts[1],
+    tableId: parts.slice(2).join("-"),
+  };
+}
+
+export function resolveServerUrl(args: string[], env: EnvLike): string {
+  return resolveServerUrlFromArgs(args, env);
+}
+
+export function resolveAuthToken(args: string[], env: EnvLike): string {
+  return resolveAuthTokenFromArgs(args, env);
+}
+
+export function parseJwtTenantId(token: string): string | undefined {
+  const parsed = decodeJwtPayload(token);
+  return typeof parsed?.userId === "string"
+    ? parsed.userId
+    : typeof parsed?.sub === "string"
+      ? parsed.sub
+      : undefined;
+}
+
+export function formatOutput(input: { envelope: any; rawData: any; mode: OutputMode }): string {
+  return formatTableDataOutput({
+    envelope: input.envelope,
+    result: input.rawData,
+    mode: input.mode,
+  });
+}