@cancia/astro 0.0.1

package/dist/loader/index.d.ts

@@ -0,0 +1,26 @@
+import { Loader } from 'astro/loaders';
+import { a as CanciaStorageV2 } from '../types-BMlLS-OS.js';
+
+interface CanciaLoaderOptions {
+    /** The list name as declared in src/cms/schemas.ts. */
+    list: string;
+    /**
+     * Site identifier. Must match the integration's `site` option so the
+     * loader reads from the same directory the routes write to.
+     */
+    site: string;
+    /**
+     * Custom storage adapter. Defaults to the JSON-file v2 adapter rooted at
+     * `process.cwd()` — which is the project root during Astro's content sync.
+     * Override to point at a different location (testing, monorepos, etc.).
+     */
+    storage?: CanciaStorageV2;
+    /**
+     * Override the project root used when constructing the default JSON-file
+     * adapter. Ignored when `storage` is supplied.
+     */
+    projectRoot?: string;
+}
+declare function canciaLoader(opts: CanciaLoaderOptions): Loader;
+
+export { type CanciaLoaderOptions, canciaLoader };

package/dist/loader/index.js

@@ -0,0 +1,7 @@
+import {
+  canciaLoader
+} from "../chunk-YQDZQSES.js";
+import "../chunk-7IA5B5CF.js";
+export {
+  canciaLoader
+};

package/dist/runtime.d.ts

@@ -0,0 +1,34 @@
+import { C as CanciaStorage, a as CanciaStorageV2 } from './types-BMlLS-OS.js';
+import { U as UploadHandler } from './upload-DwCGjXbz.js';
+
+interface CanciaRuntime {
+    /** v1 KV-only storage. Kept for the existing /content endpoint. */
+    storage: CanciaStorage;
+    /**
+     * v2 aggregate storage (KV + pages + lists). Optional for the transition
+     * period: integrations that haven't opted in to v2 leave this undefined,
+     * and list/page routes return 503 in that case.
+     */
+    storageV2: CanciaStorageV2 | undefined;
+    /** Absolute path to the user's project root, for dynamic schema imports. */
+    projectRoot: string;
+    /** Optional override for the schemas.ts path. */
+    schemasPath: string | undefined;
+    /**
+     * Default locale to use when a write request omits `?locale=`. Sourced
+     * from Astro's i18n.defaultLocale, falling back to "en" when Astro i18n
+     * isn't configured (single-language sites still go through the locale
+     * pipeline, they just always write to "en/").
+     */
+    defaultLocale: string;
+    /** All configured locales, in order with defaultLocale first. */
+    locales: string[];
+    secret: string | undefined;
+    uploadHandler: UploadHandler;
+    deployHook: string | undefined;
+    maxUploadMB: number;
+}
+declare function setCanciaRuntime(runtime: CanciaRuntime): void;
+declare function getCanciaRuntime(): CanciaRuntime;
+
+export { type CanciaRuntime, getCanciaRuntime, setCanciaRuntime };

package/dist/runtime.js

@@ -0,0 +1,8 @@
+import {
+  getCanciaRuntime,
+  setCanciaRuntime
+} from "./chunk-DGCGIEFD.js";
+export {
+  getCanciaRuntime,
+  setCanciaRuntime
+};

