create-windy 0.5.2 → 0.6.0

package/template/apps/server/src/report-staging/service.ts

@@ -0,0 +1,255 @@
+import { createHash, randomBytes } from "node:crypto";
+import type { ModuleReportStagingPortV1 } from "@southwind-ai/server-sdk";
+import type { ReportStagingFilesystemStore } from "./filesystem-store.js";
+import type { ReportStagingRepository } from "./repository.js";
+import { withPeriodicReportStagingHeartbeat } from "./heartbeat.js";
+import {
+  computeManifestSha256,
+  createGroupRecord,
+  groupFingerprint,
+  idempotencyHash,
+  opaqueId,
+  policyDigest,
+  sourceRecords,
+  validateCreateInput,
+} from "./service-input.js";
+import { createReportStagingReadPort } from "./service-read.js";
+import {
+  authorize,
+  conflict,
+  expiresAt,
+  projectGroup,
+  requireOwned,
+  requirePolicy,
+  stableError,
+  type ReportStagingPortScope,
+  type ReportStagingServiceDependencies,
+} from "./service-support.js";
+
+export type { ReportStagingPortScope } from "./service-support.js";
+
+export class ReportStagingService {
+  readonly #dependencies: ReportStagingServiceDependencies;
+
+  constructor(
+    repository: ReportStagingRepository,
+    files: ReportStagingFilesystemStore,
+    now: () => Date = () => new Date(),
+  ) {
+    this.#dependencies = { repository, files, now };
+  }
+
+  createPort(scope: ReportStagingPortScope): ModuleReportStagingPortV1 {
+    return {
+      ...createReportStagingReadPort(this.#dependencies, scope),
+      createOrResume: (input) => this.createOrResume(scope, input),
+      discard: (groupId) => this.discard(scope, groupId),
+    };
+  }
+
+  async cleanupExpired(limit = 50) {
+    const { repository, files, now: clock } = this.#dependencies;
+    const now = clock().toISOString();
+    const candidates = await repository.listPurgeCandidates(now, limit);
+    let purged = 0;
+    let pending = 0;
+    for (const group of candidates) {
+      const discarding = await repository.markDiscarding(group.groupId, now);
+      if (!discarding) {
+        pending += 1;
+        continue;
+      }
+      try {
+        await files.discard(group.groupId);
+        if (await repository.markDiscarded(group.groupId, now)) purged++;
+      } catch {
+        pending += 1;
+      }
+    }
+    return { purged, pending };
+  }
+
+  private async createOrResume(
+    scope: ReportStagingPortScope,
+    input: Parameters<ModuleReportStagingPortV1["createOrResume"]>[0],
+  ) {
+    const { repository, files, now: clock } = this.#dependencies;
+    await authorize(scope);
+    const policy = requirePolicy(scope, input.purpose);
+    validateCreateInput(input, policy);
+    const now = clock().toISOString();
+    const groupId = opaqueId("rsg");
+    const proposed = createGroupRecord({
+      groupId,
+      moduleName: scope.moduleName,
+      ownerId: scope.ownerId,
+      scopeHash: scope.scopeHash,
+      create: input,
+      policy,
+      now,
+    });
+    const created = await repository.createOrGetGroup(
+      proposed,
+      sourceRecords(groupId, input, now),
+    );
+    const group = created.group;
+    if (
+      group.fingerprint !== groupFingerprint(input) ||
+      group.policyDigest !== policyDigest(policy) ||
+      group.idempotencyHash !== idempotencyHash(input.idempotencyKey)
+    ) {
+      throw conflict();
+    }
+    requireOwned(scope, group);
+    if (group.status !== "indexing") {
+      if (group.status === "ready" && group.sealId) {
+        await this.cleanupSealSiblings(scope, group.groupId, group.sealId);
+      }
+      return projectGroup(group, clock());
+    }
+    const rawToken = randomBytes(32).toString("base64url");
+    const tokenHash = createHash("sha256").update(rawToken).digest("hex");
+    const claim = await repository.acquireClaim(
+      group.groupId,
+      tokenHash,
+      now,
+      expiresAt(clock(), policy.claimTtlMs),
+    );
+    if (!claim) return projectGroup(group, clock());
+    const heartbeat = async () => {
+      const heartbeatNow = clock();
+      if (
+        !(await repository.renewClaim(
+          group.groupId,
+          tokenHash,
+          heartbeatNow.toISOString(),
+          expiresAt(heartbeatNow, policy.claimTtlMs),
+        ))
+      ) {
+        throw conflict();
+      }
+    };
+    let prepared: Awaited<ReturnType<typeof files.prepare>> | undefined;
+    try {
+      // A newly acquired claim owns the whole indexing-group filesystem state.
+      await withPeriodicReportStagingHeartbeat(
+        (signal) => files.discardOrphans(group.groupId, signal),
+        heartbeat,
+      );
+      prepared = await files.prepare({
+        groupId: group.groupId,
+        sealId: tokenHash,
+        sourceMode: group.sourceMode,
+        entrypoint: group.entrypoint,
+        sources: await repository.getSources(group.groupId),
+        policy,
+        reader: scope.reader,
+        signal: scope.signal,
+        heartbeat,
+      });
+      try {
+        await heartbeat();
+      } catch (error) {
+        prepared.catalog.close();
+        await files.discardPrepared(group.groupId, prepared.sealId);
+        throw error;
+      }
+      let ready;
+      let sealFailure: unknown;
+      try {
+        ready = await repository.sealGroup(group.groupId, tokenHash, {
+          ...prepared,
+          manifestSha256: computeManifestSha256(
+            group,
+            prepared.sources,
+            prepared.catalog,
+          ),
+          updatedAt: clock().toISOString(),
+        });
+      } catch (cause) {
+        sealFailure = cause;
+      }
+      if (!ready) {
+        let authoritative;
+        try {
+          authoritative = await repository.getGroup(group.groupId);
+        } catch (reconcileFailure) {
+          // The commit result is unknown, so preserving the exact seal is safer.
+          throw sealFailure ?? reconcileFailure;
+        }
+        if (
+          authoritative?.status === "ready" &&
+          authoritative.sealId === prepared.sealId
+        ) {
+          ready = authoritative;
+        } else {
+          prepared.catalog.close();
+          await files.discardPrepared(group.groupId, prepared.sealId);
+          if (sealFailure) throw sealFailure;
+          throw conflict();
+        }
+      }
+      await this.cleanupSealSiblings(scope, group.groupId, prepared.sealId);
+      scope.record("report.staging.ready", "success", group.groupId, {
+        sources: ready.sourceCount,
+        entries: ready.entryCount,
+        archiveBytes: ready.archiveByteSize,
+        expandedBytes: ready.expandedByteSize,
+      });
+      return projectGroup(ready, clock());
+    } catch (cause) {
+      const error = stableError(cause);
+      if (error.retryable) {
+        await repository.releaseClaim(group.groupId, tokenHash);
+      } else {
+        await repository.failGroup(
+          group.groupId,
+          tokenHash,
+          error.code,
+          clock().toISOString(),
+        );
+      }
+      scope.record("report.staging.failed", "failure", group.groupId, {
+        errorCode: error.code,
+        retryable: error.retryable,
+      });
+      throw error;
+    } finally {
+      prepared?.catalog.close();
+    }
+  }
+
+  private async cleanupSealSiblings(
+    scope: ReportStagingPortScope,
+    groupId: string,
+    keepSealId: string,
+  ) {
+    try {
+      await this.#dependencies.files.discardPreparedSiblings(
+        groupId,
+        keepSealId,
+      );
+    } catch {
+      scope.record("report.staging.cleanup", "failure", groupId);
+    }
+  }
+
+  private async discard(scope: ReportStagingPortScope, groupId: string) {
+    const { repository, files, now: clock } = this.#dependencies;
+    await authorize(scope);
+    const group = await repository.getGroup(groupId);
+    if (!group) throw conflict();
+    requireOwned(scope, group);
+    const now = clock().toISOString();
+    const discarding = await repository.markDiscarding(groupId, now);
+    if (!discarding) throw conflict();
+    if (discarding.status === "discarded") {
+      return projectGroup(discarding, clock());
+    }
+    await files.discard(groupId);
+    const discarded = await repository.markDiscarded(groupId, now);
+    if (!discarded) throw conflict();
+    scope.record("report.staging.discard", "success", groupId);
+    return projectGroup(discarded, clock());
+  }
+}

