create-ailk 0.18.0 → 0.19.0

package/templates/apps/web/app/[locale]/(authed)/account/artifacts/__tests__/review.test.tsx

@@ -0,0 +1,288 @@
+/**
+ * The artifact review (#8234, spec 8234 D6, D7; AC-5, AC-6).
+ *
+ * Two layers:
+ *   - `submitArtifactReview` (the Server Action), with the api-client's
+ *     `member.reviewArtifact` as the one mocked boundary: the exact body it
+ *     posts for each verdict, the comment check before any call, each
+ *     refusal's reason, and logs that never carry the comment or the id.
+ *   - `ReviewForm` (the client form) over the real action, spied on to read
+ *     the `FormData` each button sends: the verdict and the comment, a
+ *     refusal that keeps the typed comment, and a sent review that refreshes
+ *     the page once.
+ */
+
+import {
+  act,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from "@testing-library/react";
+
+const mockReviewArtifact = jest.fn();
+jest.mock("@working-theory/api-client", () => ({
+  __esModule: true,
+  member: {
+    reviewArtifact: (...args: unknown[]) => mockReviewArtifact(...args),
+  },
+}));
+
+jest.mock("next/headers", () => ({
+  __esModule: true,
+  headers: jest
+    .fn()
+    .mockResolvedValue(new Headers({ origin: "https://site.example.com" })),
+  cookies: jest.fn().mockResolvedValue({ toString: () => "session=abc" }),
+}));
+
+const mockRefresh = jest.fn();
+jest.mock("next/navigation", () => ({
+  __esModule: true,
+  useRouter: () => ({ push: jest.fn(), refresh: mockRefresh }),
+}));
+
+import messages from "../../../../../../messages/en.json";
+import { ReviewForm, type ReviewFormLabels } from "../[pieceId]/review-form";
+import * as actions from "../artifact-actions";
+import { submitArtifactReview } from "../artifact-actions";
+
+const PIECE = "piece_01920000-0000-7000-8000-000000000001";
+const INIT = {
+  headers: { cookie: "session=abc", origin: "https://site.example.com" },
+};
+const COMMENT = "Tighten the logo";
+
+function form(fields: Record<string, string>): FormData {
+  const data = new FormData();
+  for (const [key, value] of Object.entries(fields)) data.set(key, value);
+  return data;
+}
+
+function review(
+  fields: Partial<Record<"pieceId" | "version" | "review" | "comment", string>>,
+) {
+  return submitArtifactReview(
+    { kind: "idle" },
+    form({
+      pieceId: PIECE,
+      version: "3",
+      review: "approved",
+      comment: "",
+      ...fields,
+    }),
+  );
+}
+
+function refusal(status: number, code: string) {
+  return {
+    ok: false,
+    status,
+    body: { ok: false, error: { code, message: "x" } },
+  };
+}
+
+let errorSpy: jest.SpyInstance;
+
+beforeEach(() => {
+  mockReviewArtifact
+    .mockReset()
+    .mockResolvedValue({ ok: true, body: { artifact: {} } });
+  mockRefresh.mockReset();
+  errorSpy = jest.spyOn(console, "error").mockImplementation(() => undefined);
+});
+
+afterEach(() => {
+  errorSpy.mockRestore();
+});
+
+describe("submitArtifactReview (D6, AC-5)", () => {
+  it("Approve posts { version, review } once with the caller's init and answers reviewed", async () => {
+    await expect(review({})).resolves.toEqual({ kind: "reviewed" });
+    expect(mockReviewArtifact).toHaveBeenCalledTimes(1);
+    expect(mockReviewArtifact).toHaveBeenCalledWith(
+      PIECE,
+      { version: 3, review: "approved" },
+      INIT,
+    );
+  });
+
+  it("Request changes posts the trimmed comment and no other key", async () => {
+    await expect(
+      review({ review: "changes-requested", comment: `  ${COMMENT}  ` }),
+    ).resolves.toEqual({ kind: "reviewed" });
+    expect(mockReviewArtifact).toHaveBeenCalledTimes(1);
+    expect(mockReviewArtifact.mock.calls[0]![1]).toStrictEqual({
+      version: 3,
+      review: "changes-requested",
+      comment: COMMENT,
+    });
+  });
+
+  it("an Approve with a comment carries it", async () => {
+    await review({ comment: "Lovely" });
+    expect(mockReviewArtifact.mock.calls[0]![1]).toStrictEqual({
+      version: 3,
+      review: "approved",
+      comment: "Lovely",
+    });
+  });
+
+  it.each(["", "   "])(
+    "Request changes with a blank comment (%j) is comment_required with no call",
+    async (comment) => {
+      await expect(
+        review({ review: "changes-requested", comment }),
+      ).resolves.toEqual({
+        kind: "error",
+        reason: "comment_required",
+      });
+      expect(mockReviewArtifact).not.toHaveBeenCalled();
+    },
+  );
+
+  it("Request changes with a comment the server would strip to nothing is comment_required with no call", async () => {
+    await expect(
+      review({ review: "changes-requested", comment: "\u200e\u202e" }),
+    ).resolves.toEqual({ kind: "error", reason: "comment_required" });
+    expect(mockReviewArtifact).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ["a malformed piece id", { pieceId: "x" }],
+    ["a version that is not a whole number", { version: "abc" }],
+    ["an unknown verdict", { review: "rejected" }],
+  ])("%s is failed with no call", async (_case, fields) => {
+    await expect(review(fields)).resolves.toEqual({
+      kind: "error",
+      reason: "failed",
+    });
+    expect(mockReviewArtifact).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ["review_closed", refusal(409, "review_closed"), "closed"],
+    ["version_not_latest", refusal(409, "version_not_latest"), "not_latest"],
+    ["too_many_requests", refusal(429, "too_many_requests"), "rate_limited"],
+    ["a 429 rate_limited", refusal(429, "rate_limited"), "rate_limited"],
+    ["invalid_input (400)", refusal(400, "invalid_input"), "failed"],
+    ["a status-0 refusal", refusal(0, "unauthorized"), "failed"],
+  ])("a %s refusal is %s", async (_case, res, reason) => {
+    mockReviewArtifact.mockResolvedValue(res);
+    await expect(
+      review({ review: "changes-requested", comment: COMMENT }),
+    ).resolves.toEqual({
+      kind: "error",
+      reason,
+    });
+    expect(mockReviewArtifact).toHaveBeenCalledTimes(1);
+  });
+
+  it("a throw is failed, logged by err.name only — never the comment or the piece id", async () => {
+    mockReviewArtifact.mockRejectedValue(
+      new TypeError(`fetch failed ${COMMENT} ${PIECE}`),
+    );
+    await expect(
+      review({ review: "changes-requested", comment: COMMENT }),
+    ).resolves.toEqual({
+      kind: "error",
+      reason: "failed",
+    });
+    expect(mockReviewArtifact).toHaveBeenCalledTimes(1);
+    expect(errorSpy).toHaveBeenCalledWith(
+      "[account] review failed errName=TypeError",
+    );
+    const logged = JSON.stringify(errorSpy.mock.calls);
+    expect(logged).not.toContain(COMMENT);
+    expect(logged).not.toContain(PIECE);
+  });
+});
+
+const r = messages.account.artifacts.review;
+const LABELS: ReviewFormLabels = {
+  heading: r.heading.replace("{version}", "3"),
+  comment: r.comment,
+  commentHint: r.commentHint,
+  approve: r.approve,
+  requestChanges: r.requestChanges,
+  submitting: r.submitting,
+  sent: r.sent,
+  errors: {
+    comment_required: r.errors.commentRequired,
+    closed: r.errors.closed,
+    not_latest: r.errors.notLatest,
+    rate_limited: r.errors.rateLimited,
+    failed: r.errors.failed,
+  },
+};
+
+describe("ReviewForm (D7, AC-6)", () => {
+  // A pass-through spy: the real action runs; the spy reads what it was sent.
+  let submitSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    submitSpy = jest.spyOn(actions, "submitArtifactReview");
+    render(<ReviewForm pieceId={PIECE} version={3} labels={LABELS} />);
+  });
+
+  afterEach(() => {
+    submitSpy.mockRestore();
+  });
+
+  function sent(): FormData {
+    expect(submitSpy).toHaveBeenCalledTimes(1);
+    return submitSpy.mock.calls[0]![1] as FormData;
+  }
+
+  it("Request changes sends the verdict, the comment, the piece and the version; a refusal shows its message and keeps the comment", async () => {
+    mockReviewArtifact.mockResolvedValue(refusal(409, "review_closed"));
+    fireEvent.change(screen.getByTestId("artifact-review-comment"), {
+      target: { value: COMMENT },
+    });
+    await act(async () => {
+      fireEvent.click(screen.getByTestId("artifact-review-request-changes"));
+    });
+    const data = sent();
+    expect(data.get("review")).toBe("changes-requested");
+    expect(data.get("comment")).toBe(COMMENT);
+    expect(data.get("pieceId")).toBe(PIECE);
+    expect(data.get("version")).toBe("3");
+    await waitFor(() =>
+      expect(screen.getByTestId("artifact-review-error")).toHaveTextContent(
+        "This version can't be reviewed now. It may already be approved.",
+      ),
+    );
+    expect(screen.getByTestId("artifact-review-comment")).toHaveValue(COMMENT);
+    expect(mockRefresh).not.toHaveBeenCalled();
+  });
+
+  it("Approve sends the approved verdict; a sent review shows the thanks line and refreshes once", async () => {
+    await act(async () => {
+      fireEvent.click(screen.getByTestId("artifact-review-approve"));
+    });
+    expect(sent().get("review")).toBe("approved");
+    expect(mockReviewArtifact).toHaveBeenCalledWith(
+      PIECE,
+      { version: 3, review: "approved" },
+      INIT,
+    );
+    await waitFor(() =>
+      expect(screen.getByTestId("artifact-review-sent")).toHaveTextContent(
+        "Thanks — your review was sent.",
+      ),
+    );
+    expect(mockRefresh).toHaveBeenCalledTimes(1);
+  });
+
+  it("labels the comment box, and gives both buttons a 44px phone target", () => {
+    expect(screen.getByLabelText("Comment")).toBe(
+      screen.getByTestId("artifact-review-comment"),
+    );
+    expect(screen.getByTestId("artifact-review-approve")).toHaveClass(
+      "max-md:min-h-11",
+    );
+    expect(screen.getByTestId("artifact-review-request-changes")).toHaveClass(
+      "max-md:min-h-11",
+    );
+  });
+});

