fimo 2.10.1-staging.1 → 2.10.1-staging.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/assets/skills/fimo-cli/SKILL.md +57 -139
- package/assets/skills/fimo-cli/SKILL.studio.md +42 -0
- package/assets/skills/fimo-cli/references/branches.md +43 -106
- package/assets/skills/fimo-cli/references/content/bulk.md +48 -0
- package/assets/skills/fimo-cli/references/content/entries.md +54 -0
- package/assets/skills/fimo-cli/references/content/localized.md +56 -0
- package/assets/skills/fimo-cli/references/content/schemas.md +29 -0
- package/assets/skills/fimo-cli/references/content/sql.md +57 -0
- package/assets/skills/fimo-cli/references/content.md +33 -272
- package/assets/skills/fimo-cli/references/deploy.md +35 -126
- package/assets/skills/fimo-cli/references/domains.md +38 -131
- package/assets/skills/fimo-cli/references/forms.md +1 -1
- package/assets/skills/fimo-cli/references/init.md +36 -170
- package/assets/skills/fimo-cli/references/locales.md +2 -2
- package/assets/skills/fimo-cli/references/projects.md +1 -1
- package/assets/skills/fimo-code/references/design.md +42 -126
- package/assets/skills/fimo-migration/SKILL.md +114 -408
- package/assets/skills/fimo-migration/references/content-delivery.md +67 -0
- package/assets/skills/fimo-migration/references/frameworks/nextjs.md +1 -1
- package/assets/skills/fimo-migration/references/qa/browser.md +41 -0
- package/assets/skills/fimo-migration/references/qa/guardrails.md +95 -0
- package/assets/skills/fimo-migration/references/qa/results.md +78 -0
- package/assets/skills/fimo-migration/references/qa.md +102 -383
- package/assets/skills/fimo-migration/references/questions-and-improvements.md +77 -168
- package/assets/skills/fimo-migration/references/setup.md +90 -0
- package/assets/skills/fimo-migration/references/workers/validator.md +2 -2
- package/assets/skills/fimo-migration/references/workers.md +1 -1
- package/assets/skills/fimo-migration/references/workflow.md +117 -171
- package/assets/skills/fimo-studio/SKILL.md +12 -11
- package/assets/skills/fimo-studio/references/ai-chat/agents.md +46 -0
- package/assets/skills/fimo-studio/references/ai-chat/default-agents.md +57 -0
- package/assets/skills/fimo-studio/references/ai-chat/routines.md +53 -0
- package/assets/skills/fimo-studio/references/ai-chat.md +39 -76
- package/assets/skills/fimo-studio/references/custom-domains.md +2 -2
- package/assets/skills/fimo-studio/references/publish-and-deploy.md +1 -1
- package/dist/cli/bundle.json +1 -1
- package/dist/cli/index.js +38 -17
- package/package.json +8 -8
- package/templates/astro/package.json +3 -3
- package/templates/nextjs/package.json +4 -4
- package/templates/react-router/package.json +5 -5
- package/templates/sveltekit/package.json +3 -3
- package/templates/vite/package.json +5 -5
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# Localized and shared content
|
|
2
|
+
|
|
3
|
+
Load this page to add a locale variant of an entry, or to work with fields or types that are the same in every language.
|
|
4
|
+
|
|
5
|
+
## Locale variants
|
|
6
|
+
|
|
7
|
+
Schemas are localized by default. Without `--locale`, a command uses the project default locale. To read, update, or delete another variant, pass `--locale`: an entry is its stable `id` plus a `locale`.
|
|
8
|
+
|
|
9
|
+
To add a variant of an existing entry, create it with the source entry's `documentId`:
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
fimo entries list Story --where '{"slug":"spring-notes"}' --fields slug,title # gives "id" and "documentId"
|
|
13
|
+
fimo entries create Story --locale es --document-id <documentId> --body '{"data":{"title":"Notas de primavera"}}'
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
- When the create names a missing shared (`"i18n": false`) field, send its current value: a shared value applies to every locale.
|
|
17
|
+
- Keep a project single-locale unless the user asks for more languages. When the project has more locales, create and update each locale explicitly.
|
|
18
|
+
- To find missing or stale translations, use SQL (`--ref content/sql`).
|
|
19
|
+
|
|
20
|
+
## Non-localized types
|
|
21
|
+
|
|
22
|
+
For content that is the same in every locale, set `"i18n": { "enabled": false }` at the schema root and create each entry once. Do not pass `--document-id` to make locale variants. Raw API and CLI responses then omit `locale`; generated collection models add the active or default locale, with no per-locale variants. The schema root accepts no other `i18n` options.
|
|
23
|
+
|
|
24
|
+
## Shared fields in a localized type
|
|
25
|
+
|
|
26
|
+
Mark a field `"i18n": false` when its value is not translated, such as a price, a SKU, a product photo, or a reference to the same target. Without it, editors enter the value once per locale, and the values drift apart.
|
|
27
|
+
|
|
28
|
+
```json
|
|
29
|
+
{
|
|
30
|
+
"uid": "Product",
|
|
31
|
+
"name": "Products",
|
|
32
|
+
"fields": {
|
|
33
|
+
"title": { "type": "string" },
|
|
34
|
+
"description": { "type": "richtext" },
|
|
35
|
+
"sku": { "type": "string", "i18n": false, "unique": true },
|
|
36
|
+
"price": { "type": "number", "i18n": false },
|
|
37
|
+
"photo": { "type": "media", "i18n": false },
|
|
38
|
+
"brand": { "type": "reference", "target": "Brand", "i18n": false }
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
A write to a shared field through any locale changes it in every locale of the document:
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
fimo entries update Product <id> --locale es --body '{"data":{"title":"Silla","price":120}}'
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
This sets the Spanish title, and sets the price to `120` in every language. An update that does not name a shared field does not change it.
|
|
50
|
+
|
|
51
|
+
- Only top-level scalar and reference fields accept `i18n`. Fields inside `blocks` follow the locale of their entry, and the push rejects `i18n` on them.
|
|
52
|
+
- On a non-localized type, the flag has no effect.
|
|
53
|
+
- `"i18n": true` is the default. Do not write it.
|
|
54
|
+
- `localized` is not a valid key anywhere.
|
|
55
|
+
|
|
56
|
+
**Making a field with content shared deletes data** when the languages hold different values. The push keeps the default-locale value of each document and discards the others, with no prompt and no undo. Before you add `"i18n": false` to a field that has content, tell the user what happens. If you are not sure, check whether the languages differ.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Schema commands and changes
|
|
2
|
+
|
|
3
|
+
Load this page to change a schema that already has content, or to list, read, or delete schemas. The schema JSON itself is in fimo-code `content/schema`.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
fimo schemas push [<Type>] # create or update from src/schemas; no type pushes all
|
|
7
|
+
fimo schemas push <Type> --rename <old.path>=<new.path> # repeat --rename for each moved field
|
|
8
|
+
fimo schemas list
|
|
9
|
+
fimo schemas get <Type> [--json]
|
|
10
|
+
fimo schemas delete <Type>
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
- The command is `fimo schemas` (plural). There is no `fimo schema`.
|
|
14
|
+
- A push of all schemas sends them as one atomic batch, so types that reference each other, also in a cycle, can go in one push.
|
|
15
|
+
- A push never deletes a schema whose file is missing. Use `fimo schemas delete <Type>`.
|
|
16
|
+
- Blocks allow at most 7 nested levels, 40 variants in one `schema.oneOf`, and 200 items per blocks field (`min` and `max`).
|
|
17
|
+
|
|
18
|
+
## What a push does to existing content
|
|
19
|
+
|
|
20
|
+
Fimo migrates content on push. A failed push changes nothing.
|
|
21
|
+
|
|
22
|
+
- Adding an optional field and changing labels keep all content.
|
|
23
|
+
- A new required field fills its `default` only where existing values need it. When no default can satisfy the existing content, the push fails.
|
|
24
|
+
- Removing a nested field or a block variant removes only those values.
|
|
25
|
+
- `string` and `text` values convert both ways. Other type changes convert safe values and reject unsafe ones, with no change to the schema or entries.
|
|
26
|
+
- Lowering a blocks `max` trims items from the end. Raising `min` adds items from the blocks `default` templates.
|
|
27
|
+
- Changing a reference target clears its links.
|
|
28
|
+
- When a field moves to a new name, pass `--rename old.path=new.path` so the one-time migration keeps its values. The rename is not stored in the schema JSON.
|
|
29
|
+
- Collection to Single removes the entries of that type and cleans the references to them. Single to collection keeps its entry.
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
# Read-only SQL over entries
|
|
2
|
+
|
|
3
|
+
Use `fimo entries query` when SQL is clearer than list filters, for example to group, count, or compare entries across types and locales.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
fimo entries query --sql "SELECT content_type, count(*) AS total FROM entries GROUP BY content_type"
|
|
7
|
+
fimo entries query --sql "SELECT document_id AS id, data->>'title' AS title FROM entries WHERE content_type = 'BlogPost' LIMIT 20"
|
|
8
|
+
fimo entries query --file query.sql
|
|
9
|
+
cat query.sql | fimo entries query --stdin
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
`fimo entries query --help` lists the columns and limits. Rows that feed another command select `document_id AS id`.
|
|
13
|
+
|
|
14
|
+
## Rules
|
|
15
|
+
|
|
16
|
+
- Common aggregate, JSON, text, date, and window functions work. A query needs content view access.
|
|
17
|
+
- **Never use SQL for content writes.** The API rejects them, because a SQL write skips schema validation, locale and reference handling, content-change events, and webhooks. Use `entries create`, `entries update`, `entries delete`, or their bulk variants (`--ref content/bulk`).
|
|
18
|
+
- If a safe read needs a SQL function that is not available, tell the user which function is missing, and use the `supportReport` tool when that gap blocks the task. Do not work around it with a write.
|
|
19
|
+
|
|
20
|
+
## Examples
|
|
21
|
+
|
|
22
|
+
English blog posts that have no Spanish variant:
|
|
23
|
+
|
|
24
|
+
```sql
|
|
25
|
+
SELECT source.document_id AS id, source.data
|
|
26
|
+
FROM entries source
|
|
27
|
+
WHERE source.content_type = 'BlogPost'
|
|
28
|
+
AND source.locale = 'en'
|
|
29
|
+
AND NOT EXISTS (
|
|
30
|
+
SELECT 1
|
|
31
|
+
FROM entries target
|
|
32
|
+
WHERE target.content_type = source.content_type
|
|
33
|
+
AND target.document_id = source.document_id
|
|
34
|
+
AND target.locale = 'es'
|
|
35
|
+
)
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Spanish variants whose English source changed later:
|
|
39
|
+
|
|
40
|
+
```sql
|
|
41
|
+
SELECT
|
|
42
|
+
target.document_id AS id,
|
|
43
|
+
target.content_type,
|
|
44
|
+
target.slug,
|
|
45
|
+
source.updated_at AS source_updated_at,
|
|
46
|
+
target.updated_at AS target_updated_at
|
|
47
|
+
FROM entries source
|
|
48
|
+
JOIN entries target
|
|
49
|
+
ON target.content_type = source.content_type
|
|
50
|
+
AND target.document_id = source.document_id
|
|
51
|
+
WHERE source.locale = 'en'
|
|
52
|
+
AND target.locale = 'es'
|
|
53
|
+
AND source.updated_at > target.updated_at
|
|
54
|
+
ORDER BY source.updated_at DESC
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
These rows are possibly stale, not proof of a bad translation: the query shows only that the source changed later. Review the content, and use each row's `id` to update the variant.
|
|
@@ -1,286 +1,47 @@
|
|
|
1
|
-
# Content
|
|
1
|
+
# Content: schemas, Singles, and entries
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
This page covers the CLI workflow. The `fimo-code` skill has the schema JSON and reference values (fimo-code `content/schema`), and the rich text and media values (fimo-code `content/richtext`). Load one with `fimo skills get fimo-code --ref <name>`. For page routes that Studio shows, load `--ref pages`.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## Choose the write path
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
- One homepage, settings document, About page, or campaign page → a Single: set `"isSingleton": true` and write it with `fimo singles update`.
|
|
8
|
+
- Repeated posts, products, team members, or other records → a collection: write rows with `fimo entries create`.
|
|
8
9
|
|
|
9
|
-
|
|
10
|
-
- Repeated posts, products, team members, or other reusable records → keep a collection and create rows with `fimo entries create <TypeName>`.
|
|
10
|
+
`entries` and `singles` are different commands. When `fimo entries create` rejects a Single, use `fimo singles update`. Do not remove `isSingleton`.
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
## Add a content type (for example, a blog)
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
1. Write `src/schemas/<Uid>.json` with a PascalCase name, for example `BlogPost.json`, as fimo-code `content/schema` shows. Do not declare `slug`, `id`, `entryId`, `documentId`, `locale`, `createdAt`, `updatedAt`, or `__fimo`: every entry already has them.
|
|
15
|
+
2. Run `fimo schemas push <Uid>`. It registers the schema and generates the public modules for the framework. Push changes before you build against them. A push does not validate the whole project: run `fimo validate` too.
|
|
16
|
+
3. If entries need cover images, generate them first with `fimo image generate` (`--ref media`).
|
|
17
|
+
4. Write the entries (next section).
|
|
18
|
+
5. Build the page with the generated clients and primitives: fimo-code `ui`, `labels`, and the detected framework reference. App code imports the generated public modules, never `.types.ts`.
|
|
15
19
|
|
|
16
|
-
|
|
17
|
-
2. Run `fimo schemas push {Uid}`. It registers the schema and generates the framework-specific public modules. It does not run whole-project validation.
|
|
18
|
-
3. App code imports generated public modules, never `.types.ts` directly. Load the detected framework reference before choosing server modules, client modules, hooks, or a registry.
|
|
19
|
-
4. Seed collections via `fimo entries create`, or update one-off content via `fimo singles update`. Generate cover images first with `fimo image generate` if needed (see `media.md` / `assets.md`).
|
|
20
|
-
5. Render tracked fields with the detected framework's Fimo primitives.
|
|
21
|
-
|
|
22
|
-
Steps 1, 3, and 5 use `fimo-code`; steps 2 and 4 are CLI workflows documented here.
|
|
23
|
-
|
|
24
|
-
## Schema CLI commands
|
|
25
|
-
|
|
26
|
-
```bash
|
|
27
|
-
fimo schemas push [TypeName] # push JSON to API (create or update). Omit TypeName to push all.
|
|
28
|
-
fimo schemas push <TypeName> --rename old.path=new.path
|
|
29
|
-
# preserve a renamed field; repeat --rename for multiple fields.
|
|
30
|
-
# Pushing all sends every schema as ONE atomic batch, so types that
|
|
31
|
-
# reference each other (even cycles) can be added in a single push.
|
|
32
|
-
# Files not present are never deleted — use `schemas delete` for that.
|
|
33
|
-
fimo schemas list # list all registered schemas
|
|
34
|
-
fimo schemas get <TypeName> # get a single schema
|
|
35
|
-
fimo schemas delete <TypeName> # delete a schema
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
The command is `fimo schemas` (plural). There is no singular `fimo schema` alias.
|
|
39
|
-
|
|
40
|
-
All commands accept `-C, --cwd <dir>` to point at a different project directory.
|
|
41
|
-
|
|
42
|
-
Blocks schemas support at most 7 nested `blocks` levels, 40 variants in one `schema.oneOf`, and `min` or `max` values up to 200 items per blocks field. Run `fimo skills get fimo-code --ref content/schema` for the complete blocks JSON shape.
|
|
43
|
-
|
|
44
|
-
Schema transitions are automatic. Adding optional fields and changing labels preserve content. A new required field backfills its `default` only where existing values need it; the push fails safely when no default can satisfy existing content. Removing a nested field or block variant removes only those values. `string` and `text` preserve values in both directions. Other primitive changes convert safe values and reject unsafe ones without changing the schema or entries. Lowering block `max` trims from the end; raising `min` fills from the blocks `default` templates. A reference target change clears its connections. Use repeatable `--rename old.path=new.path` arguments when a field moved by name so the one-time migration preserves its values; the operation is not stored in schema JSON. Collection-to-Single removes that type's entries and cleans inbound references; Single-to-collection preserves its entry.
|
|
45
|
-
|
|
46
|
-
## Singles CLI commands
|
|
47
|
-
|
|
48
|
-
Use Singles for one-off content such as a homepage, site settings, or an About story. The type name identifies the content, so these commands do not take an entry ID.
|
|
49
|
-
|
|
50
|
-
```bash
|
|
51
|
-
fimo singles get <TypeName> [--locale es] [--populate FIELDS]
|
|
52
|
-
fimo singles update <TypeName> [--locale es] (--body '<json>' | --file <path> | --stdin)
|
|
53
|
-
```
|
|
54
|
-
|
|
55
|
-
The update payload uses the regular `{ "data": { ... } }` content body. Pass exactly one input source:
|
|
56
|
-
|
|
57
|
-
```bash
|
|
58
|
-
fimo singles update Story --body '{"data":{"title":"Our story"}}'
|
|
59
|
-
fimo singles update Story --file story-body.json
|
|
60
|
-
cat story-body.json | fimo singles update Story --stdin
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
The first update creates the Single's content; later updates change it. Use `--locale` for localized variants.
|
|
64
|
-
|
|
65
|
-
## Entries CLI commands
|
|
66
|
-
|
|
67
|
-
Use singular commands for one entry. Bulk create and per-entry bulk update also accept JSON files or stdin.
|
|
68
|
-
|
|
69
|
-
```bash
|
|
70
|
-
fimo entries create <TypeName> --body '<json>'
|
|
71
|
-
fimo entries create <TypeName> --locale es --document-id <documentId> --body '<json>'
|
|
72
|
-
fimo entries list <TypeName> [--limit N] [--cursor CURSOR] [--all-pages] [--search Q] [--where JSON] [--sort F] [--fields FIELDS] [--populate FIELDS]
|
|
73
|
-
fimo entries list <TypeName> --locale es
|
|
74
|
-
fimo entries get <TypeName> <id> [--locale es] [--populate FIELDS]
|
|
75
|
-
fimo entries update <TypeName> <id> [--locale es] --body '<json>'
|
|
76
|
-
fimo entries delete <TypeName> <id> [--locale es]
|
|
77
|
-
fimo entries query (--sql '<select>' | --file <path> | --stdin)
|
|
78
|
-
fimo entries bulk-create <TypeName> (--body '<json-array>' | --file <path> | --stdin)
|
|
79
|
-
fimo entries bulk-update <TypeName> (--ids <id1>,<id2> | --where '<json>') --body '<json>'
|
|
80
|
-
fimo entries bulk-update <TypeName> (--file <path> | --stdin)
|
|
81
|
-
fimo entries bulk-delete <TypeName> (--ids <id1>,<id2> | --where '<json>') [--locale es]
|
|
82
|
-
```
|
|
83
|
-
|
|
84
|
-
`create` and `update` require `--body` with a `data` envelope. The content type is positional. For JSON files, use `bulk-create` or `bulk-update` with their documented array formats.
|
|
85
|
-
|
|
86
|
-
```bash
|
|
87
|
-
fimo entries create BlogPost --body '{"data":{"slug":"hello","title":"Hello"}}'
|
|
88
|
-
fimo entries update BlogPost <id> --body '{"data":{"title":"Updated"}}'
|
|
89
|
-
fimo entries list BlogPost --where '{"slug":"hello"}'
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
For `get`, `update`, and `delete`, use the UUID returned as `id` by create/list. To find an entry by slug, filter with `list --where` as above, then use its `id`.
|
|
93
|
-
|
|
94
|
-
Run `fimo skills get fimo-code --ref content/richtext` before constructing an entry payload: slug belongs inside `data`, media has a specific shape, and richtext must be Tiptap JSONContent.
|
|
95
|
-
|
|
96
|
-
`entries list` accepts the same read query surface as generated hooks:
|
|
97
|
-
|
|
98
|
-
```bash
|
|
99
|
-
fimo entries list BlogPost --where '{"featured":true}' --sort -publishedAt
|
|
100
|
-
fimo entries list BlogPost --where '{"rank":{"$gte":3}}' --sort rank
|
|
101
|
-
fimo entries list BlogPost --where '{"__fimo":{"contentType":{"$eq":"BlogPost"}}}'
|
|
102
|
-
fimo entries list BlogPost --search "launch"
|
|
103
|
-
fimo entries list BlogPost --limit 10 --cursor <next-cursor> --sort title
|
|
104
|
-
fimo entries list BlogPost --fields slug,title,excerpt,coverImage --sort -publishedAt --limit 12
|
|
105
|
-
fimo entries list BlogPost --fields slug,title,author --populate author
|
|
106
|
-
```
|
|
107
|
-
|
|
108
|
-
Use the canonical read query flags: `--search`, `--sort`, `--where`, `--limit`, `--cursor`, `--all-pages`, `--fields`, and `--populate`. `--offset` remains a compatibility alias for existing scripts.
|
|
109
|
-
`--where` is a JSON object keyed by schema field name. Simple values mean equality and stay typed inside the JSON (`{"featured":true}`, `{"category":"react"}`, `{"rank":{"$gte":3}}`); operator objects support `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$contains`, `$startsWith`, and `$null`, subject to the field type. Public Fimo-owned metadata lives under `__fimo`; currently `__fimo.contentType` is filterable.
|
|
110
|
-
|
|
111
|
-
Reference filters take the target `id` string (`{"author":"750e..."}`). On a to-many field, `$eq` and `$contains` mean membership, `$in` means any listed target is present, `$ne` and `$nin` mean none are present, and `$null: true` means empty or missing. Reference fields cannot be sorted; use `--sort field` / `--sort -field` on scalar fields.
|
|
112
|
-
`--fields` is a comma-separated projection for list payloads. The API always keeps `id`, `entryId`, `documentId`, and `locale`; pass only the other fields your view needs, such as `slug,title,excerpt,coverImage`.
|
|
113
|
-
|
|
114
|
-
`--populate` is a comma-separated list of top-level fields to embed, on `entries list`, `entries get`, and `singles get`. It accepts reference fields, media fields, and blocks fields that contain media; naming a blocks field populates every media value inside it. Nested paths such as `sections.image` are not supported, and other field types return 400. Run `fimo schemas get <TypeName> --json` to inspect field names and types. Without it, reference fields return `{ "id": "..." }` and media fields return the stored `{ "source", "id", "url", "alt" }`; with `--populate author,cover`, `author` returns the target entry for the requested locale and `cover` adds the asset's current `name`, `mime`, `width`, and `height`. Populate never selects which target fields come back. A populated target missing in the requested locale resolves to null unless you pass `localeFallbacks=true`, which falls back to the best available locale variant, marked by its `locale` field. Limits: 200 references per to-many write, 500 distinct populated documents per field per request (400 past either).
|
|
115
|
-
|
|
116
|
-
Polymorphic references declare `targets: ["Post", "Product"]` instead of `target` (never both) and their values carry both parts: `{ "contentType": "Post", "id": "..." }`. Populate returns mixed full entries, and generated hooks expose `$type` on each populated value to branch on. `--where` on polymorphic fields is not supported yet and fails with a clear error. Fixed and polymorphic references also work inside blocks with these same write shapes (`id`, `documentId`, or `slug` selectors), but nested fields cannot be populated or filtered.
|
|
117
|
-
|
|
118
|
-
In generated application code, the equivalent is `populate: ['author', 'contributors'] as const` in query params. Let the generated client infer the result when possible; if a named TypeScript shape is needed, use `BlogPostResult<TFields, TPopulate>` as documented by `fimo skills get fimo-code --ref content/clients`. Writes use `BlogPostInput`.
|
|
119
|
-
|
|
120
|
-
### Read-only SQL
|
|
121
|
-
|
|
122
|
-
Use `entries query` when SQL is clearer than list filters, especially for grouping and aggregation. It requires content view access, accepts one `SELECT` statement, can only read the `entries` table, and supports common aggregation, JSON, text, date, and window functions. Queries time out after five seconds and return at most 1,000 rows.
|
|
123
|
-
|
|
124
|
-
**Never use SQL for content writes.** SQL writes are rejected because they would bypass schema validation, locale and reference handling, content-change events, and current or future webhooks. Use `entries create`, `entries update`, `entries delete`, or their bulk variants so every mutation follows the content domain path.
|
|
125
|
-
|
|
126
|
-
```bash
|
|
127
|
-
fimo entries query --sql "SELECT content_type, count(*) AS total FROM entries GROUP BY content_type"
|
|
128
|
-
fimo entries query --sql "SELECT document_id AS id, data->>'title' AS title FROM entries WHERE content_type = 'BlogPost' LIMIT 20"
|
|
129
|
-
fimo entries query --file query.sql
|
|
130
|
-
cat query.sql | fimo entries query --stdin
|
|
131
|
-
```
|
|
132
|
-
|
|
133
|
-
SQL exposes the raw internal representation. `document_id` is the stable ID used by `fimo entries`, content tools, references, and the API. `id` is the internal ID of one exact locale variant. Localized variants share one `document_id` and have one row per locale; non-localized entries have a null `locale`. When query results will feed another Fimo command or tool, select `document_id AS id`; use `locale` to select a variant.
|
|
134
|
-
|
|
135
|
-
The supported content columns are `id`, `document_id`, `content_type`, `locale`, `slug`, `data`, `created_at`, and `updated_at`. Schema fields live inside the JSONB `data` column. Fimo may add internal columns, so select the fields you need instead of `SELECT *` and do not depend on other columns. If a safe read is blocked because a SQL function is unavailable, tell the user which function is missing and use the built-in `supportReport` tool when the platform gap materially blocks the task. Do not bypass the restriction with a write.
|
|
136
|
-
|
|
137
|
-
For example, find English blog posts that do not yet have a Spanish variant:
|
|
138
|
-
|
|
139
|
-
```sql
|
|
140
|
-
SELECT source.document_id AS id, source.data
|
|
141
|
-
FROM entries source
|
|
142
|
-
WHERE source.content_type = 'BlogPost'
|
|
143
|
-
AND source.locale = 'en'
|
|
144
|
-
AND NOT EXISTS (
|
|
145
|
-
SELECT 1
|
|
146
|
-
FROM entries target
|
|
147
|
-
WHERE target.content_type = source.content_type
|
|
148
|
-
AND target.document_id = source.document_id
|
|
149
|
-
AND target.locale = 'es'
|
|
150
|
-
)
|
|
151
|
-
```
|
|
152
|
-
|
|
153
|
-
Find Spanish variants whose English source was edited later:
|
|
154
|
-
|
|
155
|
-
```sql
|
|
156
|
-
SELECT
|
|
157
|
-
target.document_id AS id,
|
|
158
|
-
target.content_type,
|
|
159
|
-
target.slug,
|
|
160
|
-
source.updated_at AS source_updated_at,
|
|
161
|
-
target.updated_at AS target_updated_at
|
|
162
|
-
FROM entries source
|
|
163
|
-
JOIN entries target
|
|
164
|
-
ON target.content_type = source.content_type
|
|
165
|
-
AND target.document_id = source.document_id
|
|
166
|
-
WHERE source.locale = 'en'
|
|
167
|
-
AND target.locale = 'es'
|
|
168
|
-
AND source.updated_at > target.updated_at
|
|
169
|
-
ORDER BY source.updated_at DESC
|
|
170
|
-
```
|
|
171
|
-
|
|
172
|
-
Treat these results as possibly stale, not proof of a bad translation. The query only proves that the source row was edited later; an agent should review the content and link each target with its stable `id`.
|
|
173
|
-
|
|
174
|
-
### Bulk mutations
|
|
175
|
-
|
|
176
|
-
`bulk-create` takes an array of regular create bodies. Inline JSON, a file, and stdin all carry the same array shape:
|
|
177
|
-
|
|
178
|
-
```bash
|
|
179
|
-
fimo entries bulk-create BlogPost --body '[{"data":{"title":"First"}},{"data":{"title":"Second"},"locale":"es"}]'
|
|
180
|
-
fimo entries bulk-create BlogPost --file posts.json
|
|
181
|
-
cat posts.json | fimo entries bulk-create BlogPost --stdin
|
|
182
|
-
```
|
|
183
|
-
|
|
184
|
-
`bulk-update` applies the regular update body to explicit IDs or the normal `--where` filter:
|
|
185
|
-
|
|
186
|
-
```bash
|
|
187
|
-
fimo entries bulk-update BlogPost --ids <id1>,<id2> --body '{"data":{"status":"published"}}'
|
|
188
|
-
fimo entries bulk-update BlogPost --where '{"status":"draft"}' --body '{"data":{"status":"published"}}'
|
|
189
|
-
```
|
|
190
|
-
|
|
191
|
-
For different changes per entry, `--file` and `--stdin` accept an array of `{ "id", "body" }` records:
|
|
192
|
-
|
|
193
|
-
```json
|
|
194
|
-
[
|
|
195
|
-
{ "id": "<id1>", "body": { "data": { "status": "published" } } },
|
|
196
|
-
{ "id": "<id2>", "body": { "data": { "featured": true } } }
|
|
197
|
-
]
|
|
198
|
-
```
|
|
199
|
-
|
|
200
|
-
```bash
|
|
201
|
-
fimo entries bulk-update BlogPost --file updates.json
|
|
202
|
-
cat updates.json | fimo entries bulk-update BlogPost --stdin
|
|
203
|
-
fimo entries bulk-delete BlogPost --ids <id1>,<id2>
|
|
204
|
-
fimo entries bulk-delete BlogPost --where '{"archived":true}'
|
|
205
|
-
```
|
|
206
|
-
|
|
207
|
-
Each bulk request handles at most 1,000 entries. Missing requested IDs do not fail valid work: the CLI prints a warning, and `--json` includes both a top-level `warnings` array and the exact IDs in `data.meta.missing`. Bulk writes use the same validation, locale, reference, and content-change paths as singular entry writes. They apply entries one at a time. Recoverable create and update errors report how many earlier entries were already changed.
|
|
208
|
-
|
|
209
|
-
For reference schema JSON and entry value shape, run `fimo skills get fimo-code --ref content/schema`. The short version:
|
|
210
|
-
|
|
211
|
-
```json
|
|
212
|
-
{
|
|
213
|
-
"fields": {
|
|
214
|
-
"author": { "type": "reference", "target": "Author" },
|
|
215
|
-
"contributors": { "type": "reference", "target": "Author", "many": true }
|
|
216
|
-
}
|
|
217
|
-
}
|
|
218
|
-
```
|
|
219
|
-
|
|
220
|
-
Entry bodies use reference objects with target `id` values:
|
|
20
|
+
## Write entries and Singles
|
|
221
21
|
|
|
222
22
|
```bash
|
|
223
|
-
fimo entries create
|
|
23
|
+
fimo entries create <Type> --body '{"data":{"slug":"hello","title":"Hello"}}'
|
|
24
|
+
fimo entries list <Type> --where '{"slug":"hello"}' # find an entry by slug; use its "id"
|
|
25
|
+
fimo entries get <Type> <id> [--locale es] [--populate author,cover]
|
|
26
|
+
fimo entries update <Type> <id> [--locale es] --body '{"data":{"title":"Updated"}}'
|
|
27
|
+
fimo entries delete <Type> <id> [--locale es]
|
|
28
|
+
fimo entries query --sql "SELECT ... FROM entries WHERE content_type = '<Type>'" # read-only: --ref content/sql
|
|
29
|
+
fimo singles get <Type> [--locale es]
|
|
30
|
+
fimo singles update <Type> [--locale es] (--body '<json>' | --file <path> | --stdin)
|
|
224
31
|
```
|
|
225
32
|
|
|
226
|
-
`
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
When creating a localized variant of an existing entry, pass the source entry's `documentId` with `--document-id`. Keep projects single-locale unless the user asks for multilingual or localized output; when multiple locales are configured, create and update every locale explicitly.
|
|
233
|
-
|
|
234
|
-
For content shared across locales, define `"i18n": { "enabled": false }` at the schema root and create each entry once. Do not pass `--document-id` to manufacture locale variants. Raw API and CLI responses omit `locale`; generated collection models add the effective active/default locale without creating per-locale variants. No other schema-root `i18n` options are supported.
|
|
235
|
-
|
|
236
|
-
### Shared fields inside a localized type
|
|
237
|
-
|
|
238
|
-
A localized type can still hold fields that are the same in every language. Mark the field `"i18n": false`. Use it for anything that is not translated — a price, a SKU, a product photo, a reference to the same target everywhere. Without it those values are re-entered per locale and drift apart.
|
|
239
|
-
|
|
240
|
-
```json
|
|
241
|
-
{
|
|
242
|
-
"uid": "Product",
|
|
243
|
-
"name": "Products",
|
|
244
|
-
"fields": {
|
|
245
|
-
"title": { "type": "string" },
|
|
246
|
-
"description": { "type": "richtext" },
|
|
247
|
-
"sku": { "type": "string", "i18n": false, "unique": true },
|
|
248
|
-
"price": { "type": "number", "i18n": false },
|
|
249
|
-
"photo": { "type": "media", "i18n": false },
|
|
250
|
-
"brand": { "type": "reference", "target": "Brand", "i18n": false }
|
|
251
|
-
}
|
|
252
|
-
}
|
|
253
|
-
```
|
|
254
|
-
|
|
255
|
-
Writing a shared field through any locale updates every locale of that document:
|
|
256
|
-
|
|
257
|
-
```bash
|
|
258
|
-
fimo entries update Product <id> --locale es --body '{"data":{"title":"Silla","price":120}}'
|
|
259
|
-
```
|
|
260
|
-
|
|
261
|
-
That sets the Spanish title and moves the price to `120` for every language. An update that does not mention a shared field leaves it untouched, so partial writes are safe.
|
|
262
|
-
|
|
263
|
-
Rules:
|
|
264
|
-
|
|
265
|
-
- `i18n` belongs on top-level scalar and reference fields only. Fields inside `blocks` follow the locale of the entry containing them and are rejected.
|
|
266
|
-
- On a non-localized type the flag is inert — there is one row already.
|
|
267
|
-
- `"i18n": true` is the default and never needs writing.
|
|
268
|
-
|
|
269
|
-
Turning an existing field shared is destructive when the languages currently hold different values. The push collapses each document to its default-locale value and discards the others; there is no prompt and no undo. Most documents already agree, so most collapses change nothing — but tell the user what will happen before adding `"i18n": false` to a field that already holds content, and check whether the languages differ if you are unsure.
|
|
270
|
-
|
|
271
|
-
Use `"isSingleton": true` for a Single with exactly one set of content. Generated Single clients expose `get`/`update` and client hooks where the framework supports them, not collection create/remove APIs.
|
|
272
|
-
|
|
273
|
-
## "Add a blog" recipe
|
|
33
|
+
- `--body` is always a `{"data":{...}}` envelope, also for `singles update`. Put `slug` inside `data`.
|
|
34
|
+
- Before you write a body, load fimo-code `content/richtext`. Rich text is Tiptap JSON (`{"type":"doc","content":[...]}`), a reference is `{"id":"<id>"}`, and media has its own shape.
|
|
35
|
+
- `get`, `update`, and `delete` take the `id` (a UUID) that `create` and `list` return. Never pass a slug as the id.
|
|
36
|
+
- `update` and `singles update` change only the top-level fields in `data`; each field you send replaces its old value. The first `singles update` for a locale creates the Single, so it needs every required field.
|
|
37
|
+
- The project default locale applies when you omit `--locale`.
|
|
274
38
|
|
|
275
|
-
|
|
276
|
-
2. Write `src/schemas/BlogPost.json` with fields `title`, `body` (richtext), `coverImage` (media), etc. Do NOT declare a `slug` field — `slug` (and `id`, `entryId`, `documentId`, `locale`, `createdAt`, `updatedAt`, `__fimo`) is reserved entry metadata and will be rejected; every entry gets a `slug` for free.
|
|
277
|
-
3. Run `fimo schemas push BlogPost`.
|
|
278
|
-
4. Generate cover images: `fimo image generate --prompt "..." --aspect-ratio 16:9` (see `media.md`).
|
|
279
|
-
5. Seed entries: `fimo entries create BlogPost --body '{"data": {"slug": "first-post", "title": "...", "coverImage": {...}}}'`.
|
|
280
|
-
6. Run `fimo skills get fimo-code --ref ui` and load the detected framework reference for rendering primitives.
|
|
281
|
-
7. Run `fimo skills get fimo-code --ref labels` and load the detected framework reference for labels.
|
|
282
|
-
8. Load the detected framework reference, then build the page with its generated server or client surface.
|
|
39
|
+
**Never write content with SQL.** SQL is read-only. Write with the commands above or their bulk forms.
|
|
283
40
|
|
|
284
|
-
##
|
|
41
|
+
## Load the page for the task
|
|
285
42
|
|
|
286
|
-
|
|
43
|
+
- Filter, sort, search, select fields, populate references or media, reference values → `--ref content/entries`
|
|
44
|
+
- Count, group, or compare entries across types or locales with read-only SQL → `--ref content/sql`
|
|
45
|
+
- Create, update, or delete many entries in one command, or from a JSON file → `--ref content/bulk`
|
|
46
|
+
- Add a translation (locale variant), shared `"i18n": false` fields, non-localized types → `--ref content/localized`
|
|
47
|
+
- Rename a field, add a required field, change a type, or delete a schema → `--ref content/schemas`
|