create-windy 0.8.3 → 0.10.0

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");
+  });
+});

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

@@ -0,0 +1,108 @@
+import type {
+  AgentSkillGovernanceItem,
+  AgentSkillRuntimeBundle,
+} from "@southwind-ai/shared";
+import type { RequestGuardContext } from "../guards.js";
+import {
+  requireSkillAccess,
+  skillActor,
+  skillGovernable,
+  skillReadable,
+  skillRequirementsAvailable,
+  type AgentSkillAccess,
+} from "./access.js";
+import { skillKey } from "./bundle.js";
+import {
+  AgentSkillError,
+  type AgentSkillRepository,
+  type StoredAgentSkill,
+} from "./contracts.js";
+export class AgentSkillReader {
+  constructor(
+    protected readonly repository: AgentSkillRepository,
+    protected readonly access: AgentSkillAccess,
+  ) {}
+  async list(
+    context: RequestGuardContext,
+  ): Promise<readonly AgentSkillGovernanceItem[]> {
+    await requireSkillAccess(this.access, context, "read");
+    const records = await this.repository.versions(
+      skillActor(context).tenantId,
+    );
+    const current = new Map<string, StoredAgentSkill>();
+    for (const record of records)
+      if (record.auditCommitted) current.set(record.metadata.key, record);
+    return Promise.all(
+      [...current.values()]
+        .filter((record) => skillReadable(record.metadata, context))
+        .map(async (record) => ({
+          skill: record.metadata,
+          available:
+            record.metadata.status === "published" &&
+            (await skillRequirementsAvailable(
+              this.access,
+              record.metadata,
+              context,
+            )),
+          governable:
+            skillGovernable(record.metadata, context) &&
+            (await this.access.authorize(context, "manage")),
+        })),
+    );
+  }
+  async versions(key: string, context: RequestGuardContext) {
+    await requireSkillAccess(this.access, context, "read");
+    const records = await this.repository.versions(
+      skillActor(context).tenantId,
+      skillKey(key),
+    );
+    const current = records.filter((record) => record.auditCommitted).at(-1);
+    if (!current || !skillReadable(current.metadata, context))
+      throw unavailable();
+    return records
+      .filter(
+        (record) =>
+          record.auditCommitted && skillReadable(record.metadata, context),
+      )
+      .map(({ metadata }) => metadata);
+  }
+  async detail(key: string, context: RequestGuardContext) {
+    await requireSkillAccess(this.access, context, "read");
+    const records = await this.repository.versions(
+      skillActor(context).tenantId,
+      skillKey(key),
+    );
+    const record = records.filter((item) => item.auditCommitted).at(-1);
+    if (!record || !skillReadable(record.metadata, context))
+      throw unavailable();
+    return { skill: record.metadata, bundle: record.bundle };
+  }
+  async publishedBundles(
+    context: RequestGuardContext,
+  ): Promise<readonly AgentSkillRuntimeBundle[]> {
+    await requireSkillAccess(this.access, context, "execute");
+    const records = await this.repository.versions(
+      skillActor(context).tenantId,
+    );
+    const current = new Map<string, StoredAgentSkill>();
+    for (const record of records)
+      if (record.auditCommitted) current.set(record.metadata.key, record);
+    const results: AgentSkillRuntimeBundle[] = [];
+    for (const { metadata, bundle } of current.values())
+      if (
+        metadata.status === "published" &&
+        skillReadable(metadata, context) &&
+        (await skillRequirementsAvailable(this.access, metadata, context))
+      )
+        results.push({
+          key: metadata.key,
+          version: metadata.version,
+          digest: metadata.digest,
+          files: bundle.files,
+        });
+    return results;
+  }
+}
+function unavailable() {
+  return new AgentSkillError("SKILL_UNAVAILABLE", "技能或版本不可用", 404);
+}

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

@@ -0,0 +1,105 @@
+import type {
+  AgentSkillRepository,
+  SkillMutationIdentity,
+  SkillMutationReceipt,
+  StoredAgentSkill,
+} from "./contracts.js";
+import { AgentSkillError } from "./contracts.js";
+
+export function assertSkillMutation(
+  current: StoredAgentSkill | undefined,
+  expectedVersion: number,
+) {
+  if (
+    (current?.metadata.version ?? 0) !== expectedVersion ||
+    (current && !current.auditCommitted)
+  )
+    throw new AgentSkillError(
+      "SKILL_VERSION_CONFLICT",
+      "技能版本已变化或尚有审计未完成，请刷新后重试",
+      409,
+    );
+}
+export function assertSkillReplay(
+  receipt: SkillMutationReceipt,
+  identity: SkillMutationIdentity,
+) {
+  if (receipt.requestDigest !== identity.requestDigest)
+    throw new AgentSkillError(
+      "SKILL_IDEMPOTENCY_CONFLICT",
+      "幂等键已用于不同的技能操作",
+      409,
+    );
+}
+export class InMemoryAgentSkillRepository implements AgentSkillRepository {
+  private records: StoredAgentSkill[] = [];
+  private receipts = new Map<string, SkillMutationReceipt>();
+  private tail: Promise<void> = Promise.resolve();
+  async versions(tenantId: string, key?: string) {
+    return structuredClone(
+      this.records.filter(
+        (r) =>
+          r.metadata.tenantId === tenantId && (!key || r.metadata.key === key),
+      ),
+    );
+  }
+  async mutate(
+    input: Parameters<AgentSkillRepository["mutate"]>[0],
+    change: Parameters<AgentSkillRepository["mutate"]>[1],
+  ) {
+    const previous = this.tail;
+    let release!: () => void;
+    this.tail = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    await previous;
+    try {
+      const receiptKey = identityKey(input);
+      const replay = this.receipts.get(receiptKey);
+      if (replay) {
+        assertSkillReplay(replay, input);
+        return structuredClone(replay);
+      }
+      const versions = await this.versions(input.tenantId, input.key);
+      const current = versions.at(-1);
+      assertSkillMutation(current, input.expectedVersion);
+      const value = await change(current, versions);
+      const receipt = {
+        ...input,
+        result: value.record.metadata,
+        audit: value.audit,
+        auditCommitted: false,
+      };
+      this.records.push(structuredClone(value.record));
+      this.receipts.set(receiptKey, structuredClone(receipt));
+      return receipt;
+    } finally {
+      release();
+    }
+  }
+  async pendingAudits() {
+    return structuredClone(
+      [...this.receipts.values()].filter((receipt) => !receipt.auditCommitted),
+    );
+  }
+  async acknowledge(receipt: SkillMutationReceipt) {
+    const key = identityKey(receipt),
+      existing = this.receipts.get(key);
+    if (!existing) throw new Error("Skill mutation receipt missing");
+    this.receipts.set(key, { ...existing, auditCommitted: true });
+    this.records = this.records.map((record) =>
+      record.metadata.tenantId === receipt.tenantId &&
+      record.metadata.key === receipt.result.key &&
+      record.metadata.version === receipt.result.version
+        ? { ...record, auditCommitted: true }
+        : record,
+    );
+  }
+}
+function identityKey(identity: SkillMutationIdentity) {
+  return JSON.stringify([
+    identity.tenantId,
+    identity.actorId,
+    identity.idempotencyKey,
+  ]);
+}