package/dist/schema/index.d.ts

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+export { z } from 'zod';
+
+/**
+ * Widget hint the modal form uses to pick an input element. The Zod type
+ * is authoritative for validation; this only changes the UI affordance.
+ *
+ * Inferred widgets (when .meta({ widget }) is omitted):
+ *   z.string()           → "text"
+ *   z.string() (long)    → "textarea" (heuristic by maxLength or label "body")
+ *   z.string().url()     → "url"
+ *   z.string().email()   → "email"
+ *   z.string().datetime()→ "datetime"
+ *   z.number()           → "number"
+ *   z.boolean()          → "checkbox"
+ *   z.enum([...])        → "select"
+ */
+type FieldWidget = "text" | "textarea" | "url" | "email" | "datetime" | "number" | "checkbox" | "select" | "image";
+/**
+ * Metadata attached to a Zod field via `.meta({...})`. All optional.
+ */
+interface FieldMeta {
+    /** Display label for the field. Defaults to humanised field name. */
+    label?: string;
+    /** Help text shown under the input. */
+    description?: string;
+    /** Override widget choice. */
+    widget?: FieldWidget;
+    /** Placeholder text in the input. */
+    placeholder?: string;
+}
+interface ListSchemaOptions<TFields extends Record<string, z.ZodTypeAny>> {
+    /** Display label for the list (e.g. "Blog Posts"). */
+    label: string;
+    /** Singular form for "Add new" buttons. Defaults to label minus trailing "s". */
+    labelSingular?: string;
+    /** Field name to use as the entry title in list views. */
+    titleField: keyof TFields & string;
+    /**
+     * Field name treated as the long-form body. The list view shows it as a
+     * preview snippet; the modal renders it last so it sits below all metadata.
+     * Optional — set only when the list has long-form prose.
+     */
+    bodyField?: keyof TFields & string;
+    /**
+     * Field name to use as the URL slug for entries (e.g. /blog/[slug]).
+     * Defaults to the entry ID. The server validates slug uniqueness on save.
+     */
+    slugField?: keyof TFields & string;
+    /** Field definitions. */
+    fields: TFields;
+}
+interface ListSchema<TFields extends Record<string, z.ZodTypeAny> = Record<string, z.ZodTypeAny>> {
+    label: string;
+    labelSingular: string;
+    titleField: string;
+    bodyField: string | undefined;
+    slugField: string | undefined;
+    fields: TFields;
+    /** Zod object schema combining all fields, for one-shot validation. */
+    validator: z.ZodObject<TFields>;
+}
+declare function defineList<TFields extends Record<string, z.ZodTypeAny>>(opts: ListSchemaOptions<TFields>): ListSchema<TFields>;
+/**
+ * One field as seen by the modal form. Plain JSON, no Zod refs.
+ */
+interface FieldDescription {
+    name: string;
+    label: string;
+    description?: string;
+    widget: FieldWidget;
+    required: boolean;
+    placeholder?: string;
+    /** For select widgets: the enum values. */
+    options?: string[];
+    /** For string widgets: min/max length. */
+    minLength?: number;
+    maxLength?: number;
+    /** For number widgets: min/max. */
+    min?: number;
+    max?: number;
+}
+interface ListDescription {
+    name: string;
+    label: string;
+    labelSingular: string;
+    titleField: string;
+    bodyField?: string;
+    slugField?: string;
+    fields: FieldDescription[];
+}
+declare function describeList(name: string, schema: ListSchema): ListDescription;
+/** Map of list name → schema. What users export from src/cms/schemas.ts. */
+type SchemasModule = Record<string, ListSchema>;
+
+export { type FieldDescription, type FieldMeta, type FieldWidget, type ListDescription, type ListSchema, type ListSchemaOptions, type SchemasModule, defineList, describeList };

package/dist/schema/index.js

@@ -0,0 +1,10 @@
+import {
+  defineList,
+  describeList,
+  z
+} from "../chunk-QAM5VKAF.js";
+export {
+  defineList,
+  describeList,
+  z
+};

