@nkzw/codiff-service 1.9.0

package/index.ts

@@ -0,0 +1,5 @@
+export * from './api.ts';
+export * from './db.ts';
+export * from './fate.ts';
+export * from './schema.ts';
+export * from './views.ts';

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@nkzw/codiff-service",
+  "version": "1.9.0",
+  "description": "Provider-neutral Codiff sharing service.",
+  "license": "MIT",
+  "author": {
+    "name": "Christoph Nakazawa",
+    "email": "christoph.pojer@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nkzw-tech/codiff.git",
+    "directory": "service"
+  },
+  "files": [
+    "dist",
+    "*.ts",
+    "*.tsx"
+  ],
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.ts",
+      "@nkzw/codiff-source": "./index.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./api": {
+      "types": "./api.ts",
+      "@nkzw/codiff-source": "./api.ts",
+      "default": "./dist/api.mjs"
+    },
+    "./db": {
+      "types": "./db.ts",
+      "@nkzw/codiff-source": "./db.ts",
+      "default": "./dist/db.mjs"
+    },
+    "./fate": {
+      "types": "./fate.ts",
+      "@nkzw/codiff-source": "./fate.ts",
+      "default": "./dist/fate.mjs"
+    },
+    "./react": {
+      "types": "./react.tsx",
+      "@nkzw/codiff-source": "./react.tsx",
+      "default": "./dist/react.mjs"
+    },
+    "./schema": {
+      "types": "./schema.ts",
+      "@nkzw/codiff-source": "./schema.ts",
+      "default": "./dist/schema.mjs"
+    },
+    "./upload-intent": {
+      "types": "./upload-intent.ts",
+      "@nkzw/codiff-source": "./upload-intent.ts",
+      "default": "./dist/upload-intent.mjs"
+    },
+    "./views": {
+      "types": "./views.ts",
+      "@nkzw/codiff-source": "./views.ts",
+      "default": "./dist/views.mjs"
+    }
+  },
+  "dependencies": {
+    "@nkzw/fate": "^1.3.2",
+    "drizzle-orm": "^0.45.2",
+    "zod": "^4.4.3",
+    "@nkzw/codiff-core": "1.9.0"
+  },
+  "peerDependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && vp pack -d dist --target=node24 index.ts api.ts db.ts fate.ts react.tsx schema.ts upload-intent.ts views.ts",
+    "typecheck": "vp exec tsc --noEmit -p ../tsconfig.json"
+  }
+}

package/react.test.ts

@@ -0,0 +1,70 @@
+import { expect, test } from 'vite-plus/test';
+import { resolveSubmittedShareReply, resolveSubmittedShareThread } from './react.tsx';
+
+const comment = {
+  body: 'Keep this visible while it saves.',
+  filePath: 'src/review.ts',
+  lineNumber: 12,
+  sectionId: 'src/review.ts:unstaged',
+  side: 'additions',
+} as const;
+
+const message = {
+  authorImage: 'https://github.com/ada.png',
+  authorName: 'Ada Lovelace',
+  authorUsername: 'ada',
+  body: comment.body,
+  canEdit: true,
+  createdAt: '2026-07-16T12:00:00.000Z',
+  id: 'message-1',
+  threadId: 'thread-1',
+  updatedAt: '2026-07-16T12:00:00.000Z',
+};
+
+test('resolves submitted share comments to their persisted server identity', () => {
+  expect(
+    resolveSubmittedShareReply({
+      canResolveThread: true,
+      comment: { ...comment, threadId: 'thread-1' },
+      result: message,
+    }),
+  ).toMatchObject({
+    author: {
+      avatarUrl: 'https://github.com/ada.png',
+      login: 'ada',
+      name: 'Ada Lovelace',
+    },
+    body: comment.body,
+    canDelete: true,
+    canEdit: true,
+    canResolveThread: true,
+    id: 'message-1',
+    submittedAt: '2026-07-16T12:00:00.000Z',
+    threadId: 'thread-1',
+  });
+
+  expect(
+    resolveSubmittedShareThread({
+      canResolveThread: true,
+      comment,
+      result: {
+        id: 'thread-1',
+        messages: { items: [{ node: message }] },
+      },
+    }),
+  ).toMatchObject({
+    body: comment.body,
+    id: 'message-1',
+    threadId: 'thread-1',
+  });
+});
+
+test('rejects incomplete mutation results instead of inventing a submitted comment', () => {
+  expect(() =>
+    resolveSubmittedShareThread({
+      canResolveThread: false,
+      comment,
+      result: { id: 'thread-1', messages: { items: [] } },
+    }),
+  ).toThrow('Unable to load the submitted walkthrough comment.');
+});