package/template/apps/server/src/report-staging/supervised-process.ts

@@ -0,0 +1,194 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import type { Readable } from "node:stream";
+import { ModuleReportStagingError } from "@southwind-ai/server-sdk";
+
+const MAX_STDERR_BYTES = 64 * 1024;
+const PROCESS_KILL_GRACE_MS = 250;
+const CONSUMER_CLEANUP_GRACE_MS = 250;
+
+export interface SupervisedProcessOptions {
+  readonly signal: AbortSignal;
+  readonly timeoutMs: number;
+  readonly maxStdoutBytes: number;
+  readonly onStdout?: (chunk: Buffer) => void;
+  readonly consumeStdout?: (
+    stdout: Readable,
+    signal: AbortSignal,
+  ) => Promise<void>;
+  readonly heartbeat?: () => Promise<void>;
+}
+
+export async function runSupervisedProcess(
+  binary: string,
+  args: readonly string[],
+  options: SupervisedProcessOptions,
+): Promise<void> {
+  if (options.signal.aborted) throw cancelled();
+  const child = spawn(binary, [...args], {
+    shell: false,
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true,
+    env: {
+      LANG: "C",
+      LC_ALL: "C",
+      PATH: "/usr/bin:/bin",
+      TZ: "UTC",
+    },
+  });
+  let stdoutBytes = 0;
+  let stderrBytes = 0;
+  let streamFailure: unknown;
+  let heartbeatFailure: unknown;
+  let resolveControl!: (value: { readonly kind: "control" }) => void;
+  const control = new Promise<{ readonly kind: "control" }>((resolve) => {
+    resolveControl = resolve;
+  });
+  const consumerController = new AbortController();
+  const consumer = options.consumeStdout
+    ? options
+        .consumeStdout(child.stdout, consumerController.signal)
+        .catch((error) => {
+          streamFailure = error;
+          resolveControl({ kind: "control" });
+        })
+    : undefined;
+  if (!consumer) {
+    child.stdout.on("data", (value: Buffer) => {
+      if (streamFailure) return;
+      try {
+        stdoutBytes += value.byteLength;
+        if (stdoutBytes > options.maxStdoutBytes) {
+          throw unsafe("报告索引输出超过 Host 上限");
+        }
+        options.onStdout?.(value);
+      } catch (error) {
+        streamFailure = error;
+        resolveControl({ kind: "control" });
+      }
+    });
+  }
+  child.stderr.on("data", (value: Buffer) => {
+    // Drain all bytes so the child cannot block, retaining only a bounded count.
+    stderrBytes = Math.min(MAX_STDERR_BYTES, stderrBytes + value.byteLength);
+  });
+  const exit = processExit(child);
+  const completion = consumer
+    ? Promise.all([exit, consumer]).then(([result]) => result)
+    : exit;
+  const abort = abortPromise(options.signal);
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<{ readonly kind: "timeout" }>((resolve) => {
+    timeoutId = setTimeout(
+      () => resolve({ kind: "timeout" }),
+      options.timeoutMs,
+    );
+  });
+  let heartbeatInFlight = false;
+  const interval = options.heartbeat
+    ? setInterval(() => {
+        if (heartbeatInFlight) return;
+        heartbeatInFlight = true;
+        void options.heartbeat!()
+          .catch((error) => {
+            heartbeatFailure = error;
+            resolveControl({ kind: "control" });
+          })
+          .finally(() => {
+            heartbeatInFlight = false;
+          });
+      }, 10_000)
+    : undefined;
+  const result = await Promise.race([
+    completion,
+    abort.promise,
+    timeout,
+    control,
+  ]);
+  if (timeoutId !== undefined) clearTimeout(timeoutId);
+  if (interval) clearInterval(interval);
+  abort.dispose();
+  if (result.kind !== "exit") {
+    consumerController.abort();
+    child.stdout.destroy();
+    await terminateBounded(child, exit);
+    if (consumer) {
+      await Promise.race([consumer, delay(CONSUMER_CLEANUP_GRACE_MS)]);
+    }
+    if (result.kind === "abort") throw cancelled();
+    if (result.kind === "timeout") throw timedOut();
+    if (heartbeatFailure) throw heartbeatFailure;
+    throw streamFailure;
+  }
+  if (heartbeatFailure) throw heartbeatFailure;
+  if (streamFailure) throw streamFailure;
+  if (result.code !== 0) {
+    throw new ModuleReportStagingError(
+      "REPORT_STAGING_PROCESS_FAILED",
+      "报告解包进程未成功完成",
+    );
+  }
+}
+
+type ExitResult = {
+  readonly kind: "exit";
+  readonly code: number | null;
+};
+
+function processExit(child: ChildProcess) {
+  return new Promise<ExitResult>((resolve) => {
+    child.once("error", () => resolve({ kind: "exit", code: null }));
+    // `close` fires only after stdout/stderr have closed, so listing bytes cannot
+    // arrive after the caller starts validating the completed preflight.
+    child.once("close", (code) => resolve({ kind: "exit", code }));
+  });
+}
+
+function abortPromise(signal: AbortSignal) {
+  let listener: () => void = () => {};
+  const promise = new Promise<{ readonly kind: "abort" }>((resolve) => {
+    listener = () => resolve({ kind: "abort" });
+    if (signal.aborted) listener();
+    else signal.addEventListener("abort", listener, { once: true });
+  });
+  return {
+    promise,
+    dispose: () => signal.removeEventListener("abort", listener),
+  };
+}
+
+async function terminateBounded(
+  child: ChildProcess,
+  exit: Promise<ExitResult>,
+) {
+  child.kill("SIGTERM");
+  const graceful = await Promise.race([exit, delay(PROCESS_KILL_GRACE_MS)]);
+  if (graceful) return;
+  child.kill("SIGKILL");
+  await Promise.race([exit, delay(PROCESS_KILL_GRACE_MS)]);
+}
+
+function delay(milliseconds: number) {
+  return new Promise<undefined>((resolve) => {
+    setTimeout(resolve, milliseconds);
+  });
+}
+
+function unsafe(message: string) {
+  return new ModuleReportStagingError("REPORT_STAGING_UNSAFE_ARCHIVE", message);
+}
+
+function cancelled() {
+  return new ModuleReportStagingError(
+    "REPORT_STAGING_CANCELLED",
+    "报告暂存已取消",
+    true,
+  );
+}
+
+function timedOut() {
+  return new ModuleReportStagingError(
+    "REPORT_STAGING_PROCESS_TIMEOUT",
+    "报告解包进程超过 Host 时间上限",
+    true,
+  );
+}

