minutework 0.1.0

package/assets/templates/next-tenant-app/src/lib/platform/contracts.ts

@@ -0,0 +1,131 @@
+import { z } from "zod";
+
+export const commandTemplateKeys = [
+  "python_version",
+  "echo_hello",
+  "system_info",
+  "list_apps",
+] as const;
+
+export const commandTemplateKeySchema = z.enum(commandTemplateKeys);
+
+export const loginRequestSchema = z.object({
+  username: z.string().trim().min(1),
+  password: z.string().min(1),
+});
+
+export const sessionMembershipSchema = z.object({
+  tenant_id: z.string().min(1),
+  tenant_slug: z.string().min(1),
+  tenant_name: z.string().min(1),
+  role: z.string().min(1),
+});
+
+export const activeTenantSchema = sessionMembershipSchema;
+
+export const platformUserSchema = z.object({
+  id: z.string().min(1),
+  username: z.string().min(1),
+  email: z.string().min(1),
+});
+
+export const upstreamSessionPayloadSchema = z
+  .object({
+    user: platformUserSchema,
+    active_tenant_id: z.string().min(1),
+    active_tenant: activeTenantSchema,
+    memberships: z.array(sessionMembershipSchema),
+  })
+  .passthrough();
+
+export const anonymousPlatformSessionSchema = z.object({
+  authenticated: z.literal(false),
+});
+
+export const authenticatedPlatformSessionSchema = z.object({
+  authenticated: z.literal(true),
+  user: platformUserSchema,
+  active_tenant_id: z.string().min(1),
+  active_tenant: activeTenantSchema,
+  memberships: z.array(sessionMembershipSchema),
+});
+
+export const platformSessionSchema = z.union([
+  anonymousPlatformSessionSchema,
+  authenticatedPlatformSessionSchema,
+]);
+
+export const platformErrorPayloadSchema = z
+  .object({
+    detail: z.string().min(1).optional(),
+    error: z.string().min(1).optional(),
+    code: z.string().min(1).optional(),
+  })
+  .passthrough();
+
+export const commandDispatchRequestSchema = z.object({
+  tenant_id: z.string().min(1),
+  template_key: commandTemplateKeySchema,
+});
+
+export const tenantSessionContextRequestSchema = z.object({
+  tenant_id: z.string().min(1),
+});
+
+export const passwordStatusSchema = z.object({
+  has_password: z.boolean(),
+});
+
+export const passwordChangeRequestSchema = z
+  .object({
+    current_password: z.string().optional().default(""),
+    new_password: z.string().min(1),
+    confirm_password: z.string().min(1),
+  })
+  .superRefine((value, context) => {
+    if (value.new_password !== value.confirm_password) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["confirm_password"],
+        message: "Passwords must match.",
+      });
+    }
+  });
+
+export const upstreamPasswordChangeRequestSchema = z.object({
+  current_password: z.string().optional(),
+  new_password: z.string().min(1),
+});
+
+export const commandRunSchema = z.object({
+  run_id: z.string().min(1),
+  tenant_id: z.string().min(1),
+  runtime_id: z.string().min(1),
+  template_key: z.string().min(1),
+  status: z.string().min(1),
+  safe_summary: z.string(),
+  exit_code: z.number().int().nullable(),
+  stdout_tail: z.string(),
+  stderr_tail: z.string(),
+  source_ref: z.string(),
+  dispatch_error: z.string(),
+});
+
+export type LoginRequest = z.infer<typeof loginRequestSchema>;
+export type SessionMembership = z.infer<typeof sessionMembershipSchema>;
+export type ActiveTenant = z.infer<typeof activeTenantSchema>;
+export type PlatformUser = z.infer<typeof platformUserSchema>;
+export type PlatformSession = z.infer<typeof platformSessionSchema>;
+export type AuthenticatedPlatformSession = z.infer<
+  typeof authenticatedPlatformSessionSchema
+>;
+export type CommandTemplateKey = z.infer<typeof commandTemplateKeySchema>;
+export type CommandDispatchRequest = z.infer<
+  typeof commandDispatchRequestSchema
+>;
+export type CommandRun = z.infer<typeof commandRunSchema>;
+export type TenantSessionContextRequest = z.infer<
+  typeof tenantSessionContextRequestSchema
+>;
+export type PasswordStatus = z.infer<typeof passwordStatusSchema>;
+export type PasswordChangeRequest = z.infer<typeof passwordChangeRequestSchema>;

