create-ailk 0.19.0 → 0.20.0

package/templates/database/__tests__/person-notes.db.test.ts

@@ -0,0 +1,249 @@
+/**
+ * @file person-notes.db.test.ts
+ *
+ * LIVE-DATABASE proof of the client record's private notes and the member
+ * agent grant reset (#8514, spec
+ * docs/specs/8514-redesign-the-person-record-page-spec.md D1, D2, D2b; AC-2
+ * and the migration half of AC-3). Requires DATABASE_URL pointing at a
+ * Postgres with the migrations applied — every live suite SKIPS when
+ * DATABASE_URL is unset (the repo convention; the `apps/api Route Tests
+ * (Postgres)` workflow exercises it).
+ *
+ * Uses the `pg` driver directly, as `person-contact.db.test.ts` does. What it
+ * proves that a mock cannot:
+ *   1. The notes column's width and the people table's four new CHECKs (the
+ *      editor's user-id format, the agent's id format, the edit pair, and an
+ *      agent edit naming its person).
+ *   2. The migration's grant-reset half (its own text) removes people-read and
+ *      member-pieces-manage from an agent of a member only, and a second run
+ *      changes no row.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { Client } from "pg";
+
+const describeDb = process.env.DATABASE_URL ? describe : describe.skip;
+
+const MIGRATION = join(
+  __dirname,
+  "..",
+  "migrations",
+  "20261015120000_person_notes",
+  "migration.sql",
+);
+const RESET_MARK =
+  "-- ===== #8514 D2b member agent grant reset (data only; runs after the DDL above) =====";
+
+/** The grant-reset half of the single person_notes migration. */
+function resetSql(): string {
+  const text = readFileSync(MIGRATION, "utf8");
+  const at = text.indexOf(RESET_MARK);
+  if (at < 0) throw new Error("the grant-reset marker is missing from the migration");
+  return text.slice(at);
+}
+
+const USER_ID = "user_01920000-8514-7000-8000-0000000000a1";
+const AGENT_ID = "agent_01920000-8514-7000-8000-0000000000a2";
+
+describe("the person_notes migration file (#8514 D2, D2b)", () => {
+  it("is the DDL, then the grant reset: data only, touching the agents table's grants alone", () => {
+    const text = readFileSync(MIGRATION, "utf8");
+    const at = text.indexOf(RESET_MARK);
+    expect(at).toBeGreaterThan(0);
+    expect(text.slice(0, at)).toMatch(/ALTER TABLE "people"/);
+    expect(text.slice(0, at)).not.toMatch(/UPDATE /);
+    const reset = resetSql()
+      .split("\n")
+      .filter((line) => !line.startsWith("--"))
+      .join("\n");
+    expect(reset).not.toMatch(/ALTER TABLE|DROP |CREATE /);
+    expect(reset).toMatch(/UPDATE "agents"/);
+  });
+});
+
+describeDb("the notes columns (#8514 D1, D2, AC-2, live DB)", () => {
+  let db: Client;
+  const WS = "wksp_01920000-8514-7000-8000-0000000000c1";
+
+  async function cleanup(): Promise<void> {
+    await db.query(`DELETE FROM "people" WHERE "workspace_id" = $1`, [WS]);
+  }
+
+  beforeAll(async () => {
+    db = new Client({ connectionString: process.env.DATABASE_URL });
+    await db.connect();
+    await cleanup();
+  });
+
+  afterAll(async () => {
+    await cleanup();
+    await db.end();
+  });
+
+  let counter = 0;
+  const email = () => `p8514-${(counter += 1)}@example.com`;
+
+  /** Insert one Person with the given notes columns on top of the required pair. */
+  const insertPerson = async (cols: Record<string, unknown> = {}) => {
+    const all: Record<string, unknown> = {
+      workspace_id: WS,
+      email: email(),
+      updated_at: new Date(),
+      ...cols,
+    };
+    const names = Object.keys(all);
+    return db.query<{ id: string }>(
+      `INSERT INTO "people" (${names.map((n) => `"${n}"`).join(", ")})
+       VALUES (${names.map((_, i) => `$${i + 1}`).join(", ")}) RETURNING "id"`,
+      names.map((n) => all[n]),
+    );
+  };
+
+  const AT = new Date("2026-10-15T12:00:00.000Z");
+
+  it("a Person without notes reads all four columns as NULL", async () => {
+    const { rows } = await insertPerson();
+    const read = await db.query(
+      `SELECT "notes", "notes_updated_at", "notes_updated_by", "notes_updated_by_agent" FROM "people" WHERE "id" = $1`,
+      [rows[0]!.id],
+    );
+    expect(read.rows[0]).toEqual({
+      notes: null,
+      notes_updated_at: null,
+      notes_updated_by: null,
+      notes_updated_by_agent: null,
+    });
+  });
+
+  it("a 5000-character note saves and a 5001-character one fails", async () => {
+    await expect(
+      insertPerson({ notes: "n".repeat(5000), notes_updated_at: AT, notes_updated_by: USER_ID }),
+    ).resolves.toBeDefined();
+    await expect(
+      insertPerson({ notes: "n".repeat(5001), notes_updated_at: AT, notes_updated_by: USER_ID }),
+    ).rejects.toThrow(/value too long/);
+  });
+
+  it("a user_ editor with a timestamp succeeds; an agent_ editor fails the format CHECK", async () => {
+    await expect(
+      insertPerson({ notes: "x", notes_updated_at: AT, notes_updated_by: USER_ID }),
+    ).resolves.toBeDefined();
+    await expect(
+      insertPerson({ notes: "x", notes_updated_at: AT, notes_updated_by: AGENT_ID }),
+    ).rejects.toThrow(/people_notes_updated_by_format/);
+  });
+
+  it("a timestamp without an editor, or the reverse, fails the edit pair", async () => {
+    await expect(insertPerson({ notes: "x", notes_updated_at: AT })).rejects.toThrow(
+      /people_notes_edit_pair/,
+    );
+    await expect(insertPerson({ notes: "x", notes_updated_by: USER_ID })).rejects.toThrow(
+      /people_notes_edit_pair/,
+    );
+  });
+
+  it("an agent edit carries an agent_ id and its person", async () => {
+    await expect(
+      insertPerson({
+        notes: "x",
+        notes_updated_at: AT,
+        notes_updated_by: USER_ID,
+        notes_updated_by_agent: AGENT_ID,
+      }),
+    ).resolves.toBeDefined();
+    await expect(
+      insertPerson({
+        notes: "x",
+        notes_updated_at: AT,
+        notes_updated_by: USER_ID,
+        notes_updated_by_agent: USER_ID,
+      }),
+    ).rejects.toThrow(/people_notes_updated_by_agent_format/);
+    await expect(insertPerson({ notes_updated_by_agent: AGENT_ID })).rejects.toThrow(
+      /people_notes_agent_has_person/,
+    );
+  });
+});
+
+describeDb("the member agent grant reset (#8514 D2b, AC-3, live DB)", () => {
+  let db: Client;
+  let organizationId: string;
+  let workspaceId: string;
+  let ownerUserId: string;
+  let ownerMembershipId: string;
+  let memberMembershipId: string;
+  let adminMembershipId: string;
+  let hashSeq = 0;
+
+  const nextHash = () => (hashSeq += 1).toString(16).padStart(64, "0");
+
+  async function one(sql: string, params: unknown[]): Promise<string> {
+    return (await db.query<{ id: string }>(sql, params)).rows[0]!.id;
+  }
+
+  const insertUser = (tag: string) =>
+    one(`INSERT INTO "users" ("email", "updated_at") VALUES ($1, now()) RETURNING "id"`, [
+      `grants8514-${tag}@example.test`,
+    ]);
+
+  const insertMembership = (userId: string, role: string) =>
+    one(
+      `INSERT INTO "memberships" ("organization_id", "user_id", "role") VALUES ($1, $2, $3::"Role") RETURNING "id"`,
+      [organizationId, userId, role],
+    );
+
+  const insertAgent = (responsibleMembershipId: string, grants: string[]) =>
+    one(
+      `INSERT INTO "agents" ("organization_id", "workspace_id", "responsible_membership_id", "created_by_user_id",
+         "key_issued_to_membership_id", "credential_hash", "grants", "name", "credential_prefix", "updated_at")
+       VALUES ($1, $2, $3, $4, $5, $6, $7, 'client helper', 'ailk_agt_abcdefgh', now()) RETURNING "id"`,
+      [organizationId, workspaceId, responsibleMembershipId, ownerUserId, ownerMembershipId, nextHash(), grants],
+    );
+
+  const grantsOf = async (id: string) =>
+    (await db.query<{ grants: string[] }>(`SELECT "grants" FROM "agents" WHERE "id" = $1`, [id])).rows[0]!.grants;
+
+  beforeAll(async () => {
+    db = new Client({ connectionString: process.env.DATABASE_URL });
+    await db.connect();
+    organizationId = await one(
+      `INSERT INTO "organizations" ("name", "slug", "updated_at") VALUES ($1, $1, now()) RETURNING "id"`,
+      ["grants8514-org"],
+    );
+    workspaceId = await one(
+      `INSERT INTO "workspaces" ("organization_id", "name", "slug", "updated_at") VALUES ($1, $2, $2, now()) RETURNING "id"`,
+      [organizationId, "grants8514-ws"],
+    );
+    ownerUserId = await insertUser("owner");
+    ownerMembershipId = await insertMembership(ownerUserId, "owner");
+    memberMembershipId = await insertMembership(await insertUser("member"), "member");
+    adminMembershipId = await insertMembership(await insertUser("admin"), "admin");
+  });
+
+  afterAll(async () => {
+    await db.query(`DELETE FROM "organizations" WHERE "slug" LIKE 'grants8514-%'`);
+    await db.query(`DELETE FROM "users" WHERE "email" LIKE 'grants8514-%'`);
+    await db.end();
+  });
+
+  it("removes the two client grants from a member's agent only, and is idempotent", async () => {
+    const membersAgent = await insertAgent(memberMembershipId, [
+      "people-read",
+      "member-pieces-manage",
+      "content-edit",
+    ]);
+    const adminsAgent = await insertAgent(adminMembershipId, ["people-read"]);
+    const sql = resetSql();
+
+    const first = await db.query(sql);
+    expect(first.rowCount).toBeGreaterThanOrEqual(1);
+    expect(await grantsOf(membersAgent)).toEqual(["content-edit"]);
+    expect(await grantsOf(adminsAgent)).toEqual(["people-read"]);
+
+    const second = await db.query(sql);
+    expect(second.rowCount).toBe(0);
+    expect(await grantsOf(membersAgent)).toEqual(["content-edit"]);
+    expect(await grantsOf(adminsAgent)).toEqual(["people-read"]);
+  });
+});

