fimo 0.3.6-staging.1 → 0.4.0-experimental.1

package/assets/content-templates/hooks-template.eta

@@ -64,6 +64,8 @@ function getTypeForField(field) {
       return 'Record<string, any>';
     case 'media':
       return field.multiple ? 'FimoMedia[]' : 'FimoMedia';
+    case 'relation':
+      return field.many ? 'Array<string | Record<string, any>>' : 'string | Record<string, any> | null';
     default:
       return 'any';
   }
@@ -216,7 +218,7 @@ export async function getByField(fieldName: string, value: string, options: { lo
 }
 
 function toQueryString<TFields extends <%= model.pascal %>Fields | undefined = undefined>(params: <%= model.pascal %>Query<TFields> = {} as <%= model.pascal %>Query<TFields>): string {
-  const { where, sort, fields, ...flat } = params;
+  const { where, sort, fields, populate, ...flat } = params;
   const query = new URLSearchParams();
 
   for (const [key, value] of Object.entries(flat)) {
@@ -229,7 +231,11 @@ function toQueryString<TFields extends <%= model.pascal %>Fields | undefined = u
   }
 
   if (fields != null) {
-    query.set("fields", Array.isArray(fields) ? fields.join(",") : fields);
+    query.set("fields", typeof fields === "string" ? fields : fields.join(","));
+  }
+
+  if (populate != null) {
+    query.set("populate", typeof populate === "string" ? populate : populate.join(","));
   }
 
   if (where && Object.keys(where).length > 0) {

package/assets/skills/fimo/references/content.md

@@ -16,7 +16,9 @@ This file covers the **package surface**: the JSON shape you write, the generate
     "publishDate": { "type": "string" },
     "featured": { "type": "boolean" },
     "coverImage": { "type": "media" },
-    "metadata": { "type": "json" }
+    "metadata": { "type": "json" },
+    "author": { "type": "relation", "target": "Author" },
+    "contributors": { "type": "relation", "target": "Author", "many": true }
   }
 }
 ```
@@ -32,7 +34,7 @@ reserved entry metadata and cannot be used as a content field.`):
 `id`, `documentId`, `slug`, `locale`, `createdAt`, `updatedAt`, `__fimo`.
 
 In particular **do not add a `slug` field** — every entry gets a `slug` for free. You still
-pass `slug` inside `data` when *creating an entry* (see "Entry body shape" below); it just
+pass `slug` inside `data` when _creating an entry_ (see "Entry body shape" below); it just
 must not appear in the schema's `fields`. If you need an additional URL-ish string, name it
 something else (e.g. `handle`, `permalink`).
 
@@ -47,9 +49,47 @@ something else (e.g. `handle`, `permalink`).
 | `date`     | ISO date string, e.g. `"2026-06-03"`                                    | Publish dates, timestamps         |
 | `media`    | `{ "source": "local"\|"external", "url": "https://...", "alt": "..." }` | Images, video                     |
 | `json`     | any JSON                                                                | Structured metadata               |
+| `relation` | document ID string, `null`, or document ID array when `many: true`      | References to another schema      |
 
 A `date` field currently generates as `any` in the TS client, so for typed access (and the `<Date>` component) prefer a `string` field holding an ISO date — which is what the `publishDate` examples below do.
 
+## Relation fields
+
+Use `relation` when one content entry references another content entry. Do not store entry IDs in a `json` field as a workaround.
+
+```json
+{
+  "uid": "BlogPost",
+  "name": "Blog Posts",
+  "fields": {
+    "title": { "type": "string" },
+    "author": { "type": "relation", "target": "Author" },
+    "contributors": { "type": "relation", "target": "Author", "many": true }
+  }
+}
+```
+
+Rules:
+
+- `target` is required and must be the PascalCase schema `uid` of the referenced content type.
+- Omit `many` for a to-one relation. Use `"many": true` for a to-many relation.
+- Self-references are allowed, e.g. a `Category` schema can have `parent: { "type": "relation", "target": "Category" }`.
+- Entry values store target `documentId` values, not row `id` values. Use `null` for an empty to-one relation and `[]` for an empty to-many relation.
+- The API validates that referenced target documents exist and rejects duplicate values in to-many relation arrays.
+
+Entry payload example:
+
+```json
+{
+  "data": {
+    "slug": "relation-example",
+    "title": "Relation example",
+    "author": "750e8400-e29b-41d4-a716-446655440000",
+    "contributors": ["750e8400-e29b-41d4-a716-446655440000"]
+  }
+}
+```
+
 **Default to `richtext`** for fields named `body`, `content`, `description`, `summary`, `bio`, `intro`, `details`, `excerpt` — only use `string` when the field is explicitly short (e.g. a 160-char meta description).
 
 ## Tiptap JSONContent (richtext)
@@ -183,7 +223,7 @@ if (isLoading || !posts) return null;
 posts.map((post) => /* ... */); // BlogPost[]
 ```
 
-Query params supported: `limit` (1-100, default 20), `offset` (default 0), `search`, `sort`, `where`, and `fields`. Use these canonical names in new code.
+Query params supported: `limit` (1-100, default 20), `offset` (default 0), `search`, `sort`, `where`, `fields`, and `populate`. Use these canonical names in new code.
 
 `where` filters on the server. Use scalar values for equality and operator objects for ranges, lists, text matches, or null checks. Keep boolean, string, and number values typed in the object:
 
@@ -215,21 +255,35 @@ const { data: summaries = [] } = BlogPost.useGet({
 // summaries: Array<Pick<BlogPost, 'id' | 'slug' | 'title' | 'excerpt' | 'coverImage'>>
 ```
 
+Use `populate` to embed relation targets in read results:
+
+```tsx
+const { data: posts = [] } = BlogPost.useGet({
+  fields: ['slug', 'title', 'author'] as const,
+  populate: ['author'] as const,
+});
+// Without populate: post.author is a target documentId string.
+// With populate: post.author is the target Author entry object, or null.
+```
+
+Populate is depth-one. It only works for relation fields; trying to populate a scalar field returns 400. To-many relation order is preserved.
+
 The generated hooks do **not** surface pagination meta (`total`, `hasMore`, `limit`, `offset`). If you need it, read it from a raw fetch to `/entries/<typeName>` (see the **Read path** section below), which returns the full `{ data, meta }` envelope.
 
 ## Fimo primitives (what the field values are)
 
 The entry objects a hook returns are **not** plain JS values. The generated client wraps each _trackable_ field in a `fimo/ui` primitive that carries source metadata for inline editing. Which fields wrap, and which stay plain:
 