package/assets/templates/next-tenant-app/src/lib/platform/endpoints.server.ts

@@ -0,0 +1,34 @@
+import "server-only";
+
+import { env } from "@/lib/platform/env.server";
+
+const platformBaseUrl = new URL(
+  env.MW_PLATFORM_BASE_URL.endsWith("/")
+    ? env.MW_PLATFORM_BASE_URL
+    : `${env.MW_PLATFORM_BASE_URL}/`,
+);
+
+function buildPlatformEndpoint(path: string) {
+  return new URL(path.replace(/^\//, ""), platformBaseUrl).toString();
+}
+
+export const platformAuthEndpoints = {
+  login: buildPlatformEndpoint("/api/v1/session/login/"),
+  logout: buildPlatformEndpoint("/api/v1/session/logout/"),
+  currentSession: buildPlatformEndpoint("/api/v1/session/me/"),
+  sessionContext: buildPlatformEndpoint("/api/v1/session/context/"),
+  passwordStatus: buildPlatformEndpoint("/api/v1/session/password-status/"),
+  passwordChange: buildPlatformEndpoint("/api/v1/session/password-change/"),
+  operatorConsole: buildPlatformEndpoint("/ops/login/"),
+};
+
+export const platformGatewayEndpoints = {
+  tenantCommands: buildPlatformEndpoint("/api/v1/tenant/commands/"),
+  tenantCommandRun(runId: string, tenantId: string) {
+    const url = new URL(
+      buildPlatformEndpoint(`/api/v1/tenant/commands/${encodeURIComponent(runId)}/`),
+    );
+    url.searchParams.set("tenant_id", tenantId);
+    return url.toString();
+  },
+};

package/assets/templates/next-tenant-app/src/lib/platform/env.server.test.ts

@@ -0,0 +1,102 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const originalEnv = { ...process.env };
+
+function restoreProcessEnv() {
+  for (const key of Object.keys(process.env)) {
+    if (!(key in originalEnv)) {
+      delete process.env[key];
+    }
+  }
+
+  Object.assign(process.env, originalEnv);
+}
+
+function applyServerEnv(overrides: Record<string, string | undefined>) {
+  restoreProcessEnv();
+  process.env.MW_PLATFORM_BASE_URL = "http://127.0.0.1:8000";
+  process.env.MW_CONTENT_API_TOKEN = "test-content-token";
+  process.env.MW_PUBLIC_BASE_URL = "http://127.0.0.1:3000";
+  process.env.MW_PUBLIC_SITE_PROPERTY_KEY = "main-site";
+  process.env.MW_ENABLE_RUNTIME_COMMAND_EXAMPLE = "false";
+
+  for (const [key, value] of Object.entries(overrides)) {
+    if (value === undefined) {
+      delete process.env[key];
+    } else {
+      process.env[key] = value;
+    }
+  }
+}
+
+describe("server env", () => {
+  afterEach(() => {
+    restoreProcessEnv();
+    vi.resetModules();
+  });
+
+  it("defaults MW_PUBLIC_SITE_ENV to preview", async () => {
+    applyServerEnv({
+      MW_PUBLIC_SITE_ENV: undefined,
+    });
+
+    const { env } = await import("./env.server");
+
+    expect(env.MW_PUBLIC_SITE_ENV).toBe("preview");
+  });
+
+  it("accepts MW_PUBLIC_SITE_ENV=live", async () => {
+    applyServerEnv({
+      MW_PUBLIC_SITE_ENV: "live",
+    });
+
+    const { env } = await import("./env.server");
+
+    expect(env.MW_PUBLIC_SITE_ENV).toBe("live");
+  });
+
+  it("requires MW_PUBLIC_BASE_URL", async () => {
+    applyServerEnv({
+      MW_PUBLIC_BASE_URL: undefined,
+    });
+
+    await expect(import("./env.server")).rejects.toThrow("MW_PUBLIC_BASE_URL");
+  });
+
+  it("requires MW_CONTENT_API_TOKEN", async () => {
+    applyServerEnv({
+      MW_CONTENT_API_TOKEN: undefined,
+    });
+
+    await expect(import("./env.server")).rejects.toThrow("MW_CONTENT_API_TOKEN");
+  });
+
+  it("requires MW_PUBLIC_SITE_PROPERTY_KEY", async () => {
+    applyServerEnv({
+      MW_PUBLIC_SITE_PROPERTY_KEY: undefined,
+    });
+
+    await expect(import("./env.server")).rejects.toThrow(
+      "MW_PUBLIC_SITE_PROPERTY_KEY",
+    );
+  });
+
+  it("requires MW_PLATFORM_BASE_URL in production", async () => {
+    applyServerEnv({
+      MW_PLATFORM_BASE_URL: undefined,
+      NODE_ENV: "production",
+    });
+
+    await expect(import("./env.server")).rejects.toThrow(
+      "MW_PLATFORM_BASE_URL must be set in production.",
+    );
+  });
+
+  it("rejects unsupported public-site environments", async () => {
+    applyServerEnv({
+      MW_PUBLIC_SITE_ENV: "draft",
+    });
+
+    await expect(import("./env.server")).rejects.toThrow("MW_PUBLIC_SITE_ENV");
+  });
+});

package/assets/templates/next-tenant-app/src/lib/platform/env.server.ts

@@ -0,0 +1,87 @@
+import "server-only";
+
+import { z } from "zod";
+
+const DEFAULT_LOCAL_PLATFORM_BASE_URL = "http://127.0.0.1:8000";
+
+const exampleFlagSchema = z.preprocess(
+  (value) => value ?? "false",
+  z.enum(["true", "false"]).transform((value) => value === "true"),
+);
+
+const requiredStringEnvSchema = z.preprocess((value) => {
+  if (typeof value !== "string") {
+    return value;
+  }
+
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : undefined;
+}, z.string().min(1));
+
+const requiredUrlEnvSchema = z.preprocess((value) => {
+  if (typeof value !== "string") {
+    return value;
+  }
+
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : undefined;
+}, z.string().url());
+
+const publicSiteEnvironmentSchema = z.enum(["preview", "live"]);
+
+const envSchema = z.object({
+  MW_PLATFORM_BASE_URL: z.string().url(),
+  MW_CONTENT_API_TOKEN: requiredStringEnvSchema,
+  MW_TEMPLATE_APP_NAME: z.preprocess(
+    (value) => value ?? "MinuteWork Combined Starter",
+    z.string().trim().min(1),
+  ),
+  MW_PUBLIC_BASE_URL: requiredUrlEnvSchema,
+  MW_PUBLIC_SITE_PROPERTY_KEY: requiredStringEnvSchema,
+  MW_PUBLIC_SITE_ENV: z.preprocess(
+    (value) => value ?? "preview",
+    publicSiteEnvironmentSchema,
+  ),
+  MW_ENABLE_RUNTIME_COMMAND_EXAMPLE: exampleFlagSchema,
+  NODE_ENV: z
+    .enum(["development", "test", "production"])
+    .default("development"),
+});
+
+const defaultPlatformBaseUrl =
+  process.env.MW_PLATFORM_BASE_URL ??
+  (process.env.NODE_ENV === "production"
+    ? undefined
+    : DEFAULT_LOCAL_PLATFORM_BASE_URL);
+
+const parsedEnv = envSchema.safeParse({
+  MW_PLATFORM_BASE_URL: defaultPlatformBaseUrl,
+  MW_CONTENT_API_TOKEN: process.env.MW_CONTENT_API_TOKEN,
+  MW_TEMPLATE_APP_NAME: process.env.MW_TEMPLATE_APP_NAME,
+  MW_PUBLIC_BASE_URL: process.env.MW_PUBLIC_BASE_URL,
+  MW_PUBLIC_SITE_PROPERTY_KEY: process.env.MW_PUBLIC_SITE_PROPERTY_KEY,
+  MW_PUBLIC_SITE_ENV: process.env.MW_PUBLIC_SITE_ENV,
+  MW_ENABLE_RUNTIME_COMMAND_EXAMPLE:
+    process.env.MW_ENABLE_RUNTIME_COMMAND_EXAMPLE,
+  NODE_ENV: process.env.NODE_ENV,
+});
+
+if (!parsedEnv.success) {
+  if (
+    process.env.NODE_ENV === "production" &&
+    !process.env.MW_PLATFORM_BASE_URL
+  ) {
+    throw new Error("MW_PLATFORM_BASE_URL must be set in production.");
+  }
+
+  const issues = parsedEnv.error.issues
+    .map((issue) => {
+      const path = issue.path.join(".");
+      return path.length > 0 ? `${path}: ${issue.message}` : issue.message;
+    })
+    .join("; ");
+
+  throw new Error(`Invalid server environment for next-tenant-app: ${issues}`);
+}
+
+export const env = parsedEnv.data;

package/assets/templates/next-tenant-app/src/lib/platform/route-response.ts

@@ -0,0 +1,33 @@
+import { NextResponse } from "next/server";
+
+import { PlatformClientError } from "@/lib/platform/client.server";
+import type { PlatformAuthState } from "@/lib/platform/session.server";
+import { syncPlatformAuthStateToResponse } from "@/lib/platform/session.server";
+
+export function toPlatformErrorResponse(
+  error: unknown,
+  fallbackDetail: string,
+  previousAuthState?: PlatformAuthState,
+) {
+  if (error instanceof PlatformClientError) {
+    const response = NextResponse.json(
+      {
+        detail: error.message,
+        code: error.code,
+      },
+      { status: error.status },
+    );
+
+    if (previousAuthState && error.authState) {
+      syncPlatformAuthStateToResponse(
+        response,
+        previousAuthState,
+        error.authState,
+      );
+    }
+
+    return response;
+  }
+
+  return NextResponse.json({ detail: fallbackDetail }, { status: 500 });
+}

package/assets/templates/next-tenant-app/src/lib/platform/session.server.ts

@@ -0,0 +1,108 @@
+import "server-only";
+
+import { cookies } from "next/headers";
+import type { NextResponse } from "next/server";
+
+import { env } from "@/lib/platform/env.server";
+
+export const PLATFORM_SESSION_COOKIE = "mw_platform_session";
+export const PLATFORM_CSRF_COOKIE = "mw_platform_csrf";
+
+export type PlatformAuthState = {
+  sessionId: string | null;
+  csrfToken: string | null;
+};
+
+function platformCookie(name: string, value: string) {
+  return {
+    name,
+    value,
+    httpOnly: true,
+    sameSite: "lax" as const,
+    path: "/",
+    secure: env.NODE_ENV === "production",
+  };
+}
+
+function platformSessionCookie(value: string) {
+  return platformCookie(PLATFORM_SESSION_COOKIE, value);
+}
+
+function platformCsrfCookie(value: string) {
+  return platformCookie(PLATFORM_CSRF_COOKIE, value);
+}
+
+export async function readPlatformAuthState(): Promise<PlatformAuthState> {
+  const cookieStore = await cookies();
+
+  return {
+    sessionId: cookieStore.get(PLATFORM_SESSION_COOKIE)?.value ?? null,
+    csrfToken: cookieStore.get(PLATFORM_CSRF_COOKIE)?.value ?? null,
+  };
+}
+
+export async function readPlatformSessionId() {
+  return (await readPlatformAuthState()).sessionId;
+}
+
+export async function readPlatformCsrfToken() {
+  return (await readPlatformAuthState()).csrfToken;
+}
+
+export function applyPlatformSessionToResponse(
+  response: NextResponse,
+  sessionId: string,
+) {
+  response.cookies.set(platformSessionCookie(sessionId));
+}
+
+export function applyPlatformCsrfToResponse(
+  response: NextResponse,
+  csrfToken: string,
+) {
+  response.cookies.set(platformCsrfCookie(csrfToken));
+}
+
+export function applyPlatformAuthStateToResponse(
+  response: NextResponse,
+  authState: PlatformAuthState,
+) {
+  if (authState.sessionId) {
+    applyPlatformSessionToResponse(response, authState.sessionId);
+  }
+
+  if (authState.csrfToken) {
+    applyPlatformCsrfToResponse(response, authState.csrfToken);
+  }
+}
+
+export function syncPlatformAuthStateToResponse(
+  response: NextResponse,
+  previousAuthState: PlatformAuthState,
+  nextAuthState: PlatformAuthState,
+) {
+  if (previousAuthState.sessionId !== nextAuthState.sessionId) {
+    if (nextAuthState.sessionId) {
+      applyPlatformSessionToResponse(response, nextAuthState.sessionId);
+    } else {
+      response.cookies.delete(PLATFORM_SESSION_COOKIE);
+    }
+  }
+
+  if (previousAuthState.csrfToken !== nextAuthState.csrfToken) {
+    if (nextAuthState.csrfToken) {
+      applyPlatformCsrfToResponse(response, nextAuthState.csrfToken);
+    } else {
+      response.cookies.delete(PLATFORM_CSRF_COOKIE);
+    }
+  }
+}
+
+export function clearPlatformSessionFromResponse(response: NextResponse) {
+  response.cookies.delete(PLATFORM_SESSION_COOKIE);
+  response.cookies.delete(PLATFORM_CSRF_COOKIE);
+}
+
+export function clearPlatformCsrfFromResponse(response: NextResponse) {
+  response.cookies.delete(PLATFORM_CSRF_COOKIE);
+}

package/assets/templates/next-tenant-app/src/lib/public-site.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+
+import { buildPublicMetadata, resolvePublicSiteUrl } from "@/lib/public-site";
+
+describe("public-site helpers", () => {
+  it("builds canonical urls from MW_PUBLIC_BASE_URL", () => {
+    expect(process.env.MW_PUBLIC_BASE_URL).toBe("http://127.0.0.1:3000");
+
+    const metadata = buildPublicMetadata({
+      title: "Docs",
+      description: "Starter documentation",
+      path: "/docs",
+      siteName: "MinuteWork Combined Starter",
+    });
+
+    expect(resolvePublicSiteUrl("/docs").toString()).toBe("http://127.0.0.1:3000/docs");
+    expect(metadata.alternates?.canonical).toBe("http://127.0.0.1:3000/docs");
+    expect(metadata.openGraph?.url).toBe("http://127.0.0.1:3000/docs");
+  });
+});

package/assets/templates/next-tenant-app/src/lib/public-site.ts

@@ -0,0 +1,49 @@
+import "server-only";
+
+import type { Metadata } from "next";
+
+import { env } from "@/lib/platform/env.server";
+
+export function resolvePublicMetadataBase() {
+  return new URL(
+    env.MW_PUBLIC_BASE_URL.endsWith("/")
+      ? env.MW_PUBLIC_BASE_URL
+      : `${env.MW_PUBLIC_BASE_URL}/`,
+  );
+}
+
+export function resolvePublicSiteUrl(pathname = "/") {
+  return new URL(pathname.replace(/^\/*/, "/"), resolvePublicMetadataBase());
+}
+
+export function buildPublicMetadata(input: {
+  title: string;
+  description: string;
+  path: string;
+  siteName?: string;
+  type?: "website" | "article";
+  publishedTime?: string | null;
+}): Metadata {
+  const canonicalUrl = resolvePublicSiteUrl(input.path).toString();
+
+  return {
+    title: input.title,
+    description: input.description,
+    alternates: {
+      canonical: canonicalUrl,
+    },
+    openGraph: {
+      title: input.title,
+      description: input.description,
+      url: canonicalUrl,
+      siteName: input.siteName ?? env.MW_TEMPLATE_APP_NAME,
+      type: input.type ?? "website",
+      ...(input.publishedTime ? { publishedTime: input.publishedTime } : {}),
+    },
+    twitter: {
+      card: "summary_large_image",
+      title: input.title,
+      description: input.description,
+    },
+  };
+}

package/assets/templates/next-tenant-app/src/lib/theme-config.ts

@@ -0,0 +1,10 @@
+export type ThemeMode = "light" | "dark" | "system";
+export type ResolvedTheme = "light" | "dark";
+
+export const THEME_STORAGE_KEY = "next-tenant-app-theme";
+export const THEME_COOKIE_NAME = "next-tenant-app-theme";
+export const SYSTEM_THEME_QUERY = "(prefers-color-scheme: dark)";
+
+export function isThemeMode(value: string | null | undefined): value is ThemeMode {
+  return value === "light" || value === "dark" || value === "system";
+}