package/templates/apps/web/app/[locale]/(authed)/account/artifacts/artifact-actions.ts

@@ -0,0 +1,123 @@
+"use server";
+
+/**
+ * artifacts/artifact-actions.ts — the review write (#8234, spec
+ * docs/specs/8234-member-artifacts-account-artifacts-and-spec.md D6; the
+ * write is #8170's `POST /v1/member/artifacts/:pieceId/review`).
+ *
+ * One export: `submitArtifactReview`, the review form's action. It posts
+ * Approve or Request changes on a piece's latest version through
+ * `member.reviewArtifact` with `forwardedCookieInit()`'s init as built — the
+ * session cookie plus the request's `Origin` on a single site, the hub
+ * credential on a hub-mode spoke — so nothing here tests the topology. The
+ * body is the strict `MemberReviewBody` (`version`, `review`, `comment`), so
+ * no title, stage, note or link can be posted (AC-MAA-05). The posted
+ * `pieceId` and `version` are untrusted: they are shape-checked here, and the
+ * API scopes them to the Person the credential resolves.
+ *
+ * Not a `*.actions.ts` file and no `*Action`-suffixed export: apps/mcp's
+ * parity test reads that suffix, and the member writes have no MCP twin by
+ * decision (8170's header). The reads the pages share live in
+ * `artifact-data.ts`, never here — every export of this module is a POST
+ * endpoint. A log line carries `err.name` only — never the comment or an id.
+ */
+
+import { member } from "@working-theory/api-client";
+import {
+  memberReviewBodySchema,
+  memberReviewParamsSchema,
+  type MemberReviewBody,
+} from "@working-theory/validation";
+
+import { forwardedCookieInit } from "../../../../../lib/server-api";
+
+/** What the review form shows after a submit. */
+export type ArtifactReviewState =
+  | { kind: "idle" }
+  | { kind: "reviewed" }
+  | {
+      kind: "error";
+      reason:
+        | "comment_required"
+        | "closed"
+        | "not_latest"
+        | "rate_limited"
+        | "failed";
+    };
+
+export type ArtifactReviewReason = Extract<
+  ArtifactReviewState,
+  { kind: "error" }
+>["reason"];
+
+function error(reason: ArtifactReviewReason): ArtifactReviewState {
+  return { kind: "error", reason };
+}
+
+/** A form field as a string; a missing or file field is empty. */
+function field(formData: FormData, name: string): string {
+  const value = formData.get(name);
+  return typeof value === "string" ? value : "";
+}
+
+/** The refusal's reason, from the api-client's `{ ok: false, status, body }`. */
+function refusalReason(status: number, body: unknown): ArtifactReviewReason {
+  const code = (body as { error?: { code?: unknown } } | null)?.error?.code;
+  if (code === "review_closed") return "closed";
+  if (code === "version_not_latest") return "not_latest";
+  // The route's own budget answers `too_many_requests`; the hub's
+  // per-person budget and the per-IP limiter answer `429 rate_limited`.
+  if (code === "too_many_requests" || status === 429) return "rate_limited";
+  return "failed";
+}
+
+/** Approve, or request changes with a comment, on a piece's latest version. */
+export async function submitArtifactReview(
+  _prev: ArtifactReviewState,
+  formData: FormData,
+): Promise<ArtifactReviewState> {
+  const pieceId = field(formData, "pieceId");
+  const review = field(formData, "review");
+  const comment = field(formData, "comment").trim();
+
+  if (review === "changes-requested" && comment === "")
+    return error("comment_required");
+
+  const candidate = {
+    version: Number(field(formData, "version")),
+    review,
+    ...(comment !== "" ? { comment } : {}),
+  };
+  if (!memberReviewParamsSchema.safeParse({ pieceId }).success)
+    return error("failed");
+  const parsed = memberReviewBodySchema.safeParse(candidate);
+  if (!parsed.success) {
+    // A comment of control or bidi characters only is stripped to nothing
+    // by the server's `plainText`; to the person that is a missing comment.
+    const onComment = parsed.error.issues.some(
+      (issue) => issue.path[0] === "comment",
+    );
+    return error(
+      review === "changes-requested" && onComment
+        ? "comment_required"
+        : "failed",
+    );
+  }
+  const body: MemberReviewBody = parsed.data;
+
+  let res: Awaited<ReturnType<typeof member.reviewArtifact>>;
+  try {
+    res = await member.reviewArtifact(
+      pieceId,
+      body,
+      await forwardedCookieInit(),
+    );
+  } catch (err) {
+    console.error(
+      `[account] review failed errName=${err instanceof Error ? err.name : "unknown"}`,
+    );
+    return error("failed");
+  }
+  if (!res.ok) return error(refusalReason(res.status, res.body));
+  return { kind: "reviewed" };
+}