-| Schema field type | Field value you get         | Notes                                               |
-| ----------------- | --------------------------- | --------------------------------------------------- |
-| `string`          | `FimoString`                | `extends String` — **not** a primitive `string`     |
-| `richtext`        | `FimoRichText`              | Tiptap JSONContent + source metadata                |
-| `boolean`         | `FimoBoolean`               | class; `.valueOf()` → `boolean`                     |
-| `media`           | `FimoMedia` / `FimoMedia[]` | shape + rendering in `references/assets.md`         |
-| `number`          | `number`                    | plain — not wrapped                                 |
-| `json`            | `Record<string, any>`       | plain — not wrapped                                 |
-| `date`            | `any` (raw ISO date string) | not wrapped (`FimoDate` is not emitted — see below) |
+| Schema field type | Field value you get         | Notes                                                                                        |
+| ----------------- | --------------------------- | -------------------------------------------------------------------------------------------- |
+| `string`          | `FimoString`                | `extends String` — **not** a primitive `string`                                              |
+| `richtext`        | `FimoRichText`              | Tiptap JSONContent + source metadata                                                         |
+| `boolean`         | `FimoBoolean`               | class; `.valueOf()` → `boolean`                                                              |
+| `media`           | `FimoMedia` / `FimoMedia[]` | shape + rendering in `references/assets.md`                                                  |
+| `number`          | `number`                    | plain — not wrapped                                                                          |
+| `json`            | `Record<string, any>`       | plain — not wrapped                                                                          |
+| `date`            | `any` (raw ISO date string) | not wrapped (`FimoDate` is not emitted — see below)                                          |
+| `relation`        | `string` / `string[]`       | target `documentId` value(s); use `populate` on raw API when embedded target rows are needed |
 
 Rules of thumb:
 

package/assets/skills/fimo-cli/references/content.md

@@ -36,7 +36,7 @@ Entries are NOT JSON-file-driven. Create/update them via CLI.
 ```bash
 fimo entries create <TypeName> --body '<json>'
 fimo entries create <TypeName> --locale es --document-id <documentId> --body '<json>'
-fimo entries list <TypeName> [--limit N] [--offset N] [--search Q] [--where JSON] [--sort F] [--fields FIELDS]
+fimo entries list <TypeName> [--limit N] [--offset N] [--search Q] [--where JSON] [--sort F] [--fields FIELDS] [--populate FIELDS]
 fimo entries list <TypeName> --locale es
 fimo entries get <TypeName> <id>
 fimo entries update <TypeName> <id> --locale es --body '<json>'
@@ -54,12 +54,32 @@ fimo entries list BlogPost --where '{"__fimo":{"contentType":{"$eq":"BlogPost"}}
 fimo entries list BlogPost --search "launch"
 fimo entries list BlogPost --limit 10 --offset 20 --sort title
 fimo entries list BlogPost --fields slug,title,excerpt,coverImage --sort -publishedAt --limit 12
+fimo entries list BlogPost --fields slug,title,author --populate author
 ```
 
 Use the canonical read query flags: `--search`, `--sort`, `--where`, `--limit`, `--offset`, and `--fields`.
 `--where` is a JSON object keyed by schema field name. Simple values mean equality, so booleans, strings, and numbers should stay typed inside the JSON (`{"featured":true}`, `{"category":"react"}`, `{"rank":{"$gte":3}}`). Public Fimo-owned metadata lives under `__fimo`; currently `__fimo.contentType` is filterable. Operator objects support `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$contains`, `$startsWith`, and `$null`, subject to the field type. Use `--sort field` for ascending and `--sort -field` for descending.
 `--fields` is a comma-separated projection for list payloads. The API always keeps `id`; pass only the fields your view needs, such as `slug,title,excerpt,coverImage`.
 
+`--populate` is a comma-separated list of relation fields to embed. Without `--populate`, relation fields return target `documentId` strings. With `--populate author,contributors`, those fields return the target entry objects for the requested locale. Only relation fields can be populated; asking to populate a scalar field returns 400.
+
+For relation schema JSON and entry value shape, load `fimo/references/content.md` § Relation fields. The short version:
+
+```json
+{
+  "fields": {
+    "author": { "type": "relation", "target": "Author" },
+    "contributors": { "type": "relation", "target": "Author", "many": true }
+  }
+}
+```
+
+Entry bodies store target `documentId` values:
+
+```bash
+fimo entries create BlogPost --body '{"data":{"slug":"hello","title":"Hello","author":"750e8400-e29b-41d4-a716-446655440000","contributors":[]}}'
+```
+
 ## Localized content
 
 Content entries are stored per locale. Omit `--locale` for default-locale entries. Pass `--locale <locale>` when creating, listing, reading, or updating a specific non-default locale.

package/dist/cli/bundle.json

