create-windy 0.8.2 → 0.9.1

package/template/apps/server/src/agent-skills/drizzle-repository.ts

@@ -0,0 +1,125 @@
+import { and, asc, eq, sql } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import {
+  agentSkillMutations,
+  agentSkillVersions,
+} from "@southwind-ai/database";
+import type {
+  AgentSkillRepository,
+  SkillMutationReceipt,
+} from "./contracts.js";
+import { assertSkillMutation, assertSkillReplay } from "./repository.js";
+
+export class DrizzleAgentSkillRepository implements AgentSkillRepository {
+  constructor(private readonly db: NodePgDatabase) {}
+  async versions(tenantId: string, key?: string) {
+    return this.db
+      .select({
+        metadata: agentSkillVersions.metadata,
+        bundle: agentSkillVersions.bundle,
+        auditCommitted: agentSkillVersions.auditCommitted,
+      })
+      .from(agentSkillVersions)
+      .where(
+        and(
+          eq(agentSkillVersions.tenantId, tenantId),
+          key ? eq(agentSkillVersions.skillKey, key) : undefined,
+        ),
+      )
+      .orderBy(asc(agentSkillVersions.version));
+  }
+  async mutate(
+    input: Parameters<AgentSkillRepository["mutate"]>[0],
+    change: Parameters<AgentSkillRepository["mutate"]>[1],
+  ) {
+    return this.db.transaction(async (tx) => {
+      // Serialize both the new-key case and actor-wide mutation receipts before CAS.
+      await tx.execute(
+        sql`select pg_advisory_xact_lock(hashtextextended(${`agent-skill:${input.tenantId}`}, 0))`,
+      );
+      const [replay] = await tx
+        .select()
+        .from(agentSkillMutations)
+        .where(
+          and(
+            eq(agentSkillMutations.tenantId, input.tenantId),
+            eq(agentSkillMutations.actorId, input.actorId),
+            eq(agentSkillMutations.idempotencyKey, input.idempotencyKey),
+          ),
+        )
+        .limit(1);
+      if (replay) {
+        assertSkillReplay(replay, input);
+        return replay;
+      }
+      const versions = await tx
+        .select({
+          metadata: agentSkillVersions.metadata,
+          bundle: agentSkillVersions.bundle,
+          auditCommitted: agentSkillVersions.auditCommitted,
+        })
+        .from(agentSkillVersions)
+        .where(
+          and(
+            eq(agentSkillVersions.tenantId, input.tenantId),
+            eq(agentSkillVersions.skillKey, input.key),
+          ),
+        )
+        .orderBy(asc(agentSkillVersions.version));
+      assertSkillMutation(versions.at(-1), input.expectedVersion);
+      const { record, audit } = await change(versions.at(-1), versions);
+      const receipt = {
+        ...input,
+        result: record.metadata,
+        audit,
+        auditCommitted: false,
+      };
+      await tx.insert(agentSkillVersions).values({
+        tenantId: input.tenantId,
+        skillKey: input.key,
+        version: record.metadata.version,
+        metadata: record.metadata,
+        bundle: record.bundle,
+        auditCommitted: false,
+      });
+      await tx.insert(agentSkillMutations).values({
+        ...receipt,
+        skillKey: input.key,
+        version: record.metadata.version,
+      });
+      return receipt;
+    });
+  }
+  async pendingAudits() {
+    return this.db
+      .select()
+      .from(agentSkillMutations)
+      .where(eq(agentSkillMutations.auditCommitted, false))
+      .limit(500);
+  }
+  async acknowledge(receipt: SkillMutationReceipt) {
+    await this.db.transaction(async (tx) => {
+      await tx
+        .update(agentSkillVersions)
+        .set({ auditCommitted: true })
+        .where(
+          and(
+            eq(agentSkillVersions.tenantId, receipt.tenantId),
+            eq(agentSkillVersions.skillKey, receipt.result.key),
+            eq(agentSkillVersions.version, receipt.result.version),
+          ),
+        );
+      await tx
+        .update(agentSkillMutations)
+        .set({ auditCommitted: true })
+        .where(
+          and(
+            eq(agentSkillMutations.tenantId, receipt.tenantId),
+            eq(agentSkillMutations.actorId, receipt.actorId),
+            eq(agentSkillMutations.idempotencyKey, receipt.idempotencyKey),
+            eq(agentSkillMutations.requestDigest, receipt.requestDigest),
+          ),
+        );
+    });
+  }
+}

package/template/apps/server/src/agent-skills/input.ts

