@supacloud/cli 0.75.1 → 0.77.0

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/migration-inventory.integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/project-read-process.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/cli.d.ts

@@ -0,0 +1,18 @@
+import type { ToolSchema } from "./schema";
+import type { ToolInvocation } from "./tool-server";
+interface CliRunOptions {
+    commandName?: string;
+}
+interface CliToolResult {
+    content?: Array<{
+        type: string;
+        text?: string;
+    }>;
+    isError?: boolean;
+}
+export declare function cliToolResultIsError(toolResult: CliToolResult): boolean;
+export declare function runCli(cliTools: Record<string, {
+    schema: ToolSchema;
+    callback: ToolInvocation;
+}>, args: string[], options?: CliRunOptions): Promise<void>;
+export {};

package/dist/shared/context.d.ts

@@ -0,0 +1,26 @@
+export type ContextSourceKind = "process_env" | "named_env_file" | "explicit_env_file" | "legacy_dotenv" | "none";
+export type ContextCredentialScope = "management" | "project_application" | "incomplete";
+export interface ContextSelection {
+    environmentName?: string;
+    envFile?: string;
+}
+export interface ResolvedContext {
+    host: string;
+    sshUser: string;
+    sshPort: number;
+    sshKey: string;
+    sshPass: string;
+    apiUrl: string;
+    apiToken: string;
+    projectRef: string;
+    readOnly: boolean;
+    environment: string;
+    production: boolean;
+    inferredSupabaseUrl: string;
+    inferredServiceRoleKey: string;
+    credentialScope: ContextCredentialScope;
+    source: ContextSourceKind;
+    sourcePath: string | null;
+    insecureTls: boolean;
+}
+export declare function resolveSupaCloudContext(env?: NodeJS.ProcessEnv, cwd?: string, selection?: ContextSelection): ResolvedContext;

package/dist/shared/context.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/execution-policy.d.ts

@@ -0,0 +1,14 @@
+import type { ToolSchema } from "./schema";
+import type { ResolvedContext } from "./context";
+export type ExecutionMode = "read" | "write" | "local";
+export interface ExecutionAuthorization {
+    context: ResolvedContext;
+    confirmProduction?: string;
+}
+interface ToolCatalogEntry {
+    schema: ToolSchema;
+}
+export declare function executionMode(moduleName: string, action: string, args: Record<string, unknown>): ExecutionMode | undefined;
+export declare function authorizeExecution(moduleName: string, args: Record<string, unknown>, authorization: ExecutionAuthorization): void;
+export declare function validateExecutionPolicyCoverage(tools: Record<string, ToolCatalogEntry>): void;
+export {};

package/dist/shared/execution-policy.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/global-options.d.ts

@@ -0,0 +1,8 @@
+export interface GlobalCliOptions {
+    environmentName?: string;
+    envFile?: string;
+    confirmProduction?: string;
+    args: string[];
+}
+export declare function normalizeEnvironmentName(name: string): string;
+export declare function parseGlobalOptions(args: string[]): GlobalCliOptions;

package/dist/shared/global-options.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/mutation-protocol.d.ts