@@ -1,7 +1,7 @@
 {
   "bundled": true,
   "bundler": "esbuild",
-  "bundledAt": "2026-07-07T18:48:49.464Z",
+  "bundledAt": "2026-07-08T14:52:17.138Z",
   "cliVersion": "0.3.5",
   "external": [
     "oxc-parser",

package/dist/cli/index.js

@@ -41921,7 +41921,7 @@ var init_pagination = __esm({
 });
 
 // ../../packages/api-contracts/dist/esm/types/common.js
-var CommonSchemas, BaseEntitySchema, ProjectRoleKeySchema, ProjectRoleKeyWithSystemSchema, ProjectPrincipalTypeSchema, ProjectVisibilitySchema, ProjectStatusSchema, ProjectInviteStatusSchema, PublicationStatusSchema, OrganizationRoleSchema, AssetTypeSchema, TemplateCodeSchema, FieldTypeSchema, RESERVED_CONTENT_FIELD_NAMES;
+var CommonSchemas, BaseEntitySchema, ProjectRoleKeySchema, ProjectRoleKeyWithSystemSchema, ProjectPrincipalTypeSchema, ProjectVisibilitySchema, ProjectStatusSchema, ProjectInviteStatusSchema, PublicationStatusSchema, OrganizationRoleSchema, AssetTypeSchema, TemplateCodeSchema, FieldTypeSchema, RESERVED_CONTENT_FIELD_NAMES, CONTENT_TYPE_NAME_PATTERN, CONTENT_TYPE_NAME_PATTERN_DESCRIPTION, CONTENT_FIELD_NAME_PATTERN, CONTENT_FIELD_NAME_PATTERN_DESCRIPTION;
 var init_common = __esm({
   "../../packages/api-contracts/dist/esm/types/common.js"() {
     "use strict";
@@ -42000,7 +42000,8 @@ var init_common = __esm({
       "number",
       "boolean",
       "date",
-      "json"
+      "json",
+      "relation"
     ]);
     RESERVED_CONTENT_FIELD_NAMES = [
       "id",
@@ -42011,6 +42012,10 @@ var init_common = __esm({
       "updatedAt",
       "__fimo"
     ];
+    CONTENT_TYPE_NAME_PATTERN = /^[A-Za-z]\w*$/;
+    CONTENT_TYPE_NAME_PATTERN_DESCRIPTION = "letters, numbers, and underscores, starting with a letter";
+    CONTENT_FIELD_NAME_PATTERN = /^[A-Za-z_]\w*$/;
+    CONTENT_FIELD_NAME_PATTERN_DESCRIPTION = "letters, numbers, and underscores, starting with a letter or underscore";
   }
 });
 
@@ -45831,6 +45836,16 @@ function planRemoteConfig(remoteUrl) {
   const credentialKey = `credential.${u2.protocol}//${u2.host}`;
   return { cleanUrl, credentialKey };
 }
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function credentialHelperCommand(argv = process.argv) {
+  const entry = argv[1];
+  if (!entry) {
+    return "!fimo git-credential";
+  }
+  return `!${shellQuote(process.execPath)} ${shellQuote(entry)} git-credential`;
+}
 async function ensureFimoRemote(cwd, remoteUrl) {
   const { cleanUrl, credentialKey } = planRemoteConfig(remoteUrl);
   await runGit2(["remote", "set-url", "fimo", cleanUrl], cwd).catch(async () => {
@@ -45838,7 +45853,7 @@ async function ensureFimoRemote(cwd, remoteUrl) {
   });
   await runGit2(["config", "--unset-all", `${credentialKey}.helper`], cwd).catch(() => void 0);
   await runGit2(["config", "--add", `${credentialKey}.helper`, ""], cwd);
-  await runGit2(["config", "--add", `${credentialKey}.helper`, "!fimo git-credential"], cwd);
+  await runGit2(["config", "--add", `${credentialKey}.helper`, credentialHelperCommand()], cwd);
   await runGit2(["config", `${credentialKey}.useHttpPath`, "true"], cwd);
   await runGit2(["config", `${credentialKey}.username`, "t"], cwd);
 }
@@ -45846,6 +45861,8 @@ var init_git_credential_setup = __esm({
   "src/cli/utils/git-credential-setup.ts"() {
     init_git();
     __name(planRemoteConfig, "planRemoteConfig");
+    __name(shellQuote, "shellQuote");
+    __name(credentialHelperCommand, "credentialHelperCommand");
     __name(ensureFimoRemote, "ensureFimoRemote");
   }
 });
@@ -101079,6 +101096,10 @@ __name(listTemplatesCommand, "listTemplatesCommand");
 import fs15 from "node:fs";
 import path19 from "node:path";
 init_dist();
+init_api();
+init_auth();
+init_config2();
+init_project();
 async function runValidateAgents(opts) {
   const projectRoot = resolveProjectRoot(opts.cwd ?? process.cwd());
   const agentsDir = path19.join(projectRoot, "agents");
@@ -101261,6 +101282,94 @@ function validateOneBundle(bundle, allBundles) {
   return { name: bundle.name, ok, phases, warnings };
 }
 __name(validateOneBundle, "validateOneBundle");
+async function runAvailabilityChecks(cwd) {
+  const projectRoot = resolveProjectRoot(cwd);
+  let projectId;
+  try {
+    projectId = loadProjectSettings(projectRoot).projectId;
+  } catch {
+    projectId = process.env.FIMO_PROJECT_ID?.trim() ?? "";
+    if (!projectId) {
+      return { ok: true, skippedReason: "not-linked", issues: [] };
+    }
+  }
+  if (!process.env.FIMO_API_TOKEN?.trim() && !readCredentials()) {
+    return { ok: true, skippedReason: "not-signed-in", issues: [] };
+  }
+  const api = new FimoApiClient(loadConfig());
+  const bundles = await listBundles(path19.join(projectRoot, "agents"));
+  const issues = [];
+  const integrationsByAgent = bundles.map((bundle) => ({
+    name: bundle.name,
+    integrations: Object.entries(agentIntegrationPolicy(bundle.config)).map(([integrationKey, entry]) => ({
+      integrationKey,
+      enabled: entry.enabled,
+      tools: enabledAgentIntegrationTools(entry)
+    })).filter((entry) => entry.enabled)
+  })).filter((entry) => entry.integrations.length > 0);
+  if (integrationsByAgent.length > 0) {
+    const statuses = await api.listProjectIntegrations(projectId);
+    const statusByKey = new Map(statuses.map((status) => [status.integrationKey, status]));
+    const infoByKey = /* @__PURE__ */ new Map();
+    for (const agent of integrationsByAgent) {
+      for (const integration of agent.integrations) {
+        const file2 = `agents/${agent.name}/config.yaml`;
+        const status = statusByKey.get(integration.integrationKey);
+        if (!status) {
+          issues.push({
+            pointer: file2,
+            message: `${agent.name} allows unsupported integration ${integration.integrationKey}.`
+          });
+          continue;
+        }
+        if (integration.tools.length === 0) {
+          issues.push({
+            pointer: file2,
+            message: `${agent.name} enables ${integration.integrationKey}, but no tools are allowed. Set at least one integrations.${integration.integrationKey}.tools.<tool>: true entry.`
+          });
+        }
+        if (!status.enabled) {
+          issues.push({
+            pointer: file2,
+            message: `${agent.name} allows ${integration.integrationKey}, but the project integration is not enabled. Run: fimo integrations enable ${integration.integrationKey}`
+          });
+        }
+        const info = infoByKey.get(integration.integrationKey) ?? await api.getProjectIntegrationInfo(projectId, integration.integrationKey);
+        infoByKey.set(integration.integrationKey, info);
+        const knownTools = new Set(info.tools.map((tool) => tool.key));
+        for (const tool of integration.tools) {
+          if (!knownTools.has(tool)) {
+            issues.push({
+              pointer: file2,
+              message: `${agent.name} allows unknown ${integration.integrationKey}.${tool} tool. Supported tools: ${[...knownTools].sort().join(", ")}`
+            });
+          }
+        }
+      }
+    }
+  }
+  const secretsByAgent = bundles.map((bundle) => ({
+    name: bundle.name,
+    keys: (bundle.config.secrets ?? []).filter((secret) => secret.required !== false).map((secret) => secret.key)
+  })).filter((entry) => entry.keys.length > 0);
+  if (secretsByAgent.length > 0) {
+    const defined = new Set(
+      (await api.listProjectSecretEntries(projectId, { kind: "secret" })).map((secret) => secret.key)
+    );
+    for (const entry of secretsByAgent) {
+      for (const key of entry.keys) {
+        if (!defined.has(key)) {
+          issues.push({
+            pointer: `agents/${entry.name}/config.yaml`,
+            message: `${entry.name} requires project secret ${key}, but it is not set. Run: fimo secrets set ${key} --stdin`
+          });
+        }
+      }
+    }
+  }
+  return { ok: issues.length === 0, skippedReason: null, issues };
+}
+__name(runAvailabilityChecks, "runAvailabilityChecks");
 async function validateAgentsCommand(opts) {
   let report;
   try {
@@ -101276,6 +101385,10 @@ async function validateAgentsCommand(opts) {
     ui.info({ command: "agents validate", message: "No bundles or fimo.config.json found." });
     return report;
   }
+  report.availability = await runAvailabilityChecks(opts.cwd ?? process.cwd());
+  if (!report.availability.ok) {
+    report.ok = false;
+  }
   ui.result({
     command: "agents validate",
     data: report,
@@ -101320,6 +101433,19 @@ function renderReportHuman(report) {
       }
     }
   }
+  if (report.availability) {
+    if (report.availability.skippedReason) {
+      const why = report.availability.skippedReason === "not-signed-in" ? "not signed in \u2014 run `fimo login`" : "no linked project";
+      lines.push(`  \u21B7 integrations & secrets \u2014 skipped (${why})`);
+    } else if (report.availability.ok) {
+      lines.push("  \u2713 integrations & secrets  available");
+    } else {
+      lines.push("  \u2717 integrations & secrets");
+      for (const issue2 of report.availability.issues) {
+        lines.push(`      \u2717 ${issue2.message}`);
+      }
+    }
+  }
   return lines.join("\n");
 }
 __name(renderReportHuman, "renderReportHuman");
@@ -102283,9 +102409,9 @@ init_interactive();
 init_project_context();
 
 // src/cli/commands/validate.ts
+init_dist();
 import { readFile as readFile3 } from "node:fs/promises";
 import path29 from "node:path";
-init_dist();
 
 // src/runtime/shared/fimo-config.server.js
 import { readFileSync as readFileSync2, renameSync, writeFileSync as writeFileSync3 } from "fs";
@@ -102736,14 +102862,31 @@ function validateSchemas(options = {}) {
   }
   const files = readdirSync4(schemasDir).filter((f) => f.endsWith(".json")).sort();
   const errors2 = [];
+  const schemaUids = /* @__PURE__ */ new Set();
+  for (const fileName of files) {
+    const schema = readSchemaObject(join9(schemasDir, fileName));
+    if (schema && typeof schema.uid === "string") {
+      schemaUids.add(schema.uid);
+    }
+  }
   for (const fileName of files) {
     const file2 = join9(SCHEMAS_REL2, fileName);
-    errors2.push(...validateSchemaFile(join9(schemasDir, fileName), file2));
+    errors2.push(...validateSchemaFile(join9(schemasDir, fileName), file2, schemaUids));
   }
   return { errors: errors2, schemasChecked: files.length };
 }
 __name(validateSchemas, "validateSchemas");
-function validateSchemaFile(absolutePath, file2) {
+function readSchemaObject(absolutePath) {
+  let schema;
+  try {
+    schema = JSON.parse(readFileSync7(absolutePath, "utf-8"));
+  } catch {
+    return null;
+  }
+  return typeof schema === "object" && schema !== null && !Array.isArray(schema) ? schema : null;
+}
+__name(readSchemaObject, "readSchemaObject");
+function validateSchemaFile(absolutePath, file2, schemaUids = /* @__PURE__ */ new Set()) {
   let schema;
   try {
     schema = JSON.parse(readFileSync7(absolutePath, "utf-8"));
@@ -102774,6 +102917,12 @@ function validateSchemaFile(absolutePath, file2) {
       message: `"uid" is "${uid}" but the file is ${expectedUid}.json \u2014 they must match.`,
       file: file2
     });
+  } else if (!CONTENT_TYPE_NAME_PATTERN.test(uid)) {
+    errors2.push({
+      rule: "schemas/type-name",
+      message: `"uid" must use ${CONTENT_TYPE_NAME_PATTERN_DESCRIPTION}.`,
+      file: file2
+    });
   }
   if (typeof name !== "string" || name.length === 0) {
     errors2.push({
@@ -102791,6 +102940,14 @@ function validateSchemaFile(absolutePath, file2) {
     return errors2;
   }
   for (const [fieldName, definition] of Object.entries(fields)) {
+    if (!CONTENT_FIELD_NAME_PATTERN.test(fieldName)) {
+      errors2.push({
+        rule: "schemas/field-name",
+        message: `Field "${fieldName}" must use ${CONTENT_FIELD_NAME_PATTERN_DESCRIPTION}.`,
+        file: file2
+      });
+      continue;
+    }
     if (RESERVED_FIELD_NAMES.has(fieldName)) {
       errors2.push({
         rule: "schemas/reserved-field",
@@ -102822,6 +102979,39 @@ function validateSchemaFile(absolutePath, file2) {
         file: file2
       });
     }
+    if (type === "relation") {
+      const { target, many } = definition;
+      if (typeof target !== "string" || !CONTENT_TYPE_NAME_PATTERN.test(target)) {
+        errors2.push({
+          rule: "schemas/relation-target",
+          message: `Relation field "${fieldName}" must declare a valid "target" content type.`,
+          file: file2
+        });
+      } else if (schemaUids.size > 0 && !schemaUids.has(target)) {
+        errors2.push({
+          rule: "schemas/relation-target",
+          message: `Relation field "${fieldName}" targets unknown schema "${target}".`,
+          file: file2
+        });
+      }
+      if (many !== void 0 && typeof many !== "boolean") {
+        errors2.push({
+          rule: "schemas/relation-many",
+          message: `Relation field "${fieldName}" must use a boolean "many" value.`,
+          file: file2
+        });
+      }
+    } else {
+      for (const relationOnlyKey of ["target", "many", "localized"]) {
+        if (relationOnlyKey in definition) {
+          errors2.push({
+            rule: "schemas/relation-shape",
+            message: `Field "${fieldName}": "${relationOnlyKey}" is only supported on relation fields.`,
+            file: file2
+          });
+        }
+      }
+    }
   }
   return errors2;
 }
@@ -103590,131 +103780,12 @@ async function runAgentsCheck(opts) {
       }
     }
   }
-  errors2.push(...await runAgentSecretAvailabilityCheck({ cwd }));
-  errors2.push(...await runAgentIntegrationAvailabilityCheck({ cwd }));
   return {
     errors: errors2,
     stats: { agentsChecked: report.bundles.length }
   };
 }
 __name(runAgentsCheck, "runAgentsCheck");
-async function runAgentIntegrationAvailabilityCheck(opts) {
-  const projectRoot = resolveProjectCwd(opts.cwd);
-  let projectId;
-  try {
-    projectId = loadProjectSettings(projectRoot).projectId;
-  } catch {
-    return [];
-  }
-  const bundles = await listBundles(path29.join(projectRoot, "agents"));
-  const requiredByAgent = bundles.map((bundle) => {
-    const policy = agentIntegrationPolicy(bundle.config);
-    return {
-      name: bundle.name,
-      integrations: Object.entries(policy).map(([integrationKey, entry]) => ({
-        integrationKey,
-        enabled: entry.enabled,
-        tools: enabledAgentIntegrationTools(entry)
-      })).filter((entry) => entry.enabled)
-    };
-  }).filter((entry) => entry.integrations.length > 0);
-  if (requiredByAgent.length === 0) {
-    return [];
-  }
-  const api = new FimoApiClient(loadConfig());
-  const statuses = await api.listProjectIntegrations(projectId);
-  const statusByKey = new Map(statuses.map((status) => [status.integrationKey, status]));
-  const infoByKey = /* @__PURE__ */ new Map();
-  const errors2 = [];
-  for (const agent of requiredByAgent) {
-    for (const integration of agent.integrations) {
-      const status = statusByKey.get(integration.integrationKey);
-      if (!status) {
-        errors2.push(
-          authorError({
-            rule: "agents/integrations",
-            message: `${agent.name} allows unsupported integration ${integration.integrationKey}.`,
-            file: `agents/${agent.name}/config.yaml`
-          })
-        );
-        continue;
-      }
-      if (integration.tools.length === 0) {
-        errors2.push(
-          authorError({
-            rule: "agents/integrations",
-            message: `${agent.name} enables ${integration.integrationKey}, but no tools are allowed. Set at least one integrations.${integration.integrationKey}.tools.<tool>: true entry.`,
-            file: `agents/${agent.name}/config.yaml`
-          })
-        );
-      }
-      if (!status.enabled) {
-        errors2.push(
-          authorError({
-            rule: "agents/integrations",
-            message: `${agent.name} allows ${integration.integrationKey}, but the project integration is not enabled. Run: fimo integrations enable ${integration.integrationKey}`,
-            file: `agents/${agent.name}/config.yaml`
-          })
-        );
-      }
-      const info = infoByKey.get(integration.integrationKey) ?? await api.getProjectIntegrationInfo(projectId, integration.integrationKey);
-      infoByKey.set(integration.integrationKey, info);
-      const knownTools = new Set(info.tools.map((tool) => tool.key));
-      for (const tool of integration.tools) {
-        if (!knownTools.has(tool)) {
-          errors2.push(
-            authorError({
-              rule: "agents/integrations",
-              message: `${agent.name} allows unknown ${integration.integrationKey}.${tool} tool. Supported tools: ${[
-                ...knownTools
-              ].sort().join(", ")}`,
-              file: `agents/${agent.name}/config.yaml`
-            })
-          );
-        }
-      }
-    }
-  }
-  return errors2;
-}
-__name(runAgentIntegrationAvailabilityCheck, "runAgentIntegrationAvailabilityCheck");
-async function runAgentSecretAvailabilityCheck(opts) {
-  const projectRoot = resolveProjectCwd(opts.cwd);
-  let projectId;
-  try {
-    projectId = loadProjectSettings(projectRoot).projectId;
-  } catch {
-    return [];
-  }
-  const bundles = await listBundles(path29.join(projectRoot, "agents"));
-  const requiredByAgent = bundles.map((bundle) => ({
-    name: bundle.name,
-    keys: (bundle.config.secrets ?? []).filter((secret) => secret.required !== false).map((secret) => secret.key)
-  })).filter((entry) => entry.keys.length > 0);
-  if (requiredByAgent.length === 0) {
-    return [];
-  }
-  const api = new FimoApiClient(loadConfig());
-  const defined = new Set(
-    (await api.listProjectSecretEntries(projectId, { kind: "secret" })).map((secret) => secret.key)
-  );
-  const errors2 = [];
-  for (const entry of requiredByAgent) {
-    for (const key of entry.keys) {
-      if (!defined.has(key)) {
-        errors2.push(
-          authorError({
-            rule: "agents/secrets",
-            message: `${entry.name} requires project secret ${key}, but it is not set. Run: fimo secrets set ${key} --stdin`,
-            file: `agents/${entry.name}/config.yaml`
-          })
-        );
-      }
-    }
-  }
-  return errors2;
-}
-__name(runAgentSecretAvailabilityCheck, "runAgentSecretAvailabilityCheck");
 function runRouteMetadataCheck(opts) {
   return validateRouteMetadata({ cwd: opts.cwd });
 }
@@ -103778,8 +103849,24 @@ async function runLabelsPhase(opts) {
   }
   const api = new FimoApiClient(loadConfig()).withEnv(ctx.env);
   const locale = getConfigServer(cwd).i18n?.defaultLocale ?? "en";
+  const pinnedBranch = (await readProjectEnv(cwd)).VITE_FIMO_BRANCH;
   try {
-    const labels2 = await loadPublicTenantLabels(cwd, locale) ?? labelsToRecord(await api.listLabels(ctx.projectId, locale));
+    let labels2;
+    if (pinnedBranch) {
+      const branchLabels = await loadPublicTenantLabels(cwd, locale);
+      if (branchLabels == null) {
+        return {
+          name: "Labels",
+          ok: false,
+          errors: [
+            infraErrorFromException("labels-check", new Error(`Could not read labels from branch "${pinnedBranch}"`))
+          ]
+        };
+      }
+      labels2 = branchLabels;
+    } else {
+      labels2 = labelsToRecord(await api.listLabels(ctx.projectId, locale));
+    }
     const existingKeys = new Set(Object.keys(labels2));
     const missing = labelKeys.filter((label) => !existingKeys.has(label.key));
     return {
@@ -105989,6 +106076,9 @@ async function entriesListCommand(typeName, options, cmd) {
   if (options.fields) {
     params.fields = options.fields;
   }
+  if (options.populate) {
+    params.populate = options.populate;
+  }
   if (options.locale) {
     params.locale = options.locale;
   }
@@ -107857,14 +107947,18 @@ __name(labelsSetCommand, "labelsSetCommand");
 async function labelsSetManyCommand(options, cmd) {
   const { ctx, api } = await bootstrapProjectCommand(options, cmd, { refuseReadOnly: true });
   await requireOperation("i18n.update", { projectId: ctx.projectId, env: ctx.env });
-  const locale = options.locale ?? defaultLocaleForProject(options.cwd);
-  const labels2 = readLabelMap(options);
-  const records = Object.entries(labels2).map(([key, value]) => ({ key, value, locale }));
+  const fallbackLocale = options.locale ?? defaultLocaleForProject(options.cwd);
+  const records = readLabelRecords(options).map(({ key, value, locale }) => ({
+    key,
+    value,
+    locale: locale ?? fallbackLocale
+  }));
+  const locales = [...new Set(records.map((record2) => record2.locale))];
   const result = await api.setLabels(ctx.projectId, records);
   ui.result({
     command: "labels set-many",
-    data: { ...result, locale, labels: records.length },
-    render: /* @__PURE__ */ __name(() => `Set ${records.length} label${records.length === 1 ? "" : "s"} (${locale})`, "render"),
+    data: { ...result, locale: fallbackLocale, locales, labels: records.length },
+    render: /* @__PURE__ */ __name(() => `Set ${records.length} label${records.length === 1 ? "" : "s"} (${locales.join(", ")})`, "render"),
     warnings: dbLabelsRuntimeWarnings(options.cwd)
   });
 }
@@ -107882,7 +107976,7 @@ async function labelsDeleteCommand(key, options, cmd) {
   });
 }
 __name(labelsDeleteCommand, "labelsDeleteCommand");
-function readLabelMap(options) {
+function readLabelRecords(options) {
   if (options.file && options.data) {
     throw new Error("Pass either --file or --data, not both.");
   }
@@ -107892,36 +107986,39 @@ function readLabelMap(options) {
   const raw = options.data ?? readLabelFile(options);
   const parsed = JSON.parse(raw);
   if (Array.isArray(parsed)) {
-    return Object.fromEntries(
-      parsed.map((item) => {
-        if (!item || typeof item !== "object") {
-          throw new Error("Label arrays must contain objects with key and value fields.");
-        }
-        const record2 = item;
-        if (typeof record2.key !== "string") {
-          throw new Error("Each label record must include a string key.");
-        }
-        const value = record2.value ?? record2.defaultValue;
-        if (typeof value !== "string") {
-          throw new Error(`Label ${record2.key} must include a string value.`);
+    return parsed.map((item) => {
+      if (!item || typeof item !== "object") {
+        throw new Error("Label arrays must contain objects with key and value fields.");
+      }
+      const record2 = item;
+      if (typeof record2.key !== "string") {
+        throw new Error("Each label record must include a string key.");
+      }
+      const value = record2.value ?? record2.defaultValue;
+      if (typeof value !== "string") {
+        throw new Error(`Label ${record2.key} must include a string value.`);
+      }
+      let locale;
+      if (record2.locale !== void 0) {
+        if (typeof record2.locale !== "string") {
+          throw new Error(`Label ${record2.key} has a non-string locale.`);
         }
-        return [record2.key, value];
-      })
-    );
+        locale = record2.locale;
+      }
+      return { key: record2.key, value, locale };
+    });
   }
   if (!parsed || typeof parsed !== "object") {
     throw new Error("Labels JSON must be an object map or an array of { key, value } records.");
   }
-  const labels2 = {};
-  for (const [key, value] of Object.entries(parsed)) {
+  return Object.entries(parsed).map(([key, value]) => {
     if (typeof value !== "string") {
       throw new Error(`Label ${key} must be a string.`);
     }
-    labels2[key] = value;
-  }
-  return labels2;
+    return { key, value };
+  });
 }
-__name(readLabelMap, "readLabelMap");
+__name(readLabelRecords, "readLabelRecords");
 function readLabelFile(options) {
   const projectRoot = resolveProjectCwd(options.cwd);
   const filePath = path38.resolve(projectRoot, options.file);
@@ -109974,7 +110071,7 @@ schemas2.command("get").description("Get a schema by type name").argument("<type
 schemas2.command("push").description("Push schema JSON files to the API (create or update)").argument("[typeName]", "Schema name to push (omit to push all)").option("-C, --cwd <dir>", "Project directory").action(schemaPushCommand);
 schemas2.command("delete").description("Delete a schema by type name").argument("<typeName>", "Content type name").option("-C, --cwd <dir>", "Project directory").action(schemaDeleteCommand);
 var entries = program.command("entries").description("Manage content entries");
-entries.command("list").description("List entries of a content type").argument("<typeName>", "Content type name").option("-C, --cwd <dir>", "Project directory").option("--limit <n>", "Max entries to return").option("--offset <n>", "Offset for pagination").option("--search <query>", "Search query").option("--where <json>", `JSON filter object, e.g. '{"featured":true}'`).option("--sort <field>", "Sort field, prefix with - for descending").option("--fields <fields>", "Comma-separated fields to return, e.g. slug,title,excerpt").option("--locale <locale>", "Locale to list (default en)").option("--sort-by <field>", "Sort field").option("--sort-direction <dir>", "Sort direction (asc|desc)").action(entriesListCommand);
+entries.command("list").description("List entries of a content type").argument("<typeName>", "Content type name").option("-C, --cwd <dir>", "Project directory").option("--limit <n>", "Max entries to return").option("--offset <n>", "Offset for pagination").option("--search <query>", "Search query").option("--where <json>", `JSON filter object, e.g. '{"featured":true}'`).option("--sort <field>", "Sort field, prefix with - for descending").option("--fields <fields>", "Comma-separated fields to return, e.g. slug,title,excerpt").option("--populate <fields>", "Comma-separated relation fields to populate, e.g. author,contributors").option("--locale <locale>", "Locale to list (default en)").option("--sort-by <field>", "Sort field").option("--sort-direction <dir>", "Sort direction (asc|desc)").action(entriesListCommand);
 entries.command("get").description("Get a single entry").argument("<typeName>", "Content type name").argument("<id>", "Entry ID").option("-C, --cwd <dir>", "Project directory").option("--locale <locale>", "Locale to read (default en)").action(entriesGetCommand);
 entries.command("create").description("Create a new entry").argument("<typeName>", "Content type name").option("-C, --cwd <dir>", "Project directory").requiredOption("--body <json>", "Entry JSON body (slug + data)").option("--locale <locale>", "Entry locale (default en)").option("--document-id <id>", "Document ID shared by localized variants").action(entriesCreateCommand);
 entries.command("update").description("Update an existing entry").argument("<typeName>", "Content type name").argument("<id>", "Entry ID").option("-C, --cwd <dir>", "Project directory").requiredOption("--body <json>", "Updated entry JSON body").option("--locale <locale>", "Entry locale").option("--document-id <id>", "Document ID shared by localized variants").action(entriesUpdateCommand);
@@ -110051,7 +110148,7 @@ rules.command("sync").description(
 var labels = program.command("labels").description("Manage site labels stored in Fimo");
 labels.command("list").description("List labels stored in the DB").option("-C, --cwd <dir>", "Project directory").option("--locale <locale>", "Filter by locale (e.g. en)").action(labelsListCommand);
 labels.command("set <key> [value]").description("Set one label value").option("-C, --cwd <dir>", "Project directory").option("--locale <locale>", "Target locale (default en)").option("--value <value>", "Label value").option("--stdin", "Read the label value from stdin").action(labelsSetCommand);
-labels.command("set-many").description("Set many label values from JSON").option("-C, --cwd <dir>", "Project directory").option("--locale <locale>", "Target locale (default en)").option("--file <path>", "JSON object map or array of { key, value } records").option("--data <json>", "Inline JSON object map or array of { key, value } records").action(labelsSetManyCommand);
+labels.command("set-many").description("Set many label values from JSON").option("-C, --cwd <dir>", "Project directory").option("--locale <locale>", "Target locale (default en)").option("--file <path>", "JSON object map or array of { key, value, locale? } records").option("--data <json>", "Inline JSON object map or array of { key, value, locale? } records").action(labelsSetManyCommand);
 labels.command("delete <key>").alias("unset").description("Delete one label value").option("-C, --cwd <dir>", "Project directory").option("--locale <locale>", "Target locale (default en)").action(labelsDeleteCommand);
 var analytics = program.command("analytics").description("Read site analytics (pageviews, top breakdowns, annotations)");
 var rangeOptions = /* @__PURE__ */ __name((cmd) => {

package/dist/runtime/primitives/lib/query.d.ts

@@ -61,6 +61,7 @@ export type Query<T extends {
     limit?: number;
     offset?: number;
     fields?: TFields;
+    populate?: Fields<T>;
 };
 export {};
 //# sourceMappingURL=query.d.ts.map

package/dist/runtime/primitives/lib/query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../../src/runtime/primitives/lib/query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElG,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IACzB,GAAG,CAAC,EAAE,CAAC,CAAC;IACR,GAAG,CAAC,EAAE,CAAC,CAAC;IACR,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;IACV,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;IACX,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,SAAS,CAAC,MAAM,CAAC,GAAG;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,SAAS,CAAC,MAAM,CAAC,GAAG;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG,SAAS,CAAC;AAEhC,MAAM,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;AAEzC,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,UAAU,GAAG,MAAM,CAAC,GACxD,MAAM,GAAG,SAAS,GAClB,CAAC,CAAC,CAAC,SAAS,CAAC,WAAW,GAAG,OAAO,CAAC,GACjC,OAAO,GAAG,OAAO,GACjB,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,GAAG,IAAI,CAAC,GAC3B,MAAM,GAAG,OAAO,GAChB,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,GAClB,MAAM,GAAG,SAAS,GAClB,CAAC,CAAC,CAAC,SAAS,CAAC,SAAS,GAAG,SAAS,EAAE,CAAC,GACnC,WAAW,GACX,CAAC,CAAC,CAAC,SAAS,CAAC,YAAY,CAAC,GACxB,MAAM,GAAG,SAAS,GAClB,WAAW,CAAC;AAE1B,KAAK,aAAa,GAAG;IACnB,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7B,MAAM,CAAC,EAAE;QACP,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KAClC,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,aAAa,GAAG;KACpC,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,aAAa,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/D,CAAC;AAEF,KAAK,iBAAiB,GAAG,aAAa,CAAC;AACvC,KAAK,SAAS,GAAG,QAAQ,GAAG,UAAU,iBAAiB,EAAE,CAAC;AAE1D,MAAM,MAAM,SAAS,CAAC,CAAC,IACnB,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,QAAQ,CAAC,GAC3C,WAAW,GACX,WAAW,GACX,OAAO,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AAEjC,MAAM,MAAM,IAAI,CAAC,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;AAExD,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,GAAG,WAAW,GAAG,WAAW,GAAG,SAAS,CAAC;AAExF,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,GAAG,SAAS,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AAEvD,KAAK,aAAa,CAAC,MAAM,IAAI,MAAM,SAAS,UAAU,MAAM,EAAE,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEnF,KAAK,cAAc,CAAC,OAAO,IAAI,OAAO,SAAS,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,aAAa,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;AAEhH,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,OAAO,SAAS,MAAM,CAAC,CAAC,CAAC,GAAG,SAAS,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,GAClH,CAAC,GACD,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,GAAG,cAAc,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;AAE9D,MAAM,MAAM,KAAK,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,OAAO,SAAS,MAAM,CAAC,CAAC,CAAC,GAAG,SAAS,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,SAAS,IAAI;IAC3G,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../../src/runtime/primitives/lib/query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElG,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IACzB,GAAG,CAAC,EAAE,CAAC,CAAC;IACR,GAAG,CAAC,EAAE,CAAC,CAAC;IACR,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;IACV,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;IACX,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,SAAS,CAAC,MAAM,CAAC,GAAG;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,SAAS,CAAC,MAAM,CAAC,GAAG;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG,SAAS,CAAC;AAEhC,MAAM,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;AAEzC,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,UAAU,GAAG,MAAM,CAAC,GACxD,MAAM,GAAG,SAAS,GAClB,CAAC,CAAC,CAAC,SAAS,CAAC,WAAW,GAAG,OAAO,CAAC,GACjC,OAAO,GAAG,OAAO,GACjB,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,GAAG,IAAI,CAAC,GAC3B,MAAM,GAAG,OAAO,GAChB,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,GAClB,MAAM,GAAG,SAAS,GAClB,CAAC,CAAC,CAAC,SAAS,CAAC,SAAS,GAAG,SAAS,EAAE,CAAC,GACnC,WAAW,GACX,CAAC,CAAC,CAAC,SAAS,CAAC,YAAY,CAAC,GACxB,MAAM,GAAG,SAAS,GAClB,WAAW,CAAC;AAE1B,KAAK,aAAa,GAAG;IACnB,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7B,MAAM,CAAC,EAAE;QACP,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KAClC,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,aAAa,GAAG;KACpC,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,aAAa,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/D,CAAC;AAEF,KAAK,iBAAiB,GAAG,aAAa,CAAC;AACvC,KAAK,SAAS,GAAG,QAAQ,GAAG,UAAU,iBAAiB,EAAE,CAAC;AAE1D,MAAM,MAAM,SAAS,CAAC,CAAC,IACnB,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,QAAQ,CAAC,GAC3C,WAAW,GACX,WAAW,GACX,OAAO,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AAEjC,MAAM,MAAM,IAAI,CAAC,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;AAExD,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,GAAG,WAAW,GAAG,WAAW,GAAG,SAAS,CAAC;AAExF,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,GAAG,SAAS,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AAEvD,KAAK,aAAa,CAAC,MAAM,IAAI,MAAM,SAAS,UAAU,MAAM,EAAE,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEnF,KAAK,cAAc,CAAC,OAAO,IAAI,OAAO,SAAS,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,aAAa,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;AAEhH,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,OAAO,SAAS,MAAM,CAAC,CAAC,CAAC,GAAG,SAAS,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,GAClH,CAAC,GACD,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,GAAG,cAAc,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;AAE9D,MAAM,MAAM,KAAK,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,OAAO,SAAS,MAAM,CAAC,CAAC,CAAC,GAAG,SAAS,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,SAAS,IAAI;IAC3G,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;CACtB,CAAC"}

package/dist/runtime/primitives/public-surface.test.js

@@ -6,9 +6,11 @@ describe('fimo/ui public type surface', () => {
         const query = {
             where: { name: 'BASIC' },
             sort: '-price',
+            populate: 'name',
             limit: 10,
         };
         expectTypeOf(query.fields).toEqualTypeOf();
+        expectTypeOf(query.populate).toEqualTypeOf();
         expectTypeOf().toEqualTypeOf();
     });
 });

package/dist/scripts/validate-schemas.d.ts

@@ -10,4 +10,4 @@ export interface ValidateSchemasResult {
 export declare function validateSchemas(options?: {
     cwd?: string;
 }): ValidateSchemasResult;
-export declare function validateSchemaFile(absolutePath: string, file: string): SchemaFileError[];
+export declare function validateSchemaFile(absolutePath: string, file: string, schemaUids?: Set<string>): SchemaFileError[];

package/dist/scripts/validate-schemas.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
-import { FieldTypeSchema, RESERVED_CONTENT_FIELD_NAMES } from '@fimo/api-contracts';
+import { CONTENT_FIELD_NAME_PATTERN, CONTENT_FIELD_NAME_PATTERN_DESCRIPTION, CONTENT_TYPE_NAME_PATTERN, CONTENT_TYPE_NAME_PATTERN_DESCRIPTION, FieldTypeSchema, RESERVED_CONTENT_FIELD_NAMES, } from '@fimo/api-contracts';
 /**
  * Validate `src/schemas/*.json` locally against the same rules the API's
  * schema validator enforces (field types, reserved field names, required
@@ -20,13 +20,32 @@ export function validateSchemas(options = {}) {
         .filter((f) => f.endsWith('.json'))
         .sort();
     const errors = [];
+    const schemaUids = new Set();
+    for (const fileName of files) {
+        const schema = readSchemaObject(join(schemasDir, fileName));
+        if (schema && typeof schema.uid === 'string') {
+            schemaUids.add(schema.uid);
+        }
+    }
     for (const fileName of files) {
         const file = join(SCHEMAS_REL, fileName);
-        errors.push(...validateSchemaFile(join(schemasDir, fileName), file));
+        errors.push(...validateSchemaFile(join(schemasDir, fileName), file, schemaUids));
     }
     return { errors, schemasChecked: files.length };
 }
-export function validateSchemaFile(absolutePath, file) {
+function readSchemaObject(absolutePath) {
+    let schema;
+    try {
+        schema = JSON.parse(readFileSync(absolutePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+    return typeof schema === 'object' && schema !== null && !Array.isArray(schema)
+        ? schema
+        : null;
+}
+export function validateSchemaFile(absolutePath, file, schemaUids = new Set()) {
     let schema;
     try {
         schema = JSON.parse(readFileSync(absolutePath, 'utf-8'));
@@ -60,6 +79,13 @@ export function validateSchemaFile(absolutePath, file) {
             file,
         });
     }
+    else if (!CONTENT_TYPE_NAME_PATTERN.test(uid)) {
+        errors.push({
+            rule: 'schemas/type-name',
+            message: `"uid" must use ${CONTENT_TYPE_NAME_PATTERN_DESCRIPTION}.`,
+            file,
+        });
+    }
     if (typeof name !== 'string' || name.length === 0) {
         errors.push({
             rule: 'schemas/name',
@@ -76,6 +102,14 @@ export function validateSchemaFile(absolutePath, file) {
         return errors;
     }
     for (const [fieldName, definition] of Object.entries(fields)) {
+        if (!CONTENT_FIELD_NAME_PATTERN.test(fieldName)) {
+            errors.push({
+                rule: 'schemas/field-name',
+                message: `Field "${fieldName}" must use ${CONTENT_FIELD_NAME_PATTERN_DESCRIPTION}.`,
+                file,
+            });
+            continue;
+        }
         if (RESERVED_FIELD_NAMES.has(fieldName)) {
             errors.push({
                 rule: 'schemas/reserved-field',
@@ -108,6 +142,41 @@ export function validateSchemaFile(absolutePath, file) {
                 file,
             });
         }
+        if (type === 'relation') {
+            const { target, many } = definition;
+            if (typeof target !== 'string' || !CONTENT_TYPE_NAME_PATTERN.test(target)) {
+                errors.push({
+                    rule: 'schemas/relation-target',
+                    message: `Relation field "${fieldName}" must declare a valid "target" content type.`,
+                    file,
+                });
+            }
+            else if (schemaUids.size > 0 && !schemaUids.has(target)) {
+                errors.push({
+                    rule: 'schemas/relation-target',
+                    message: `Relation field "${fieldName}" targets unknown schema "${target}".`,
+                    file,
+                });
+            }
+            if (many !== undefined && typeof many !== 'boolean') {
+                errors.push({
+                    rule: 'schemas/relation-many',
+                    message: `Relation field "${fieldName}" must use a boolean "many" value.`,
+                    file,
+                });
+            }
+        }
+        else {
+            for (const relationOnlyKey of ['target', 'many', 'localized']) {
+                if (relationOnlyKey in definition) {
+                    errors.push({
+                        rule: 'schemas/relation-shape',
+                        message: `Field "${fieldName}": "${relationOnlyKey}" is only supported on relation fields.`,
+                        file,
+                    });
+                }
+            }
+        }
     }
     return errors;
 }

package/dist/scripts/validate-schemas.test.js

@@ -21,6 +21,13 @@ describe('validateSchemas', () => {
     }
     it('accepts a valid schema', () => {
         const cwd = writeProject({
+            'Author.json': {
+                uid: 'Author',
+                name: 'Authors',
+                fields: {
+                    name: { type: 'string' },
+                },
+            },
             'BlogPost.json': {
                 uid: 'BlogPost',
                 name: 'Blog Posts',
@@ -29,6 +36,20 @@ describe('validateSchemas', () => {
                     body: { type: 'richtext' },
                     coverImage: { type: 'media' },
                     featured: { type: 'boolean' },
+                    author: { type: 'relation', target: 'Author' },
+                },
+            },
+        });
+        expect(validateSchemas({ cwd })).toEqual({ errors: [], schemasChecked: 2 });
+    });
+    it('accepts self-referential relation fields', () => {
+        const cwd = writeProject({
+            'Item.json': {
+                uid: 'Item',
+                name: 'Items',
+                fields: {
+                    title: { type: 'string' },
+                    parent: { type: 'relation', target: 'Item' },
                 },
             },
         });
@@ -84,6 +105,67 @@ describe('validateSchemas', () => {
         expect(errors[0].message).toContain('"decimal"');
         expect(errors[0].message).toContain('string, richtext, media');
     });
+    it('rejects relation fields without a valid target', () => {
+        const cwd = writeProject({
+            'Post.json': {
+                uid: 'Post',
+                name: 'Posts',
+                fields: { author: { type: 'relation' } },
+            },
+        });
+        const { errors } = validateSchemas({ cwd });
+        expect(errors).toHaveLength(1);
+        expect(errors[0]).toMatchObject({ rule: 'schemas/relation-target' });
+    });
+    it('rejects relation fields targeting a missing local schema', () => {
+        const cwd = writeProject({
+            'Post.json': {
+                uid: 'Post',
+                name: 'Posts',
+                fields: { author: { type: 'relation', target: 'Author' } },
+            },
+        });
+        const { errors } = validateSchemas({ cwd });
+        expect(errors).toHaveLength(1);
+        expect(errors[0]).toMatchObject({ rule: 'schemas/relation-target' });
+        expect(errors[0].message).toContain('unknown schema "Author"');
+    });
+    it('rejects relation-only properties on scalar fields', () => {
+        const cwd = writeProject({
+            'Post.json': {
+                uid: 'Post',
+                name: 'Posts',
+                fields: { author: { type: 'string', target: 'Author' } },
+            },
+        });
+        const { errors } = validateSchemas({ cwd });
+        expect(errors).toHaveLength(1);
+        expect(errors[0]).toMatchObject({ rule: 'schemas/relation-shape' });
+    });
+    it('rejects schema uid names that cannot be used as content type identifiers', () => {
+        const cwd = writeProject({
+            'blog-post.json': {
+                uid: 'blog-post',
+                name: 'Blog Posts',
+                fields: { title: { type: 'string' } },
+            },
+        });
+        const { errors } = validateSchemas({ cwd });
+        expect(errors).toHaveLength(1);
+        expect(errors[0]).toMatchObject({ rule: 'schemas/type-name' });
+    });
+    it('rejects field names that cannot be used in generated source paths', () => {
+        const cwd = writeProject({
+            'Page.json': {
+                uid: 'Page',
+                name: 'Pages',
+                fields: { 'hero-title': { type: 'string' } },
+            },
+        });
+        const { errors } = validateSchemas({ cwd });
+        expect(errors).toHaveLength(1);
+        expect(errors[0]).toMatchObject({ rule: 'schemas/field-name' });
+    });
     it('rejects field-level i18n settings', () => {
         const cwd = writeProject({
             'Page.json': {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fimo",
-  "version": "0.3.6-staging.1",
+  "version": "0.4.0-experimental.1",
   "description": "Fimo CLI - create, deploy, and manage Fimo projects",
   "bin": {
     "fimo": "dist/cli/index.js"

package/templates/react-router/package.json

@@ -21,7 +21,7 @@
     "cmdk": "^1.1.1",
     "date-fns": "^4.1.0",
     "embla-carousel-react": "^8.6.0",
-    "fimo": "0.3.6-staging.1",
+    "fimo": "0.4.0-experimental.1",
     "input-otp": "^1.4.2",
     "isbot": "^5",
     "lucide-react": "^0.577.0",

package/templates/react-router/src/routes.ts

@@ -1,16 +1,15 @@
-import type { RouteConfig } from '@react-router/dev/routes';
-import { index, layout, route } from '@react-router/dev/routes';
+import { index } from '@react-router/dev/routes';
 import { fimoRoutes } from 'fimo/react-router/routes';
 
 // Examples of React Router route patterns:
 //   index('./pages/Index.tsx'),
+//   import { route } from '@react-router/dev/routes';
 //   route('about', './pages/About.tsx'),
 //   route('blog/:slug', './pages/BlogPost.tsx'),
+//   import { layout } from '@react-router/dev/routes';
 //   layout('./pages/layouts/Dashboard.tsx', [
 //     index('./pages/dashboard/Overview.tsx'),
 //     route('settings', './pages/dashboard/Settings.tsx'),
 //   ]),
 
-const routes = [index('./pages/Index.tsx', { id: 'home' })] satisfies RouteConfig;
-
-export default fimoRoutes(routes) satisfies RouteConfig;
+export default fimoRoutes([index('./pages/Index.tsx', { id: 'home' })]);