@@ -0,0 +1,29 @@
+import type { ImportAgentSkillRequest } from "@southwind-ai/shared";
+import { AgentSkillError } from "./contracts.js";
+export function version(value: number) {
+  if (!Number.isSafeInteger(value) || value < 0)
+    throw new AgentSkillError(
+      "SKILL_INPUT_INVALID",
+      "expectedVersion 必须为非负整数",
+    );
+}
+export function validateImport(input: ImportAgentSkillRequest) {
+  version(input.expectedVersion);
+  if (!["personal", "department", "tenant"].includes(input.scope))
+    throw new AgentSkillError("SKILL_INPUT_INVALID", "技能共享范围无效");
+  if (
+    (input.requirements?.length ?? 0) > 64 ||
+    (input.safetyConstraints?.length ?? 0) > 32
+  )
+    throw new AgentSkillError("SKILL_INPUT_INVALID", "技能依赖或约束数量过多");
+  for (const item of input.requirements ?? [])
+    if (
+      ![item.toolKey, item.permissionKey, item.featureKey].every(
+        (key) => typeof key === "string" && key.length > 0 && key.length <= 160,
+      )
+    )
+      throw new AgentSkillError("SKILL_INPUT_INVALID", "技能依赖无效");
+  for (const item of input.safetyConstraints ?? [])
+    if (typeof item !== "string" || !item.trim() || item.length > 1000)
+      throw new AgentSkillError("SKILL_INPUT_INVALID", "技能安全约束无效");
+}

package/template/apps/server/src/agent-skills/postgres.integration.test.ts

