nolo-cli 0.1.26 → 0.1.29

package/spaceReadCommands.ts

@@ -0,0 +1,323 @@
+import { ContentType } from "./app/types";
+import { parseSkillDocProtocol, resolvePageSkillMetadata } from "./ai/skills/skillDocProtocol";
+import { createSpaceKey } from "./create/space/spaceKeys";
+import { getReadableCliDb, type AgentCommandDeps } from "./agentCommandSupport";
+import { readDbRecord } from "./agentRecordHelpers";
+import {
+  parseUserIdFromAuthToken,
+  readOption,
+  resolveAuthToken,
+  resolveServerCandidates,
+  resolveServerUrl,
+} from "./cliEnvHelpers";
+import { readRecordWithCandidates } from "./hybridReadHelpers";
+import { parseSpaceIdFromInput } from "./spaceMutationHelpers";
+
+function readPositionalInput(args: string[]) {
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index];
+    if (value === "--content-key") {
+      index += 1;
+      continue;
+    }
+    if (!value.startsWith("-")) return value;
+  }
+  return undefined;
+}
+
+function parseSpaceReadArgs(args: string[]) {
+  const raw = readPositionalInput(args);
+  if (!raw) throw new Error("Usage: nolo space read <spaceId|spaceKey|spaceUrl> [--brief] [--content-key <key>] [--include-record]");
+  const brief = args.includes("--brief");
+  const contentKeyFilter = readOption(args, "--content-key");
+  const includeRecord = args.includes("--include-record") || (!brief && !contentKeyFilter);
+  return {
+    raw,
+    brief,
+    contentKeyFilter,
+    includeRecord,
+  };
+}
+
+function buildContentEntries(space: Record<string, any>) {
+  return Object.entries(space.contents ?? {})
+    .filter(([, value]) => value && typeof value === "object")
+    .map(([entryKey, value]) => ({
+      entryKey,
+      ...(value as Record<string, any>),
+    }))
+    .sort((a, b) => {
+      const pinnedDiff = Number(Boolean(b.pinned)) - Number(Boolean(a.pinned));
+      if (pinnedDiff !== 0) return pinnedDiff;
+      const orderA = typeof a.order === "number" ? a.order : Number.MAX_SAFE_INTEGER;
+      const orderB = typeof b.order === "number" ? b.order : Number.MAX_SAFE_INTEGER;
+      if (orderA !== orderB) return orderA - orderB;
+      return (b.updatedAt ?? 0) - (a.updatedAt ?? 0);
+    });
+}
+
+function buildCategories(space: Record<string, any>) {
+  return Object.entries(space.categories ?? {})
+    .filter(([, value]) => value && typeof value === "object")
+    .map(([categoryId, value]) => ({
+      categoryId,
+      ...(value as Record<string, any>),
+    }))
+    .sort((a, b) => {
+      const orderA = typeof a.order === "number" ? a.order : Number.MAX_SAFE_INTEGER;
+      const orderB = typeof b.order === "number" ? b.order : Number.MAX_SAFE_INTEGER;
+      if (orderA !== orderB) return orderA - orderB;
+      return String(a.name ?? "").localeCompare(String(b.name ?? ""), "zh-Hans");
+    });
+}
+
+export async function runSpaceReadCommand(
+  args: string[],
+  deps: AgentCommandDeps = {}
+) {
+  const env = deps.env ?? process.env;
+  const output = deps.output ?? process.stdout;
+  const { raw, brief, contentKeyFilter, includeRecord } = parseSpaceReadArgs(args);
+
+  const authToken = resolveAuthToken(env);
+  if (!authToken) {
+    output.write("[nolo] space read requires an auth token. Run `nolo login` or set AUTH_TOKEN.\n");
+    return 1;
+  }
+
+  const userId = parseUserIdFromAuthToken(authToken);
+  if (!userId) {
+    output.write("[nolo] space read could not read userId from AUTH_TOKEN.\n");
+    return 1;
+  }
+
+  const db = deps.db ?? await getReadableCliDb(output);
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const fallbackFetchImpl = deps.fallbackFetchImpl;
+  const defaultServerUrl = resolveServerUrl(env);
+  const serverCandidates = resolveServerCandidates(env, defaultServerUrl);
+
+  try {
+    const spaceId = parseSpaceIdFromInput(raw);
+    const spaceKey = createSpaceKey.space(spaceId);
+    const space = await readRecordWithCandidates<Record<string, any>>({
+      db,
+      dbKey: spaceKey,
+      serverCandidates,
+      readRemote: async (serverUrl, dbKey) =>
+        readDbRecord({
+          authToken,
+          dbKey,
+          fallbackFetchImpl,
+          fetchImpl,
+          serverUrl,
+        }),
+    });
+
+    const categories = buildCategories(space);
+    const allContents = buildContentEntries(space);
+    const contents = contentKeyFilter
+      ? allContents.filter((item) => {
+          const contentKey =
+            typeof item.contentKey === "string" && item.contentKey.trim()
+              ? item.contentKey.trim()
+              : item.entryKey;
+          return item.entryKey === contentKeyFilter || contentKey === contentKeyFilter;
+        })
+      : allContents;
+
+    const contentCounts = allContents.reduce<Record<string, number>>((acc, item) => {
+      const type = typeof item.type === "string" ? item.type : "unknown";
+      acc[type] = (acc[type] ?? 0) + 1;
+      return acc;
+    }, {});
+
+    const categoryContentMap = allContents.reduce<Record<string, string[]>>((acc, item) => {
+      const categoryId =
+        typeof item.categoryId === "string" && item.categoryId.trim()
+          ? item.categoryId.trim()
+          : "";
+      if (!categoryId) return acc;
+      if (!acc[categoryId]) acc[categoryId] = [];
+      acc[categoryId].push(
+        typeof item.contentKey === "string" && item.contentKey.trim()
+          ? item.contentKey.trim()
+          : item.entryKey
+      );
+      return acc;
+    }, {});
+
+    const categoriesWithStats = categories.map((category) => ({
+      ...category,
+      itemCount: categoryContentMap[category.categoryId]?.length ?? 0,
+      contentKeys: categoryContentMap[category.categoryId] ?? [],
+    }));
+
+    const uncategorizedContentKeys = contents
+      .filter((item) => !(typeof item.categoryId === "string" && item.categoryId.trim()))
+      .map((item) =>
+        typeof item.contentKey === "string" && item.contentKey.trim()
+          ? item.contentKey.trim()
+          : item.entryKey
+      );
+
+    const resolvedAgents = await Promise.all(
+      contents
+        .filter((item) => item.type === ContentType.AGENT && !brief)
+        .map(async (item) => {
+          const contentKey =
+            typeof item.contentKey === "string" && item.contentKey.trim()
+              ? item.contentKey.trim()
+              : item.entryKey;
+          try {
+            const record = await readRecordWithCandidates<Record<string, any>>({
+              db,
+              dbKey: contentKey,
+              serverCandidates,
+              readRemote: async (serverUrl, dbKey) =>
+                readDbRecord({
+                  authToken,
+                  dbKey,
+                  fallbackFetchImpl,
+                  fetchImpl,
+                  serverUrl,
+                }),
+            });
+            return {
+              contentKey,
+              slotTitle: item.title,
+              categoryId: item.categoryId ?? null,
+              pinned: !!item.pinned,
+              updatedAt: item.updatedAt ?? null,
+              agentId: record?.id ?? null,
+              name: record?.name ?? null,
+              model: record?.model ?? null,
+              provider: record?.provider ?? record?.apiSource ?? null,
+              isPublic: typeof record?.isPublic === "boolean" ? record.isPublic : null,
+              userId: record?.userId ?? null,
+              tools: Array.isArray(record?.tools) ? record.tools : [],
+              customProviderUrl: record?.customProviderUrl ?? null,
+            };
+          } catch (error) {
+            return {
+              contentKey,
+              slotTitle: item.title,
+              categoryId: item.categoryId ?? null,
+              pinned: !!item.pinned,
+              updatedAt: item.updatedAt ?? null,
+              readError: error instanceof Error ? error.message : String(error),
+            };
+          }
+        })
+    );
+
+    const resolvedSkillDocs = (
+      await Promise.all(
+        contents
+          .filter((item) => item.type === ContentType.DOC && !brief)
+          .map(async (item) => {
+            const contentKey =
+              typeof item.contentKey === "string" && item.contentKey.trim()
+                ? item.contentKey.trim()
+                : item.entryKey;
+            try {
+              const record = await readRecordWithCandidates<Record<string, any>>({
+                db,
+                dbKey: contentKey,
+                serverCandidates,
+                readRemote: async (serverUrl, dbKey) =>
+                  readDbRecord({
+                    authToken,
+                    dbKey,
+                    fallbackFetchImpl,
+                    fetchImpl,
+                    serverUrl,
+                  }),
+              });
+              const parsed = parseSkillDocProtocol(
+                typeof record?.content === "string" ? record.content : "",
+                record?.meta,
+                record?.tools
+              );
+              const meta = resolvePageSkillMetadata(record);
+              const skillConfig = meta?.skillConfig;
+              if (!(meta?.kind === "skill" || skillConfig)) {
+                return null;
+              }
+              return {
+                contentKey,
+                slotTitle: item.title,
+                title: record?.title ?? item.title ?? null,
+                categoryId: item.categoryId ?? null,
+                pinned: !!item.pinned,
+                updatedAt: item.updatedAt ?? null,
+                skillId: skillConfig?.id ?? record?.id ?? null,
+                name: skillConfig?.name ?? null,
+                description: skillConfig?.description ?? null,
+                toolNames: skillConfig?.toolNames ?? [],
+                requiredSkills: skillConfig?.requiredSkills ?? [],
+                recommendedSkills: skillConfig?.recommendedSkills ?? [],
+                triggerMode: skillConfig?.triggerMode ?? null,
+                promptPatch: skillConfig?.promptPatch ?? null,
+                bodyPreview:
+                  typeof parsed.content === "string" ? parsed.content.slice(0, 240) : "",
+              };
+            } catch (error) {
+              return {
+                contentKey,
+                slotTitle: item.title,
+                categoryId: item.categoryId ?? null,
+                pinned: !!item.pinned,
+                updatedAt: item.updatedAt ?? null,
+                readError: error instanceof Error ? error.message : String(error),
+              };
+            }
+          })
+      )
+    ).filter(Boolean);
+
+    const result: Record<string, any> = {
+      baseUrl: defaultServerUrl,
+      spaceId,
+      spaceKey,
+      name: space?.name ?? null,
+      description: space?.description ?? null,
+      ownerId: space?.ownerId ?? null,
+      visibility: space?.visibility ?? null,
+      memberCount: Array.isArray(space?.members) ? space.members.length : 0,
+      members: Array.isArray(space?.members) ? space.members : [],
+      categoryCount: categories.length,
+      categories: brief
+        ? categoriesWithStats.map(({ contentKeys, ...category }) => category)
+        : categoriesWithStats,
+      uncategorizedCount: uncategorizedContentKeys.length,
+      ...(brief ? {} : { uncategorizedContentKeys }),
+      contentCount: allContents.length,
+      contentCounts,
+      contents,
+      agents: resolvedAgents,
+      pageCount: allContents.filter((item) => item.type === ContentType.DOC).length,
+      skillDocCount: resolvedSkillDocs.length,
+      skillDocs: resolvedSkillDocs,
+    };
+
+    if (contentKeyFilter) {
+      result.contentKeyFilter = contentKeyFilter;
+      result.matchedCount = contents.length;
+    }
+
+    if (includeRecord) {
+      result.record = space;
+    }
+
+    output.write(`${JSON.stringify(result, null, 2)}\n`);
+    return 0;
+  } catch (error) {
+    output.write(
+      `[nolo] space read failed: ${
+        error instanceof Error ? error.message : String(error)
+      }\n`
+    );
+    return 1;
+  }
+}

