@cancia/astro 0.2.0 → 0.3.0

package/dist/chunk-AIPRCBJM.js

@@ -0,0 +1,258 @@
+import {
+  createGitBackedAdapter,
+  createSqliteAdapterV2
+} from "./chunk-52URFK5Y.js";
+import {
+  createJsonFileAdapter,
+  createJsonFileAdapterV2
+} from "./chunk-L2VKQJPY.js";
+import {
+  detectImageType,
+  isValidSite
+} from "./chunk-5IPHDIC6.js";
+
+// src/routes/upload.ts
+import { writeFile, mkdir } from "fs/promises";
+import { join } from "path";
+import { randomUUID } from "crypto";
+function makeLocalUploadHandler(opts) {
+  const uploadDir = opts.uploadDir ?? join(process.cwd(), "public/uploads");
+  const publicUrlBase = opts.publicUrlBase ?? "/uploads";
+  const maxBytes = (opts.maxMB ?? 10) * 1024 * 1024;
+  return async (file, site, detected) => {
+    const dest = join(uploadDir, site);
+    await mkdir(dest, { recursive: true });
+    const name = `${randomUUID()}.${detected.ext}`;
+    await writeFile(join(dest, name), Buffer.from(await file.arrayBuffer()));
+    return `${publicUrlBase}/${site}/${name}`;
+  };
+}
+function makeUploadRoute(uploadHandler, secret, maxMB = 10) {
+  return async ({ request }) => {
+    if (secret) {
+      const token = request.headers.get("Authorization")?.replace("Bearer ", "").trim();
+      if (token !== secret) {
+        return new Response(JSON.stringify({ error: "Unauthorized" }), { status: 401 });
+      }
+    }
+    const form = await request.formData().catch(() => null);
+    const file = form?.get("file");
+    const site = form?.get("site");
+    if (!(file instanceof File)) {
+      return new Response(JSON.stringify({ error: "Missing file field" }), { status: 400 });
+    }
+    if (typeof site !== "string" || !isValidSite(site)) {
+      return new Response(
+        JSON.stringify({ error: "Invalid site (allowed: a-z, 0-9, and . _ -; must start alphanumeric)" }),
+        { status: 400 }
+      );
+    }
+    if (file.size > maxMB * 1024 * 1024) {
+      return new Response(JSON.stringify({ error: `File too large (max ${maxMB}MB)` }), { status: 413 });
+    }
+    const buf = new Uint8Array(await file.arrayBuffer());
+    const detected = detectImageType(buf);
+    if (!detected) {
+      return new Response(JSON.stringify({ error: "File type not allowed" }), { status: 415 });
+    }
+    const url = await uploadHandler(file, site, detected);
+    return new Response(JSON.stringify({ url }), {
+      headers: { "Content-Type": "application/json" }
+    });
+  };
+}
+
+// src/routes/upload-r2.ts
+import { createHmac, createHash } from "crypto";
+import { randomUUID as randomUUID2 } from "crypto";
+function sha256hex(data) {
+  return createHash("sha256").update(data).digest("hex");
+}
+function hmacSha256(key, data) {
+  return createHmac("sha256", key).update(data).digest();
+}
+function getSigningKey(secretKey, date, region, service) {
+  const kDate = hmacSha256(Buffer.from(`AWS4${secretKey}`, "utf8"), date);
+  const kRegion = hmacSha256(kDate, region);
+  const kService = hmacSha256(kRegion, service);
+  const kSigning = hmacSha256(kService, "aws4_request");
+  return kSigning;
+}
+async function signedPutRequest(opts) {
+  const { endpoint, bucket, key, body, contentType, accessKeyId, secretAccessKey } = opts;
+  const region = "auto";
+  const service = "s3";
+  const now = /* @__PURE__ */ new Date();
+  const isoDate = now.toISOString().replace(/[:-]|\.\d{3}/g, "").slice(0, 15) + "Z";
+  const shortDate = isoDate.slice(0, 8);
+  const url = `${endpoint}/${bucket}/${key}`;
+  const host = new URL(endpoint).host;
+  const payloadHash = sha256hex(body);
+  const headers = {
+    "content-type": contentType,
+    "host": host,
+    "x-amz-content-sha256": payloadHash,
+    "x-amz-date": isoDate
+  };
+  const signedHeaders = Object.keys(headers).sort().join(";");
+  const canonicalHeaders = Object.keys(headers).sort().map((k) => `${k}:${headers[k]}
+`).join("");
+  const canonicalRequest = [
+    "PUT",
+    `/${bucket}/${key}`,
+    "",
+    canonicalHeaders,
+    signedHeaders,
+    payloadHash
+  ].join("\n");
+  const credentialScope = `${shortDate}/${region}/${service}/aws4_request`;
+  const stringToSign = [
+    "AWS4-HMAC-SHA256",
+    isoDate,
+    credentialScope,
+    sha256hex(canonicalRequest)
+  ].join("\n");
+  const signingKey = getSigningKey(secretAccessKey, shortDate, region, service);
+  const signature = createHmac("sha256", signingKey).update(stringToSign).digest("hex");
+  const authHeader = `AWS4-HMAC-SHA256 Credential=${accessKeyId}/${credentialScope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+  let res;
+  try {
+    res = await fetch(url, {
+      method: "PUT",
+      headers: { ...headers, Authorization: authHeader },
+      body: new Uint8Array(body)
+    });
+  } catch (err) {
+    throw new Error(`R2 upload: network error reaching ${url} \u2014 ${err}`);
+  }
+  if (!res.ok) {
+    const text = await res.text().catch(() => res.statusText);
+    throw new Error(`R2 upload failed (${res.status}): ${text}`);
+  }
+}
+function makeR2UploadHandler(opts) {
+  const {
+    accountId,
+    bucket,
+    accessKeyId,
+    secretAccessKey,
+    publicUrl,
+    prefix = "uploads"
+  } = opts;
+  const endpoint = `https://${accountId}.r2.cloudflarestorage.com`;
+  return async (file, _site, detected) => {
+    const key = `${prefix}/${randomUUID2()}.${detected.ext}`;
+    const body = Buffer.from(await file.arrayBuffer());
+    await signedPutRequest({
+      endpoint,
+      bucket,
+      key,
+      body,
+      contentType: file.type,
+      accessKeyId,
+      secretAccessKey
+    });
+    return `${publicUrl.replace(/\/$/, "")}/${key}`;
+  };
+}
+
+// src/runtime.ts
+import { isAbsolute, join as join2 } from "path";
+var _runtime = null;
+var _bakedConfig = null;
+function setBakedConfig(config) {
+  _bakedConfig = config;
+}
+function setCanciaRuntime(runtime) {
+  _runtime = runtime;
+}
+function buildRuntimeFromBaked(baked) {
+  const projectRoot = baked.projectRoot || process.cwd();
+  const token = process.env.CANCIA_TOKEN?.trim() || "";
+  const secret = baked.public ? void 0 : token || void 0;
+  const deployHook = process.env.CANCIA_DEPLOY_HOOK || void 0;
+  const deployHookToken = process.env.CANCIA_DEPLOY_HOOK_TOKEN || void 0;
+  const storageV2 = buildStorageV2(baked, projectRoot);
+  const storage = storageV2 ? storageV2.kv : lazyJsonFileAdapter(projectRoot);
+  const uploadHandler = buildUploadHandler(baked, projectRoot);
+  return {
+    storage,
+    storageV2,
+    projectRoot,
+    schemasPath: baked.schemasPath,
+    defaultLocale: baked.defaultLocale,
+    locales: baked.locales,
+    secret,
+    uploadHandler,
+    deployHook,
+    deployHookToken,
+    deployHookMethod: baked.deployHookMethod,
+    deployHookHeaders: baked.deployHookHeaders,
+    maxUploadMB: baked.maxUploadMB
+  };
+}
+function lazyJsonFileAdapter(projectRoot) {
+  return createJsonFileAdapter(projectRoot + "/cancia-content.json");
+}
+function resolveDbPath(dbPath, projectRoot) {
+  return isAbsolute(dbPath) ? dbPath : join2(projectRoot, dbPath);
+}
+function buildStorageV2(baked, projectRoot) {
+  const desc = baked.storage;
+  if (!desc) return void 0;
+  if (desc.kind === "git-backed") {
+    const local = createJsonFileAdapterV2({ projectRoot });
+    return createGitBackedAdapter({
+      local,
+      repo: desc.repo,
+      branch: desc.branch,
+      token: process.env.CANCIA_GITHUB_TOKEN,
+      committer: desc.committer,
+      projectRoot,
+      debounceMs: desc.debounceMs,
+      commitMessage: desc.commitMessage
+    });
+  }
+  if (desc.kind === "sqlite-v2") {
+    const dbPath = desc.dbPath ? resolveDbPath(desc.dbPath, projectRoot) : `${projectRoot}/cancia.db`;
+    return createSqliteAdapterV2({ dbPath });
+  }
+  return createJsonFileAdapterV2({ projectRoot });
+}
+function buildUploadHandler(baked, projectRoot) {
+  if (baked.r2) {
+    const env = process.env;
+    const resolved = {
+      accountId: baked.r2.accountId ?? env.R2_ACCOUNT_ID ?? "",
+      bucket: baked.r2.bucket ?? env.R2_BUCKET_NAME ?? env.R2_BUCKET ?? "",
+      accessKeyId: env.R2_ACCESS_KEY_ID ?? "",
+      secretAccessKey: env.R2_SECRET_ACCESS_KEY ?? "",
+      publicUrl: baked.r2.publicUrl ?? env.R2_PUBLIC_URL ?? "",
+      prefix: baked.r2.prefix
+    };
+    return makeR2UploadHandler(resolved);
+  }
+  return makeLocalUploadHandler({
+    uploadDir: projectRoot + "/public/uploads",
+    maxMB: baked.maxUploadMB
+  });
+}
+function getCanciaRuntime() {
+  if (_runtime) return _runtime;
+  if (_bakedConfig) {
+    _runtime = buildRuntimeFromBaked(_bakedConfig);
+    return _runtime;
+  }
+  throw new Error(
+    "[cancia] Runtime not initialised and no baked config available. This is a bug \u2014 the virtual:cancia/runtime module should have called setBakedConfig() at import time."
+  );
+}
+
+export {
+  makeLocalUploadHandler,
+  makeUploadRoute,
+  makeR2UploadHandler,
+  setBakedConfig,
+  setCanciaRuntime,
+  getCanciaRuntime
+};