@@ -0,0 +1,348 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { resolve } from "node:path";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { Pool } from "pg";
+import type { AuditEvent } from "@southwind-ai/shared";
+import { PostgresRegressionHarness } from "../../../../scripts/lib/postgres-regression.js";
+import { buildScopeContext } from "../data-access/context.js";
+import type { RequestGuardContext } from "../guards.js";
+import {
+  diagnosticRecord,
+  newDiagnosticId,
+} from "../observability/diagnostic-index.js";
+import { DrizzleDiagnosticIndex } from "../observability/diagnostic-repository.js";
+import { DrizzleAgentSkillRepository } from "./drizzle-repository.js";
+import { AgentSkillService } from "./service.js";
+
+// Opt-in, self-contained: never consumes DATABASE_URL or an existing database.
+// WINDY_DSH_POSTGRES_TEST=1 bun test apps/server/src/agent-skills/postgres.integration.test.ts
+const describePostgres =
+  process.env.WINDY_DSH_POSTGRES_TEST === "1" ? describe : describe.skip;
+const harness = new PostgresRegressionHarness("windy-dsh-0064-test");
+const schema = `dsh_acceptance_${crypto.randomUUID().replaceAll("-", "")}`;
+const markdown =
+  "---\nname: cas-query\ndescription: 合成只读查询\n---\n仅使用已授权的查询工具。\n";
+const context: RequestGuardContext = {
+  requestId: "pg18-acceptance",
+  startedAt: new Date().toISOString(),
+  actor: {
+    id: "operator",
+    type: "user",
+    name: "合成验收用户",
+    credentialState: "active",
+    roleCodes: [],
+    permissionKeys: [],
+    scopeContext: buildScopeContext("operator", undefined, [
+      { id: "admin", code: "admin", dataScope: "tenant", departmentIds: [] },
+    ]),
+  },
+};
+
+describePostgres("DSH 0064 isolated PostgreSQL 18 acceptance", () => {
+  let control: Pool | undefined, pool: Pool;
+  const createPool = () =>
+    new Pool({
+      connectionString: harness.databaseUrl(),
+      options: `-c search_path=${schema}`,
+      max: 6,
+    });
+
+  beforeAll(async () => {
+    try {
+      await harness.start();
+      control = new Pool({ connectionString: harness.databaseUrl() });
+      await control.query(`CREATE SCHEMA "${schema}"`);
+      pool = createPool();
+      const migration = await Bun.file(
+        resolve(
+          import.meta.dir,
+          "../../../../packages/database/drizzle/0064_dsh_skills_diagnostics.sql",
+        ),
+      ).text();
+      await pool.query(migration);
+    } catch (error) {
+      await pool?.end();
+      await control?.end();
+      await harness.close();
+      throw error;
+    }
+  }, 60_000);
+
+  afterAll(async () => {
+    try {
+      await pool?.end();
+      if (control) {
+        await control.query(`DROP SCHEMA IF EXISTS "${schema}" CASCADE`);
+        await control.end();
+      }
+    } finally {
+      await harness.close();
+    }
+  }, 20_000);
+
+  test("0064 creates exactly the three new tables and their indexes on PostgreSQL 18", async () => {
+    const version = await pool.query<{ server_version_num: string }>(
+      "show server_version_num",
+    );
+    expect(Number(version.rows[0]!.server_version_num)).toBeGreaterThanOrEqual(
+      180000,
+    );
+    expect(Number(version.rows[0]!.server_version_num)).toBeLessThan(190000);
+    const tables = await pool.query<{ table_name: string }>(
+      "select table_name from information_schema.tables where table_schema=$1 and table_type='BASE TABLE' order by table_name",
+      [schema],
+    );
+    expect(tables.rows.map((row) => row.table_name)).toEqual([
+      "agent_skill_mutations",
+      "agent_skill_versions",
+      "diagnostic_events",
+    ]);
+    const indexes = await pool.query<{ indexname: string }>(
+      "select indexname from pg_indexes where schemaname=$1 and indexname like 'idx_%' order by indexname",
+      [schema],
+    );
+    expect(indexes.rows.map((row) => row.indexname)).toEqual([
+      "idx_agent_skill_audit_pending",
+      "idx_agent_skill_catalog",
+      "idx_diagnostic_events_expiry",
+      "idx_diagnostic_events_request",
+    ]);
+  });
+
+  test("real transactions serialize concurrent CAS and preserve idempotency receipts", async () => {
+    const events: AuditEvent[] = [];
+    const access = {
+      async authorize() {
+        return true;
+      },
+      async requirement() {
+        return true;
+      },
+    };
+    const audit = async (event: AuditEvent) => {
+      events.push(event);
+    };
+    const first = new AgentSkillService(
+      new DrizzleAgentSkillRepository(drizzle(pool)),
+      access,
+      audit,
+    );
+    const second = new AgentSkillService(
+      new DrizzleAgentSkillRepository(drizzle(pool)),
+      access,
+      audit,
+    );
+    const request = {
+      format: "markdown" as const,
+      content: markdown,
+      scope: "tenant" as const,
+      expectedVersion: 0,
+    };
+    const keys = ["cas-publish-one", "cas-publish-two"];
+    const results = await Promise.allSettled([
+      first.publish(request, keys[0]!, context),
+      second.publish(request, keys[1]!, context),
+    ]);
+    expect(
+      results.filter((result) => result.status === "fulfilled"),
+    ).toHaveLength(1);
+    expect(
+      results.filter((result) => result.status === "rejected"),
+    ).toHaveLength(1);
+    const winnerIndex = results.findIndex(
+        (result) => result.status === "fulfilled",
+      ),
+      winner = results[winnerIndex]!;
+    if (winner.status !== "fulfilled") throw new Error("CAS winner missing");
+    const loser = results.find((result) => result.status === "rejected");
+    expect(
+      loser?.status === "rejected" ? loser.reason : undefined,
+    ).toMatchObject({ code: "SKILL_VERSION_CONFLICT" });
+    const repository = new DrizzleAgentSkillRepository(drizzle(pool));
+    const restarted = new AgentSkillService(repository, access, audit);
+    expect(
+      await restarted.publish(request, keys[winnerIndex]!, context),
+    ).toEqual(winner.value);
+    expect(events).toHaveLength(1);
+    await expect(
+      restarted.publish(
+        { ...request, content: `${markdown}changed` },
+        keys[winnerIndex]!,
+        context,
+      ),
+    ).rejects.toMatchObject({ code: "SKILL_IDEMPOTENCY_CONFLICT" });
+    expect(
+      await repository.versions("single-tenant", "cas-query"),
+    ).toHaveLength(1);
+    expect(await repository.pendingAudits()).toHaveLength(0);
+    const receipts = await pool.query<{ audit: AuditEvent }>(
+      "select audit from agent_skill_mutations where skill_key='cas-query'",
+    );
+    expect(receipts.rows).toHaveLength(1);
+    expect(receipts.rows[0]!.audit.id).toBe(events[0]!.id);
+  }, 15_000);
+
+  test("a fresh pool and service recover pending audit then persist disable and rollback", async () => {
+    const access = {
+      async authorize() {
+        return true;
+      },
+      async requirement() {
+        return true;
+      },
+    };
+    const failed = new AgentSkillService(
+      new DrizzleAgentSkillRepository(drizzle(pool)),
+      access,
+      async () => {
+        throw new Error("synthetic audit outage");
+      },
+    );
+    await expect(
+      failed.publish(
+        {
+          format: "markdown",
+          content: markdown.replace("cas-query", "restart-query"),
+          scope: "tenant",
+          expectedVersion: 0,
+        },
+        "restart-publish-0001",
+        context,
+      ),
+    ).rejects.toThrow("synthetic audit outage");
+    expect(
+      (await failed.publishedBundles(context)).some(
+        (bundle) => bundle.key === "restart-query",
+      ),
+    ).toBe(false);
+    const before = await new DrizzleAgentSkillRepository(
+      drizzle(pool),
+    ).pendingAudits();
+    expect(before).toHaveLength(1);
+    await pool.end();
+    pool = createPool();
+    const events: AuditEvent[] = [],
+      repository = new DrizzleAgentSkillRepository(drizzle(pool));
+    const recovered = new AgentSkillService(
+      repository,
+      access,
+      async (event) => {
+        events.push(event);
+      },
+    );
+    await recovered.recoverPendingAudits();
+    expect(events.map((event) => event.id)).toEqual([before[0]!.audit.id]);
+    const original = (await recovered.publishedBundles(context)).find(
+      (bundle) => bundle.key === "restart-query",
+    );
+    expect(original?.version).toBe(1);
+    expect(await repository.pendingAudits()).toEqual([]);
+    await recovered.publish(
+      {
+        format: "markdown",
+        content: markdown.replace("cas-query", "restart-query"),
+        scope: "tenant",
+        expectedVersion: 0,
+      },
+      "restart-publish-0001",
+      context,
+    );
+    expect(events).toHaveLength(1);
+    await recovered.command(
+      "restart-query",
+      "disable",
+      { expectedVersion: 1 },
+      "restart-disable-0001",
+      context,
+    );
+    expect(
+      (await recovered.publishedBundles(context)).some(
+        (bundle) => bundle.key === "restart-query",
+      ),
+    ).toBe(false);
+    await pool.end();
+    pool = createPool();
+    const next = new AgentSkillService(
+      new DrizzleAgentSkillRepository(drizzle(pool)),
+      access,
+      async (event) => {
+        events.push(event);
+      },
+    );
+    const rollback = await next.command(
+      "restart-query",
+      "rollback",
+      { expectedVersion: 2, version: 1 },
+      "restart-rollback-0001",
+      context,
+    );
+    expect(rollback.version).toBe(3);
+    expect(rollback.restoredFromVersion).toBe(1);
+    expect(rollback.digest).toBe(original!.digest);
+    expect(
+      (await next.versions("restart-query", context)).map(
+        (version) => version.status,
+      ),
+    ).toEqual(["published", "disabled", "published"]);
+    expect(events.map((event) => event.action)).toEqual([
+      "agent.skill.publish",
+      "agent.skill.disable",
+      "agent.skill.rollback",
+    ]);
+  }, 15_000);
+
+  test("diagnostic lookup and bounded cleanup honor the exact thirty-day boundary", async () => {
+    const now = new Date("2026-10-29T00:00:00.000Z"),
+      retention = 30 * 86_400_000;
+    const index = new DrizzleDiagnosticIndex(drizzle(pool));
+    const diagnostic = (occurredAt: number) =>
+      diagnosticRecord(
+        {
+          diagnosticId: newDiagnosticId(),
+          requestId: "request-synthetic",
+          service: "server",
+          stage: "http",
+          method: "GET",
+          route: "/api/fixture",
+          statusCode: 503,
+          errorCode: "SYNTHETIC_FAILURE",
+        },
+        new Date(occurredAt),
+      );
+    const expired = diagnostic(now.getTime() - retention - 1),
+      boundary = diagnostic(now.getTime() - retention),
+      active = diagnostic(now.getTime() - retention + 60_000);
+    expect(
+      new Date(active.expiresAt).getTime() -
+        new Date(active.occurredAt).getTime(),
+    ).toBe(retention);
+    for (const record of [expired, boundary, active])
+      await index.record(record);
+    await index.record({
+      ...active,
+      requestId: "duplicate-must-not-overwrite",
+    });
+    expect(await index.find(expired.diagnosticId, now)).toBeUndefined();
+    expect(await index.find(boundary.diagnosticId, now)).toBeUndefined();
+    expect(await index.find(active.diagnosticId, now)).toEqual(active);
+    await pool.end();
+    pool = createPool();
+    const restarted = new DrizzleDiagnosticIndex(drizzle(pool));
+    expect(await restarted.find(active.diagnosticId, now)).toEqual(active);
+    expect(await restarted.purgeExpired(now)).toBe(2);
+    expect(await restarted.purgeExpired(now)).toBe(0);
+    expect(
+      await restarted.find(
+        active.diagnosticId,
+        new Date(now.getTime() + 60_000),
+      ),
+    ).toBeUndefined();
+    expect(await restarted.purgeExpired(new Date(now.getTime() + 60_000))).toBe(
+      1,
+    );
+    const remaining = await pool.query<{ count: string }>(
+      "select count(*) from diagnostic_events",
+    );
+    expect(remaining.rows[0]!.count).toBe("0");
+  }, 15_000);
+});