package/dist/types-BMlLS-OS.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Revision token for optimistic concurrency. Opaque to callers — only equality
+ * matters. JSON-file adapter uses a SHA-256 hash of canonical JSON; a SQL
+ * adapter could use a row version column. Mismatches on write must throw
+ * a RevConflictError.
+ */
+type Rev = string;
+declare class RevConflictError extends Error {
+    readonly name = "RevConflictError";
+    constructor(message?: string);
+}
+type CMSData = Record<string, string>;
+interface CanciaKVStore {
+    /** Get a single value. Returns null if not found. */
+    get(site: string, key: string, lang: string): Promise<string | null>;
+    /** Upsert a value. */
+    set(site: string, key: string, lang: string, value: string): Promise<void>;
+    /** Get all overrides for a site as a flat map: "key.lang" → value. */
+    getAll(site: string): Promise<CMSData>;
+    /** Delete a single override. */
+    delete(site: string, key: string, lang: string): Promise<void>;
+}
+/**
+ * @deprecated Use CanciaKVStore. Kept as an alias so existing adapter code
+ * (createJsonFileAdapter, createSQLiteAdapter) compiles without changes.
+ */
+type CanciaStorage = CanciaKVStore;
+/**
+ * SEO fields the agent and visual editor can write. Subset of what a typical
+ * SEO integration consumes (e.g. astro-seo-graph). Fields are optional so
+ * pages can override only what they need; the site default fills the rest.
+ */
+interface PageSEO {
+    title?: string;
+    description?: string;
+    /** Override the canonical URL. Rarely needed — Astro emits one by default. */
+    canonical?: string;
+    /** Open Graph image URL (already uploaded; not a file). */
+    ogImage?: string;
+    /** Twitter card image URL — defaults to ogImage if omitted. */
+    twitterImage?: string;
+    /** robots meta: e.g. "noindex, nofollow". Omit for default indexing. */
+    robots?: string;
+}
+/**
+ * One record per route. `metadata` is open-ended for future fields the agent
+ * might want to attach (publish date overrides, A/B variant flags, etc.) so
+ * the schema doesn't need to grow every time.
+ */
+interface PageMeta {
+    seo?: PageSEO;
+    metadata?: Record<string, unknown>;
+}
+interface PageRecord {
+    /** Route path, e.g. "/", "/blog", "/blog/[slug]". Includes the leading slash. */
+    route: string;
+    meta: PageMeta;
+    _rev: Rev;
+}
+interface CanciaPageStore {
+    /** Get the meta for a route. Returns null if no overrides exist. */
+    get(site: string, route: string): Promise<PageRecord | null>;
+    /** List all routes that have meta. */
+    list(site: string): Promise<PageRecord[]>;
+    /**
+     * Upsert page meta. Pass the `_rev` from the last read to enforce
+     * optimistic concurrency. Omit `_rev` on first write (route had no prior
+     * record). Throws RevConflictError on mismatch.
+     */
+    set(site: string, route: string, meta: PageMeta, rev?: Rev): Promise<PageRecord>;
+    /** Remove all meta for a route. */
+    delete(site: string, route: string): Promise<void>;
+}
+/**
+ * One entry in a list. Shape is validated at the route layer against the
+ * schema declared in `src/cms/schemas.ts`; storage is shape-agnostic.
+ *
+ * `id` is stable across edits and is the URL slug component for entries
+ * exposed on the public site (e.g. `/blog/[id].astro`). Callers pass an
+ * explicit ID on create (typically the user's slug); if omitted, the
+ * adapter generates a random one — but the recommended pattern is to
+ * have the schema declare a slugField so creates are always deterministic.
+ *
+ * `locale` identifies which language this entry was authored in. Translation
+ * pairs share the same `id` across locales — that's how the loader and the
+ * toolbar know two entries are translations of each other.
+ */
+interface ListEntry {
+    id: string;
+    /** Locale this entry was authored in (e.g. "en", "es"). */
+    locale: string;
+    /** Arbitrary fields — validated against the list's schema upstream. */
+    data: Record<string, unknown>;
+    /** When this entry was first created. */
+    createdAt: string;
+    /** When this entry was last updated. */
+    updatedAt: string;
+    /** Per-entry revision token for optimistic concurrency. */
+    _rev: Rev;
+}
+/**
+ * Translation status for a single list entry — which locales have a
+ * file for this ID. The toolbar uses this to render "not translated"
+ * badges and to power the "translate this entry" affordance.
+ */
+interface TranslationStatus {
+    id: string;
+    /** Locales where an entry with this ID exists. */
+    locales: string[];
+}
+interface CanciaListStore {
+    /**
+     * List entries in a list. When `locale` is provided, returns only entries
+     * authored in that locale. When omitted, returns entries from all locales
+     * tagged with their `locale` field — used by the Content Layer loader to
+     * emit every translation in one pass.
+     * Stored order is shared across locales (driven by a single _order index),
+     * so calling list(...,"en") and list(...,"es") returns the same IDs in the
+     * same positions when both locales have the entry.
+     */
+    list(site: string, listName: string, locale?: string): Promise<ListEntry[]>;
+    /** Get one entry by ID + locale. Returns null if not found. */
+    get(site: string, listName: string, id: string, locale: string): Promise<ListEntry | null>;
+    /**
+     * Create a new entry in `locale`. If `id` is omitted, the adapter
+     * generates a random one. If an entry with this id+locale already exists,
+     * throws. New IDs are appended to the shared order index; if the ID
+     * already exists in another locale (i.e. this create is a translation),
+     * the existing position is reused.
+     */
+    create(site: string, listName: string, data: Record<string, unknown>, locale: string, id?: string): Promise<ListEntry>;
+    /**
+     * Update an entry's data. Pass the `_rev` from the last read; mismatch
+     * throws RevConflictError. Position is unchanged.
+     */
+    update(site: string, listName: string, id: string, locale: string, data: Record<string, unknown>, rev: Rev): Promise<ListEntry>;
+    /**
+     * Delete an entry for a specific locale. If this was the last locale
+     * with the entry, the ID is also removed from the order index.
+     */
+    delete(site: string, listName: string, id: string, locale: string): Promise<void>;
+    /**
+     * Replace the canonical order of entries by ID. Order is shared across
+     * locales — an ID at position 0 sits there in every locale. IDs not in
+     * `ids` are dropped from the order (and from storage in every locale).
+     * Atomic.
+     */
+    reorder(site: string, listName: string, ids: string[]): Promise<void>;
+    /**
+     * For each entry ID in the list, report which locales have it.
+     * Used by the toolbar to flag untranslated entries.
+     */
+    translations(site: string, listName: string): Promise<TranslationStatus[]>;
+}
+interface CanciaStorageV2 {
+    kv: CanciaKVStore;
+    pages: CanciaPageStore;
+    lists: CanciaListStore;
+}
+
+export { type CanciaStorage as C, type ListEntry as L, type PageMeta as P, type Rev as R, type CanciaStorageV2 as a, type CanciaKVStore as b, type CanciaListStore as c, type CanciaPageStore as d, type PageRecord as e, type PageSEO as f, RevConflictError as g };