package/template/apps/server/src/speech/contracts.ts

@@ -4,6 +4,7 @@ import type {
   AiProviderEgressPolicy,
 } from "@southwind-ai/modules";
 import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type { AiOutputArtifactSinkDescriptorV1 } from "../ai-output-artifact/contracts.js";
 
 export interface SpeechRuntimeArtifact {
   readonly value: string;
@@ -14,6 +15,11 @@ export interface SpeechRuntimeArtifact {
 
 export interface SpeechRuntimeOperation {
   readonly kind: "speech";
+  /** Host-planned operation-bound Run identity; public callers cannot set it. */
+  readonly runId?: string;
+  /** Missing version is the legacy V1 transcribe operation. */
+  readonly contractVersion?: 2;
+  readonly variant?: "normalize" | "transcribe" | "translate";
   readonly operationKey: string;
   readonly options: ModuleAiJsonValue;
   readonly source: SpeechRuntimeArtifact;
@@ -28,6 +34,7 @@ export interface SpeechRuntimeOperation {
   };
   readonly providerEgress: AiProviderEgressPolicy;
   readonly providerDataPolicy?: AiProviderDataPolicy;
+  readonly outputArtifactSink?: AiOutputArtifactSinkDescriptorV1;
 }
 
 export interface SpeechRuntimeStartResponse {
@@ -41,6 +48,7 @@ export interface SpeechRuntimePort {
     request: SpeechRuntimeOperation,
     idempotencyKey: string,
     signal?: AbortSignal,
+    outputArtifactGrant?: string,
   ): Promise<SpeechRuntimeStartResponse>;
   events(
     runId: string,

package/template/apps/server/src/speech/errors.ts

@@ -0,0 +1,10 @@
+export class SpeechFacadeError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+    readonly status: number,
+  ) {
+    super(message);
+    this.name = "SpeechFacadeError";
+  }
+}

package/template/apps/server/src/speech/facade-contract.ts

@@ -0,0 +1,49 @@
+import type { FeatureFlagDefinition } from "@southwind-ai/shared";
+import type { ModuleAiOperationDefinition } from "@southwind-ai/modules";
+import type { ModuleAiOperationHandlerRegistration } from "@southwind-ai/server-sdk";
+
+export interface RegisteredSpeechOperation {
+  definition: ModuleAiOperationDefinition;
+  feature: FeatureFlagDefinition | undefined;
+  registration?: ModuleAiOperationHandlerRegistration;
+  moduleName?: string;
+}
+
+export interface SpeechStartContract {
+  readonly contractVersion?: 2;
+  readonly variant?: "normalize" | "transcribe" | "translate";
+}
+
+export function matchesSpeechContractVariant(
+  definition: ModuleAiOperationDefinition,
+  contract: SpeechStartContract,
+): boolean {
+  return (
+    contract.contractVersion !== 2 ||
+    (Boolean(definition.readiness) &&
+      definition.readiness?.variant === contract.variant)
+  );
+}
+
+export function legacySpeechCapabilities(
+  value: Record<string, unknown>,
+): string[] {
+  if (Array.isArray(value.capabilities)) {
+    return value.capabilities.filter(
+      (item): item is string => typeof item === "string",
+    );
+  }
+  if (!Array.isArray(value.offers)) return [];
+  return value.offers.flatMap((offer) => {
+    const capabilities =
+      offer &&
+      typeof offer === "object" &&
+      "capabilities" in offer &&
+      Array.isArray(offer.capabilities)
+        ? (offer.capabilities as unknown[])
+        : [];
+    return capabilities.filter(
+      (item): item is string => typeof item === "string",
+    );
+  });
+}