@pplethai/cli 0.7.0 → 0.8.0

package/templates/golden-path/src/dev-read-dataset.ts

@@ -0,0 +1,429 @@
+// Offline Dataset reads (ADR-0030, ADR-0026). Active only where
+// `import.meta.env.DEV` is true and `DEV_PERSONA` is not `"none"` — `vite dev`,
+// not vitest and not the production build. `readDataset` reaches this module
+// only from that branch, so `vite build` drops it the same way it drops the
+// Persona bypass (ADR-0011).
+//
+// The overlay is `.pple/registry/<provider>/<name>/`. Vite's `import.meta.glob`
+// skips a dot-folder unless the dot sits in the pattern's fixed base, so both
+// globs below keep `.pple/registry` in that base. CI has no overlay; tests
+// pass a fixture glob to `answerOfflineDataset` and never read `.pple/`.
+//
+// Object Type shape, schema, id, index and level come from `entry.md`'s last
+// approved frontmatter. Static `subs` arrays are not in that file (ADR-0025),
+// and a swept list never reaches the workspace. A missing list is empty, so
+// `passesLevel` admits nobody for that part — the same as before the first
+// sweep (ADR-0028) and the same as a level made only of subs (ADR-0026).
+// That fails closed: the offline path does not invent a list it cannot see.
+//
+// `sweptAt` is the mock file's write time, or `entry.md`'s if the mock has
+// none. The Worker cannot stat, so the dev server embeds the mtime. `snapshot`
+// is a stable hash of the mock text: the warehouse's integer is not in the
+// overlay, and pages of one file must share a snapshot. A declared Object Type
+// with no mock file is `no_mock`, not an empty page. Offline has no warehouse,
+// and a missing mock is the dev-only miss (ADR-0026).
+
+import { parse as parseYaml } from "yaml";
+import { forcedError, platformRefusal } from "./dev-call-service";
+import { resolveDevPersona } from "./dev-personas";
+import { applyDatasetQuery, datasetOpaqueHash, datasetPageHash, parseDatasetQuery, type DatasetQuerySpec, type DatasetRow } from "./dataset-query";
+import { passesLevel, type AccessLevel } from "./levels";
+import { isPlainObject } from "./dataset-schema";
+
+const MOCK_HEADER = "x-pple-mock";
+const ERROR_HEADER = "x-pple-error";
+
+export interface OfflineDatasetCall {
+  entry: string;
+  objectType: string;
+  id?: string;
+  /** Query entries, in the order `readDataset` puts them on the URL. */
+  search?: readonly (readonly [string, string])[];
+  userToken?: string;
+  /** Active Persona name. An unknown name warns and uses `hq-staff`. */
+  persona: string;
+  devRegistryError?: string;
+}
+
+interface DeclaredType {
+  shape: "singleton" | "collection";
+  level: AccessLevel;
+  idProperty: string;
+  spec: DatasetQuerySpec | null;
+}
+
+interface IndexedEntry {
+  types: Map<string, DeclaredType> | null;
+  mocks: Map<string, string>;
+}
+
+/** `npm run dev` entry. Reads the overlay glob, its mtimes, and the active Persona. */
+export function answerOfflineRead(
+  env: { DEV_PERSONA?: string; DEV_REGISTRY_ERROR?: string },
+  entry: string,
+  objectType: string,
+  request: { id?: string; search?: readonly (readonly [string, string])[]; userToken?: string },
+): Response {
+  return answerOfflineDataset(overlayFiles(), overlayWrittenAt(), {
+    entry,
+    objectType,
+    id: request.id,
+    search: request.search,
+    userToken: request.userToken,
+    persona: env.DEV_PERSONA ?? "",
+    devRegistryError: env.DEV_REGISTRY_ERROR,
+  });
+}
+
+/**
+ * The response a Builder observes for one offline read. `files` is an
+ * `import.meta.glob` of raw text. `writtenAt` is the matching `?mtime` glob:
+ * each value is the file's write time.
+ */
+export function answerOfflineDataset(
+  files: Readonly<Record<string, unknown>>,
+  writtenAt: Readonly<Record<string, unknown>>,
+  call: OfflineDatasetCall,
+): Response {
+  const forced = forcedError(call.devRegistryError, call.entry);
+  if (forced) return platformRefusal(forced);
+
+  const indexed = indexOverlay(files);
+  const entry = indexed.get(call.entry);
+  if (!entry) return noMock(missingEntryMessage(call.entry));
+
+  const declared = entry.types?.get(call.objectType) ?? null;
+  if (!declared) return platformRefusal("not_found");
+
+  const identity = resolveDevPersona(call.persona);
+  if (declared.level !== "public" && !hasToken(call.userToken)) {
+    return platformRefusal("user_token_invalid");
+  }
+  // Once, for the Object Type, before any row is read. A swept list is empty
+  // here: it is not in the overlay. A static list was removed from entry.md,
+  // so a missing `subs` array admits nobody.
+  const swept = typeof declared.level === "object" && declared.level.subs === "swept";
+  if (!passesLevel(identity, declared.level, swept ? { sweptSubs: [] } : undefined)) {
+    return platformRefusal("level_not_met");
+  }
+
+  const mock = entry.mocks.get(call.objectType);
+  if (mock === undefined) return noMock(missingMockMessage(call.entry, call.objectType));
+
+  const sweptAt = writtenTime(writtenAt, call.entry, call.objectType);
+  const snapshot = snapshotOf(mock);
+  const search = call.search ?? [];
+
+  if (declared.shape === "singleton") {
+    if (call.id !== undefined) return platformRefusal("not_found");
+    if (search.length > 0) return platformRefusal("invalid_query");
+    const object = parseSingleton(call.entry, call.objectType, mock);
+    if (object === undefined) return noMock(unreadableMockMessage(call.entry, call.objectType));
+    return jsonAnswer(call.entry, { object, sweptAt, snapshot }, etag(snapshot, datasetOpaqueHash({ singleton: true })));
+  }
+
+  // A query on an id lookup is invalid even when the declaration cannot be
+  // queried. A list against that declaration is invalid_query too.
+  if (call.id !== undefined && search.length > 0) return platformRefusal("invalid_query");
+  if (!declared.spec) {
+    return call.id !== undefined ? platformRefusal("not_found") : platformRefusal("invalid_query");
+  }
+
+  const rows = parseRows(call.entry, call.objectType, mock, declared);
+  if (!rows) return noMock(unreadableMockMessage(call.entry, call.objectType));
+
+  if (call.id !== undefined) {
+    const id = canonicalId(call.id, declared.spec.idType);
+    const found = id === null ? undefined : rows.find((row) => row.id === id);
+    if (!found) return platformRefusal("not_found");
+    return jsonAnswer(
+      call.entry,
+      { object: found.object, sweptAt, snapshot },
+      etag(snapshot, datasetOpaqueHash({ lookup: id })),
+    );
+  }
+
+  const params = new URLSearchParams();
+  for (const [key, value] of search) params.append(key, value);
+  const parsed = parseDatasetQuery(params, declared.spec);
+  if (!parsed.ok) return platformRefusal("invalid_query");
+  const page = applyDatasetQuery(rows, parsed.query, declared.spec);
+  return jsonAnswer(
+    call.entry,
+    { objects: page.objects, next: page.next, sweptAt, snapshot },
+    etag(snapshot, datasetPageHash(parsed.query)),
+  );
+}
+
+function overlayFiles(): Record<string, unknown> {
+  if (!import.meta.env.DEV) return {};
+  return import.meta.glob("../.pple/registry/**/*", {
+    eager: true,
+    query: "?raw",
+    import: "default",
+  });
+}
+
+function overlayWrittenAt(): Record<string, unknown> {
+  if (!import.meta.env.DEV) return {};
+  return import.meta.glob("../.pple/registry/**/*", {
+    eager: true,
+    query: "?mtime",
+    import: "default",
+  });
+}
+
+function indexOverlay(files: Readonly<Record<string, unknown>>): Map<string, IndexedEntry> {
+  const found = new Map<string, { entryMd?: string; mocks: Map<string, string> }>();
+  const touch = (id: string) => {
+    const row = found.get(id) ?? { mocks: new Map<string, string>() };
+    found.set(id, row);
+    return row;
+  };
+  for (const [file, value] of Object.entries(files)) {
+    const text = asText(value);
+    if (text === null) continue;
+    const path = normalize(file);
+    const entryMd = path.match(/(?:^|\/)([^/]+)\/([^/]+)\/entry\.md$/);
+    if (entryMd?.[1] && entryMd[2]) {
+      touch(`${entryMd[1]}/${entryMd[2]}`).entryMd = text;
+      continue;
+    }
+    const mock = path.match(/(?:^|\/)([^/]+)\/([^/]+)\/mocks\/([^/]+)\.json$/);
+    if (mock?.[1] && mock[2] && mock[3]) {
+      touch(`${mock[1]}/${mock[2]}`).mocks.set(mock[3], text);
+    }
+  }
+  const entries = new Map<string, IndexedEntry>();
+  for (const [id, row] of found) {
+    entries.set(id, {
+      types: row.entryMd === undefined ? null : declaredTypes(id, row.entryMd),
+      mocks: row.mocks,
+    });
+  }
+  return entries;
+}
+
+function declaredTypes(entry: string, entryMd: string): Map<string, DeclaredType> | null {
+  const parsed = readFrontmatter(entryMd);
+  if (!parsed) {
+    console.warn(`readDataset could not read .pple/registry/${entry}/entry.md. Run pple registry to refresh it.`);
+    return null;
+  }
+  const datasetLevel = "level" in parsed ? asLevel(parsed.level) : null;
+  if ("level" in parsed && datasetLevel === null) return null;
+  const raw = parsed.objectTypes;
+  if (!isPlainObject(raw)) return new Map();
+  const types = new Map<string, DeclaredType>();
+  for (const [name, body] of Object.entries(raw)) {
+    if (!isPlainObject(body)) continue;
+    const shape = body.shape === "singleton" || body.shape === "collection" ? body.shape : null;
+    if (!shape) continue;
+    const ownLevel = "level" in body ? asLevel(body.level) : null;
+    if ("level" in body && ownLevel === null) continue;
+    const level = ownLevel ?? datasetLevel;
+    if (!level) continue;
+    const schema = isPlainObject(body.schema) ? body.schema : null;
+    if (!schema) continue;
+    if (shape === "singleton") {
+      types.set(name, { shape, level, idProperty: "id", spec: null });
+      continue;
+    }
+    const idProperty = typeof body.id === "string" && body.id !== "" ? body.id : "id";
+    const index = readIndex(body.index, schema);
+    const idType = idTypeOf(schema, idProperty);
+    types.set(name, {
+      shape,
+      level,
+      idProperty,
+      spec: index === null ? null : { idType, index },
+    });
+  }
+  return types;
+}
+
+function readFrontmatter(entryMd: string): Record<string, unknown> | null {
+  const fence = entryMd.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  const body = fence?.[1];
+  if (body === undefined) return null;
+  try {
+    const value = parseYaml(body) as unknown;
+    if (!isPlainObject(value)) return null;
+    return value;
+  } catch {
+    return null;
+  }
+}
+
+function asLevel(value: unknown): AccessLevel | null {
+  if (value === "public" || value === "member" || value === "internal") return value;
+  if (!isPlainObject(value)) return null;
+  const level: { roles?: string[]; subs?: string[] | "swept" } = {};
+  if ("roles" in value) {
+    if (!Array.isArray(value.roles) || value.roles.some((item) => typeof item !== "string")) return null;
+    level.roles = value.roles;
+  }
+  if ("subs" in value) {
+    if (value.subs === "swept") level.subs = "swept";
+    else if (Array.isArray(value.subs) && value.subs.every((item) => typeof item === "string")) {
+      level.subs = value.subs;
+    } else return null;
+  }
+  return level;
+}
+
+function readIndex(
+  value: unknown,
+  schema: Record<string, unknown>,
+): { name: string; schema: Record<string, unknown> }[] | null {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item === "")) return null;
+  const properties = isPlainObject(schema.properties) ? schema.properties : null;
+  if (!properties) return null;
+  const index: { name: string; schema: Record<string, unknown> }[] = [];
+  for (const name of value) {
+    const property = properties[name];
+    if (!isPlainObject(property)) return null;
+    index.push({ name, schema: property });
+  }
+  return index;
+}
+
+function idTypeOf(schema: Record<string, unknown>, idProperty: string): DatasetQuerySpec["idType"] {
+  const properties = isPlainObject(schema.properties) ? schema.properties : null;
+  const idSchema = properties ? properties[idProperty] : null;
+  return isPlainObject(idSchema) && idSchema.type === "integer" ? "integer" : "string";
+}
+
+function parseSingleton(entry: string, objectType: string, text: string): Record<string, unknown> | null | undefined {
+  const parsed = parseJson(entry, objectType, text);
+  if (parsed === undefined) return undefined;
+  if (parsed === null) return null;
+  if (!isPlainObject(parsed)) return undefined;
+  return parsed;
+}
+
+function parseRows(entry: string, objectType: string, text: string, declared: DeclaredType): DatasetRow[] | null {
+  const parsed = parseJson(entry, objectType, text);
+  if (!Array.isArray(parsed)) return null;
+  const idType = declared.spec?.idType ?? "string";
+  const rows: DatasetRow[] = [];
+  for (const item of parsed) {
+    if (!isPlainObject(item)) return null;
+    const id = rowId(item, declared.idProperty, idType);
+    if (id === null) return null;
+    rows.push({ id, object: item });
+  }
+  return rows;
+}
+
+function parseJson(entry: string, objectType: string, text: string): unknown | undefined {
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    console.warn(
+      `readDataset could not read .pple/registry/${entry}/mocks/${objectType}.json. Run pple registry to refresh it.`,
+    );
+    return undefined;
+  }
+}
+
+function rowId(object: Record<string, unknown>, idProperty: string, idType: DatasetQuerySpec["idType"]): string | null {
+  if (!Object.hasOwn(object, idProperty)) return null;
+  const value = object[idProperty];
+  if (idType === "integer") {
+    if (typeof value !== "number" || !Number.isSafeInteger(value)) return null;
+    return String(value);
+  }
+  if (typeof value !== "string" || value === "") return null;
+  return value;
+}
+
+function canonicalId(raw: string, idType: DatasetQuerySpec["idType"]): string | null {
+  if (idType === "string") return raw === "" ? null : raw;
+  if (!/^-?\d+$/.test(raw)) return null;
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value)) return null;
+  return String(value);
+}
+
+function writtenTime(writtenAt: Readonly<Record<string, unknown>>, entry: string, objectType: string): string | null {
+  const times = new Map<string, string>();
+  for (const [file, value] of Object.entries(writtenAt)) {
+    if (typeof value !== "string" || value === "") continue;
+    times.set(normalize(file), value);
+  }
+  const mockSuffix = `${entry}/mocks/${objectType}.json`;
+  const entrySuffix = `${entry}/entry.md`;
+  for (const [path, iso] of times) {
+    if (pathEnds(path, mockSuffix)) return iso;
+  }
+  for (const [path, iso] of times) {
+    if (pathEnds(path, entrySuffix)) return iso;
+  }
+  return null;
+}
+
+function pathEnds(path: string, suffix: string): boolean {
+  return path === suffix || path.endsWith(`/${suffix}`);
+}
+
+/** Stable across pages of one file, and different after the mock text changes. */
+function snapshotOf(text: string): number {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < text.length; i++) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  const value = hash >>> 0;
+  return value === 0 ? 1 : value;
+}
+
+function etag(snapshot: number, hash: string): string {
+  return `"${snapshot}-${hash}"`;
+}
+
+function hasToken(userToken: string | undefined): boolean {
+  return userToken !== undefined && userToken.trim() !== "";
+}
+
+function noMock(message: string): Response {
+  return Response.json(
+    { error: "no_mock", message },
+    { status: 404, headers: { [ERROR_HEADER]: "no_mock" } },
+  );
+}
+
+function missingEntryMessage(entry: string): string {
+  return `ไม่มี ${entry} ใน .pple/registry/ — รัน pple registry เพื่อดึงข้อมูลจำลอง`;
+}
+
+function missingMockMessage(entry: string, objectType: string): string {
+  return `${entry} ไม่มีข้อมูลจำลองสำหรับ ${objectType} — รัน pple registry เพื่อรีเฟรช`;
+}
+
+function unreadableMockMessage(entry: string, objectType: string): string {
+  return `อ่าน .pple/registry/${entry}/mocks/${objectType}.json ไม่ได้ — รัน pple registry เพื่อรีเฟรช`;
+}
+
+function jsonAnswer(entry: string, body: unknown, tag: string): Response {
+  const headers = new Headers({
+    "content-type": "application/json; charset=utf-8",
+    etag: tag,
+    [MOCK_HEADER]: entry,
+  });
+  return new Response(JSON.stringify(body), { status: 200, headers });
+}
+
+function asText(value: unknown): string | null {
+  if (typeof value === "string") return value;
+  if (value !== null && typeof value === "object" && "default" in value) {
+    const inner = (value as { default: unknown }).default;
+    if (typeof inner === "string") return inner;
+  }
+  return null;
+}
+
+function normalize(file: string): string {
+  return file.split("?")[0]?.replaceAll("\\", "/") ?? file;
+}