package/templates/apps/web/app/[locale]/(authed)/account/artifacts/artifact-data.ts

@@ -0,0 +1,82 @@
+/**
+ * artifacts/artifact-data.ts — the Artifacts pages' read and its helpers
+ * (#8234, spec docs/specs/8234-member-artifacts-account-artifacts-and-spec.md
+ * D2, C6).
+ *
+ * The list and the artifact page read the same artifacts, so the read lives
+ * here — not in `artifact-actions.ts`, where every export of a
+ * `"use server"` module is a POST endpoint, and not in
+ * `lib/account-config.ts`, whose `read()` stays private. The account area's
+ * read rule is restated: a 404 (no tenancy module, or a spoke route the hub
+ * does not admit) is "nothing delivered"; a 401 or 403 is the same while the
+ * person's email is unverified; anything else throws, so the page shows its
+ * error row with Retry (spec 7423 D12), never an empty list.
+ *
+ * The read serves versions newest first and at least one (8169 D6), so
+ * `versions[0]` is the latest version. Items keep the read's order — newest
+ * delivery first — and are never re-sorted here.
+ */
+
+import { member } from "@working-theory/api-client";
+import type { AccountContext } from "@working-theory/templates/account";
+import { localeHref } from "@working-theory/ui";
+import type { MemberArtifact } from "@working-theory/validation";
+import { cache } from "react";
+
+import { unwrapApiResult } from "../../../../../lib/server-api";
+
+/** The member's artifacts, newest delivery first. One read per request. */
+export const loadArtifacts = cache(
+  async (ctx: AccountContext): Promise<MemberArtifact[]> => {
+    const res = await member.artifacts(ctx.init);
+    if (!res.ok) {
+      if (res.status === 404) return [];
+      if (!ctx.user.emailVerified && (res.status === 401 || res.status === 403))
+        return [];
+    }
+    return (await unwrapApiResult(Promise.resolve(res))).items;
+  },
+);
+
+export type ArtifactState = "approved" | "changes-requested" | "ready";
+
+/** The `account` catalog key that names each review state. */
+export const STATE_KEYS = {
+  approved: "artifacts.states.approved",
+  "changes-requested": "artifacts.states.changesRequested",
+  ready: "artifacts.states.ready",
+} as const satisfies Record<ArtifactState, string>;
+
+/** The artifact's review state, from its approval and its latest version. */
+export function artifactState(a: MemberArtifact): ArtifactState {
+  if (a.approvedAt !== null) return "approved";
+  return a.versions[0]?.review === "changes-requested"
+    ? "changes-requested"
+    : "ready";
+}
+
+/**
+ * True while the latest version can be reviewed: the artifact is not
+ * approved and that version has no review yet (8170 C7 — a reviewed version
+ * is `review_closed` until the provider delivers the next one).
+ */
+export function isReviewable(a: MemberArtifact): boolean {
+  return a.approvedAt === null && a.versions[0]?.review === null;
+}
+
+/** The artifact page of one piece. */
+export function artifactHref(locale: string, pieceId: string): string {
+  return localeHref(
+    locale,
+    `/account/artifacts/${encodeURIComponent(pieceId)}`,
+  );
+}
+
+/** The download route of one version's file. */
+export function versionFileHref(
+  locale: string,
+  pieceId: string,
+  version: number,
+): string {
+  return `${artifactHref(locale, pieceId)}/versions/${version}/file`;
+}