package/react.tsx

@@ -0,0 +1,151 @@
+import type {
+  GitIdentity,
+  PullRequestExistingReviewComment,
+  PullRequestReviewComment,
+  SharedWalkthroughSnapshot,
+} from '@nkzw/codiff-core';
+import {
+  PlanReviewSurface,
+  ReviewSurface,
+  type PlanReviewCommenting,
+  type ReviewCommenting,
+} from '@nkzw/codiff-core/react';
+import type { ComponentProps, ReactNode } from 'react';
+
+export type SharedPlanCommenting = PlanReviewCommenting;
+export type SharedWalkthroughCommenting = ReviewCommenting;
+
+type SubmittedShareCommentMessage = {
+  authorImage: null | string;
+  authorName: string;
+  authorUsername: null | string;
+  body: string;
+  canEdit: boolean;
+  createdAt: string;
+  id: string;
+  threadId: string;
+};
+
+const asRecord = (value: unknown): Record<string, unknown> | null =>
+  value && typeof value === 'object' ? (value as Record<string, unknown>) : null;
+
+const submittedShareCommentMessage = (value: unknown): SubmittedShareCommentMessage => {
+  const message = asRecord(value);
+  if (
+    !message ||
+    typeof message.authorName !== 'string' ||
+    typeof message.body !== 'string' ||
+    typeof message.canEdit !== 'boolean' ||
+    typeof message.createdAt !== 'string' ||
+    typeof message.id !== 'string' ||
+    typeof message.threadId !== 'string'
+  ) {
+    throw new Error('Unable to load the submitted walkthrough comment.');
+  }
+  return {
+    authorImage: typeof message.authorImage === 'string' ? message.authorImage : null,
+    authorName: message.authorName,
+    authorUsername: typeof message.authorUsername === 'string' ? message.authorUsername : null,
+    body: message.body,
+    canEdit: message.canEdit,
+    createdAt: message.createdAt,
+    id: message.id,
+    threadId: message.threadId,
+  };
+};
+
+const toSubmittedReviewComment = (
+  comment: PullRequestReviewComment,
+  message: SubmittedShareCommentMessage,
+  threadId: string,
+  canResolveThread: boolean,
+): PullRequestExistingReviewComment => ({
+  ...comment,
+  author: {
+    ...(message.authorImage ? { avatarUrl: message.authorImage } : {}),
+    login: message.authorUsername ?? message.authorName,
+    name: message.authorName,
+  },
+  body: message.body,
+  ...(message.canEdit ? { canDelete: true, canEdit: true } : {}),
+  ...(canResolveThread ? { canResolveThread: true } : {}),
+  id: message.id,
+  submittedAt: message.createdAt,
+  threadId,
+});
+
+export const resolveSubmittedShareReply = ({
+  canResolveThread,
+  comment,
+  result,
+}: {
+  canResolveThread: boolean;
+  comment: PullRequestReviewComment & { threadId: string };
+  result: unknown;
+}) =>
+  toSubmittedReviewComment(
+    comment,
+    submittedShareCommentMessage(result),
+    comment.threadId,
+    canResolveThread,
+  );
+
+export const resolveSubmittedShareThread = ({
+  canResolveThread,
+  comment,
+  result,
+}: {
+  canResolveThread: boolean;
+  comment: PullRequestReviewComment;
+  result: unknown;
+}) => {
+  const thread = asRecord(result);
+  const messages = thread ? asRecord(thread.messages) : null;
+  const firstItem = messages && Array.isArray(messages.items) ? asRecord(messages.items[0]) : null;
+  if (!thread || typeof thread.id !== 'string' || !firstItem) {
+    throw new Error('Unable to load the submitted walkthrough comment.');
+  }
+  return toSubmittedReviewComment(
+    comment,
+    submittedShareCommentMessage(firstItem.node),
+    thread.id,
+    canResolveThread,
+  );
+};
+
+export function SharedPlanApp({
+  providerLabel,
+  ...props
+}: Omit<ComponentProps<typeof PlanReviewSurface>, 'signInLabel'> & {
+  providerLabel: string;
+}) {
+  return <PlanReviewSurface {...props} signInLabel={`Sign in with ${providerLabel} to comment`} />;
+}
+
+export function SharedWalkthroughApp({
+  commenting,
+  gitIdentity,
+  onDeleteShare,
+  providerLabel,
+  settingsBar,
+  snapshot,
+}: {
+  commenting?: SharedWalkthroughCommenting;
+  gitIdentity?: GitIdentity | null;
+  onDeleteShare?: () => Promise<void> | void;
+  providerLabel: string;
+  settingsBar?: ReactNode;
+  snapshot: SharedWalkthroughSnapshot;
+}) {
+  return (
+    <ReviewSurface
+      commenting={commenting}
+      gitIdentity={gitIdentity}
+      onDeleteShare={onDeleteShare}
+      providerLabel={providerLabel}
+      settingsBar={settingsBar}
+      signInLabel={`Sign in with ${providerLabel} to comment`}
+      snapshot={snapshot}
+    />
+  );
+}