package/dist/{chunk-ST44VULL.js → chunk-L2VKQJPY.js}

@@ -48,10 +48,8 @@ function createJsonFileAdapter(filePath) {
   };
 }
 
-// src/storage/json-file-v2.ts
-import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, existsSync as existsSync2, mkdirSync as mkdirSync2, readdirSync, rmSync } from "fs";
-import { dirname as dirname2, join } from "path";
-import { createHash, randomUUID } from "crypto";
+// src/storage/rev.ts
+import { createHash } from "crypto";
 function canonicalize(value) {
   if (value === null || typeof value !== "object") return JSON.stringify(value);
   if (Array.isArray(value)) {
@@ -64,6 +62,11 @@ function canonicalize(value) {
 function hashRev(value) {
   return createHash("sha256").update(canonicalize(value)).digest("hex").slice(0, 16);
 }
+
+// src/storage/json-file-v2.ts
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, existsSync as existsSync2, mkdirSync as mkdirSync2, readdirSync, rmSync } from "fs";
+import { dirname as dirname2, join } from "path";
+import { randomUUID } from "crypto";
 function readJsonFile(filePath, fallback) {
   if (!existsSync2(filePath)) return fallback;
   try {
@@ -315,5 +318,7 @@ function createJsonFileAdapterV2(opts = {}) {
 
 export {
   createJsonFileAdapter,
+  canonicalize,
+  hashRev,
   createJsonFileAdapterV2
 };

package/dist/chunk-PIDFNJME.js

@@ -0,0 +1,19 @@
+// src/publish-hook.ts
+async function firePublish(hook, opts = {}) {
+  if (!hook) return { ok: false, kind: "no-hook" };
+  const headers = { ...opts.headers ?? {} };
+  if (opts.token) headers.Authorization = `Bearer ${opts.token}`;
+  const init = { method: opts.method ?? "POST" };
+  if (Object.keys(headers).length > 0) init.headers = headers;
+  try {
+    const res = await fetch(hook, init);
+    if (!res.ok) return { ok: false, kind: "bad-response", status: res.status };
+    return { ok: true };
+  } catch {
+    return { ok: false, kind: "unreachable" };
+  }
+}
+
+export {
+  firePublish
+};

package/dist/{chunk-337LJIKX.js → chunk-UR5WC3RA.js}

@@ -1,6 +1,6 @@
 import {
   createJsonFileAdapterV2
-} from "./chunk-ST44VULL.js";
+} from "./chunk-L2VKQJPY.js";
 
 // src/loader/index.ts
 import { join } from "path";

package/dist/endpoints/publish.js

@@ -1,33 +1,39 @@
+import {
+  firePublish
+} from "../chunk-PIDFNJME.js";
+
 // src/endpoints/publish.ts
 import { getCanciaRuntime } from "virtual:cancia/runtime";
 async function POST({ request }) {
-  const { deployHook, secret } = getCanciaRuntime();
+  const { deployHook, deployHookToken, deployHookMethod, deployHookHeaders, secret } = getCanciaRuntime();
   if (secret) {
     const token = request.headers.get("Authorization")?.replace("Bearer ", "").trim();
     if (token !== secret)
       return new Response(JSON.stringify({ error: "Unauthorized" }), { status: 401 });
   }
   const hook = deployHook ?? process.env.CANCIA_DEPLOY_HOOK;
-  if (!hook)
+  const result = await firePublish(hook, {
+    token: deployHookToken,
+    method: deployHookMethod,
+    headers: deployHookHeaders
+  });
+  if (result.ok)
+    return new Response(JSON.stringify({ ok: true }), {
+      headers: { "Content-Type": "application/json" }
+    });
+  if (result.kind === "no-hook")
     return new Response(
       JSON.stringify({ error: "No deploy hook configured. Set CANCIA_DEPLOY_HOOK." }),
       { status: 503 }
     );
-  try {
-    const res = await fetch(hook, { method: "POST" });
-    if (!res.ok)
-      return new Response(
-        JSON.stringify({ error: `Deploy hook responded with ${res.status}` }),
-        { status: 502 }
-      );
-    return new Response(JSON.stringify({ ok: true }), {
-      headers: { "Content-Type": "application/json" }
-    });
-  } catch {
-    return new Response(JSON.stringify({ error: "Failed to reach deploy hook" }), {
-      status: 502
-    });
-  }
+  if (result.kind === "bad-response")
+    return new Response(
+      JSON.stringify({ error: `Deploy hook responded with ${result.status}` }),
+      { status: 502 }
+    );
+  return new Response(JSON.stringify({ error: "Failed to reach deploy hook" }), {
+    status: 502
+  });
 }
 export {
   POST

package/dist/git-backed-DFAB0tzf.d.ts

@@ -0,0 +1,98 @@
+import { C as CanciaStorage, a as CanciaStorageV2 } from './types-BMlLS-OS.js';
+import { G as GitHubCommitter, a as GitHubClient, F as FetchLike } from './github-client-BAZ1pW24.js';
+
+declare function createJsonFileAdapter(filePath?: string): CanciaStorage;
+
+interface JsonFileV2Options {
+    /** Project root. Defaults to process.cwd(). */
+    projectRoot?: string;
+    /** Override the KV file path. Defaults to <root>/cancia-content.json. */
+    kvPath?: string;
+    /** Override the pages file path. Defaults to <root>/.cancia/pages.json. */
+    pagesPath?: string;
+    /** Override the lists directory. Defaults to <root>/.cancia/lists. */
+    listsDir?: string;
+}
+declare function createJsonFileAdapterV2(opts?: JsonFileV2Options): CanciaStorageV2;
+
+declare function createSQLiteAdapter(dbPath?: string): CanciaStorage;
+
+interface SqliteV2Options {
+    /** Absolute path to the .db file. Defaults to <projectRoot>/cancia.db. */
+    dbPath?: string;
+    /** Project root. Defaults to process.cwd(). Used to derive dbPath. */
+    projectRoot?: string;
+}
+declare function createSqliteAdapterV2(opts?: SqliteV2Options): CanciaStorageV2;
+/**
+ * Close and forget the cached connection for a db path (or all connections
+ * when no path is given). The store interface has no lifecycle hook, so this
+ * is the seam for graceful shutdown and for tests that need to release the
+ * file handle before deleting the .db (Windows keeps WAL files locked while
+ * the connection is open). No-op if the path was never opened.
+ */
+declare function closeSqliteAdapterV2(dbPath?: string): void;
+
+interface GitBackedContentPaths {
+    /** KV file path. Default <projectRoot>/cancia-content.json. */
+    kvPath?: string;
+    /** Pages file path. Default <projectRoot>/.cancia/pages.json. */
+    pagesPath?: string;
+    /** Lists directory. Default <projectRoot>/.cancia/lists. */
+    listsDir?: string;
+}
+interface GitBackedOptions {
+    /** The wrapped local adapter — the on-disk source of truth. */
+    local: CanciaStorageV2;
+    /** "owner/name" of the GitHub repo whose builds carry the content. */
+    repo: string;
+    /** Branch to commit onto. Default "main". */
+    branch?: string;
+    /**
+     * GitHub PAT. Reads CANCIA_GITHUB_TOKEN if omitted. When absent entirely the
+     * adapter runs in local-only mode (disk writes only; no commits) + warns once.
+     */
+    token?: string;
+    /** Optional committer identity for commits. */
+    committer?: GitHubCommitter;
+    /**
+     * Project root the local adapter writes under — needed to turn absolute
+     * on-disk paths into repo-relative commit paths. Default process.cwd().
+     */
+    projectRoot?: string;
+    /** Override where the local adapter's content lives (must match `local`). */
+    contentPaths?: GitBackedContentPaths;
+    /** Quiet window (ms) before a flush fires. Default 3000. */
+    debounceMs?: number;
+    /** Commit message for content updates. */
+    commitMessage?: string;
+    /** Injected GitHub client (tests pass a mock). Overrides token/fetch. */
+    client?: GitHubClient;
+    /** Injected fetch, forwarded to the default GitHub client. */
+    fetch?: FetchLike;
+    /** API base override, forwarded to the default GitHub client (tests). */
+    apiBase?: string;
+    /** Warn sink (tests capture). Default console.warn. */
+    warn?: (msg: string) => void;
+    /** Error sink for push failures (tests capture). Default console.error. */
+    onError?: (msg: string, err: unknown) => void;
+}
+/** The extra control surface the git adapter adds on top of CanciaStorageV2. */
+interface GitBackedControls {
+    /**
+     * Force any pending dirty files to commit now, bypassing the debounce.
+     * Resolves once the flush completes (or rejects if the push failed — the
+     * files stay dirty for the next flush). For tests + graceful shutdown.
+     */
+    flush(): Promise<void>;
+    /** True if git commits are active (token present). */
+    readonly gitEnabled: boolean;
+    /** Snapshot of currently-dirty repo-relative paths (for tests/inspection). */
+    pendingPaths(): string[];
+}
+type GitBackedStorage = CanciaStorageV2 & {
+    git: GitBackedControls;
+};
+declare function createGitBackedAdapter(opts: GitBackedOptions): GitBackedStorage;
+
+export { type GitBackedContentPaths as G, type SqliteV2Options as S, type GitBackedControls as a, type GitBackedOptions as b, type GitBackedStorage as c, closeSqliteAdapterV2 as d, createGitBackedAdapter as e, createJsonFileAdapter as f, createJsonFileAdapterV2 as g, createSQLiteAdapter as h, createSqliteAdapterV2 as i };

package/dist/github-client-BAZ1pW24.d.ts

@@ -0,0 +1,48 @@
+/** Minimal fetch signature — matches the global `fetch` we depend on. */
+type FetchLike = (input: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}>;
+interface GitHubCommitter {
+    name: string;
+    email: string;
+}
+interface GitHubClientOptions {
+    /** "owner/name" */
+    repo: string;
+    /** Branch to commit onto, e.g. "main". */
+    branch: string;
+    /** Fine-grained PAT with contents:write on the one repo. */
+    token: string;
+    /** Optional committer identity. GitHub uses the token's user if omitted. */
+    committer?: GitHubCommitter;
+    /** Injectable fetch (defaults to global fetch) — tests mock this. */
+    fetch?: FetchLike;
+    /** API base — defaults to https://api.github.com. Overridable for tests. */
+    apiBase?: string;
+}
+interface CommitFile {
+    /** Repo-relative path, forward slashes, no leading slash. */
+    path: string;
+    /** Raw file content (UTF-8 text). Encoded to base64 before PUT. */
+    content: string;
+}
+interface GitHubClient {
+    /** Current blob sha for `path`, or null if the file doesn't exist yet. */
+    getFileSha(path: string): Promise<string | null>;
+    /**
+     * Commit each file to the branch. Updates pass the current sha; creates omit
+     * it. Resolves once every PUT succeeds; rejects (without partial silence) if
+     * any PUT fails so the caller can keep the batch dirty and retry.
+     */
+    commitFiles(files: CommitFile[], message: string): Promise<void>;
+}
+declare function createGitHubClient(opts: GitHubClientOptions): GitHubClient;
+
+export { type CommitFile as C, type FetchLike as F, type GitHubCommitter as G, type GitHubClient as a, type GitHubClientOptions as b, createGitHubClient as c };

package/dist/index.d.ts

@@ -3,9 +3,10 @@ import { C as CanciaStorage, a as CanciaStorageV2 } from './types-BMlLS-OS.js';
 export { b as CanciaKVStore, c as CanciaListStore, d as CanciaPageStore, L as ListEntry, P as PageMeta, e as PageRecord, f as PageSEO, R as Rev, g as RevConflictError } from './types-BMlLS-OS.js';
 import { U as UploadHandler } from './upload-DwCGjXbz.js';
 export { m as makeLocalUploadHandler } from './upload-DwCGjXbz.js';
+import { G as GitHubCommitter } from './github-client-BAZ1pW24.js';
 export { CanciaLoaderOptions, canciaLoader } from './loader/index.js';
 export { FieldDescription, FieldMeta, FieldMetaBase, FieldWidget, ListDescription, ListSchema, SchemasModule, defineField, defineList, describeList } from './schema/index.js';
-export { GitBackedContentPaths, GitBackedControls, GitBackedOptions, GitBackedStorage, createGitBackedAdapter, createJsonFileAdapter, createJsonFileAdapterV2, createSQLiteAdapter } from './storage/index.js';
+export { G as GitBackedContentPaths, a as GitBackedControls, b as GitBackedOptions, c as GitBackedStorage, S as SqliteV2Options, d as closeSqliteAdapterV2, e as createGitBackedAdapter, f as createJsonFileAdapter, g as createJsonFileAdapterV2, h as createSQLiteAdapter, i as createSqliteAdapterV2 } from './git-backed-DFAB0tzf.js';
 export { z } from 'zod';
 import 'astro/loaders';
 import './portable-text-BikSqS9T.js';
@@ -47,6 +48,17 @@ interface CanciaIntegrationOptions {
     accentColor?: string;
     /** Deploy hook URL. Reads CANCIA_DEPLOY_HOOK env var if not set. */
     deployHook?: string;
+    /**
+     * Auth token for the deploy hook (e.g. Coolify's "auth required" hook).
+     * When set, the publish POST sends `Authorization: Bearer <token>`.
+     * SECRET — prefer the CANCIA_DEPLOY_HOOK_TOKEN env var (read at runtime,
+     * never baked into the build). This option is a dev/testing convenience.
+     */
+    deployHookToken?: string;
+    /** Optional HTTP method for the deploy hook. Default: "POST". */
+    deployHookMethod?: string;
+    /** Optional extra headers merged into the deploy-hook request. */
+    deployHookHeaders?: Record<string, string>;
     /**
      * Custom storage adapter.
      * Default: SQLite (cancia.db in project root) — works anywhere with Node.
@@ -89,6 +101,50 @@ interface CanciaIntegrationOptions {
      * (named or default) — a record of list name → defineList() output.
      */
     schemasPath?: string;
+    /**
+     * Declarative v2 storage backend — bakes SERIALISABLY into the runtime
+     * descriptor so a fresh production SSR server reconstructs the same adapter
+     * from config + `process.cwd()` (no live object crosses the build→deploy
+     * boundary). Prefer this over a live `storageV2` object for production.
+     *
+     * - `{ kind: "sqlite" }` (recommended) — the everything-store: KV + pages +
+     *   lists in ONE `.db` per site (default `<root>/cancia.db`; override with
+     *   `path`, relative paths resolve against the project root). Gitignore the
+     *   `.db` for webhook-publish sites — it is NOT committed (contrast the
+     *   git-backed model).
+     * - `{ kind: "json-file" }` — the JSON-file v2 default (files under
+     *   `<root>/.cancia/`).
+     *
+     * Ignored when `git` is set (git-backed wins) or `storageV2` is passed as a
+     * live object (dev uses that eagerly).
+     */
+    db?: {
+        kind: "sqlite" | "json-file";
+        path?: string;
+    };
+    /**
+     * Git-backed storage, described SERIALISABLY so a production SSR server can
+     * reconstruct the adapter in its own (fresh) process from this config + the
+     * `CANCIA_GITHUB_TOKEN` env var. Prefer this over passing a live
+     * `storageV2: createGitBackedAdapter(...)` object: a live adapter constructed
+     * during config evaluation cannot cross the build→deploy process boundary,
+     * so it would silently degrade to local-only in production. When `git` is
+     * set, Cancia builds the git-backed adapter (wrapping a JSON-file v2 local
+     * store) lazily at first request. The token is NEVER baked — it is read from
+     * `process.env.CANCIA_GITHUB_TOKEN` at runtime.
+     */
+    git?: {
+        /** "owner/name" of the GitHub repo whose builds carry the content. */
+        repo: string;
+        /** Branch to commit onto. Default "main". */
+        branch?: string;
+        /** Optional committer identity for commits. */
+        committer?: GitHubCommitter;
+        /** Quiet window (ms) before a flush fires. Default 3000. */
+        debounceMs?: number;
+        /** Commit message for content updates. */
+        commitMessage?: string;
+    };
 }
 declare function canciaIntegration(opts?: CanciaIntegrationOptions): AstroIntegration;