package/template/apps/server/src/agent-skills/read-routes.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, test } from "bun:test";
+import type { AuditEvent } from "@southwind-ai/shared";
+import { buildScopeContext } from "../data-access/context.js";
+import type { RequestGuardContext } from "../guards.js";
+import type { RouteApp } from "../system/route-types.js";
+import { AgentSkillService } from "./service.js";
+import { InMemoryAgentSkillRepository } from "./repository.js";
+import { registerAgentSkillRoutes } from "./routes.js";
+const context: RequestGuardContext = {
+  requestId: "request-read",
+  startedAt: new Date().toISOString(),
+  actor: {
+    id: "actor",
+    type: "user",
+    name: "用户",
+    credentialState: "active",
+    roleCodes: [],
+    permissionKeys: [],
+    scopeContext: buildScopeContext("actor", undefined, [
+      { id: "admin", code: "admin", dataScope: "tenant", departmentIds: [] },
+    ]),
+  },
+};
+async function fixture() {
+  const events: AuditEvent[] = [],
+    routes = new Map<string, (raw: unknown) => unknown>();
+  let allowed = true,
+    auditAvailable = true;
+  const service = new AgentSkillService(
+    new InMemoryAgentSkillRepository(),
+    {
+      async authorize() {
+        return allowed;
+      },
+      async requirement() {
+        return true;
+      },
+    },
+    async (event) => {
+      if (!auditAvailable) throw new Error("private audit failure");
+      events.push(event);
+    },
+  );
+  await service.publish(
+    {
+      format: "markdown",
+      content:
+        "---\nname: safe-query\ndescription: 查询\n---\nPRIVATE_SKILL_BODY\n",
+      scope: "tenant",
+      expectedVersion: 0,
+    },
+    "publish-read-0001",
+    context,
+  );
+  const app: RouteApp = {
+    get(path, handler) {
+      routes.set(path, handler);
+    },
+    post() {},
+    put() {},
+    delete() {},
+  };
+  registerAgentSkillRoutes(app, service);
+  return {
+    events,
+    deny: () => {
+      allowed = false;
+    },
+    failAudit: () => {
+      auditAvailable = false;
+    },
+    async read(path: string) {
+      return (await routes.get(path)!({
+        guardContext: context,
+        request: new Request(
+          `http://localhost/api${path.replace(":key", "safe-query")}`,
+        ),
+        params: { key: "safe-query" },
+      })) as Response;
+    },
+  };
+}
+describe("技能管理读取审计", () => {
+  test("catalog, detail and version reads record only minimal summaries", async () => {
+    const f = await fixture();
+    for (const path of [
+      "/agent/skills",
+      "/agent/skills/:key",
+      "/agent/skills/:key/versions",
+    ])
+      expect((await f.read(path)).status).toBe(200);
+    const reads = f.events.filter(
+      (event) => event.action === "agent.skill.read",
+    );
+    expect(reads.map((event) => event.metadata?.kind)).toEqual([
+      "catalog",
+      "detail",
+      "versions",
+    ]);
+    expect(reads[1]?.metadata?.version).toBe(1);
+    expect(JSON.stringify(reads)).not.toContain("PRIVATE_SKILL_BODY");
+  });
+  test("denied reads do not record a successful read and audit failure is controlled", async () => {
+    const denied = await fixture();
+    denied.deny();
+    expect((await denied.read("/agent/skills/:key")).status).toBe(403);
+    expect(
+      denied.events.filter((event) => event.action === "agent.skill.read"),
+    ).toHaveLength(0);
+    const failed = await fixture();
+    failed.failAudit();
+    const result = await failed.read("/agent/skills/:key");
+    expect(result.status).toBe(503);
+    expect(await result.text()).not.toContain("PRIVATE_SKILL_BODY");
+  });
+});