package/templates/apps/web/app/[locale]/(authed)/account/artifacts/page.tsx

@@ -0,0 +1,177 @@
+/**
+ * /[locale]/account/artifacts — Library › Artifacts (#8338, spec
+ * docs/specs/8338-account-artifacts-structured-like-the-spec.md D3; D3
+ * supersedes #8234's D3, which rendered the flat Inbox-style list.
+ *
+ * RSC, inside the account layout's SignedInShell (the rail's Artifacts row,
+ * #8231 D1, is selected here). Renders `AccountListFrame` — the Admin Docs
+ * page's structure: a second column with an "All artifacts" count and a
+ * Review facet group (Ready for review · Changes requested · Approved),
+ * each counted over every artifact with zeros kept, and a table of Title ·
+ * Latest · Delivered · Review in the read's order — newest delivery first.
+ * Below `md` the column becomes a filter select and the table becomes the
+ * phone row list.
+ *
+ * A 404 read (no tenancy module, or a spoke route the hub does not admit)
+ * shows the frame with every count at 0 and the plain empty line; any other
+ * failed read renders today's error row with Retry and no frame (spec 7423
+ * D12). Nothing here tests the topology: the same file serves a single site
+ * and a hub-mode spoke.
+ */
+
+import {
+  AccountListFrame,
+  type AccountListFrameRow,
+} from "@working-theory/templates/account";
+import { Heading, Text } from "@working-theory/ui/primitives";
+import type { MemberArtifact } from "@working-theory/validation";
+import type { Metadata } from "next";
+import { getTranslations } from "next-intl/server";
+import type { ReactElement } from "react";
+
+import { accountSession, logReadFailure } from "../account-data";
+import { ErrorRow } from "../error-row";
+
+import {
+  artifactHref,
+  artifactState,
+  loadArtifacts,
+  STATE_KEYS,
+  type ArtifactState,
+} from "./artifact-data";
+
+interface Props {
+  params: Promise<{ locale: string }>;
+}
+
+const REVIEW_FACETS: Array<{
+  state: ArtifactState;
+  glyph: "circle-dashed" | "message-square" | "circle-check";
+}> = [
+  { state: "ready", glyph: "circle-dashed" },
+  { state: "changes-requested", glyph: "message-square" },
+  { state: "approved", glyph: "circle-check" },
+];
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { locale } = await params;
+  const t = await getTranslations({ locale, namespace: "account" });
+  return { title: t("artifacts.title") };
+}
+
+export default async function AccountArtifactsPage({
+  params,
+}: Props): Promise<ReactElement> {
+  const { locale } = await params;
+  const t = await getTranslations({ locale, namespace: "account" });
+  const session = await accountSession(locale);
+
+  const heading = (
+    <>
+      <Heading level={1} visual={2}>
+        {t("artifacts.title")}
+      </Heading>
+      <Text as="p" variant="body-sm" tone="muted" className="mt-block-tight">
+        {t("artifacts.lead")}
+      </Text>
+    </>
+  );
+
+  // Unreachable behind the (authed) gate — the layout renders the sign-in
+  // gate instead — but the page still renders in parallel with it, so a
+  // `notFound()` here streams a 404 digest over the gate (the scaffold render
+  // sweep's `/account/artifacts -> streamed not-found`). Mirror
+  // `../general/page.tsx`: the heading alone.
+  if (!session) {
+    return (
+      <div className="max-w-3xl py-8" data-testid="artifacts">
+        {heading}
+      </div>
+    );
+  }
+
+  let artifacts: MemberArtifact[] | null;
+  try {
+    artifacts = await loadArtifacts(session.ctx);
+  } catch (err) {
+    logReadFailure("artifacts", err);
+    artifacts = null;
+  }
+
+  if (artifacts === null) {
+    return (
+      <div className="max-w-3xl py-8" data-testid="artifacts">
+        {heading}
+        <ErrorRow
+          className="mt-block-loose"
+          message={t("artifacts.error")}
+          retryLabel={t("artifacts.retry")}
+        />
+      </div>
+    );
+  }
+
+  const row = (artifact: MemberArtifact): AccountListFrameRow => {
+    const state = artifactState(artifact);
+    const latest = artifact.versions[0]!;
+    const delivered = new Intl.DateTimeFormat(locale, {
+      dateStyle: "medium",
+      timeZone: "UTC",
+    }).format(new Date(latest.deliveredAt));
+    const reviewWord = t(STATE_KEYS[state]);
+    return {
+      id: artifact.id,
+      title: artifact.title,
+      href: artifactHref(locale, artifact.id),
+      facet: state,
+      caption: `${t("artifacts.version", { version: latest.version })} · ${reviewWord}`,
+      cells: {
+        latest: t("artifacts.version", { version: latest.version }),
+        delivered,
+        review: reviewWord,
+      },
+    };
+  };
+
+  return (
+    <AccountListFrame
+      title={t("artifacts.title")}
+      lead={t("artifacts.lead")}
+      glyph="layers"
+      all={{ label: t("artifacts.all") }}
+      group={{
+        heading: t("artifacts.reviewGroup"),
+        facets: REVIEW_FACETS.map(({ state, glyph }) => ({
+          id: state,
+          label: t(STATE_KEYS[state]),
+          glyph,
+        })),
+      }}
+      columns={[
+        { key: "title", header: t("artifacts.columns.title") },
+        { key: "latest", header: t("artifacts.columns.latest"), width: "1/6" },
+        {
+          key: "delivered",
+          header: t("artifacts.columns.delivered"),
+          width: "1/6",
+          minWidth: "28",
+        },
+        {
+          key: "review",
+          header: t("artifacts.columns.review"),
+          width: "1/6",
+          minWidth: "32",
+        },
+      ]}
+      rows={artifacts.map(row)}
+      labels={{
+        nav: t("artifacts.facets"),
+        table: t("artifacts.title"),
+        filter: t("artifacts.filter"),
+        empty: t("artifacts.empty"),
+        facetEmpty: t("artifacts.facetEmpty"),
+      }}
+      testIdPrefix="artifacts"
+    />
+  );
+}