@@ -0,0 +1,45 @@
+import type { HttpTransport } from "./transports/http";
+export interface SafeMutationStatus {
+    project_ref: string;
+    mutation_id: string;
+    operation: string;
+    resource_key: string | null;
+    request_fingerprint: string;
+    principal: {
+        type: "master" | "admin" | "project";
+        id: string;
+    };
+    status: "pending" | "running" | "succeeded" | "failed_retryable" | "failed_terminal" | "outcome_unknown";
+    checkpoint: Record<string, unknown>;
+    receipt: Record<string, unknown> | null;
+    response_status: number | null;
+    failure_code: string | null;
+    lease: {
+        owner: string | null;
+        expires_at: string | null;
+        fencing_epoch: number;
+    };
+    completed_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface MutationExpectation {
+    ref: string;
+    mutationId: string;
+    operation: string;
+    requestFingerprint: string;
+}
+export type MutationStatusReadback = {
+    kind: "available";
+    mutation: SafeMutationStatus;
+} | {
+    kind: "unavailable";
+    httpStatus: number | null;
+} | {
+    kind: "invalid";
+};
+export declare function isMutationId(candidate: unknown): candidate is string;
+export declare function mutationRequestFingerprint(normalizedRequest: unknown): string;
+export declare function mutationStatusPath(ref: string, mutationId: string): string;
+export declare function fetchMutationStatus(http: HttpTransport, ref: string, mutationId: string): Promise<MutationStatusReadback>;
+export declare function verifiedMutationReadback(http: HttpTransport, expectation: MutationExpectation): Promise<MutationStatusReadback>;

package/dist/shared/mutation-protocol.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/outcome-guidance.d.ts

@@ -0,0 +1 @@
+export declare function outcomeUnknownGuidance(text: string): string | null;

package/dist/shared/project-ref.d.ts

@@ -0,0 +1 @@
+export declare function projectRefPathSegment(ref: unknown, operation: string): string;

package/dist/shared/schema.d.ts

@@ -0,0 +1,13 @@
+import { Type } from "typebox";
+import type { StaticDecode, TObject, TSchema, TSchemaOptions } from "typebox";
+export type ToolSchema = Record<string, TSchema>;
+export type ToolArguments<S extends ToolSchema> = StaticDecode<TObject<S>>;
+export declare function validateToolArguments(schema: ToolSchema, input: unknown): asserts input is Record<string, unknown>;
+export declare function parseToolArguments<S extends ToolSchema>(schema: S, input: unknown): ToolArguments<S>;
+export declare function stringEnum<const Values extends readonly [string, ...string[]]>(values: Values, options?: TSchemaOptions): Type.TEnum<Values[number][]>;
+export declare function withDescription<T extends TSchema>(schema: T, description: string): T;
+export declare function optional<T extends TSchema>(schema: T, description?: string): "~optional" extends keyof T ? T : Type.TOptional<T>;
+export declare function decodedSchema<TInput extends TSchema, TOutput extends TSchema>(inputSchema: TInput, outputSchema: TOutput, decode: (input: StaticDecode<TInput>) => unknown, options?: TSchemaOptions): Type.TCodec<TInput, import("typebox").StaticType<[], "Decode", {}, {}, TOutput>>;
+export declare function schemaEnumValues(schema: TSchema): string[];
+export declare function schemaDescription(schema: TSchema): string;
+export declare function schemaProperties(schema: TSchema | ToolSchema): ToolSchema;

package/dist/shared/schema.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/tool-server.d.ts

@@ -0,0 +1,15 @@
+import { type ToolArguments, type ToolSchema } from "./schema.js";
+export interface ToolTextContent {
+    readonly type: "text";
+    readonly text: string;
+}
+export interface ToolResult {
+    content: ToolTextContent[];
+    readonly isError?: boolean;
+}
+export type ToolCallback<TArgs, TResult extends ToolResult = ToolResult> = (args: TArgs) => Promise<TResult>;
+export type ToolInvocation = (args: unknown) => Promise<ToolResult>;
+export interface ToolServer {
+    tool: (name: string, description: string, schema: ToolSchema, callback: ToolInvocation) => void;
+}
+export declare function registerTool<S extends ToolSchema, TResult extends ToolResult = ToolResult>(server: ToolServer, name: string, description: string, schema: S, callback: ToolCallback<NoInfer<ToolArguments<S>>, TResult>): void;

package/dist/shared/tool-server.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/tools/advanced-tools.d.ts

@@ -0,0 +1,5 @@
+import { type ToolServer } from "../tool-server";
+import type { HttpTransport } from "../transports/http";
+export declare function registerAdvancedTools(server: ToolServer, http: HttpTransport, environment?: NodeJS.ProcessEnv, options?: {
+    readOnly?: boolean;
+}): void;

package/dist/shared/tools/advanced-tools.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/tools/ai-tools.d.ts

@@ -0,0 +1,28 @@
+import { type ToolServer } from "../tool-server";
+declare const SKILL_NAME = "supacloud-cli";
+type InstallMode = "dry-run" | "write";
+type ConflictPolicy = "reject" | "replace";
+type InstallAction = "create" | "replace" | "none";
+interface InstallSkillRequest {
+    sourceDirectory: string;
+    targetRoot: string;
+    mode: InstallMode;
+    conflictPolicy: ConflictPolicy;
+    now: Date;
+}
+export interface SkillInstallSummary {
+    name: typeof SKILL_NAME;
+    sourceDirectory: string;
+    targetRoot: string;
+    destinationDirectory: string;
+    action: InstallAction;
+    mode: InstallMode;
+    changed: boolean;
+    backupDirectory: string | null;
+    files: string[];
+}
+export declare function installSkill(request: InstallSkillRequest): SkillInstallSummary;
+export declare function resolveDefaultCodexSkillRoot(environment?: NodeJS.ProcessEnv, homeDirectory?: string): string;
+export declare function resolveBundledSkillDirectory(moduleUrl?: string): string;
+export declare function registerAiTools(server: ToolServer): void;
+export {};

package/dist/shared/tools/ai-tools.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/tools/app-database-check.d.ts

@@ -0,0 +1,7 @@
+export interface AppDatabaseCheck {
+    name: "database-source-contracts";
+    ok: boolean;
+    detail: string;
+}
+/** Use the project's installed tool, not arbitrary package scripts or remote database access. */
+export declare function checkAppDatabaseSources(projectRoot: string): AppDatabaseCheck | undefined;

package/dist/shared/tools/app-database-check.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/tools/app-delivery.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/tools/app-dev-regressions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/tools/app-dev.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/tools/app-local-dev.d.ts

@@ -0,0 +1,15 @@
+export interface LocalDevOptions {
+    root: string;
+    profile?: "fast" | "integration";
+    databaseUrl?: string;
+    signal?: AbortSignal;
+    onOutput?: (text: string) => void;
+}
+export declare function localDatabaseUrl(value: string | undefined): string;
+/** Launch the project's one dev loop; do not add another compiler watcher. */
+export declare function runLocalDevelopment(options: LocalDevOptions): Promise<{
+    profile: "fast" | "integration";
+    script: string;
+    exitCode: number;
+    state: "stopped";
+}>;

package/dist/shared/tools/app-local-dev.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/tools/app-minimal-starter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/tools/app-resource-generation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/tools/app-resource.d.ts

@@ -0,0 +1,5 @@
+/**
+ * One editable read resource, not a persistence implementation or a second DI
+ * system. Module/provider/controller wiring uses the existing compiler model.
+ */
+export declare function resourceScaffold(name: string, className: string): Record<string, string>;

package/dist/shared/tools/app-scaffold-writes.d.ts

@@ -0,0 +1,33 @@
+export declare class ScaffoldError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export interface ScaffoldWrite {
+    readonly path: string;
+    readonly content: string;
+    /** A registration edit must still match the source used by the compiler. */
+    readonly expected?: string;
+    readonly overwrite?: boolean;
+}
+interface FileSnapshot {
+    readonly content: string;
+    readonly mode: number;
+    readonly dev: number;
+    readonly ino: number;
+}
+export interface ScaffoldPlan {
+    readonly root: string;
+    readonly writes: readonly (ScaffoldWrite & {
+        readonly before: FileSnapshot | null;
+    })[];
+}
+export declare function scaffoldPath(root: string, path: string): string;
+/** Preflight the complete set before creating any directory or file. */
+export declare function planScaffoldWrites(root: string, writes: readonly ScaffoldWrite[]): Promise<ScaffoldPlan>;
+/**
+ * Serializes generator writers and rolls back handled write failures. This is
+ * not a crash-atomic filesystem transaction or a sandbox against hostile local
+ * writers. Concurrent edits detected during validation are never overwritten.
+ */
+export declare function applyScaffoldWrites(plan: ScaffoldPlan): Promise<void>;
+export {};

package/dist/shared/tools/app-scaffold-writes.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/tools/app-starter-attachment-worker.d.ts

@@ -0,0 +1,2 @@
+export declare const STARTER_ATTACHMENT_WORKER = "import { createWorker, type CompiledModule } from \"@supacloud/elysia\";\nimport type { SupaCloudWorkflowClaim, SupaCloudWorkflowsClient } from \"@supacloud/js\";\nimport { createReviewAttachmentAdapters, type ReviewAttachmentOptions } from \"./review-attachments\";\n\nexport interface ReviewAttachmentWorkerOptions extends ReviewAttachmentOptions {\n  modules: readonly CompiledModule[];\n  workflows: Pick<SupaCloudWorkflowsClient, \"claim\" | \"complete\" | \"retry\" | \"fail\">;\n  workerId: string;\n  queueOwnership: \"exclusive-review-attachments\";\n  pollIntervalMs?: number;\n}\n\nexport async function createReviewAttachmentWorker(options: ReviewAttachmentWorkerOptions) {\n  if (options.queueOwnership !== \"exclusive-review-attachments\") {\n    throw new Error(\"Attachment worker requires an exclusively owned Workflow queue\");\n  }\n  const { store } = await createReviewAttachmentAdapters(options);\n  const { workflows, workerId } = options;\n  const failure = Promise.withResolvers<never>();\n  // The executable attaches its fatal listener after this async factory returns.\n  void failure.promise.catch(() => {});\n  let halted: boolean = false;\n  const fatal = () => {\n    halted = true;\n    failure.reject(new Error(\"Attachment worker requires recovery\"));\n  };\n  const attempt = (claim: SupaCloudWorkflowClaim) => ({\n    stepId: claim.stepId, messageId: claim.messageId, attempt: claim.attempt, workerId: claim.workerId,\n  });\n  async function ownedClaim(claim: SupaCloudWorkflowClaim) {\n    if (claim.workflowName !== \"review.verify-attachment\" || claim.workflowVersion !== \"1\"\n      || claim.stepKey !== \"verify\" || claim.maxAttempts !== 3 || claim.workerId !== workerId) {\n      throw new Error(\"Unsupported attachment workflow\");\n    }\n    const { reviewId, artifactId } = claim.input;\n    if (typeof reviewId !== \"string\" || typeof artifactId !== \"string\") {\n      throw new Error(\"Invalid attachment workflow input\");\n    }\n    const bound = await options.database.transaction(tx => tx.query(\n      \"SELECT run_id FROM public.starter_attachments WHERE review_id=$1 AND artifact_id=$2 AND run_id=$3\",\n      [reviewId, artifactId, claim.runId],\n    ));\n    if (!Array.isArray(bound) || bound.length !== 1) throw new Error(\"Attachment workflow ownership mismatch\");\n  }\n  const worker = createWorker({\n    modules: options.modules, deps: { dbClient: store }, workerId, concurrency: 1,\n    pollIntervalMs: options.pollIntervalMs ?? 1000,\n    onError: fatal,\n    transport: {\n      async claim(signal): Promise<SupaCloudWorkflowClaim | null> {\n        if (halted || signal.aborted) return null;\n        try {\n          const claim = await workflows.claim({ workerId, visibilityTimeoutSeconds: 120 });\n          if (signal.aborted || halted) return null;\n          if (!claim || claim.status !== \"claimed\") return null;\n          await ownedClaim(claim);\n          return claim;\n        } catch {\n          if (!signal.aborted) fatal();\n          throw new Error(\"Attachment workflow claim failed\");\n        }\n      },\n      async ack(claim, output) {\n        try {\n          if (!output || typeof output !== \"object\" || Array.isArray(output)) throw new Error(\"Invalid Job output\");\n          // The compiled Job validates output; Workflow SDK validates the receipt.\n          await workflows.complete({ ...attempt(claim), runOutput: { ...output } });\n        } catch {\n          fatal();\n          throw new Error(\"Attachment workflow completion is unconfirmed\");\n        }\n      },\n      async fail(claim) {\n        try {\n          const request: Parameters<typeof workflows.fail>[0] = { ...attempt(claim), errorMessage: \"Attachment verification failed\" };\n          if (claim.attempt < claim.maxAttempts) await workflows.retry({ ...request, delaySeconds: 5 });\n          else await workflows.fail(request);\n        } catch {\n          fatal();\n          throw new Error(\"Attachment workflow failure receipt is unconfirmed\");\n        }\n      },\n    },\n    mapClaim: (claim: SupaCloudWorkflowClaim) => ({\n      id: claim.stepId, jobName: claim.workflowName, input: claim.input, attempt: claim.attempt,\n      requestContext: { workerId, jobId: claim.stepId, requestId: claim.runId },\n    }),\n  });\n  if (worker.jobNames.length !== 1 || worker.jobNames[0] !== \"review.verify-attachment\") {\n    throw new Error(\"Attachment worker requires its compiled reference Job\");\n  }\n  let closing: Promise<void> | undefined;\n  return {\n    failure: failure.promise,\n    async start() {\n      if (halted) throw new Error(\"Attachment worker is not startable\");\n      await worker.start();\n    },\n    close() {\n      halted = true;\n      return closing ??= worker.stop();\n    },\n  };\n}\n";
+export declare const STARTER_ATTACHMENT_DELIVERY_WORKER = "import { SQL } from \"bun\";\nimport { createClient } from \"@supabase/supabase-js\";\nimport { SupaCloudWorkflowsClient } from \"@supacloud/js\";\nimport { createBunCommandDatabase } from \"@supacloud/db/bun\";\nimport type { CompiledModule } from \"@supacloud/elysia\";\nimport { createReviewAttachmentWorker } from \"./host/review-attachment-worker\";\n\nfunction required(name: string): string {\n  const value = process.env[name];\n  if (!value?.trim()) throw new Error(\"Missing required worker setting: \" + name);\n  return value;\n}\n\nfunction databaseConnection(): SQL.Options {\n  const socket = process.env[\"DATABASE_SOCKET_PATH\"];\n  if (socket && process.env[\"DATABASE_URL\"]) throw new Error(\"Conflicting database connection settings\");\n  if (socket) {\n    return { adapter: \"postgres\", path: socket, database: required(\"DATABASE_NAME\"), username: required(\"DATABASE_USER\") };\n  }\n  const url = new URL(required(\"DATABASE_URL\"));\n  if (url.protocol !== \"postgres:\" && url.protocol !== \"postgresql:\") throw new Error(\"Invalid database URL\");\n  return {\n    adapter: \"postgres\", url: url.href, hostname: url.hostname.replace(/^\\[|\\]$/g, \"\"), port: Number(url.port || 5432),\n    username: decodeURIComponent(url.username), password: decodeURIComponent(url.password),\n    database: decodeURIComponent(url.pathname.slice(1)),\n  };\n}\n\nexport async function createDeliveryWorker(modules: CompiledModule[], lifecycle: { signal: AbortSignal }) {\n  lifecycle.signal.throwIfAborted();\n  if (required(\"REVIEW_QUEUE_OWNERSHIP\") !== \"exclusive-review-attachments\") {\n    throw new Error(\"Attachment worker requires an exclusively owned Workflow queue\");\n  }\n  const connection = databaseConnection();\n  const settings = {\n    projectId: required(\"SUPACLOUD_PROJECT_ID\"), tenantId: required(\"APP_TENANT_ID\"),\n    workerId: required(\"REVIEW_WORKER_ID\"), url: required(\"SUPACLOUD_URL\"), key: required(\"SUPACLOUD_SERVICE_ROLE_KEY\"),\n  };\n  const service = createClient(settings.url, settings.key, {\n    auth: { persistSession: false, autoRefreshToken: false, detectSessionInUrl: false },\n  });\n  const pool = new SQL({ ...connection, max: 4, connectionTimeout: 5 });\n  let closing: Promise<void> | undefined;\n  const closePool = () => closing ??= pool.close({ timeout: 5 });\n  try {\n    const worker = await createReviewAttachmentWorker({\n      database: createBunCommandDatabase(pool), service, projectId: settings.projectId,\n      tenantId: settings.tenantId, modules, workerId: settings.workerId,\n      workflows: new SupaCloudWorkflowsClient(service), queueOwnership: \"exclusive-review-attachments\",\n    });\n    lifecycle.signal.throwIfAborted();\n    return {\n      start: () => worker.start(), failure: worker.failure,\n      async close() { try { await worker.close(); } finally { await closePool(); } },\n    };\n  } catch (error) {\n    await closePool();\n    const code = error !== null && typeof error === \"object\" && \"code\" in error\n      && typeof error.code === \"string\" && /^[A-Z0-9_]{1,64}$/.test(error.code) ? error.code : \"UNKNOWN\";\n    console.error(JSON.stringify({ event: \"review-worker-initialization-failed\", code }));\n    throw new Error(\"Attachment worker initialization failed\");\n  }\n}\n";

package/dist/shared/tools/app-starter-attachments.d.ts

@@ -0,0 +1,2 @@
+export declare const STARTER_ATTACHMENT_SCHEMA = "-- Apply with the migration owner, never from an application process.\nCREATE TABLE public.starter_attachments (\n  review_id text PRIMARY KEY REFERENCES public.starter_reviews(id),\n  artifact_id uuid NOT NULL UNIQUE, owner_id text NOT NULL, run_id uuid NOT NULL UNIQUE,\n  object_path text NOT NULL UNIQUE\n);\nCREATE TABLE public.starter_attachment_results (\n  review_id text NOT NULL REFERENCES public.starter_reviews(id),\n  version integer NOT NULL CHECK (version >= 2), artifact_id uuid NOT NULL,\n  result jsonb NOT NULL, PRIMARY KEY(review_id,version,artifact_id)\n);\nALTER TABLE public.starter_attachments ENABLE ROW LEVEL SECURITY;\nALTER TABLE public.starter_attachment_results ENABLE ROW LEVEL SECURITY;\n";
+export declare const STARTER_ATTACHMENT_POSTGRES = "import { SupaCloudArtifactsClient } from \"@supacloud/js\";\nimport type { SupabaseClient } from \"@supabase/supabase-js\";\nimport type { CommandDatabase, CommandTransaction } from \"@supacloud/db\";\nimport type { ReviewAttachmentInput, ReviewAttachmentResult, ReviewAttachmentStore } from \"../review/attachment\";\n\nexport interface ReviewAttachmentOptions {\n  database: CommandDatabase;\n  // Provision this client for the same project as the database; never use a caller's bearer token.\n  service: SupabaseClient;\n  projectId: string;\n  tenantId: string;\n}\n\nfunction rows(value: unknown): Record<string, unknown>[] {\n  if (!Array.isArray(value)) throw new TypeError(\"Invalid attachment database result\");\n  return value.map(record);\n}\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return value !== null && typeof value === \"object\" && !Array.isArray(value);\n}\nfunction record(value: unknown): Record<string, unknown> {\n  if (!isRecord(value)) throw new TypeError(\"Invalid attachment record\");\n  return value;\n}\nfunction durableResult(value: unknown): ReviewAttachmentResult {\n  const item = record(value);\n  if (typeof item[\"reviewId\"] !== \"string\" || typeof item[\"artifactId\"] !== \"string\"\n    || typeof item[\"version\"] !== \"number\" || typeof item[\"sha256\"] !== \"string\"\n    || typeof item[\"bytes\"] !== \"number\" || Object.keys(item).length !== 5) {\n    throw new Error(\"Invalid durable attachment result\");\n  }\n  return { reviewId: item[\"reviewId\"], artifactId: item[\"artifactId\"], version: item[\"version\"], sha256: item[\"sha256\"], bytes: item[\"bytes\"] };\n}\n\nexport async function createReviewAttachmentAdapters(options: ReviewAttachmentOptions): Promise<{\n  store: ReviewAttachmentStore;\n  enqueue(tx: CommandTransaction, reviewId: string, version: number): Promise<void>;\n}> {\n  const { database, service, projectId, tenantId } = options;\n  if (!projectId.trim() || !tenantId.trim()) throw new TypeError(\"Attachment project/tenant is required\");\n  const artifacts = new SupaCloudArtifactsClient(service);\n  const binding = rows(await database.transaction(tx => tx.query(\n    \"SELECT project_id,tenant_id FROM public.starter_application WHERE singleton\",\n  )));\n  if (binding.length !== 1 || binding[0]?.[\"project_id\"] !== projectId || binding[0]?.[\"tenant_id\"] !== tenantId) {\n    throw new Error(\"Attachment database project/tenant binding mismatch\");\n  }\n  async function authorize(tx: CommandTransaction, input: ReviewAttachmentInput) {\n    const allowed = rows(await tx.query(\n      \"SELECT a.object_path,a.run_id FROM public.starter_attachments a \" +\n      \"JOIN public.starter_reviews r ON r.id=a.review_id AND r.owner_id=a.owner_id \" +\n      \"JOIN public.starter_members m ON m.subject=a.owner_id AND m.enabled AND m.can_approve \" +\n      \"CROSS JOIN public.starter_application p \" +\n      \"WHERE a.review_id=$1 AND a.artifact_id=$2 AND r.version=$3 AND r.state='approved' \" +\n      \"AND p.singleton AND p.project_id=$4 AND p.tenant_id=$5 \" +\n      \"FOR UPDATE OF r,a,m FOR SHARE OF p\",\n      [input.reviewId, input.artifactId, input.version, projectId, tenantId],\n    ));\n    if (allowed.length !== 1 || typeof allowed[0]?.[\"object_path\"] !== \"string\") {\n      throw new Error(\"Attachment worker authorization or review revision is no longer valid\");\n    }\n    return allowed[0];\n  }\n  return {\n    async enqueue(tx, reviewId, version) {\n      const found = rows(await tx.query(\n        \"SELECT artifact_id FROM public.starter_attachments WHERE review_id=$1\", [reviewId],\n      ))[0];\n      if (!found) return;\n      const input = { reviewId, version, artifactId: String(found[\"artifact_id\"]) };\n      const allowed = await authorize(tx, input);\n      // Bind serialized JSON as text so drivers cannot encode the string as a JSON scalar.\n      await tx.query(\"SELECT supacloud_workflows.start_run($1::uuid,$2,'1','verify',$3::text::jsonb,3)\", [\n        String(allowed[\"run_id\"]), \"review.verify-attachment\", JSON.stringify(input),\n      ]);\n    },\n    store: {\n      async readAttachment(input) {\n        const allowed = await database.transaction(tx => authorize(tx, input));\n        const artifact = await artifacts.get(input.artifactId);\n        if (!artifact || artifact.bucketId !== \"review-attachments\"\n          || artifact.objectPath !== allowed[\"object_path\"] || artifact.artifactType !== \"review.attachment\"\n          || artifact.mimeType !== \"text/plain\" || !/^[1-9][0-9]*$/.test(artifact.sizeBytes)\n          || BigInt(artifact.sizeBytes) > 1048576n) throw new Error(\"Invalid attachment artifact\");\n        const downloaded = await service.storage.from(artifact.bucketId).download(artifact.objectPath);\n        if (downloaded.error || !downloaded.data) throw new Error(\"Attachment download failed\");\n        if (downloaded.data.size !== Number(artifact.sizeBytes)) throw new Error(\"Attachment size mismatch\");\n        return { body: new Uint8Array(await downloaded.data.arrayBuffer()), sha256: artifact.sha256 };\n      },\n      async recordAttachment(input, result) {\n        if (result.reviewId !== input.reviewId || result.version !== input.version\n          || result.artifactId !== input.artifactId || !/^[a-f0-9]{64}$/.test(result.sha256)\n          || !Number.isSafeInteger(result.bytes) || result.bytes < 1 || result.bytes > 1048576) {\n          throw new Error(\"Invalid attachment result\");\n        }\n        return database.transaction(async tx => {\n          await authorize(tx, input);\n          await tx.query(\n            \"INSERT INTO public.starter_attachment_results VALUES($1,$2,$3,$4::text::jsonb) ON CONFLICT DO NOTHING\",\n            [input.reviewId, input.version, input.artifactId, JSON.stringify(result)],\n          );\n          const saved = rows(await tx.query(\n            \"SELECT result FROM public.starter_attachment_results WHERE review_id=$1 AND version=$2 AND artifact_id=$3\",\n            [input.reviewId, input.version, input.artifactId],\n          ))[0]?.[\"result\"];\n          const value = durableResult(saved);\n          if (value.reviewId !== result.reviewId || value.version !== result.version || value.artifactId !== result.artifactId\n            || value.sha256 !== result.sha256 || value.bytes !== result.bytes) {\n            throw new Error(\"Conflicting durable attachment result\");\n          }\n          return value;\n        });\n      },\n    },\n  };\n}\n";

package/dist/shared/tools/app-starter-composition.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/tools/app-starter-database.d.ts

@@ -0,0 +1,14 @@
+export declare const STARTER_DATABASE_CONFIG: {
+    version: number;
+    schema: string[];
+    functions: string;
+    migrations: string;
+    contracts: string;
+    audit: string;
+    consumers: string[];
+    auditConsumers: never[];
+    role: string;
+};
+export declare const STARTER_DATABASE_SCHEMA = "import { sql } from \"drizzle-orm\";\nimport { boolean, check, integer, jsonb, pgTable, primaryKey, text, uuid } from \"drizzle-orm/pg-core\";\n\n// Structure for the reviewed starter migrations. Grants/policies stay in those migrations.\nexport const application = pgTable.withRLS(\"starter_application\", {\n  singleton: boolean().default(true).primaryKey(),\n  projectId: text(\"project_id\").notNull(),\n  tenantId: text(\"tenant_id\").notNull(),\n}, table => [\n  check(\"starter_application_singleton_check\", sql`${table.singleton}`),\n  check(\"starter_application_project_id_check\", sql`length(${table.projectId}) > 0`),\n  check(\"starter_application_tenant_id_check\", sql`length(${table.tenantId}) > 0`),\n]);\n\nexport const reviews = pgTable.withRLS(\"starter_reviews\", {\n  id: text().primaryKey(),\n  ownerId: text(\"owner_id\").notNull(),\n  state: text({ enum: [\"draft\", \"approved\"] }).notNull(),\n  version: integer().notNull(),\n}, table => [\n  check(\"starter_reviews_state_check\", sql`${table.state} IN ('draft', 'approved')`),\n  check(\"starter_reviews_version_check\", sql`${table.version} > 0`),\n]);\n\nexport const members = pgTable.withRLS(\"starter_members\", {\n  subject: text().primaryKey(),\n  enabled: boolean().default(true).notNull(),\n  canApprove: boolean(\"can_approve\").default(false).notNull(),\n  storageSubject: uuid(\"storage_subject\").unique(),\n});\n\nexport const attachments = pgTable.withRLS(\"starter_attachments\", {\n  reviewId: text(\"review_id\").primaryKey().references(() => reviews.id),\n  artifactId: uuid(\"artifact_id\").notNull().unique(),\n  ownerId: text(\"owner_id\").notNull(),\n  runId: uuid(\"run_id\").notNull().unique(),\n  objectPath: text(\"object_path\").notNull().unique(),\n});\n\nexport const attachmentResults = pgTable.withRLS(\"starter_attachment_results\", {\n  reviewId: text(\"review_id\").notNull().references(() => reviews.id),\n  version: integer().notNull(),\n  artifactId: uuid(\"artifact_id\").notNull(),\n  result: jsonb().$type<unknown>().notNull(),\n}, table => [\n  primaryKey({ columns: [table.reviewId, table.version, table.artifactId] }),\n  check(\"starter_attachment_results_version_check\", sql`${table.version} >= 2`),\n]);\n\nexport type ReviewRow = typeof reviews.$inferSelect;\nexport type NewReview = typeof reviews.$inferInsert;\n";
+export declare const STARTER_DATABASE_GUIDE = "\n## Database Source Workflow\n\nDrizzle owns table declarations and inferred row types in db/schema.ts.\nUse the existing @supacloud/db/drizzle-bun adapters for typed queries and governed\ntransactions; never replace permission, idempotency or audit checks with plain CRUD.\nOpaque JSON still needs runtime decoding.\n\nAfter installing dependencies, run `bun run db:generate` once and commit db/contracts/.\nThe default `bun run check` and build fail on stale database contracts before any\ncompiler regeneration. After an intentional source change, run db:generate again,\nreview the diff, then run check. Ordinary checks are offline.\n\n- Maintain one schema-qualified function with explicit grants per db/functions/*.sql.\n- Preserve migrations/ and its existing executor/ledger. Add forward migrations only.\n- `bun run db:diff` generates Drizzle drafts under db/migration-candidates/, never\n  into the deployment directory. The starter has existing SQL history, so establish\n  and review a matching Drizzle baseline before promoting any draft; the first\n  draft is not automatically an incremental production migration.\n- `bun run db:pull` requires an explicitly selected DATABASE_URL and writes only\n  output/database-audit/drizzle-candidate/. Review candidates; never overwrite source blindly.\n- Full SQL dumps belong under the ignored output/database-audit/ directory. They are\n  audit/recovery artifacts, never ordinary type, application or test inputs.\n- `bun run db:assess` explains adoption/findings without writing or connecting.\n- GraphQL/PostgREST exports remain legitimate protocol contracts. This check is not\n  proof of deployed schema, effective role permissions or complete RLS equivalence.\n\nDo not introduce any/@ts-ignore to bypass a contract. Use Drizzle-inferred types,\npreserve bigint/numeric precision and decode unknown results at the boundary.\n";
+export declare function starterDatabaseFiles(): Record<string, string>;

package/dist/shared/tools/app-starter-environment.d.ts

@@ -0,0 +1,2 @@
+export declare const STARTER_ENVIRONMENT: string;
+export declare const STARTER_ENVIRONMENT_TEST: string;

package/dist/shared/tools/app-starter-postgres.d.ts

@@ -0,0 +1,4 @@
+export declare const STARTER_REVIEW_SCHEMA = "-- Apply with the platform migration owner, never from the HTTP process.\n-- One application database belongs to one explicitly provisioned project/tenant.\nCREATE TABLE public.starter_application (\n  singleton boolean PRIMARY KEY DEFAULT true CHECK (singleton),\n  project_id text NOT NULL CHECK (length(project_id) > 0),\n  tenant_id text NOT NULL CHECK (length(tenant_id) > 0)\n);\nCREATE TABLE public.starter_reviews (\n  id text PRIMARY KEY, owner_id text NOT NULL,\n  state text NOT NULL CHECK (state IN ('draft','approved')),\n  version integer NOT NULL CHECK (version > 0)\n);\nCREATE TABLE public.starter_members (\n  subject text PRIMARY KEY, enabled boolean NOT NULL DEFAULT true,\n  can_approve boolean NOT NULL DEFAULT false\n);\nALTER TABLE public.starter_application ENABLE ROW LEVEL SECURITY;\nALTER TABLE public.starter_reviews ENABLE ROW LEVEL SECURITY;\nALTER TABLE public.starter_members ENABLE ROW LEVEL SECURITY;\n";
+export declare const STARTER_REVIEW_POSTGRES = "import { AsyncLocalStorage } from \"node:async_hooks\";\nimport { createTransactionalCommand, plaintextCommandInput } from \"@supacloud/commands\";\nimport { CommandError } from \"@supacloud/contracts\";\nimport { createPostgresCommandStore, type CommandDatabase, type CommandTransaction } from \"@supacloud/db\";\nimport {\n  ApplicationError, createSupAuthRequestContext, requireTrustedIdentity, requireIdempotencyKey,\n  type CommandInvocation, type SupAuthContextOptions,\n} from \"@supacloud/elysia\";\nimport type { AppAdapters } from \"../application\";\nimport type { ReviewStore } from \"../review/review\";\nimport type { ReviewUploadPort } from \"../review/uploads\";\n\ninterface Approval { id: string; expectedVersion: number }\ninterface Review { state: \"draft\" | \"approved\"; version: number }\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return value !== null && typeof value === \"object\" && !Array.isArray(value);\n}\nfunction record(value: unknown): Record<string, unknown> {\n  if (!isRecord(value)) throw new TypeError(\"Invalid review record\");\n  return value;\n}\nfunction rows(value: unknown): Record<string, unknown>[] {\n  if (!Array.isArray(value)) throw new TypeError(\"Invalid database result\");\n  return value.map(record);\n}\nfunction isPublicConflict(value: unknown): boolean {\n  return value instanceof ApplicationError && value.status === 409\n    || isRecord(value) && value[\"expose\"] === true && value[\"status\"] === 409 && typeof value[\"code\"] === \"string\";\n}\nfunction input(value: unknown): Approval {\n  const item = record(value);\n  if (typeof item[\"id\"] !== \"string\" || !item[\"id\"].length || typeof item[\"expectedVersion\"] !== \"number\"\n    || !Number.isSafeInteger(item[\"expectedVersion\"]) || item[\"expectedVersion\"] < 1) throw new TypeError(\"Invalid approval input\");\n  return { id: item[\"id\"], expectedVersion: item[\"expectedVersion\"] };\n}\nfunction result(value: unknown): Review {\n  const item = record(value);\n  if ((item[\"state\"] !== \"draft\" && item[\"state\"] !== \"approved\") || typeof item[\"version\"] !== \"number\"\n    || !Number.isSafeInteger(item[\"version\"]) || item[\"version\"] < 1) throw new TypeError(\"Invalid review result\");\n  return { state: item[\"state\"], version: item[\"version\"] };\n}\n\nexport interface ReviewPostgresOptions {\n  database: CommandDatabase;\n  tenantId: string;\n  identity: Omit<SupAuthContextOptions, \"resolveAccess\">;\n  uploads?: ReviewUploadPort;\n  // Only database effects here: they commit/rollback with the approval and receipt.\n  afterApproved?(tx: CommandTransaction, id: string, version: number): Promise<void>;\n}\n\nexport async function createReviewPostgresAdapters(options: ReviewPostgresOptions): Promise<\n  AppAdapters & { requestContext: ReturnType<typeof createSupAuthRequestContext> }\n> {\n  const { database, tenantId, identity } = options;\n  const projectId = identity.projectId;\n  const afterApproved = options.afterApproved;\n  if (!tenantId.trim()) throw new TypeError(\"Review tenantId is required\");\n  const query = (text: string, parameters: readonly string[] = []) =>\n    database.transaction(tx => tx.query(text, parameters));\n  const binding = rows(await query(\n    \"SELECT project_id,tenant_id FROM public.starter_application WHERE singleton\",\n  ));\n  if (binding.length !== 1 || binding[0]?.[\"project_id\"] !== projectId || binding[0]?.[\"tenant_id\"] !== tenantId) {\n    throw new Error(\"Review database project/tenant binding mismatch\");\n  }\n  const requestContext = createSupAuthRequestContext({\n    ...identity,\n    async resolveAccess(who) {\n      const found = rows(await query(\n        \"SELECT m.can_approve FROM public.starter_members m,public.starter_application a \" +\n        \"WHERE m.subject=$1 AND m.enabled AND a.singleton AND a.project_id=$2 AND a.tenant_id=$3\",\n        [who.subject, projectId, tenantId],\n      ));\n      return found.length === 1 ? { projectId, tenantId,\n        permissions: found[0]?.[\"can_approve\"] === true ? [\"review.approve\"] : [],\n      } : null;\n    },\n  });\n  const scope = new AsyncLocalStorage<CommandTransaction>();\n  const transaction = () => {\n    const tx = scope.getStore();\n    if (!tx) throw new Error(\"Review storage requires its durable command transaction\");\n    return tx;\n  };\n  const store: ReviewStore = {\n    ...options.uploads,\n    async get(table, id) {\n      if (table !== \"reviews\") throw new Error(\"Unsupported review table\");\n      return rows(await transaction().query(\n        \"SELECT state,version FROM public.starter_reviews WHERE id=$1 FOR UPDATE\", [id],\n      ))[0];\n    },\n    async set(table, id, value) {\n      if (table !== \"reviews\") throw new Error(\"Unsupported review table\");\n      const review = result(value);\n      const updated = rows(await transaction().query(\n        \"UPDATE public.starter_reviews SET state=$2,version=$3 WHERE id=$1 RETURNING id\",\n        [id, review.state, review.version],\n      ));\n      if (updated.length !== 1) throw new Error(\"Review write did not update one record\");\n      await afterApproved?.(transaction(), id, review.version);\n    },\n  };\n  function actor(invocation: CommandInvocation): string {\n    const who = requireTrustedIdentity(invocation.requestContext);\n    const access = record(record(invocation.requestContext)[\"access\"]);\n    if (access[\"projectId\"] !== projectId || access[\"tenantId\"] !== tenantId\n      || !Array.isArray(access[\"permissions\"]) || !access[\"permissions\"].includes(\"review.approve\")) {\n      throw new ApplicationError(\"Command permission denied\", { status: 403, code: \"REVIEW_PERMISSION_DENIED\" });\n    }\n    return who.subject;\n  }\n  const commandStore = createPostgresCommandStore(database);\n  return {\n    deps: { dbClient: store }, requestContext,\n    commandGovernance: {\n      authorize(invocation) {\n        const command = invocation.command;\n        if (command.name !== \"review.approve\" || command.permission !== \"review.approve\"\n          || command.transaction !== \"required\" || command.idempotency !== \"required\"\n          || command.audit !== \"review.approved\" || command.rpc !== undefined) {\n          throw new ApplicationError(\"Unsupported review command\", { status: 501, code: \"REVIEW_COMMAND_UNSUPPORTED\" });\n        }\n        actor(invocation);\n      },\n      async idempotency(invocation, next) {\n        const command = createTransactionalCommand({\n          name: invocation.command.name, store: commandStore,\n          inputCodec: plaintextCommandInput, input, result,\n          async authorize(who, request, tx) {\n            const found = rows(await tx.query(\n              \"SELECT r.id FROM public.starter_reviews r JOIN public.starter_members m ON m.subject=r.owner_id \" +\n              \"CROSS JOIN public.starter_application a \" +\n              \"WHERE r.id=$1 AND r.owner_id=$2 AND m.enabled AND m.can_approve \" +\n              \"AND a.singleton AND a.project_id=$3 AND a.tenant_id=$4 FOR UPDATE OF r,m FOR SHARE OF a\",\n              [request.id, who.actorId, projectId, who.tenantId],\n            ));\n            return found.length === 1 ? \"allow\" : \"deny\";\n          },\n          execute: tx => scope.run(tx, async () => {\n            try { return await next(); }\n            catch (error) {\n              if (isPublicConflict(error)) {\n                throw new CommandError(\"COMMAND_IDEMPOTENCY_CONFLICT\");\n              }\n              throw error;\n            }\n          }),\n          audit: { event: \"review.approved\", details: request => ({ reviewId: request.id }) },\n        });\n        try {\n          const receipt = await command.execute(\n            { actorId: actor(invocation), tenantId }, requireIdempotencyKey(invocation),\n            { id: invocation.input.params[\"id\"], expectedVersion: record(invocation.input.body)[\"expectedVersion\"] },\n            invocation.request.signal,\n          );\n          if (receipt.status !== \"confirmed\") throw new CommandError(\"COMMAND_OUTCOME_UNKNOWN\");\n          return receipt.result;\n        } catch (error) {\n          if (!(error instanceof CommandError)) throw error;\n          const status = error.code === \"COMMAND_REJECTED\" ? 403\n            : error.code === \"COMMAND_IDEMPOTENCY_CONFLICT\" ? 409 : 503;\n          throw new ApplicationError(error.code, { code: error.code, status });\n        }\n      },\n      transaction(_invocation, next) { transaction(); return next(); },\n      // The durable command owns the authoritative audit and receipt in the same transaction.\n      audit: { succeeded() { transaction(); }, failed() {} },\n    },\n  };\n}\n";
+export declare const STARTER_REVIEW_POSTGRES_TEST = "import { expect, test } from \"bun:test\";\nimport { createReviewPostgresAdapters } from \"../src/host/review-postgres\";\nimport type { ReviewStore } from \"../src/review/review\";\n\nconst identity = {\n  issuer: \"https://identity.example.test\", audience: \"review-test\", clientId: \"review-client\",\n  projectId: \"review-test\", jwksUrl: \"https://identity.example.test/jwks\",\n};\nfunction database(binding: unknown) {\n  const queries: string[] = [];\n  return {\n    queries,\n    async transaction<T>(run: (tx: { query(text: string): Promise<unknown> }) => Promise<T>): Promise<T> {\n      return run({ async query(text) { queries.push(text); return binding; } });\n    },\n  };\n}\n\ntest(\"PostgreSQL host rejects missing or mismatched application ownership without creating data\", async () => {\n  for (const binding of [[], [{ project_id: \"other\", tenant_id: \"review-test\" }],\n    [{ project_id: \"review-test\", tenant_id: \"other\" }]]) {\n    const db = database(binding);\n    await expect(createReviewPostgresAdapters({ database: db, identity, tenantId: \"review-test\" }))\n      .rejects.toThrow(\"binding mismatch\");\n    expect(db.queries).toEqual([\"SELECT project_id,tenant_id FROM public.starter_application WHERE singleton\"]);\n  }\n});\n\ntest(\"PostgreSQL host never falls back to demo identity or unbound business storage\", async () => {\n  const db = database([{ project_id: \"review-test\", tenant_id: \"review-test\" }]);\n  const adapters = await createReviewPostgresAdapters({ database: db, identity, tenantId: \"review-test\" });\n  await expect(adapters.requestContext(new Request(\"http://localhost/reviews/health\")))\n    .rejects.toMatchObject({ code: \"AUTHENTICATION_REQUIRED\" });\n  const store = adapters.deps[\"dbClient\"] as ReviewStore;\n  await expect(store.get(\"reviews\", \"example\")).rejects.toThrow(\"durable command transaction\");\n  await expect(store.set(\"reviews\", \"example\", { state: \"approved\", version: 2 }))\n    .rejects.toThrow(\"durable command transaction\");\n  expect(db.queries).toHaveLength(1);\n});\n";
+export declare const STARTER_REVIEW_DELIVERY_HOST = "import { SQL } from \"bun\";\nimport { createClient } from \"@supabase/supabase-js\";\nimport { createBunCommandDatabase } from \"@supacloud/db/bun\";\nimport { createApplication, type CompiledModule } from \"@supacloud/elysia\";\nimport { createReviewPostgresAdapters } from \"./host/review-postgres\";\nimport { createReviewAttachmentAdapters } from \"./host/review-attachments\";\nimport { createReviewUploadAdapters } from \"./host/review-uploads\";\n\nfunction required(name: string): string {\n  const value = process.env[name];\n  if (!value?.trim()) throw new Error(\"Missing required host setting: \" + name);\n  return value;\n}\n\nfunction databaseConnection(): SQL.Options {\n  const socket = process.env[\"DATABASE_SOCKET_PATH\"];\n  if (socket && process.env[\"DATABASE_URL\"]) throw new Error(\"Conflicting database connection settings\");\n  if (socket) {\n    return { adapter: \"postgres\", path: socket, database: required(\"DATABASE_NAME\"), username: required(\"DATABASE_USER\") };\n  }\n  const url = new URL(required(\"DATABASE_URL\"));\n  if (url.protocol !== \"postgres:\" && url.protocol !== \"postgresql:\") throw new Error(\"Invalid database URL\");\n  return {\n    adapter: \"postgres\", url: url.href, hostname: url.hostname.replace(/^\\[|\\]$/g, \"\"), port: Number(url.port || 5432),\n    username: decodeURIComponent(url.username), password: decodeURIComponent(url.password),\n    database: decodeURIComponent(url.pathname.slice(1)),\n  };\n}\n\nexport async function createDeliveryApplication(modules: CompiledModule[], lifecycle: { signal: AbortSignal }) {\n  lifecycle.signal.throwIfAborted();\n  const connection = databaseConnection();\n  const attachments = process.env[\"REVIEW_ATTACHMENTS\"];\n  if (attachments !== undefined && attachments !== \"enabled\") throw new Error(\"Invalid attachment configuration\");\n  const settings = {\n    tenantId: required(\"APP_TENANT_ID\"),\n    identity: {\n      issuer: required(\"SUPAUTH_ISSUER\"), audience: required(\"SUPAUTH_AUDIENCE\"),\n      clientId: required(\"SUPAUTH_CLIENT_ID\"), projectId: required(\"SUPACLOUD_PROJECT_ID\"),\n      jwksUrl: required(\"SUPAUTH_JWKS_URL\"),\n    },\n  };\n  const pool = new SQL({ ...connection, max: 12, connectionTimeout: 5 });\n  let closing: Promise<void> | undefined;\n  const close = () => closing ??= pool.close({ timeout: 5 });\n  let stage: \"attachments\" | \"uploads\" | \"postgres\" | \"application\" = \"attachments\";\n  try {\n    const database = createBunCommandDatabase(pool);\n    const attachmentOptions = attachments === \"enabled\" ? {\n      database, tenantId: settings.tenantId, projectId: settings.identity.projectId,\n      service: createClient(required(\"SUPACLOUD_URL\"), required(\"SUPACLOUD_SERVICE_ROLE_KEY\"), {\n        auth: { persistSession: false, autoRefreshToken: false, detectSessionInUrl: false },\n      }),\n    } : undefined;\n    const durable = attachmentOptions ? await createReviewAttachmentAdapters(attachmentOptions) : undefined;\n    stage = \"uploads\";\n    const uploads = attachmentOptions ? await createReviewUploadAdapters(attachmentOptions) : undefined;\n    stage = \"postgres\";\n    const adapters = await createReviewPostgresAdapters({\n      database, tenantId: settings.tenantId, identity: settings.identity,\n      ...(uploads ? { uploads } : {}),\n      ...(durable ? { afterApproved: durable.enqueue } : {}),\n    });\n    lifecycle.signal.throwIfAborted();\n    stage = \"application\";\n    const app = createApplication({ name: \"review\", modules, ...adapters });\n    return { fetch: (request: Request) => app.handle(request), close };\n  } catch (error) {\n    await close();\n    const code = error !== null && typeof error === \"object\" && \"code\" in error\n      && typeof error.code === \"string\" && /^[A-Z0-9_]{1,64}$/.test(error.code) ? error.code : \"UNKNOWN\";\n    console.error(JSON.stringify({ event: \"review-host-initialization-failed\", stage, code }));\n    // Database/identity errors can contain connection details; never echo the underlying cause.\n    throw new Error(\"Review host initialization failed\");\n  }\n}\n";

package/dist/shared/tools/app-starter-reactive.d.ts

@@ -0,0 +1,4 @@
+/** Shared reactive conventions for command, HTTP and edge starters. */
+export declare const STARTER_REACTIVE_GUIDE = "# Reactive development / \u54CD\u5E94\u5F0F\u5F00\u53D1\n\nRxJS is installed by default. Ordinary queries and business commands still use\nasync/await. Use RxJS for ongoing events and timing/composition, not as a new\ntransaction, retry or durable-delivery system.\n\nHost defaults:\n- In a native Angular host, use signal/resource APIs from @supacloud/app/angular\n  and Angular's scheduler. Do not mix them with the legacy root signal graph.\n- In framework-neutral code, use async/await for one result and RxJS for event\n  composition. The host owns cancellation through an explicit signal.\n\n- Import native operators from rxjs; do not invent another event/operator library.\n- Import takeUntilAborted / toReadableStream from @supacloud/app/reactive.\n- Every subscription belongs to a request, connection, task or application owner.\n  Bind the owner's AbortSignal before starting work; release it on exit.\n- toReadableStream has a bounded item buffer and fails on overflow. It is not\n  an event journal. Do not silently drop durable business events or audit records.\n- Never wrap command submission in defer/retry/repeat or submit from subscribe.\n  Await the existing governed command and then observe its existing receipt.\n- Do not shareReplay authenticated values globally across projects or sessions.\n- subscribe(async ...) does not await processing. Keep acknowledged task-output\n  consumers on the SDK's for-await watch path; do not advance onCursor via next().\n\n## SupaCloud JS\n\nThe platform SDK is @supacloud/js, not a replacement Supabase client. Keep the\nclient from createSupaCloudClient. Database/Auth/Storage calls use client.supabase;\nplatform commands/tasks use the existing client.commands / client.tasks APIs.\nFor applications using this SDK, import observeQuery and observeTask from\n@supacloud/js/reactive. Pass the request signal to the native query builder:\n\n    observeQuery(signal => client.supabase.from(\"widgets\").select(\"id\").abortSignal(signal), { signal: owner.signal })\n\nThe query result keeps data/error/count/status; non-null errors enter error().\nThe query factory runs once per subscriber. This is intended for reads, not\nreplaying writes. A PromiseLike is supported; an already-started Promise is not\nan appropriate factory. Unsubscribe aborts cooperative I/O, not committed work.\n\nSubmit a background task ONCE with the existing SDK, then observe the receipt:\n\n    const task = await client.functions.invokeBackground(\"render\", { body: input });\n    const progress = observeTask(task, { signal: owner.signal });\n\nUnsubscribing progress does not cancel the server task. Task read/decoder errors\nterminate observation; there is no automatic business retry. Realtime-to-polling\nfallback and project validation remain the SDK's responsibilities. Do not invent\na public.tasks table or copy service credentials into browser code.\n\nRun bun run check. Add cancellation, error, overflow and cross-owner isolation\ncoverage whenever adding streaming behavior. These APIs require the matching\nframework/SDK release or the packed candidate packages used by repository CI.\n";
+export declare const STARTER_REACTIVE_AGENTS = "# Application development rules\n\nRead README.md and REACTIVE.md before adding asynchronous features. If the\napplication is hosted by Angular, read the @supacloud/app/angular guidance\nbefore choosing a signal API.\nPrefer the generated contracts and existing project-bound @supacloud/js client.\nUse async/await for a single result; RxJS is the default event-composition library.\nBind subscriptions to an explicit owner and propagate cancellation to native I/O.\nNever automatically retry a write or turn observable delivery into durable ack.\nDo not bypass authorization, transactions, idempotency or audit to simplify code.\nRun bun run check; include negative and cleanup tests. Never store live credentials.\n";
+export declare const STARTER_REACTIVE_TEST = "import { expect, test } from \"bun:test\";\nimport { Observable } from \"rxjs\";\nimport { takeUntilAborted, toReadableStream } from \"@supacloud/app/reactive\";\n\ntest(\"the owner's signal releases reactive work exactly once\", () => {\n  const owner = new AbortController();\n  let starts = 0, stops = 0;\n  const source = new Observable<number>(() => { starts++; return () => { stops++; }; });\n  source.pipe(takeUntilAborted(owner.signal)).subscribe();\n  owner.abort();\n  source.pipe(takeUntilAborted(owner.signal)).subscribe();\n  expect(starts).toBe(1);\n  expect(stops).toBe(1);\n});\n\ntest(\"cancelled stream consumers release their subscription\", async () => {\n  let stops = 0;\n  const source = new Observable<number>(() => () => { stops++; });\n  const stream = toReadableStream(source);\n  await stream.cancel();\n  expect(stops).toBe(1);\n});\n";

package/dist/shared/tools/app-starter-reactive.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/tools/app-starter-review-job.d.ts

@@ -0,0 +1,2 @@
+export declare const STARTER_REVIEW_JOB = "import { DB_CLIENT, Inject, Injectable, Job } from \"@supacloud/app\";\nimport { ApplicationError } from \"@supacloud/elysia\";\nimport { t } from \"elysia\";\nimport type { Static } from \"elysia/type\";\n\nexport const AttachmentInput = t.Object({\n  reviewId: t.String({ minLength: 1, maxLength: 100 }),\n  version: t.Integer({ minimum: 2 }),\n  artifactId: t.String({ format: \"uuid\" }),\n}, { additionalProperties: false });\n\nexport const AttachmentResult = t.Object({\n  ...AttachmentInput.properties,\n  sha256: t.String({ pattern: \"^[a-f0-9]{64}$\" }),\n  bytes: t.Integer({ minimum: 1, maximum: 1048576 }),\n}, { additionalProperties: false });\n\nexport type ReviewAttachmentInput = Static<typeof AttachmentInput>;\nexport type ReviewAttachmentResult = Static<typeof AttachmentResult>;\n\nexport interface ReviewAttachmentStore {\n  // Resolve the immutable artifact under the worker's own authorization and current review revision.\n  readAttachment(input: ReviewAttachmentInput): Promise<{ body: Uint8Array; sha256: string }>;\n  // Revalidate revision/ownership and persist idempotently in a transaction; return the durable result.\n  recordAttachment(input: ReviewAttachmentInput, result: ReviewAttachmentResult): Promise<ReviewAttachmentResult>;\n}\n\n@Injectable({ scope: \"job\" })\n@Job({\n  name: \"review.verify-attachment\", mode: \"task\", idempotency: \"required\",\n  timeoutSec: 30, maxAttempts: 3, input: AttachmentInput, output: AttachmentResult,\n})\nexport class VerifyReviewAttachment {\n  constructor(@Inject(DB_CLIENT) private readonly store: ReviewAttachmentStore) {}\n\n  async run(input: ReviewAttachmentInput): Promise<ReviewAttachmentResult> {\n    const source = await this.store.readAttachment(input);\n    if (source.body.byteLength < 1 || source.body.byteLength > 1048576) {\n      throw new ApplicationError(\"Attachment size is outside the supported range\", { code: \"ATTACHMENT_SIZE_INVALID\" });\n    }\n    const digest = await crypto.subtle.digest(\"SHA-256\", new Uint8Array(source.body));\n    const sha256 = Array.from(new Uint8Array(digest), byte => byte.toString(16).padStart(2, \"0\")).join(\"\");\n    if (sha256 !== source.sha256) {\n      throw new ApplicationError(\"Attachment integrity check failed\", { code: \"ATTACHMENT_INTEGRITY_FAILED\" });\n    }\n    return this.store.recordAttachment(input, { ...input, sha256, bytes: source.body.byteLength });\n  }\n}\n";
+export declare const STARTER_REVIEW_JOB_TEST = "import { expect, test } from \"bun:test\";\nimport { VerifyReviewAttachment, type ReviewAttachmentResult } from \"../src/review/attachment\";\n\nconst input = { reviewId: \"review\", version: 2, artifactId: \"11111111-1111-4111-8111-111111111111\" };\nconst body = new TextEncoder().encode(\"review attachment\");\nconst sha256 = Array.from(new Uint8Array(await crypto.subtle.digest(\"SHA-256\", body)),\n  byte => byte.toString(16).padStart(2, \"0\")).join(\"\");\n\ntest(\"attachment job awaits the authorized reader and the committed result\", async () => {\n  let recorded: ReviewAttachmentResult | undefined;\n  const job = new VerifyReviewAttachment({\n    async readAttachment() { return { body, sha256 }; },\n    async recordAttachment(_input, result) { await Promise.resolve(); recorded = result; return result; },\n  });\n  expect(await job.run(input)).toEqual({ ...input, sha256, bytes: body.byteLength });\n  expect(recorded).toEqual({ ...input, sha256, bytes: body.byteLength });\n});\n\ntest(\"missing authorization, corrupted bytes and persistence failures are not successful jobs\", async () => {\n  let records = 0;\n  for (const readAttachment of [\n    async () => { throw new Error(\"Access denied\"); },\n    async () => ({ body, sha256: \"0\".repeat(64) }),\n    async () => ({ body: new Uint8Array(), sha256 }),\n    async () => ({ body: new Uint8Array(1048577), sha256 }),\n  ]) {\n    const job = new VerifyReviewAttachment({\n      readAttachment, async recordAttachment(_input, result) { records++; return result; },\n    });\n    await expect(job.run(input)).rejects.toThrow();\n  }\n  expect(records).toBe(0);\n  await expect(new VerifyReviewAttachment({\n    async readAttachment() { return { body, sha256 }; },\n    async recordAttachment() { throw new Error(\"Commit failed\"); },\n  }).run(input)).rejects.toThrow(\"Commit failed\");\n});\n";

package/dist/shared/tools/app-starter-roles.d.ts

@@ -0,0 +1,2 @@
+export declare function renderStarterRuntimeRolesSchema(httpRole: string, workerRole: string): string;
+export declare const STARTER_RUNTIME_ROLES_SCHEMA: string;

package/dist/shared/tools/app-starter-roles.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/tools/app-starter-templates.d.ts

@@ -0,0 +1,7 @@
+export type StarterTemplate = "minimal" | "http" | "command" | "edge";
+export interface StarterSdkDependencies {
+    "@supacloud/js": string;
+    "@supabase/supabase-js": string;
+}
+/** Explicit recipes retain their existing layouts; new projects default to minimal. */
+export declare function appTemplateFiles(name: string, template: StarterTemplate, sdkDependencies?: StarterSdkDependencies): Record<string, string>;

package/dist/shared/tools/app-starter-upload.d.ts

@@ -0,0 +1,3 @@
+export declare const STARTER_UPLOAD_FEATURE = "import { Effect } from \"effect\";\nimport { Body, Controller, Inject, Injectable, Param, Post, DB_CLIENT, REQUEST_CONTEXT } from \"@supacloud/app\";\nimport { ApplicationError } from \"@supacloud/elysia\";\nimport { UploadBody, UploadLocation, UploadParams, UploadResult } from \"./contracts\";\n\nexport interface ReviewUploadInput { reviewId: string; artifactId: string; expectedVersion: number }\nexport interface ReviewUploadLocation { artifactId: string; bucketId: string; objectPath: string }\nexport interface ReviewUploadResult { artifactId: string; runId: string; objectPath: string; sha256: string; bytes: number }\ntype PreviewUploadError =\n  | { readonly _tag: \"AUTHENTICATION_REQUIRED\" }\n  | { readonly _tag: \"UPLOAD_INPUT_INVALID\" }\n  | { readonly _tag: \"UPLOAD_DENIED\" }\n  | { readonly _tag: \"UPLOADS_UNAVAILABLE\" };\ntype RegisterUploadError =\n  | PreviewUploadError\n  | { readonly _tag: \"UPLOAD_CONTENT_INVALID\" }\n  | { readonly _tag: \"COMMAND_IDEMPOTENCY_CONFLICT\" }\n  | { readonly _tag: \"COMMAND_REJECTED\" }\n  | { readonly _tag: \"UPLOAD_OUTCOME_UNKNOWN\" };\nexport interface ReviewUploadPort {\n  previewUpload(context: unknown, input: ReviewUploadInput): Promise<ReviewUploadLocation>;\n  registerUpload(context: unknown, input: ReviewUploadInput): Promise<ReviewUploadResult>;\n}\n@Injectable({ scope: \"request\" })\nexport class ReviewUploads {\n  constructor(@Inject(DB_CLIENT) private readonly store: Partial<ReviewUploadPort>,\n    @Inject(REQUEST_CONTEXT) private readonly context: unknown) {}\n\n  preview(input: ReviewUploadInput): Promise<ReviewUploadLocation> {\n    if (!this.store.previewUpload) throw new ApplicationError(\"Attachment uploads are not configured\", { status: 501, code: \"UPLOADS_UNAVAILABLE\" });\n    return this.store.previewUpload(this.context, input);\n  }\n  register(input: ReviewUploadInput): Promise<ReviewUploadResult> {\n    if (!this.store.registerUpload) throw new ApplicationError(\"Attachment uploads are not configured\", { status: 501, code: \"UPLOADS_UNAVAILABLE\" });\n    return this.store.registerUpload(this.context, input);\n  }\n}\n\n@Controller(\"/reviews\")\nexport class ReviewUploadsController {\n  constructor(@Inject(ReviewUploads) private readonly uploads: ReviewUploads) {}\n\n  @Post(\"/:id/attachment-upload\", {\n    params: UploadParams,\n    body: UploadBody,\n    responses: { 200: UploadLocation },\n    effect: {\n      required: true,\n      dependencies: [],\n      errors: [\n        { tag: \"AUTHENTICATION_REQUIRED\", status: 401, code: \"AUTHENTICATION_REQUIRED\" },\n        { tag: \"UPLOAD_INPUT_INVALID\", status: 400, code: \"UPLOAD_INPUT_INVALID\" },\n        { tag: \"UPLOAD_DENIED\", status: 403, code: \"UPLOAD_DENIED\" },\n        { tag: \"UPLOADS_UNAVAILABLE\", status: 501, code: \"UPLOADS_UNAVAILABLE\" },\n      ],\n      retry: \"none\",\n    },\n  })\n  preview(@Param(\"id\") id: string, @Body() body: { artifactId: string; expectedVersion: number }): Effect.Effect<ReviewUploadLocation, PreviewUploadError, never> {\n    return Effect.promise(() => this.uploads.preview({ reviewId: id, artifactId: body.artifactId, expectedVersion: body.expectedVersion }));\n  }\n  @Post(\"/:id/attachment-registration\", {\n    params: UploadParams,\n    body: UploadBody,\n    responses: { 200: UploadResult },\n    effect: {\n      required: true,\n      dependencies: [],\n      errors: [\n        { tag: \"AUTHENTICATION_REQUIRED\", status: 401, code: \"AUTHENTICATION_REQUIRED\" },\n        { tag: \"UPLOAD_INPUT_INVALID\", status: 400, code: \"UPLOAD_INPUT_INVALID\" },\n        { tag: \"UPLOAD_DENIED\", status: 403, code: \"UPLOAD_DENIED\" },\n        { tag: \"UPLOAD_CONTENT_INVALID\", status: 400, code: \"UPLOAD_CONTENT_INVALID\" },\n        { tag: \"COMMAND_IDEMPOTENCY_CONFLICT\", status: 409, code: \"COMMAND_IDEMPOTENCY_CONFLICT\" },\n        { tag: \"COMMAND_REJECTED\", status: 403, code: \"COMMAND_REJECTED\" },\n        { tag: \"UPLOADS_UNAVAILABLE\", status: 501, code: \"UPLOADS_UNAVAILABLE\" },\n        { tag: \"UPLOAD_OUTCOME_UNKNOWN\", status: 503, code: \"UPLOAD_OUTCOME_UNKNOWN\" },\n      ],\n      retry: \"none\",\n    },\n  })\n  register(@Param(\"id\") id: string, @Body() body: { artifactId: string; expectedVersion: number }): Effect.Effect<ReviewUploadResult, RegisterUploadError, never> {\n    return Effect.promise(() => this.uploads.register({ reviewId: id, artifactId: body.artifactId, expectedVersion: body.expectedVersion }));\n  }\n}\n";
+export declare const STARTER_UPLOAD_SCHEMA = "-- Apply explicitly with the migration owner.\nALTER TABLE public.starter_members ADD COLUMN storage_subject uuid UNIQUE;\nGRANT SELECT (subject,enabled,can_approve,storage_subject) ON public.starter_members TO authenticated;\nCREATE POLICY starter_member_read ON public.starter_members FOR SELECT TO authenticated\n  USING (subject=COALESCE(NULLIF(auth.jwt()->>'external_sub',''),auth.jwt()->>'sub') AND storage_subject=auth.uid());\nGRANT SELECT ON public.starter_reviews TO authenticated;\nCREATE POLICY starter_review_read ON public.starter_reviews FOR SELECT TO authenticated\n  USING (owner_id=COALESCE(NULLIF(auth.jwt()->>'external_sub',''),auth.jwt()->>'sub') AND EXISTS (\n    SELECT 1 FROM public.starter_members m WHERE m.subject=owner_id\n      AND m.enabled AND m.can_approve AND m.storage_subject=auth.uid()\n  ));\nINSERT INTO storage.buckets(id,name,public,file_size_limit,allowed_mime_types)\n  VALUES ('review-attachments','review-attachments',false,1048576,ARRAY['text/plain']);\nCREATE POLICY starter_attachment_read ON storage.objects FOR SELECT TO authenticated\n  USING (bucket_id='review-attachments');\nCREATE POLICY starter_attachment_insert ON storage.objects FOR INSERT TO authenticated\n  WITH CHECK (bucket_id='review-attachments');\n-- Restrictive fences also apply when the host already has permissive Storage policies.\nCREATE POLICY starter_attachment_owner_fence ON storage.objects AS RESTRICTIVE FOR ALL TO authenticated\n  USING (bucket_id<>'review-attachments' OR (split_part(name,'/',1)=auth.uid()::text AND EXISTS (\n    SELECT 1 FROM public.starter_reviews r JOIN public.starter_members m ON m.subject=r.owner_id\n    WHERE r.id=split_part(name,'/',2) AND m.subject=COALESCE(NULLIF(auth.jwt()->>'external_sub',''),auth.jwt()->>'sub')\n      AND m.storage_subject=auth.uid() AND m.enabled AND m.can_approve\n  )))\n  WITH CHECK (bucket_id<>'review-attachments' OR (split_part(name,'/',1)=auth.uid()::text\n    AND name ~ '^[a-f0-9-]{36}/[a-f0-9-]{36}/[a-f0-9-]{36}[.]txt$' AND EXISTS (\n      SELECT 1 FROM public.starter_reviews r JOIN public.starter_members m ON m.subject=r.owner_id\n      WHERE r.id=split_part(name,'/',2) AND r.state='draft' AND m.subject=COALESCE(NULLIF(auth.jwt()->>'external_sub',''),auth.jwt()->>'sub')\n        AND m.storage_subject=auth.uid() AND m.enabled AND m.can_approve\n    )));\nCREATE POLICY starter_attachment_update_fence ON storage.objects AS RESTRICTIVE FOR UPDATE TO authenticated\n  USING (bucket_id<>'review-attachments') WITH CHECK (bucket_id<>'review-attachments');\nCREATE POLICY starter_attachment_delete_fence ON storage.objects AS RESTRICTIVE FOR DELETE TO authenticated\n  USING (bucket_id<>'review-attachments');\n";
+export declare const STARTER_UPLOAD_ADAPTER = "import { MIMEType } from \"node:util\";\nimport { SupaCloudArtifactsClient } from \"@supacloud/js\";\nimport { createTransactionalCommand, plaintextCommandInput } from \"@supacloud/commands\";\nimport { CommandError } from \"@supacloud/contracts\";\nimport { createPostgresCommandStore, type CommandTransaction } from \"@supacloud/db\";\nimport { ApplicationError, requireTrustedIdentity } from \"@supacloud/elysia\";\nimport type { ReviewAttachmentOptions } from \"./review-attachments\";\nimport type { ReviewUploadInput, ReviewUploadPort, ReviewUploadResult } from \"../review/uploads\";\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return value !== null && typeof value === \"object\" && !Array.isArray(value);\n}\nfunction record(value: unknown): Record<string, unknown> {\n  if (!isRecord(value)) throw new TypeError(\"Invalid upload record\");\n  return value;\n}\nfunction rows(value: unknown): Record<string, unknown>[] {\n  if (!Array.isArray(value)) throw new TypeError(\"Invalid upload database result\");\n  return value.map(record);\n}\nfunction capture(value: unknown): ReviewUploadInput {\n  const item = record(value), uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;\n  if (typeof item[\"reviewId\"] !== \"string\" || !uuid.test(item[\"reviewId\"])\n    || typeof item[\"artifactId\"] !== \"string\" || !uuid.test(item[\"artifactId\"])\n    || typeof item[\"expectedVersion\"] !== \"number\" || !Number.isSafeInteger(item[\"expectedVersion\"]) || item[\"expectedVersion\"] < 1) {\n    throw new ApplicationError(\"Invalid upload input\", { status: 400, code: \"UPLOAD_INPUT_INVALID\" });\n  }\n  return { reviewId: item[\"reviewId\"].toLowerCase(), artifactId: item[\"artifactId\"].toLowerCase(), expectedVersion: item[\"expectedVersion\"] };\n}\nfunction result(value: unknown): ReviewUploadResult {\n  const item = record(value);\n  if (typeof item[\"artifactId\"] !== \"string\" || typeof item[\"runId\"] !== \"string\" || typeof item[\"objectPath\"] !== \"string\"\n    || typeof item[\"sha256\"] !== \"string\" || typeof item[\"bytes\"] !== \"number\") throw new TypeError(\"Invalid upload receipt\");\n  return { artifactId: item[\"artifactId\"], runId: item[\"runId\"], objectPath: item[\"objectPath\"], sha256: item[\"sha256\"], bytes: item[\"bytes\"] };\n}\n\nexport async function createReviewUploadAdapters(options: ReviewAttachmentOptions): Promise<ReviewUploadPort> {\n  const { database, service, projectId, tenantId } = options;\n  const binding = rows(await database.transaction(tx => tx.query(\n    \"SELECT project_id,tenant_id FROM public.starter_application WHERE singleton\",\n  )));\n  if (!projectId.trim() || !tenantId.trim() || binding.length !== 1\n    || binding[0]?.[\"project_id\"] !== projectId || binding[0]?.[\"tenant_id\"] !== tenantId) {\n    throw new Error(\"Upload database project/tenant binding mismatch\");\n  }\n  const artifacts = new SupaCloudArtifactsClient(service);\n  function actor(context: unknown): string {\n    const who = requireTrustedIdentity(context);\n    const access = record(record(context)[\"access\"]);\n    if (access[\"projectId\"] !== projectId || access[\"tenantId\"] !== tenantId\n      || !Array.isArray(access[\"permissions\"]) || !access[\"permissions\"].includes(\"review.approve\")) {\n      throw new ApplicationError(\"Upload permission denied\", { status: 403, code: \"UPLOAD_DENIED\" });\n    }\n    return who.subject;\n  }\n  async function authorize(tx: CommandTransaction, subject: string, input: ReviewUploadInput, replay = false) {\n    const allowed = rows(await tx.query(\n      \"SELECT m.storage_subject::text AS storage_subject FROM public.starter_reviews r \" +\n      \"JOIN public.starter_members m ON m.subject=r.owner_id CROSS JOIN public.starter_application p \" +\n      \"WHERE r.id=$1 AND r.owner_id=$2 AND ((r.state='draft' AND r.version=$3) OR \" +\n      \"($6::boolean AND r.state='approved' AND r.version=$3+1 AND EXISTS (\" +\n      \"SELECT 1 FROM public.starter_attachments b WHERE b.review_id=r.id AND b.artifact_id=$7::uuid AND b.owner_id=$2 \" +\n      \"AND b.object_path=m.storage_subject::text || '/' || r.id || '/' || $7::text || '.txt'))) \" +\n      \"AND m.enabled AND m.can_approve AND m.storage_subject IS NOT NULL \" +\n      \"AND p.singleton AND p.project_id=$4 AND p.tenant_id=$5 FOR UPDATE OF r,m FOR SHARE OF p\",\n      [input.reviewId, subject, input.expectedVersion, projectId, tenantId, replay, input.artifactId],\n    ));\n    if (allowed.length !== 1 || typeof allowed[0]?.[\"storage_subject\"] !== \"string\") {\n      throw new ApplicationError(\"Upload ownership, permission or revision changed\", { status: 403, code: \"UPLOAD_DENIED\" });\n    }\n    return allowed[0][\"storage_subject\"] + \"/\" + input.reviewId + \"/\" + input.artifactId + \".txt\";\n  }\n  return {\n    async previewUpload(context, value) {\n      const input = capture(value), subject = actor(context);\n      const objectPath = await database.transaction(tx => authorize(tx, subject, input));\n      return { artifactId: input.artifactId, bucketId: \"review-attachments\", objectPath };\n    },\n    async registerUpload(context, value) {\n      const input = capture(value), subject = actor(context);\n      const objectPath = await database.transaction(tx => authorize(tx, subject, input, true));\n      try {\n        const downloaded = await service.storage.from(\"review-attachments\").download(objectPath);\n        if (downloaded.error || !downloaded.data) throw new Error(\"Upload unavailable\");\n        const blob = downloaded.data;\n        if (blob.size < 1 || blob.size > 1048576 || new MIMEType(blob.type).essence !== \"text/plain\") {\n          throw new ApplicationError(\"Unsupported upload\", { status: 400, code: \"UPLOAD_CONTENT_INVALID\" });\n        }\n        const sha256 = Array.from(new Uint8Array(await crypto.subtle.digest(\"SHA-256\", await blob.arrayBuffer())),\n          byte => byte.toString(16).padStart(2, \"0\")).join(\"\");\n        await artifacts.register({ artifactId: input.artifactId, bucketId: \"review-attachments\", objectPath,\n          artifactType: \"review.attachment\", sha256, sizeBytes: blob.size, mimeType: \"text/plain\" });\n        const command = createTransactionalCommand({\n          name: \"review.attach\", store: createPostgresCommandStore(database), inputCodec: plaintextCommandInput,\n          input: capture, result,\n          async authorize(who, request, tx) {\n            try {\n              const currentPath = await authorize(tx, who.actorId, request, true);\n              return currentPath === objectPath ? \"allow\" : \"deny\";\n            } catch (error) {\n              if (error instanceof ApplicationError && error.code === \"UPLOAD_DENIED\") return \"deny\";\n              throw error;\n            }\n          },\n          async execute(tx, request) {\n            const existing = rows(await tx.query(\"SELECT artifact_id FROM public.starter_attachments WHERE review_id=$1\", [request.reviewId]));\n            if (existing.length) throw new CommandError(\"COMMAND_IDEMPOTENCY_CONFLICT\");\n            const bound: ReviewUploadResult = { artifactId: request.artifactId, runId: request.artifactId, objectPath, sha256, bytes: blob.size };\n            await tx.query(\"INSERT INTO public.starter_attachments VALUES($1,$2,$3,$4,$5)\",\n              [request.reviewId, bound.artifactId, subject, bound.runId, bound.objectPath]);\n            return bound;\n          },\n          audit: { event: \"review.attachment-bound\", details: request => ({ reviewId: request.reviewId, artifactId: request.artifactId }) },\n        });\n        const receipt = await command.execute({ actorId: subject, tenantId }, input.artifactId, input);\n        if (receipt.status !== \"confirmed\") throw new CommandError(\"COMMAND_OUTCOME_UNKNOWN\");\n        return receipt.result;\n      } catch (error) {\n        if (error instanceof ApplicationError) throw error;\n        if (error instanceof CommandError && error.code === \"COMMAND_IDEMPOTENCY_CONFLICT\") {\n          throw new ApplicationError(\"Conflicting attachment binding\", { status: 409, code: error.code });\n        }\n        if (error instanceof CommandError && error.code === \"COMMAND_REJECTED\") {\n          throw new ApplicationError(\"Upload permission denied\", { status: 403, code: error.code });\n        }\n        // Registration may have committed even when binding failed; never delete immutable evidence here.\n        throw new ApplicationError(\"Upload registration could not be confirmed\", { status: 503, code: \"UPLOAD_OUTCOME_UNKNOWN\" });\n      }\n    },\n  };\n}\n";

package/dist/shared/tools/app-starter.d.ts

@@ -0,0 +1,12 @@
+import { type StarterTemplate } from "./app-starter-templates";
+/** Embedded source strings are included in both the npm CLI and standalone binary. */
+export declare function appStarterFiles(name: string): Record<string, string>;
+export declare function initializeAppProject(options: {
+    root?: string;
+    name?: string;
+    template?: StarterTemplate;
+}): Promise<{
+    root: string;
+    name: string;
+    files: string[];
+}>;

package/dist/shared/tools/app-starter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/tools/app-tool-export.d.ts

@@ -0,0 +1,42 @@
+import type { ModuleNode } from "@supacloud/compiler";
+export interface AppManifest {
+    version: number;
+    modules: ModuleNode[];
+    externalTokens: string[];
+}
+export interface ToolSchemaProperty {
+    type: string;
+    description: string;
+    additionalProperties?: boolean;
+}
+export interface ToolInputSchema {
+    type: "object";
+    properties: Record<string, ToolSchemaProperty>;
+    required: string[];
+    additionalProperties?: boolean;
+}
+export interface OpenAIToolDefinition {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: ToolInputSchema;
+    };
+}
+export interface McpToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: ToolInputSchema;
+    annotations: {
+        readOnly: boolean;
+        audited: boolean;
+        permission: string;
+        httpPath?: string;
+        httpMethod?: string;
+    };
+}
+export interface ExportedToolDefinitions {
+    openai: OpenAIToolDefinition[];
+    mcp: McpToolDefinition[];
+}
+export declare function buildToolDefinitions(manifest: AppManifest): ExportedToolDefinitions;