package/templates/database/__tests__/person.db.test.ts

@@ -129,7 +129,9 @@ describe("the Person backfill files (#852 D2)", () => {
     const schema = readFileSync(join(__dirname, "..", "inbox", "schema.prisma"), "utf8");
     const block = /^model Person \{[\s\S]*?^\}/m.exec(schema)?.[0] ?? "";
     expect(block).not.toBe("");
-    expect(block).not.toMatch(/phone|traits|brief|merge|secondary/);
+    // #8435: `telephone` is a deliberate column now; the bare word `phone`
+    // (the #852 deferral this guards) stays absent.
+    expect(block).not.toMatch(/\bphone\b|traits|brief|merge|secondary/);
     expect(readFileSync(PERSON_MIGRATION, "utf8")).not.toMatch(/"(phone|traits|brief)"/);
   });
 });

package/templates/database/__tests__/piece-kind-migration.test.ts

@@ -0,0 +1,67 @@
+/**
+ * @file piece-kind-migration.test.ts
+ *
+ * DB-free proof of the piece_kind migration's shape (#8516, spec
+ * docs/specs/8516-proposals-as-an-artifact-kind-spec.md D2, AC-1). Reads the
+ * migration's own text: it is DDL only — eight `ADD COLUMN`s on "pieces", one
+ * unique index and CHECKs added `NOT VALID` then `VALIDATE`d — with no
+ * `UPDATE`, `INSERT` or `DELETE`, so no existing row is rewritten, and `kind`
+ * defaults to `deliverable` as a constant. The live-database half is
+ * `piece-kind.db.test.ts`.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const MIGRATION = join(__dirname, "..", "migrations", "20261016120000_piece_kind", "migration.sql");
+
+/** The migration's statements, comments stripped, whitespace collapsed. */
+function statements(): string[] {
+  const text = readFileSync(MIGRATION, "utf8")
+    .split("\n")
+    .filter((line) => !line.trimStart().startsWith("--"))
+    .join("\n");
+  return text
+    .split(";")
+    .map((s) => s.replace(/\s+/g, " ").trim())
+    .filter((s) => s.length > 0);
+}
+
+describe("the piece_kind migration (#8516 D2, AC-1)", () => {
+  it("is only ADD COLUMN on pieces, one unique index, and NOT VALID CHECKs then VALIDATE", () => {
+    const shapes = statements().map((s) => {
+      if (/^ALTER TABLE "pieces" ADD COLUMN /.test(s)) return "add-column";
+      if (/^CREATE UNIQUE INDEX "pieces_checkout_session_id_key" ON "pieces"/.test(s)) return "index";
+      if (/^ALTER TABLE "pieces" ADD CONSTRAINT "pieces_[a-z_]+" CHECK \(.*\) NOT VALID$/.test(s)) {
+        return "check";
+      }
+      if (/^ALTER TABLE "pieces" VALIDATE CONSTRAINT "pieces_[a-z_]+"$/.test(s)) return "validate";
+      return `unexpected: ${s}`;
+    });
+    expect(shapes.filter((s) => s.startsWith("unexpected"))).toEqual([]);
+    expect(shapes.filter((s) => s === "add-column")).toHaveLength(1);
+    expect(shapes.filter((s) => s === "index")).toHaveLength(1);
+    expect(shapes.filter((s) => s === "check")).toHaveLength(11);
+    expect(shapes.filter((s) => s === "validate")).toHaveLength(11);
+  });
+
+  it("writes no row: no UPDATE, INSERT or DELETE", () => {
+    for (const s of statements()) expect(s).not.toMatch(/\b(UPDATE|INSERT|DELETE)\b/i);
+  });
+
+  it("adds kind as VARCHAR(16) NOT NULL DEFAULT 'deliverable' and seven nullable columns", () => {
+    const add = statements().find((s) => s.startsWith('ALTER TABLE "pieces" ADD COLUMN'));
+    expect(add).toContain(`"kind" VARCHAR(16) NOT NULL DEFAULT 'deliverable'`);
+    for (const column of [
+      `"price_amount" INTEGER`,
+      `"price_currency" CHAR(3)`,
+      `"checkout_session_id" TEXT`,
+      `"checkout_url" VARCHAR(2048)`,
+      `"checkout_expires_at" TIMESTAMP(3)`,
+      `"paid_at" TIMESTAMP(3)`,
+      `"paid_session_id" TEXT`,
+    ]) {
+      expect(add).toMatch(new RegExp(`${column.replace(/[()]/g, "\\$&")}(,|$)`));
+    }
+    expect(add).not.toMatch(/DEFAULT 'proposal'/);
+  });
+});