package/dist/upload-DwCGjXbz.d.ts

@@ -0,0 +1,13 @@
+interface DetectedImage {
+    mime: string;
+    ext: string;
+}
+
+type UploadHandler = (file: File, site: string, detected: DetectedImage) => Promise<string>;
+declare function makeLocalUploadHandler(opts: {
+    uploadDir?: string;
+    publicUrlBase?: string;
+    maxMB?: number;
+}): UploadHandler;
+
+export { type UploadHandler as U, makeLocalUploadHandler as m };

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@cancia/astro",
+  "version": "0.0.1",
+  "description": "Astro integration for Cancia CMS — inline editing with zero separate server",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ninuzdellalb/cancia",
+    "directory": "packages/astro"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./schema": {
+      "types": "./dist/schema/index.d.ts",
+      "import": "./dist/schema/index.js"
+    },
+    "./loader": {
+      "types": "./dist/loader/index.d.ts",
+      "import": "./dist/loader/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "astro": ">=5.0.0 <8.0.0",
+    "better-sqlite3": ">=9.0.0"
+  },
+  "peerDependenciesMeta": {
+    "astro": {
+      "optional": false
+    },
+    "better-sqlite3": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "astro": "^7.0.0",
+    "better-sqlite3": "^11.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vite": "^8.0.0"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}