package/schema.ts

@@ -0,0 +1,320 @@
+import { relations, sql } from 'drizzle-orm';
+import {
+  check,
+  index,
+  integer,
+  primaryKey,
+  sqliteTable,
+  text,
+  uniqueIndex,
+} from 'drizzle-orm/sqlite-core';
+
+const idColumn = () =>
+  text()
+    .notNull()
+    .$defaultFn(() => crypto.randomUUID());
+
+const timestampColumn = () =>
+  integer({ mode: 'timestamp' })
+    .notNull()
+    .default(sql`(unixepoch())`);
+const nullableTimestampColumn = () => integer({ mode: 'timestamp' });
+
+export const shareCommentThreadKind = ['plan', 'walkthrough-diff', 'walkthrough-general'] as const;
+export const shareCommentThreadStatus = ['open', 'resolved'] as const;
+export const shareKind = ['plan', 'walkthrough'] as const;
+
+export const user = sqliteTable(
+  'user',
+  {
+    banExpires: nullableTimestampColumn(),
+    banned: integer({ mode: 'boolean' }),
+    banReason: text(),
+    createdAt: timestampColumn(),
+    displayUsername: text(),
+    email: text().notNull(),
+    emailVerified: integer({ mode: 'boolean' }).notNull().default(false),
+    id: idColumn().primaryKey(),
+    image: text(),
+    name: text().notNull(),
+    password: text(),
+    role: text().notNull().default('user'),
+    updatedAt: timestampColumn(),
+    username: text(),
+  },
+  (table) => [
+    uniqueIndex('user_email_key').on(table.email),
+    uniqueIndex('user_username_key').on(table.username),
+    index('user_id_idx').on(table.id),
+  ],
+);
+
+export const walkthrough = sqliteTable(
+  'Walkthrough',
+  {
+    branch: text(),
+    byteSize: integer().notNull(),
+    codiffVersion: text().notNull(),
+    commentsImportedAt: nullableTimestampColumn(),
+    createdAt: timestampColumn(),
+    description: text(),
+    filesIndexedAt: nullableTimestampColumn(),
+    id: idColumn().primaryKey(),
+    objectKey: text().notNull(),
+    pullRequestNumber: integer(),
+    pullRequestTitle: text(),
+    pullRequestUrl: text(),
+    repositoryHost: text(),
+    repositoryName: text(),
+    repositoryOwner: text(),
+    repositoryUrl: text(),
+    schemaVersion: integer().notNull(),
+    sha256: text().notNull(),
+    sharedByEmail: text(),
+    sharedByName: text(),
+    sharedByUserId: text().references(() => user.id, { onDelete: 'set null' }),
+    slug: text().notNull(),
+    sourceType: text().notNull(),
+    title: text().notNull(),
+    updatedAt: timestampColumn(),
+  },
+  (table) => [
+    uniqueIndex('Walkthrough_slug_key').on(table.slug),
+    index('Walkthrough_sharedByEmail_idx').on(table.sharedByEmail),
+    index('Walkthrough_sharedByUserId_idx').on(table.sharedByUserId),
+    index('Walkthrough_repository_idx').on(table.repositoryOwner, table.repositoryName),
+  ],
+);
+
+export const walkthroughFile = sqliteTable(
+  'WalkthroughFile',
+  {
+    path: text().notNull(),
+    walkthroughId: text()
+      .notNull()
+      .references(() => walkthrough.id, { onDelete: 'cascade' }),
+  },
+  (table) => [
+    primaryKey({
+      columns: [table.walkthroughId, table.path],
+      name: 'WalkthroughFile_walkthroughId_path_pkey',
+    }),
+  ],
+);
+
+export const plan = sqliteTable(
+  'Plan',
+  {
+    agent: text(),
+    byteSize: integer().notNull(),
+    codiffVersion: text().notNull(),
+    commentsImportedAt: nullableTimestampColumn(),
+    createdAt: timestampColumn(),
+    id: idColumn().primaryKey(),
+    objectKey: text().notNull(),
+    schemaVersion: integer().notNull(),
+    sessionId: text(),
+    sha256: text().notNull(),
+    sharedByEmail: text(),
+    sharedByName: text(),
+    sharedByUserId: text().references(() => user.id, { onDelete: 'set null' }),
+    slug: text().notNull(),
+    sourceFileName: text().notNull(),
+    title: text().notNull(),
+    updatedAt: timestampColumn(),
+  },
+  (table) => [
+    uniqueIndex('Plan_slug_key').on(table.slug),
+    index('Plan_sharedByEmail_idx').on(table.sharedByEmail),
+    index('Plan_sharedByUserId_idx').on(table.sharedByUserId),
+  ],
+);
+
+export const uploadIntent = sqliteTable(
+  'UploadIntent',
+  {
+    claimedAt: nullableTimestampColumn(),
+    code: text().notNull(),
+    createdAt: timestampColumn(),
+    expiresAt: integer({ mode: 'timestamp' }).notNull(),
+    id: idColumn().primaryKey(),
+    secretHash: text().notNull(),
+    sharedByUserId: text().references(() => user.id, { onDelete: 'set null' }),
+    shareKind: text({ enum: shareKind }).notNull().default('walkthrough'),
+    status: text({ enum: ['pending', 'claimed', 'uploaded'] })
+      .notNull()
+      .default('pending'),
+    updatedAt: timestampColumn(),
+    uploadTokenHash: text(),
+    walkthroughSlug: text(),
+  },
+  (table) => [
+    uniqueIndex('UploadIntent_code_key').on(table.code),
+    index('UploadIntent_sharedByUserId_idx').on(table.sharedByUserId),
+  ],
+);
+
+export const shareCommentThread = sqliteTable(
+  'ShareCommentThread',
+  {
+    anchorJson: text(),
+    createdAt: timestampColumn(),
+    filePath: text(),
+    id: idColumn().primaryKey(),
+    kind: text({ enum: shareCommentThreadKind }).notNull(),
+    lineNumber: integer(),
+    planId: text().references(() => plan.id, { onDelete: 'cascade' }),
+    resolvedAt: nullableTimestampColumn(),
+    sectionId: text(),
+    side: text({ enum: ['additions', 'deletions'] }),
+    sourceThreadId: text(),
+    startLineNumber: integer(),
+    startSide: text({ enum: ['additions', 'deletions'] }),
+    status: text({ enum: shareCommentThreadStatus }).notNull().default('open'),
+    updatedAt: timestampColumn(),
+    walkthroughId: text().references(() => walkthrough.id, { onDelete: 'cascade' }),
+  },
+  (table) => [
+    check(
+      'ShareCommentThread_parent_check',
+      sql`(${table.planId} is not null and ${table.walkthroughId} is null) or (${table.planId} is null and ${table.walkthroughId} is not null)`,
+    ),
+    index('ShareCommentThread_planId_createdAt_idx').on(table.planId, table.createdAt),
+    index('ShareCommentThread_walkthroughId_createdAt_idx').on(
+      table.walkthroughId,
+      table.createdAt,
+    ),
+    uniqueIndex('ShareCommentThread_planId_sourceThreadId_key').on(
+      table.planId,
+      table.sourceThreadId,
+    ),
+    uniqueIndex('ShareCommentThread_walkthroughId_sourceThreadId_key').on(
+      table.walkthroughId,
+      table.sourceThreadId,
+    ),
+  ],
+);
+
+export const shareCommentMessage = sqliteTable(
+  'ShareCommentMessage',
+  {
+    authorImage: text(),
+    authorName: text().notNull(),
+    authorUserId: text().references(() => user.id, { onDelete: 'set null' }),
+    authorUsername: text(),
+    body: text().notNull(),
+    createdAt: timestampColumn(),
+    id: idColumn().primaryKey(),
+    sourceMessageId: text(),
+    threadId: text()
+      .notNull()
+      .references(() => shareCommentThread.id, { onDelete: 'cascade' }),
+    updatedAt: timestampColumn(),
+  },
+  (table) => [
+    index('ShareCommentMessage_authorUserId_idx').on(table.authorUserId),
+    index('ShareCommentMessage_threadId_createdAt_idx').on(table.threadId, table.createdAt),
+    uniqueIndex('ShareCommentMessage_threadId_sourceMessageId_key').on(
+      table.threadId,
+      table.sourceMessageId,
+    ),
+  ],
+);
+
+export const shareDailyUsage = sqliteTable(
+  'ShareDailyUsage',
+  {
+    date: text().notNull(),
+    planCount: integer().notNull().default(0),
+    userId: text()
+      .notNull()
+      .references(() => user.id, { onDelete: 'cascade' }),
+    walkthroughCount: integer().notNull().default(0),
+  },
+  (table) => [
+    primaryKey({
+      columns: [table.userId, table.date],
+      name: 'ShareDailyUsage_userId_date_pkey',
+    }),
+  ],
+);
+
+export const userRelations = relations(user, ({ many }) => ({
+  shareCommentMessages: many(shareCommentMessage),
+  shareDailyUsage: many(shareDailyUsage),
+}));
+
+export const walkthroughRelations = relations(walkthrough, ({ many }) => ({
+  commentThreads: many(shareCommentThread),
+  files: many(walkthroughFile),
+}));
+
+export const walkthroughFileRelations = relations(walkthroughFile, ({ one }) => ({
+  walkthrough: one(walkthrough, {
+    fields: [walkthroughFile.walkthroughId],
+    references: [walkthrough.id],
+  }),
+}));
+
+export const planRelations = relations(plan, ({ many }) => ({
+  commentThreads: many(shareCommentThread),
+}));
+
+export const shareCommentThreadRelations = relations(shareCommentThread, ({ many, one }) => ({
+  messages: many(shareCommentMessage),
+  plan: one(plan, {
+    fields: [shareCommentThread.planId],
+    references: [plan.id],
+  }),
+  walkthrough: one(walkthrough, {
+    fields: [shareCommentThread.walkthroughId],
+    references: [walkthrough.id],
+  }),
+}));
+
+export const shareCommentMessageRelations = relations(shareCommentMessage, ({ one }) => ({
+  author: one(user, {
+    fields: [shareCommentMessage.authorUserId],
+    references: [user.id],
+  }),
+  thread: one(shareCommentThread, {
+    fields: [shareCommentMessage.threadId],
+    references: [shareCommentThread.id],
+  }),
+}));
+
+export const shareDailyUsageRelations = relations(shareDailyUsage, ({ one }) => ({
+  user: one(user, {
+    fields: [shareDailyUsage.userId],
+    references: [user.id],
+  }),
+}));
+
+export type UserRow = typeof user.$inferSelect;
+export type UploadIntentRow = typeof uploadIntent.$inferSelect;
+export type PlanRow = typeof plan.$inferSelect;
+export type WalkthroughRow = typeof walkthrough.$inferSelect;
+export type ShareCommentThreadRow = typeof shareCommentThread.$inferSelect;
+export type ShareCommentMessageRow = typeof shareCommentMessage.$inferSelect;
+export type ShareCommentThreadKind = (typeof shareCommentThreadKind)[number];
+export type ShareCommentThreadStatus = (typeof shareCommentThreadStatus)[number];
+
+const schema = {
+  plan,
+  planRelations,
+  shareCommentMessage,
+  shareCommentMessageRelations,
+  shareCommentThread,
+  shareCommentThreadRelations,
+  shareDailyUsage,
+  shareDailyUsageRelations,
+  uploadIntent,
+  user,
+  userRelations,
+  walkthrough,
+  walkthroughFile,
+  walkthroughFileRelations,
+  walkthroughRelations,
+} as const;
+
+export default schema;