package/templates/database/__tests__/piece-kind.db.test.ts

@@ -0,0 +1,208 @@
+/**
+ * @file piece-kind.db.test.ts
+ *
+ * LIVE-DATABASE proof of the piece kind and a proposal's price and payment
+ * columns (#8516, spec docs/specs/8516-proposals-as-an-artifact-kind-spec.md
+ * D1, D2, AC-1). Requires DATABASE_URL pointing at a Postgres with the
+ * migrations applied — SKIPS when DATABASE_URL is unset (the repo convention;
+ * the `apps/api Route Tests (Postgres)` workflow exercises it).
+ *
+ * Uses the `pg` driver directly, in ONE transaction that is rolled back, so
+ * dropping and re-adding the columns never outlives the suite. What it proves
+ * that a mock cannot:
+ *   1. Re-running the migration's own text over a piece written with the
+ *      pre-#8516 column set reads it back as a `deliverable`, the seven other
+ *      columns NULL and every pre-existing column (`updated_at` included)
+ *      byte-equal — no row is rewritten.
+ *   2. Each CHECK and the unique index refuse what they name.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { Client } from "pg";
+
+const describeDb = process.env.DATABASE_URL ? describe : describe.skip;
+
+const MIGRATION = join(__dirname, "..", "migrations", "20261016120000_piece_kind", "migration.sql");
+
+const WS = "wksp_01920000-8516-7000-8000-0000000000c1";
+const USER = "user_01920000-8516-7000-8000-0000000000a1";
+const NEW_COLUMNS = [
+  "kind",
+  "price_amount",
+  "price_currency",
+  "checkout_session_id",
+  "checkout_url",
+  "checkout_expires_at",
+  "paid_at",
+  "paid_session_id",
+] as const;
+
+describeDb("the piece kind columns (#8516 D1, D2, AC-1, live DB)", () => {
+  let db: Client;
+  let personId: string;
+
+  beforeAll(async () => {
+    db = new Client({ connectionString: process.env.DATABASE_URL });
+    await db.connect();
+    await db.query("BEGIN");
+    personId = (
+      await db.query<{ id: string }>(
+        `INSERT INTO "people" ("workspace_id", "email", "updated_at") VALUES ($1, $2, now()) RETURNING "id"`,
+        [WS, "p8516@example.com"],
+      )
+    ).rows[0]!.id;
+  });
+
+  afterAll(async () => {
+    await db.query("ROLLBACK");
+    await db.end();
+  });
+
+  /** Insert one piece with the pre-#8516 column set plus any of the new ones. */
+  const insertPiece = (cols: Record<string, unknown> = {}) => {
+    const all: Record<string, unknown> = {
+      workspace_id: WS,
+      person_id: personId,
+      title: "Site redesign",
+      stage: "requested",
+      updated_by: USER,
+      updated_at: new Date("2026-10-01T09:00:00.000Z"),
+      ...cols,
+    };
+    const names = Object.keys(all);
+    return db.query<{ id: string }>(
+      `INSERT INTO "pieces" (${names.map((n) => `"${n}"`).join(", ")})
+       VALUES (${names.map((_, i) => `$${i + 1}`).join(", ")}) RETURNING "id"`,
+      names.map((n) => all[n]),
+    );
+  };
+
+  /** Run `sql` inside a savepoint; resolve to the violated constraint's name, or null. */
+  const violation = async (run: () => Promise<unknown>): Promise<string | null> => {
+    await db.query("SAVEPOINT attempt");
+    try {
+      await run();
+      await db.query("RELEASE SAVEPOINT attempt");
+      return null;
+    } catch (err) {
+      await db.query("ROLLBACK TO SAVEPOINT attempt");
+      return (err as { constraint?: string }).constraint ?? String(err);
+    }
+  };
+
+  it("re-running the migration over a pre-#8516 row reads it as a deliverable, nothing else changed", async () => {
+    await db.query(
+      `ALTER TABLE "pieces" ${NEW_COLUMNS.map((c) => `DROP COLUMN "${c}"`).join(", ")}`,
+    );
+    const pieceId = (await insertPiece()).rows[0]!.id;
+    await db.query(
+      `INSERT INTO "piece_versions" ("workspace_id", "person_id", "piece_id", "version", "link", "delivered_by")
+       VALUES ($1, $2, $3, 1, 'https://example.com/v1.pdf', $4)`,
+      [WS, personId, pieceId, USER],
+    );
+    const before = (
+      await db.query<{ row: Record<string, unknown> }>(
+        `SELECT row_to_json(p) AS row FROM "pieces" p WHERE "id" = $1`,
+        [pieceId],
+      )
+    ).rows[0]!.row;
+
+    await db.query(readFileSync(MIGRATION, "utf8"));
+
+    const after = (
+      await db.query<{ row: Record<string, unknown> }>(
+        `SELECT row_to_json(p) AS row FROM "pieces" p WHERE "id" = $1`,
+        [pieceId],
+      )
+    ).rows[0]!.row;
+    expect(after.kind).toBe("deliverable");
+    for (const column of NEW_COLUMNS.slice(1)) expect(after[column]).toBeNull();
+    const kept = Object.fromEntries(
+      Object.entries(after).filter(([key]) => !(NEW_COLUMNS as readonly string[]).includes(key)),
+    );
+    expect(kept).toEqual(before);
+  });
+
+  it("refuses a kind outside the two", async () => {
+    expect(await violation(() => insertPiece({ kind: "other" }))).toBe("pieces_kind_allowed");
+  });
+
+  it("refuses a price on a deliverable, half a price, and an amount out of range", async () => {
+    expect(
+      await violation(() => insertPiece({ price_amount: 1000, price_currency: "usd" })),
+    ).toBe("pieces_price_proposal_only");
+    expect(await violation(() => insertPiece({ kind: "proposal", price_amount: 1000 }))).toBe(
+      "pieces_price_pair",
+    );
+    for (const amount of [0, 100000001]) {
+      expect(
+        await violation(() =>
+          insertPiece({ kind: "proposal", price_amount: amount, price_currency: "usd" }),
+        ),
+      ).toBe("pieces_price_range");
+    }
+    expect(
+      await violation(() =>
+        insertPiece({ kind: "proposal", price_amount: 1, price_currency: "usd" }),
+      ),
+    ).toBeNull();
+  });
+
+  const SESSION = {
+    checkout_session_id: "cs_test_a1",
+    checkout_url: "https://checkout.stripe.com/c/pay/cs_test_a1",
+    checkout_expires_at: new Date("2026-10-16T13:00:00.000Z"),
+  };
+
+  it("refuses a checkout session on an unapproved or unpriced piece, and a partial session", async () => {
+    expect(
+      await violation(() =>
+        insertPiece({ kind: "proposal", price_amount: 5000, price_currency: "usd", ...SESSION }),
+      ),
+    ).toBe("pieces_checkout_needs_approved_price");
+    expect(
+      await violation(() => insertPiece({ kind: "proposal", approved_at: new Date(), ...SESSION })),
+    ).toBe("pieces_checkout_needs_approved_price");
+    expect(
+      await violation(() =>
+        insertPiece({
+          kind: "proposal",
+          price_amount: 5000,
+          price_currency: "usd",
+          approved_at: new Date(),
+          checkout_session_id: "cs_test_a2",
+        }),
+      ),
+    ).toBe("pieces_checkout_triple");
+  });
+
+  it("refuses paid_at without the session that paid it", async () => {
+    expect(
+      await violation(() =>
+        insertPiece({
+          kind: "proposal",
+          price_amount: 5000,
+          price_currency: "usd",
+          approved_at: new Date(),
+          paid_at: new Date(),
+        }),
+      ),
+    ).toBe("pieces_paid_pair");
+  });
+
+  it("refuses two pieces holding one checkout session", async () => {
+    const approvedPriced = {
+      kind: "proposal",
+      price_amount: 5000,
+      price_currency: "usd",
+      approved_at: new Date(),
+      ...SESSION,
+      checkout_session_id: "cs_test_dup",
+    };
+    expect(await violation(() => insertPiece(approvedPriced))).toBeNull();
+    expect(await violation(() => insertPiece(approvedPriced))).toBe(
+      "pieces_checkout_session_id_key",
+    );
+  });
+});

package/templates/database/_gitignore

@@ -0,0 +1,8 @@
+# Generated Prisma Client
+generated/
+
+# Compiled output (tsc emit from generated/)
+dist/
+
+# Node modules
+node_modules/