deepline 0.3.212 → 0.3.214

package/dist/bundling-sources/shared_libs/plays/settings-contract.ts

@@ -0,0 +1,176 @@
+import { z } from 'zod';
+
+/** Keep schema diagnostics readable in both interactive settings and the CLI. */
+export function formatPlaySettingsError(error: unknown): string {
+  if (error instanceof z.ZodError)
+    return [...new Set(error.issues.map((issue) => issue.message))].join(' ');
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Location organizes Plays. Existing workspace permissions still apply. */
+export const PLAY_LOCATION_ROOTS = [
+  {
+    value: 'person',
+    label: 'Personal',
+    description:
+      'The creator’s personal root, displayed as their name followed by “’s team”.',
+  },
+  {
+    value: 'team',
+    label: 'Team library',
+    description:
+      'The shared team library. Publishing moves personal locations here, keeping their folders.',
+  },
+] as const;
+
+const folder = z
+  .string()
+  .min(1)
+  .max(128)
+  .refine(
+    (value) =>
+      value === value.trim() &&
+      value !== '.' &&
+      value !== '..' &&
+      !/[\\/\u0000-\u001f\u007f]/u.test(value),
+    'Folder names must be trimmed, cannot be . or .., and cannot contain slashes or control characters.',
+  );
+export const playPathSchema = z
+  .union([
+    z.null(),
+    z
+      .object({
+        root: z.enum(['person', 'team']),
+        folders: z.array(folder).max(16).default([]),
+      })
+      .strict(),
+  ])
+  .transform((path) =>
+    path?.root === 'person' && path.folders.length === 0 ? null : path,
+  );
+export type PlayPath = z.output<typeof playPathSchema>;
+
+export function parsePlayPath(value: string): PlayPath {
+  const [root, ...parts] = value.split('/');
+  if (!PLAY_LOCATION_ROOTS.some((option) => option.value === root)) {
+    throw new Error(
+      'Path must start with person or team. Example: person/Research/ICP.',
+    );
+  }
+  let folders: string[];
+  try {
+    folders = parts.map(decodeURIComponent);
+  } catch {
+    throw new Error(
+      'Path contains an invalid percent escape. Encode a literal % as %25.',
+    );
+  }
+  return playPathSchema.parse({ root, folders });
+}
+export function formatPlayPath(path: PlayPath): string {
+  return path === null
+    ? 'person'
+    : [path.root, ...path.folders.map(encodeURIComponent)].join('/');
+}
+export function personalPlayRootLabel(ownerName?: string | null): string {
+  const name = ownerName?.trim();
+  return name ? `${name.split(/\s+/)[0]}’s team` : 'Personal';
+}
+export function displayPlayPath(
+  path: PlayPath,
+  ownerName?: string | null,
+): string {
+  return [
+    path?.root === 'team' ? 'Team library' : personalPlayRootLabel(ownerName),
+    ...(path?.folders ?? []),
+  ].join(' / ');
+}
+export function publishedPlayPath(path: PlayPath): PlayPath {
+  return { root: 'team', folders: path?.folders ?? [] };
+}
+
+/** One registry drives validation, defaults, CLI keys/help and settings controls. */
+export const PLAY_SETTING_FIELDS = {
+  path: {
+    schema: playPathSchema
+      .default(null)
+      .describe(
+        'Play location. Null means the creator’s personal root. Publishing moves it into Team library, preserving folders.',
+      ),
+    label: 'Location',
+    description:
+      'Organize this Play in the creator’s personal root or Team library. Publishing moves it to Team library and keeps its folders. Workspace sharing permissions apply in both roots.',
+    get defaultValue(): PlayPath {
+      return this.schema.parse(undefined);
+    },
+    cli: {
+      valueSyntax: 'person[/folder/…] | team[/folder/…] | null',
+      examples: [
+        'person',
+        'person/Research/ICP',
+        'team',
+        'team/Research',
+        'null',
+      ],
+      parse: (value: string) =>
+        value === 'null' ? null : parsePlayPath(value),
+      format: formatPlayPath,
+    },
+    ui: { control: 'play-location-picker' as const },
+  },
+} as const;
+export const playSettingsSchema = z.object(
+  Object.fromEntries(
+    Object.entries(PLAY_SETTING_FIELDS).map(([key, field]) => [
+      key,
+      field.schema,
+    ]),
+  ) as {
+    [K in keyof typeof PLAY_SETTING_FIELDS]: (typeof PLAY_SETTING_FIELDS)[K]['schema'];
+  },
+).passthrough();
+export const playSettingsPatchSchema = z
+  .object(
+    Object.fromEntries(
+      Object.entries(PLAY_SETTING_FIELDS).map(([key, field]) => [
+        key,
+        field.schema.unwrap().optional(),
+      ]),
+    ) as {
+      [K in keyof typeof PLAY_SETTING_FIELDS]: z.ZodOptional<
+        ReturnType<(typeof PLAY_SETTING_FIELDS)[K]['schema']['unwrap']>
+      >;
+    },
+  )
+  .strict()
+  .refine(
+    (patch) => Object.keys(patch).length > 0,
+    'Supply at least one setting.',
+  );
+export type PlaySettings = {
+  [K in keyof typeof PLAY_SETTING_FIELDS]: z.output<
+    (typeof PLAY_SETTING_FIELDS)[K]['schema']
+  >;
+};
+export type PlaySettingsPatch = z.output<typeof playSettingsPatchSchema>;
+/** Validate registered keys while preserving future keys in stored objects. */
+export function parsePlaySettings(value: unknown): PlaySettings {
+  return playSettingsSchema.parse(value) as PlaySettings;
+}
+export const DEFAULT_PLAY_SETTINGS: PlaySettings = parsePlaySettings({});
+export type PlaySettingsResult = {
+  playDefinitionId: string;
+  ownerUserId: string | null;
+  ownerName: string | null;
+  settings: PlaySettings;
+};
+export type PlaySettingsPathsPage = {
+  paths: Array<{
+    path: PlayPath;
+    ownerUserId: string | null;
+    ownerName: string | null;
+    playName: string;
+  }>;
+  cursor: string | null;
+  hasMore: boolean;
+};