package/upload-intent.test.ts

@@ -0,0 +1,24 @@
+import { expect, test } from 'vite-plus/test';
+import {
+  createUploadIntentSecret,
+  hashUploadIntentSecret,
+  verifyUploadIntentSecret,
+} from './upload-intent.ts';
+
+const env = { BETTER_AUTH_SECRET: 'test-secret-with-at-least-thirty-two-characters' };
+
+test('creates upload intent capabilities bound to their code and expiration', async () => {
+  const expiresAt = new Date('2026-07-16T12:00:00.000Z');
+  const secret = await createUploadIntentSecret(env, 'UPLOADCODE', expiresAt);
+
+  expect(await verifyUploadIntentSecret(env, 'UPLOADCODE', secret)).toEqual({ expiresAt });
+  expect(await verifyUploadIntentSecret(env, 'OTHER-CODE', secret)).toBeNull();
+  expect(await verifyUploadIntentSecret(env, 'UPLOADCODE', `${secret}tampered`)).toBeNull();
+  expect(await hashUploadIntentSecret(secret)).toMatch(/^[a-f0-9]{64}$/);
+});
+
+test('requires a configured signing secret', async () => {
+  await expect(
+    createUploadIntentSecret({}, 'UPLOADCODE', new Date('2026-07-16T12:00:00.000Z')),
+  ).rejects.toThrow('BETTER_AUTH_SECRET');
+});