package/systemInternalCommandEntries.ts

@@ -1,10 +1,12 @@
 import { runLoginCommand, runLogoutCommand, runWhoamiCommand } from "./authCommands";
 import {
+  createArgsCommand,
+  createContextCommand,
+  createDaemonShortcutCommand,
   createEntrypointEnvCommand,
   createEnvCommand,
 } from "./cliCommandFactories";
-import { createInternalCommand, type CommandEntry } from "./cliCommandTypes";
-import { withDaemonShortcutArgs } from "./cliCommandDispatch";
+import type { CommandEntry } from "./cliCommandTypes";
 import { DEFAULT_NOLO_SERVER_URL } from "./defaultServer";
 import {
   runMachineConnectCommand,
@@ -20,21 +22,13 @@ import {
 export function getSystemInternalCommandEntries(renderHelpText: () => string): CommandEntry[] {
   return [
     createEnvCommand(["doctor", "runtime"], "Diagnose local-first agent runtime selection", runDoctorRuntimeCommand),
-    createInternalCommand(["login"], "Log in to Nolo", (args) => Promise.resolve(runLoginCommand(args))),
-    createInternalCommand(["logout"], "Log out of Nolo", async () => runLogoutCommand()),
-    createInternalCommand(["whoami"], "Show the current login state", async () => runWhoamiCommand()),
+    createArgsCommand(["login"], "Log in to Nolo", (args) => Promise.resolve(runLoginCommand(args))),
+    createArgsCommand(["logout"], "Log out of Nolo", async () => runLogoutCommand()),
+    createArgsCommand(["whoami"], "Show the current login state", async () => runWhoamiCommand()),
     createEntrypointEnvCommand(["connect"], "Send machine heartbeats or hold a connector websocket", runMachineConnectCommand),
-    createInternalCommand(["daemon"], "Run the connector daemon shortcut", (args, ctx) => {
-      const normalized = withDaemonShortcutArgs(args, ctx.env);
-      return runMachineConnectCommand(["--ws"], {
-        env: normalized.envOverride ?? ctx.env,
-        cliEntrypointPath: ctx.entrypointPath,
-      });
-    }),
-    createInternalCommand(["machine", "status"], "List machines registered to the current profile", (args, ctx) =>
-      runMachineStatusCommand(args, { env: ctx.env })
-    ),
-    createInternalCommand(["doctor"], "Show CLI doctor information", async (_args, ctx) => {
+    createDaemonShortcutCommand(["daemon"], "Run the connector daemon shortcut", runMachineConnectCommand),
+    createEnvCommand(["machine", "status"], "List machines registered to the current profile", runMachineStatusCommand),
+    createContextCommand(["doctor"], "Show CLI doctor information", async (_args, ctx) => {
       console.log(
         buildCliDoctorText({
           packageName: ctx.packageInfo.name,
@@ -46,24 +40,24 @@ export function getSystemInternalCommandEntries(renderHelpText: () => string): C
       );
       return 0;
     }),
-    createInternalCommand(["update"], "Update the CLI", async () => runSelfUpdate()),
-    createInternalCommand(["version"], "Show CLI version", async (_args, ctx) => {
+    createArgsCommand(["update"], "Update the CLI", async () => runSelfUpdate()),
+    createContextCommand(["version"], "Show CLI version", async (_args, ctx) => {
       console.log(buildCliVersionText(ctx.packageInfo));
       return 0;
     }),
-    createInternalCommand(["--version"], "Show CLI version", async (_args, ctx) => {
+    createContextCommand(["--version"], "Show CLI version", async (_args, ctx) => {
       console.log(buildCliVersionText(ctx.packageInfo));
       return 0;
     }),
-    createInternalCommand(["-v"], "Show CLI version", async (_args, ctx) => {
+    createContextCommand(["-v"], "Show CLI version", async (_args, ctx) => {
       console.log(buildCliVersionText(ctx.packageInfo));
       return 0;
     }),
-    createInternalCommand(["--help"], "Show help", async () => {
+    createArgsCommand(["--help"], "Show help", async () => {
       console.log(renderHelpText());
       return 0;
     }),
-    createInternalCommand(["-h"], "Show help", async () => {
+    createArgsCommand(["-h"], "Show help", async () => {
       console.log(renderHelpText());
       return 0;
     }),

package/tableCommands.ts

@@ -1,8 +1,21 @@
-import { DEFAULT_NOLO_SERVER_URL } from "./defaultServer";
-import { includeTableActivityColumns } from "./render/table/activityColumns";
-
-type EnvLike = Record<string, string | undefined>;
-type OutputLike = { write(chunk: string): unknown };
+import type { EnvLike } from "./tableQueryParsing";
+import type { OutputLike } from "./cliIoTypes";
+import {
+  formatOutput,
+  hasFlag,
+  parseJsonOption,
+  parseJsonOptionAlias,
+  parseJwtTenantId,
+  parseOutputMode,
+  parseTableArg,
+  readOption,
+  resolveAuthToken,
+  resolveServerUrl,
+} from "./tableQueryParsing";
+import {
+  buildTableQueryRequest,
+  mergeQueryShortcutFilters,
+} from "./tableQueryRequest";
 
 type TableCommandDeps = {
   env?: EnvLike;
@@ -10,121 +23,6 @@ type TableCommandDeps = {
   fetchImpl?: typeof fetch;
 };
 
-type OutputMode = "full" | "raw" | "items" | "jsonl";
-
-function readOption(args: string[], flag: string): string {
-  for (let i = 0; i < args.length; i++) {
-    const value = args[i];
-    if (value === flag) return args[i + 1] ?? "";
-    if (value.startsWith(`${flag}=`)) return value.slice(flag.length + 1);
-  }
-  return "";
-}
-
-function hasFlag(args: string[], flag: string): boolean {
-  return args.includes(flag);
-}
-
-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)}`);
-  }
-}
-
-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)}`);
-  }
-}
-
-function parseOutputMode(raw: string): OutputMode {
-  if (!raw) return "full";
-  if (raw === "json") return "raw";
-  if (raw === "full" || raw === "raw" || raw === "items" || raw === "jsonl") return raw;
-  throw new Error(`--output must be one of full, raw, items, json, jsonl; got ${raw}`);
-}
-
-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("-"),
-  };
-}
-
-function resolveServerUrl(args: string[], env: EnvLike): string {
-  return (
-    readOption(args, "--server-url") ||
-    readOption(args, "--server") ||
-    readOption(args, "--base-url") ||
-    env.NOLO_SERVER_URL ||
-    env.NOLO_SERVER ||
-    env.BASE_URL ||
-    DEFAULT_NOLO_SERVER_URL
-  ).replace(/\/+$/, "");
-}
-
-function resolveAuthToken(args: string[], env: EnvLike): string {
-  return (
-    readOption(args, "--api-key") ||
-    readOption(args, "--token") ||
-    env.AUTH_TOKEN ||
-    env.AUTH ||
-    ""
-  );
-}
-
-function parseJwtTenantId(token: string): string | undefined {
-  const [, payload] = token.split(".");
-  if (!payload) return undefined;
-  try {
-    const normalized = payload.replace(/-/g, "+").replace(/_/g, "/");
-    const decoded = Buffer.from(normalized, "base64").toString("utf8");
-    const parsed = JSON.parse(decoded);
-    return typeof parsed.userId === "string" ? parsed.userId : typeof parsed.sub === "string" ? parsed.sub : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-function formatOutput(input: { envelope: any; rawData: any; mode: OutputMode }): string {
-  if (input.mode === "full") return JSON.stringify(input.envelope, null, 2);
-  if (input.mode === "raw") return JSON.stringify(input.rawData, null, 2);
-  const items = Array.isArray(input.rawData?.items) ? input.rawData.items : input.rawData;
-  if (input.mode === "items") return JSON.stringify(items, null, 2);
-  return Array.isArray(items) ? items.map((item) => JSON.stringify(item)).join("\n") : JSON.stringify(items);
-}
-
-function mergeQueryShortcutFilters(args: string[], filters: Record<string, unknown> | undefined): Record<string, unknown> | undefined {
-  const row = readOption(args, "--row") || readOption(args, "--row-id");
-  const rowDbKey = readOption(args, "--row-dbkey");
-  const shortcutFilters: Record<string, unknown> = {};
-  if (row) {
-    if (row.startsWith("row-")) shortcutFilters.dbKey = row;
-    else shortcutFilters.rowId = row;
-  }
-  if (rowDbKey) shortcutFilters.dbKey = rowDbKey;
-  if (Object.keys(shortcutFilters).length === 0) return filters;
-  return {
-    ...(filters ?? {}),
-    ...shortcutFilters,
-  };
-}
-
 function usage(): string {
   return [
     "Usage:",
@@ -180,19 +78,21 @@ export async function runTableQueryCommand(args: string[], deps: TableCommandDep
         Authorization: `Bearer ${authToken}`,
         "Content-Type": "application/json",
       },
-      body: JSON.stringify({
-        tenantId,
-        tableId,
-        filters: filters ?? {},
-        columns: hasFlag(args, "--include-activity")
-          ? includeTableActivityColumns(columns)
-          : columns,
-        includeBaseFields: !hasFlag(args, "--no-base-fields"),
-        limit: Number(readOption(args, "--limit") || (hasSingleRowShortcut ? 1 : 20)),
-        offset: Number(readOption(args, "--offset") || 0),
-        sortBy: readOption(args, "--sort-by") || "updatedAt",
-        sortOrder: readOption(args, "--sort-order") === "asc" ? "asc" : "desc",
-      }),
+      body: JSON.stringify(
+        buildTableQueryRequest({
+          tenantId,
+          tableId,
+          filters,
+          columns,
+          includeActivity: hasFlag(args, "--include-activity"),
+          includeBaseFields: !hasFlag(args, "--no-base-fields"),
+          hasSingleRowShortcut,
+          limit: readOption(args, "--limit"),
+          offset: readOption(args, "--offset"),
+          sortBy: readOption(args, "--sort-by"),
+          sortOrder: readOption(args, "--sort-order"),
+        })
+      ),
     });
   } catch (error) {
     output.write(`[nolo] table query failed: ${error instanceof Error ? error.message : String(error)}\n`);

package/tableDataOutput.ts

@@ -0,0 +1,41 @@
+export type TableDataOutputMode = "full" | "raw" | "items" | "jsonl";
+
+export function parseTableDataOutputMode(raw?: string): TableDataOutputMode {
+  const value = raw?.trim();
+  if (!value) return "full";
+  if (value === "json") return "raw";
+  if (value === "full" || value === "raw" || value === "items" || value === "jsonl") {
+    return value;
+  }
+  throw new Error(`--output must be one of full, raw, items, json, jsonl; got ${value}`);
+}
+
+function getItems(result: unknown): unknown[] | undefined {
+  if (!result || typeof result !== "object") return undefined;
+  const items = (result as any).items;
+  return Array.isArray(items) ? items : undefined;
+}
+
+export function formatTableDataOutput(input: {
+  envelope: unknown;
+  result: unknown;
+  mode: TableDataOutputMode;
+}): string {
+  if (input.mode === "full") {
+    return JSON.stringify(input.envelope, null, 2);
+  }
+  if (input.mode === "raw") {
+    return JSON.stringify(input.result, null, 2);
+  }
+
+  const items = getItems(input.result);
+  const value = items ?? input.result;
+  if (input.mode === "items") {
+    return JSON.stringify(value, null, 2);
+  }
+  if (!Array.isArray(value)) {
+    return JSON.stringify(value);
+  }
+  return value.map((item) => JSON.stringify(item)).join("\n");
+}
+

package/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));
+}