@puckeditor/cli 0.24.0-canary.90a7801f → 0.24.0-canary.b20be8d3
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/dist/bin.mjs +148 -7
- package/dist/docs/ai/ai-configuration.md +246 -0
- package/dist/docs/ai/business-context.md +69 -0
- package/dist/docs/ai/custom-agents.md +133 -0
- package/dist/docs/ai/design-mode.md +177 -0
- package/dist/docs/ai/getting-started.md +185 -0
- package/dist/docs/ai/headless-generation.md +155 -0
- package/dist/docs/ai/localization.md +43 -0
- package/dist/docs/ai/model-configuration.md +113 -0
- package/dist/docs/ai/overview.md +21 -0
- package/dist/docs/ai/tools.md +99 -0
- package/dist/docs/api-reference/ai/ai-plugin/create-ai-plugin.md +307 -0
- package/dist/docs/api-reference/ai/ai-plugin/dictionary.md +77 -0
- package/dist/docs/api-reference/ai/ai-plugin/installation.md +14 -0
- package/dist/docs/api-reference/ai/ai-plugin/use-puck-ai.md +175 -0
- package/dist/docs/api-reference/ai/ai-plugin/with-dynamic-config.md +35 -0
- package/dist/docs/api-reference/ai/cloud-client/chat.md +496 -0
- package/dist/docs/api-reference/ai/cloud-client/generate.md +546 -0
- package/dist/docs/api-reference/ai/cloud-client/installation.md +16 -0
- package/dist/docs/api-reference/ai/cloud-client/puck-handler.md +423 -0
- package/dist/docs/api-reference/ai/cloud-client/tool.md +128 -0
- package/dist/docs/api-reference/ai/configuration/components.md +72 -0
- package/dist/docs/api-reference/ai/configuration/fields.md +231 -0
- package/dist/docs/api-reference/components/action-bar-drag-handle.md +33 -0
- package/dist/docs/api-reference/components/field-group-item.md +39 -0
- package/dist/docs/api-reference/components/field-group.md +86 -0
- package/dist/docs/api-reference/components/field-tab.md +55 -0
- package/dist/docs/api-reference/data-model/ai-field-type.md +31 -0
- package/dist/docs/api-reference/data-model/ai-part.md +90 -0
- package/dist/docs/api-reference/fields/checkbox.md +87 -0
- package/dist/docs/api-reference/theming/field-tabs.md +28 -0
- package/dist/docs/cli.md +28 -3
- package/dist/docs/index.json +124 -0
- package/dist/docs/integrating-puck/field-grouping.md +149 -0
- package/dist/templates/next/app/puck/[...puckPath]/page.tsx +3 -2
- package/dist/templates/next/app/puck/page.tsx +0 -2
- package/dist/templates/next-ai/app/puck/[...puckPath]/page.tsx +3 -2
- package/dist/templates/next-ai/app/puck/page.tsx +0 -2
- package/dist/templates/vinext/app/puck/[...puckPath]/page.tsx +3 -2
- package/dist/templates/vinext/app/puck/page.tsx +0 -2
- package/dist/templates/vinext-ai/app/puck/[...puckPath]/page.tsx +3 -2
- package/dist/templates/vinext-ai/app/puck/page.tsx +0 -2
- package/package.json +1 -1
package/dist/bin.mjs
CHANGED
|
@@ -159,6 +159,19 @@ var findStringProperty = (code, filename, key) => {
|
|
|
159
159
|
});
|
|
160
160
|
return result;
|
|
161
161
|
};
|
|
162
|
+
var hasTrueProperty = (code, filename, key) => {
|
|
163
|
+
const ast = tryParseModule(code, filename);
|
|
164
|
+
let found = false;
|
|
165
|
+
if (ast) {
|
|
166
|
+
walk(ast.program, (node) => {
|
|
167
|
+
if (node.type !== "ObjectProperty" || node.computed) return;
|
|
168
|
+
const name = node.key.type === "Identifier" ? node.key.name : node.key.type === "StringLiteral" ? node.key.value : null;
|
|
169
|
+
if (name === key && node.value.type === "BooleanLiteral")
|
|
170
|
+
found ||= node.value.value;
|
|
171
|
+
});
|
|
172
|
+
}
|
|
173
|
+
return found;
|
|
174
|
+
};
|
|
162
175
|
|
|
163
176
|
// src/detect/package-json.ts
|
|
164
177
|
import path from "path";
|
|
@@ -340,6 +353,18 @@ var findViteConfig = (vfs, root) => firstExisting(
|
|
|
340
353
|
root,
|
|
341
354
|
CONFIG_EXTENSIONS.map((ext) => `vite.config.${ext}`)
|
|
342
355
|
);
|
|
356
|
+
var detectCacheComponents = (vfs, root) => {
|
|
357
|
+
const config = firstExisting(
|
|
358
|
+
vfs,
|
|
359
|
+
root,
|
|
360
|
+
CONFIG_EXTENSIONS.map((ext) => `next.config.${ext}`)
|
|
361
|
+
);
|
|
362
|
+
return config ? hasTrueProperty(
|
|
363
|
+
vfs.readText(path3.join(root, config)) ?? "",
|
|
364
|
+
config,
|
|
365
|
+
"cacheComponents"
|
|
366
|
+
) : false;
|
|
367
|
+
};
|
|
343
368
|
var normalizeDir = (dir) => path3.posix.normalize(dir).replace(/^\.\/?$/, "").replace(/\/+$/, "");
|
|
344
369
|
var dynamicConfig = (file, what) => ({
|
|
345
370
|
status: "unsupported",
|
|
@@ -396,7 +421,8 @@ var detectNext = (vfs, root, range) => {
|
|
|
396
421
|
version,
|
|
397
422
|
major: major2,
|
|
398
423
|
...layout,
|
|
399
|
-
proxyKind: major2 >= 16 ? "proxy" : "middleware"
|
|
424
|
+
proxyKind: major2 >= 16 ? "proxy" : "middleware",
|
|
425
|
+
cacheComponents: detectCacheComponents(vfs, root)
|
|
400
426
|
}
|
|
401
427
|
};
|
|
402
428
|
};
|
|
@@ -418,6 +444,7 @@ var detectVinext = (vfs, root, range) => {
|
|
|
418
444
|
major: majorOf(version) ?? majorOf(range),
|
|
419
445
|
...layout,
|
|
420
446
|
proxyKind: hasMiddleware ? "middleware" : "proxy",
|
|
447
|
+
cacheComponents: false,
|
|
421
448
|
viteConfig: findViteConfig(vfs, root)
|
|
422
449
|
}
|
|
423
450
|
};
|
|
@@ -783,6 +810,7 @@ var OPTIONS = {
|
|
|
783
810
|
config: { type: "string" },
|
|
784
811
|
"package-manager": { type: "string" },
|
|
785
812
|
wait: { type: "boolean" },
|
|
813
|
+
login: { type: "boolean" },
|
|
786
814
|
framework: { type: "string" },
|
|
787
815
|
name: { type: "string" },
|
|
788
816
|
offline: { type: "boolean" },
|
|
@@ -816,6 +844,7 @@ var MUTATING = [
|
|
|
816
844
|
"config",
|
|
817
845
|
"package-manager",
|
|
818
846
|
"wait",
|
|
847
|
+
"login",
|
|
819
848
|
"backend",
|
|
820
849
|
"backend-url"
|
|
821
850
|
];
|
|
@@ -965,6 +994,7 @@ var parseCliArgs = (argv) => {
|
|
|
965
994
|
config: values.config,
|
|
966
995
|
packageManager: pm,
|
|
967
996
|
wait: Boolean(values.wait),
|
|
997
|
+
login: Boolean(values.login),
|
|
968
998
|
framework,
|
|
969
999
|
name: values.name,
|
|
970
1000
|
offline: Boolean(values.offline),
|
|
@@ -1161,6 +1191,22 @@ var createCloudApi = (baseUrl, fetchImpl) => {
|
|
|
1161
1191
|
}
|
|
1162
1192
|
return body;
|
|
1163
1193
|
},
|
|
1194
|
+
async createClaimableProject(client) {
|
|
1195
|
+
const res = await request("api/claimable-projects", {
|
|
1196
|
+
method: "POST",
|
|
1197
|
+
headers: { "content-type": "application/json" },
|
|
1198
|
+
body: JSON.stringify(client)
|
|
1199
|
+
});
|
|
1200
|
+
if (res.status === 404 || res.status === 429) return null;
|
|
1201
|
+
const body = await json(res);
|
|
1202
|
+
if (!res.ok || typeof body.apiKey !== "string" || typeof body.claimUrl !== "string") {
|
|
1203
|
+
throw new CloudRequestError(
|
|
1204
|
+
`Puck Cloud returned an unexpected response (${res.status})`,
|
|
1205
|
+
"bad_response"
|
|
1206
|
+
);
|
|
1207
|
+
}
|
|
1208
|
+
return body;
|
|
1209
|
+
},
|
|
1164
1210
|
async pollConnect(deviceCode) {
|
|
1165
1211
|
const res = await request("api/cli/connect/token", {
|
|
1166
1212
|
method: "POST",
|
|
@@ -1406,6 +1452,8 @@ Flags:
|
|
|
1406
1452
|
add one, use one elsewhere, or none (editor only)
|
|
1407
1453
|
--backend-url <url> The server for --backend external, e.g. http://localhost:3000
|
|
1408
1454
|
--wait Wait for Puck Cloud login approval instead of returning
|
|
1455
|
+
--login Log in to Puck Cloud instead of starting on a project
|
|
1456
|
+
without an account (init, add)
|
|
1409
1457
|
--framework <name> Framework for new apps (init), one of:
|
|
1410
1458
|
${FRAMEWORK_IDS.join(", ")}
|
|
1411
1459
|
--name <name> Directory name for new apps (init)
|
|
@@ -1417,7 +1465,8 @@ Flags:
|
|
|
1417
1465
|
For agents:
|
|
1418
1466
|
Every command prints exactly one JSON document with --json. When "status" is
|
|
1419
1467
|
"action_required", surface each entry in "actions" to the developer (e.g. a
|
|
1420
|
-
browser_login URL and code), then run its "rerun" command.
|
|
1468
|
+
browser_login URL and code), then run its "rerun" command. Show a
|
|
1469
|
+
claim_project link to the developer even when "status" is "success". Exit codes:
|
|
1421
1470
|
0 success, 2 usage, 3 unsupported project, 4 file conflict, 5 package manager,
|
|
1422
1471
|
6 doctor found problems, 7 Puck Cloud unreachable, 10 action required, 11 partial.
|
|
1423
1472
|
|
|
@@ -1896,6 +1945,27 @@ var configImportClause = (shape, local) => {
|
|
|
1896
1945
|
if (shape.named.length === 1) return `{ ${shape.named[0]} as ${local} }`;
|
|
1897
1946
|
return null;
|
|
1898
1947
|
};
|
|
1948
|
+
var INSTANT = `// Cache Components: allow rendering on request, outside <Suspense>
|
|
1949
|
+
export const instant = false;`;
|
|
1950
|
+
var cacheComponentsEdits = (ast, code) => {
|
|
1951
|
+
const dynamic = ast.program.body.find(
|
|
1952
|
+
(s) => s.type === "ExportNamedDeclaration" && s.declaration?.type === "VariableDeclaration" && s.declaration.declarations.some(
|
|
1953
|
+
(d) => d.id.type === "Identifier" && d.id.name === "dynamic"
|
|
1954
|
+
)
|
|
1955
|
+
);
|
|
1956
|
+
if (!dynamic) {
|
|
1957
|
+
return [{ start: code.length, end: code.length, text: `
|
|
1958
|
+
${INSTANT}
|
|
1959
|
+
` }];
|
|
1960
|
+
}
|
|
1961
|
+
return [
|
|
1962
|
+
{
|
|
1963
|
+
start: dynamic.leadingComments?.[0]?.start ?? dynamic.start,
|
|
1964
|
+
end: dynamic.end,
|
|
1965
|
+
text: INSTANT
|
|
1966
|
+
}
|
|
1967
|
+
];
|
|
1968
|
+
};
|
|
1899
1969
|
var TYPE_FALLBACKS = {
|
|
1900
1970
|
UserData: 'import("@puckeditor/core").Data'
|
|
1901
1971
|
};
|
|
@@ -1988,6 +2058,9 @@ var relocateModule = (code, opts) => {
|
|
|
1988
2058
|
});
|
|
1989
2059
|
}
|
|
1990
2060
|
}
|
|
2061
|
+
if (opts.cacheComponents && /(^|\/)page\.[jt]sx?$/.test(opts.to)) {
|
|
2062
|
+
edits.push(...cacheComponentsEdits(ast, code));
|
|
2063
|
+
}
|
|
1991
2064
|
return { ok: true, code: applyEdits(code, edits) };
|
|
1992
2065
|
};
|
|
1993
2066
|
|
|
@@ -2574,6 +2647,7 @@ import "@puckeditor/core/puck.css";
|
|
|
2574
2647
|
${ai ? `import "@puckeditor/plugin-ai/styles.css";
|
|
2575
2648
|
` : ""}import "@puckeditor/plugin-pages/styles.css";
|
|
2576
2649
|
import { Metadata } from "next";
|
|
2650
|
+
import { connection } from "next/server";
|
|
2577
2651
|
import { Client } from "./client";${auth ? `
|
|
2578
2652
|
import { requirePuckSession } from "../../../lib/puck-auth";` : ""}
|
|
2579
2653
|
|
|
@@ -2588,15 +2662,18 @@ ${auth ? `export default async function Page({
|
|
|
2588
2662
|
}: {
|
|
2589
2663
|
searchParams: Promise<Record<string, string>>;
|
|
2590
2664
|
}) {
|
|
2665
|
+
// Puck renders in the browser, so the editor is rendered on every request
|
|
2666
|
+
await connection();
|
|
2591
2667
|
const query = new URLSearchParams(await searchParams).toString();
|
|
2592
2668
|
await requirePuckSession(\`/puck\${query ? \`?\${query}\` : ""}\`);
|
|
2593
2669
|
|
|
2594
2670
|
return <Client />;
|
|
2595
2671
|
}` : `export default async function Page() {
|
|
2672
|
+
// Puck renders in the browser, so the editor is rendered on every request
|
|
2673
|
+
await connection();
|
|
2674
|
+
|
|
2596
2675
|
return <Client />;
|
|
2597
2676
|
}`}
|
|
2598
|
-
|
|
2599
|
-
export const dynamic = "force-dynamic";
|
|
2600
2677
|
`;
|
|
2601
2678
|
var nextPagesRenderPage = (host) => `/**
|
|
2602
2679
|
* This file implements a catch-all route that renders the pages published in
|
|
@@ -3312,7 +3389,8 @@ var nextRelocation = (p, info) => {
|
|
|
3312
3389
|
"lib/puck-auth": `${lib}/puck-auth`,
|
|
3313
3390
|
"puck.config": configModuleTarget(p)
|
|
3314
3391
|
},
|
|
3315
|
-
config: configRelocation(p)
|
|
3392
|
+
config: configRelocation(p),
|
|
3393
|
+
cacheComponents: info.cacheComponents
|
|
3316
3394
|
};
|
|
3317
3395
|
};
|
|
3318
3396
|
var conflictingSegments = (p, appDir) => {
|
|
@@ -6790,6 +6868,12 @@ var actionLines = (action) => {
|
|
|
6790
6868
|
` and confirm the code ${pc.bold(action.userCode)}`
|
|
6791
6869
|
);
|
|
6792
6870
|
break;
|
|
6871
|
+
case "claim_project":
|
|
6872
|
+
lines.push(
|
|
6873
|
+
` Open ${pc.cyan(action.url)}`,
|
|
6874
|
+
` before ${new Date(action.expiresAt).toLocaleString()}`
|
|
6875
|
+
);
|
|
6876
|
+
break;
|
|
6793
6877
|
case "provide_api_key":
|
|
6794
6878
|
lines.push(` ${action.instructions}`);
|
|
6795
6879
|
break;
|
|
@@ -8194,6 +8278,28 @@ var connectFallback = (rc, err) => {
|
|
|
8194
8278
|
warnings: []
|
|
8195
8279
|
};
|
|
8196
8280
|
};
|
|
8281
|
+
var startUnclaimed = async (rc, info) => {
|
|
8282
|
+
let created;
|
|
8283
|
+
try {
|
|
8284
|
+
created = await rc.cloud.createClaimableProject(clientPayload(rc, info));
|
|
8285
|
+
} catch (err) {
|
|
8286
|
+
return connectFallback(rc, err);
|
|
8287
|
+
}
|
|
8288
|
+
if (!created) return null;
|
|
8289
|
+
const secret = secretFrom(rc, created.apiKey, "Puck Cloud");
|
|
8290
|
+
rc.log(
|
|
8291
|
+
`\u2713 Created the Puck Cloud project "${created.project.name}" without an account (key "${created.keyName}")`
|
|
8292
|
+
);
|
|
8293
|
+
return {
|
|
8294
|
+
kind: "resolved",
|
|
8295
|
+
secret,
|
|
8296
|
+
source: "connect",
|
|
8297
|
+
needsWrite: true,
|
|
8298
|
+
verified: "valid",
|
|
8299
|
+
warnings: [],
|
|
8300
|
+
claim: { url: created.claimUrl, expiresAt: created.expiresAt }
|
|
8301
|
+
};
|
|
8302
|
+
};
|
|
8197
8303
|
var connectNonInteractive = async (rc, info, attempt = 0) => {
|
|
8198
8304
|
const store = new SessionStore(
|
|
8199
8305
|
cacheDirFor(rc.deps.env, rc.deps.homedir),
|
|
@@ -8412,10 +8518,22 @@ var resolveCredential = async (rc, state, info, { fresh = false } = {}) => {
|
|
|
8412
8518
|
"How do you want to connect to Puck Cloud?",
|
|
8413
8519
|
[
|
|
8414
8520
|
{ value: "login", name: "Log in with the browser (recommended)" },
|
|
8521
|
+
// `connect` replaces the key, often for a branch, so it always logs in
|
|
8522
|
+
...fresh ? [] : [
|
|
8523
|
+
{
|
|
8524
|
+
value: "unclaimed",
|
|
8525
|
+
name: "Start without an account (claim it within 72 hours)"
|
|
8526
|
+
}
|
|
8527
|
+
],
|
|
8415
8528
|
{ value: "paste", name: "Paste an existing API key" }
|
|
8416
8529
|
]
|
|
8417
8530
|
);
|
|
8418
|
-
if (method === "
|
|
8531
|
+
if (method === "unclaimed") {
|
|
8532
|
+
const started = await startUnclaimed(rc, info);
|
|
8533
|
+
if (started?.kind === "resolved") return { ...started, warnings };
|
|
8534
|
+
rc.log("Couldn't start without an account. Log in instead.");
|
|
8535
|
+
}
|
|
8536
|
+
if (method === "login" || method === "unclaimed") {
|
|
8419
8537
|
const connected = await connectInteractive(rc, info);
|
|
8420
8538
|
if (connected) return { ...connected, warnings };
|
|
8421
8539
|
rc.log("Falling back to pasting an API key.");
|
|
@@ -8437,6 +8555,11 @@ var resolveCredential = async (rc, state, info, { fresh = false } = {}) => {
|
|
|
8437
8555
|
}
|
|
8438
8556
|
};
|
|
8439
8557
|
}
|
|
8558
|
+
if (!fresh && !rc.flags.login) {
|
|
8559
|
+
const started = await startUnclaimed(rc, info);
|
|
8560
|
+
if (started)
|
|
8561
|
+
return { ...started, warnings: [...warnings, ...started.warnings] };
|
|
8562
|
+
}
|
|
8440
8563
|
const resolution = await connectNonInteractive(rc, info);
|
|
8441
8564
|
return { ...resolution, warnings: [...warnings, ...resolution.warnings] };
|
|
8442
8565
|
};
|
|
@@ -8908,6 +9031,24 @@ var runMutation = async (rc, input) => {
|
|
|
8908
9031
|
[credential.action]
|
|
8909
9032
|
);
|
|
8910
9033
|
}
|
|
9034
|
+
if (credential.kind === "resolved" && credential.claim) {
|
|
9035
|
+
const { url, expiresAt } = credential.claim;
|
|
9036
|
+
planner.manual({
|
|
9037
|
+
id: "cloud:claim",
|
|
9038
|
+
type: "claim_project",
|
|
9039
|
+
required: false,
|
|
9040
|
+
message: "Ask the developer to claim this Puck Cloud project before it expires, or it's deleted with its pages.",
|
|
9041
|
+
url,
|
|
9042
|
+
expiresAt,
|
|
9043
|
+
instructions: `Open ${url} and sign up or log in before ${expiresAt}. ${ENV_KEY} keeps working once it's claimed.`
|
|
9044
|
+
});
|
|
9045
|
+
if (capabilities.includes("ai") || state.ai.installed) {
|
|
9046
|
+
planner.warn(
|
|
9047
|
+
"PUCK-CLI-W-AI-UNCLAIMED",
|
|
9048
|
+
`Puck AI works once the project is claimed. Open ${url} to claim it.`
|
|
9049
|
+
);
|
|
9050
|
+
}
|
|
9051
|
+
}
|
|
8911
9052
|
if (credential.kind === "resolved" && credential.needsWrite) {
|
|
8912
9053
|
planEnvWrite(planner, credential.secret);
|
|
8913
9054
|
} else if (credential.kind === "resolved" && state.cloud.apiKey.file) {
|
|
@@ -11573,7 +11714,7 @@ runCli(process.argv.slice(2), {
|
|
|
11573
11714
|
stdout: process.stdout,
|
|
11574
11715
|
stderr: process.stderr,
|
|
11575
11716
|
stdinIsTTY: Boolean(process.stdin.isTTY),
|
|
11576
|
-
cliVersion: "0.24.0-canary.
|
|
11717
|
+
cliVersion: "0.24.0-canary.b20be8d3",
|
|
11577
11718
|
invocation: localInvocation(
|
|
11578
11719
|
fs8.realpathSync(fileURLToPath(import.meta.url)),
|
|
11579
11720
|
fs8.realpathSync(process.cwd()),
|
|
@@ -0,0 +1,246 @@
|
|
|
1
|
+
# AI Configuration
|
|
2
|
+
|
|
3
|
+
AI configuration allows further control of agent behavior via the `ai` parameter on both [component](/docs/api-reference/ai/configuration/components) and [field](/docs/api-reference/ai/configuration/fields) configs.
|
|
4
|
+
|
|
5
|
+
## Providing instructions
|
|
6
|
+
|
|
7
|
+
The `instructions` parameter provides the agent with natural-language guidance on how to use a component or field.
|
|
8
|
+
|
|
9
|
+
Here's an example using [`instructions` on components](/docs/api-reference/ai/configuration/components#instructions):
|
|
10
|
+
|
|
11
|
+
```ts
|
|
12
|
+
const config = {
|
|
13
|
+
components: {
|
|
14
|
+
HeadingBlock: {
|
|
15
|
+
ai: {
|
|
16
|
+
instructions: "Always place this first",
|
|
17
|
+
},
|
|
18
|
+
fields: {
|
|
19
|
+
title: {
|
|
20
|
+
type: "text",
|
|
21
|
+
},
|
|
22
|
+
},
|
|
23
|
+
render: ({ title }) => <h1>{title}</h1>,
|
|
24
|
+
},
|
|
25
|
+
},
|
|
26
|
+
};
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
And using [`instructions` on fields](/docs/api-reference/ai/configuration/fields#instructions):
|
|
30
|
+
|
|
31
|
+
```ts
|
|
32
|
+
const config = {
|
|
33
|
+
components: {
|
|
34
|
+
HeadingBlock: {
|
|
35
|
+
fields: {
|
|
36
|
+
title: {
|
|
37
|
+
type: "text",
|
|
38
|
+
ai: {
|
|
39
|
+
instructions: "Always use caps",
|
|
40
|
+
},
|
|
41
|
+
},
|
|
42
|
+
},
|
|
43
|
+
render: ({ title }) => <h1>{title}</h1>,
|
|
44
|
+
},
|
|
45
|
+
},
|
|
46
|
+
};
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Setting a schema
|
|
50
|
+
|
|
51
|
+
Some field types like [`custom`](/docs/api-reference/fields/custom), [`external`](/docs/api-reference/fields/external), or [user fields](/docs/api-reference/overrides/field-types), are not supported without further configuration. This is because the shape of the data produced by those fields is unknown to the agent.
|
|
52
|
+
|
|
53
|
+
To address this, provide a [`schema`](/docs/api-reference/ai/configuration/fields#schema) using JSON Schema:
|
|
54
|
+
|
|
55
|
+
```tsx
|
|
56
|
+
const config = {
|
|
57
|
+
components: {
|
|
58
|
+
HeadingBlock: {
|
|
59
|
+
fields: {
|
|
60
|
+
title: {
|
|
61
|
+
type: "custom",
|
|
62
|
+
ai: {
|
|
63
|
+
schema: { type: "text" },
|
|
64
|
+
},
|
|
65
|
+
render: () => <input />,
|
|
66
|
+
},
|
|
67
|
+
},
|
|
68
|
+
render: ({ title }) => <h1>{title}</h1>,
|
|
69
|
+
},
|
|
70
|
+
},
|
|
71
|
+
};
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
We recommend using [Zod](https://zod.dev/json-schema) to help with producing JSON Schema for complex shapes:
|
|
75
|
+
|
|
76
|
+
```tsx
|
|
77
|
+
|
|
78
|
+
const config = {
|
|
79
|
+
components: {
|
|
80
|
+
HeadingBlock: {
|
|
81
|
+
fields: {
|
|
82
|
+
object: {
|
|
83
|
+
type: "custom",
|
|
84
|
+
ai: {
|
|
85
|
+
schema: z.toJSONSchema(
|
|
86
|
+
z.object({
|
|
87
|
+
title: z.string(),
|
|
88
|
+
})
|
|
89
|
+
),
|
|
90
|
+
},
|
|
91
|
+
render: () => <input />,
|
|
92
|
+
},
|
|
93
|
+
},
|
|
94
|
+
render: ({ object }) => <h1>{object.title}</h1>,
|
|
95
|
+
},
|
|
96
|
+
},
|
|
97
|
+
};
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
## Excluding components
|
|
101
|
+
|
|
102
|
+
To completely ignore a component when generating a page, use the [`exclude` API](/docs/api-reference/ai/configuration/components#exclude):
|
|
103
|
+
|
|
104
|
+
```tsx
|
|
105
|
+
const config = {
|
|
106
|
+
components: {
|
|
107
|
+
HeadingBlock: {
|
|
108
|
+
fields: {
|
|
109
|
+
title: { type: "text" },
|
|
110
|
+
},
|
|
111
|
+
ai: {
|
|
112
|
+
exclude: true,
|
|
113
|
+
},
|
|
114
|
+
render: ({ title }) => <h1>{title}</h1>,
|
|
115
|
+
},
|
|
116
|
+
},
|
|
117
|
+
};
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
## Disabling streaming
|
|
121
|
+
|
|
122
|
+
When using the [AI plugin](/docs/api-reference/ai/ai-plugin/installation), Puck AI will stream field values wherever possible. This can sometimes result in unexpected behavior when rendering the preview, such as broken image URLs.
|
|
123
|
+
|
|
124
|
+
You can set the [`stream` parameter](/docs/api-reference/ai/configuration/fields#stream) to `false` to disable streaming of a field:
|
|
125
|
+
|
|
126
|
+
```tsx
|
|
127
|
+
const config = {
|
|
128
|
+
components: {
|
|
129
|
+
HeadingBlock: {
|
|
130
|
+
fields: {
|
|
131
|
+
src: {
|
|
132
|
+
type: "text",
|
|
133
|
+
ai: {
|
|
134
|
+
stream: false,
|
|
135
|
+
},
|
|
136
|
+
},
|
|
137
|
+
},
|
|
138
|
+
render: ({ src }) => <img src={src} />,
|
|
139
|
+
},
|
|
140
|
+
},
|
|
141
|
+
};
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
## Setting required fields
|
|
145
|
+
|
|
146
|
+
By default, all fields provided in [`defaultProps`](/docs/api-reference/configuration/component-config#defaultprops) are considered required by the agent.
|
|
147
|
+
|
|
148
|
+
You can explicitly mark a field as required or optional by using the [`required` parameter](/docs/api-reference/ai/configuration/fields#required).
|
|
149
|
+
|
|
150
|
+
```tsx
|
|
151
|
+
const config = {
|
|
152
|
+
components: {
|
|
153
|
+
HeadingBlock: {
|
|
154
|
+
fields: {
|
|
155
|
+
src: {
|
|
156
|
+
type: "text",
|
|
157
|
+
ai: {
|
|
158
|
+
required: true, // Mark this as required, even though it doesn't exist in defaultProps
|
|
159
|
+
},
|
|
160
|
+
},
|
|
161
|
+
},
|
|
162
|
+
render: ({ src }) => <img src={src} />,
|
|
163
|
+
defaultProps: {},
|
|
164
|
+
},
|
|
165
|
+
},
|
|
166
|
+
};
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
## Excluding fields
|
|
170
|
+
|
|
171
|
+
To completely ignore a field when generating a page, use the [`exclude` API](/docs/api-reference/ai/configuration/fields#exclude):
|
|
172
|
+
|
|
173
|
+
```tsx
|
|
174
|
+
const config = {
|
|
175
|
+
components: {
|
|
176
|
+
HeadingBlock: {
|
|
177
|
+
fields: {
|
|
178
|
+
src: {
|
|
179
|
+
type: "text",
|
|
180
|
+
ai: {
|
|
181
|
+
exclude: true,
|
|
182
|
+
},
|
|
183
|
+
},
|
|
184
|
+
},
|
|
185
|
+
render: ({ src }) => <img src={src} />,
|
|
186
|
+
},
|
|
187
|
+
},
|
|
188
|
+
};
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
## Registering reusable field types
|
|
192
|
+
|
|
193
|
+
A [user field type](/docs/api-reference/overrides/field-types) can be shared by many fields. Rather than repeating `ai.schema` on each one, describe the type once via `fieldTypes` on the [AI plugin](/docs/api-reference/ai/ai-plugin/create-ai-plugin#fieldtypes):
|
|
194
|
+
|
|
195
|
+
```tsx
|
|
196
|
+
const aiPlugin = createAiPlugin({
|
|
197
|
+
fieldTypes: {
|
|
198
|
+
cta: {
|
|
199
|
+
// Included in the prompt, so describe any rules for using the field
|
|
200
|
+
description: "Renders a call-to-action button",
|
|
201
|
+
schema: {
|
|
202
|
+
type: "object",
|
|
203
|
+
properties: {
|
|
204
|
+
label: { type: "string" },
|
|
205
|
+
},
|
|
206
|
+
},
|
|
207
|
+
},
|
|
208
|
+
},
|
|
209
|
+
});
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
When using this field, Puck AI will generate against the `schema`.
|
|
213
|
+
|
|
214
|
+
Omit `schema` and provide a `defaultValue` to have Puck AI add a field without generating the value.
|
|
215
|
+
|
|
216
|
+
```tsx
|
|
217
|
+
const aiPlugin = createAiPlugin({
|
|
218
|
+
fieldTypes: {
|
|
219
|
+
timer: {
|
|
220
|
+
defaultValue: { label: "Countdown" },
|
|
221
|
+
description: "Renders a countdown",
|
|
222
|
+
},
|
|
223
|
+
},
|
|
224
|
+
});
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
## Rendering components as fields
|
|
228
|
+
|
|
229
|
+
By combining `fieldTypes` with [field transforms](/docs/extending-puck/field-transforms), Puck AI can render your components using fields. This works with [design mode](/docs/ai/design-mode).
|
|
230
|
+
|
|
231
|
+
```tsx
|
|
232
|
+
const fieldTransforms = {
|
|
233
|
+
cta: ({ value }) => <button>{value.label}</button>,
|
|
234
|
+
};
|
|
235
|
+
|
|
236
|
+
const Example = () => <Puck fieldTransforms={fieldTransforms} />;
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
## Further reading
|
|
240
|
+
|
|
241
|
+
- [Field AI Config API reference](/docs/api-reference/ai/configuration/fields)
|
|
242
|
+
- [Component AI Config API reference](/docs/api-reference/ai/configuration/components)
|
|
243
|
+
- [`AiFieldType` API reference](/docs/api-reference/data-model/ai-field-type)
|
|
244
|
+
- [`createAiPlugin()` API reference](/docs/api-reference/ai/ai-plugin/create-ai-plugin)
|
|
245
|
+
- [Field transforms](/docs/extending-puck/field-transforms)
|
|
246
|
+
- [Design mode](/docs/ai/design-mode)
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Business Context
|
|
2
|
+
|
|
3
|
+
Providing business context enables Puck AI to understand your business and build relevant pages. It applies in both assembly and design modes.
|
|
4
|
+
|
|
5
|
+
## Context for AI plugin
|
|
6
|
+
|
|
7
|
+
When using the [AI plugin](/docs/api-reference/ai/ai-plugin/installation), you can provide context to all interactions by using the [`ai.context`](/docs/api-reference/ai/cloud-client/puck-handler#aicontext) parameter in the [`puckHandler()`](/docs/api-reference/ai/cloud-client/puck-handler).
|
|
8
|
+
|
|
9
|
+
```tsx
|
|
10
|
+
|
|
11
|
+
export async function POST(request) {
|
|
12
|
+
return puckHandler(request, {
|
|
13
|
+
ai: {
|
|
14
|
+
context: "We are Google. You create Google landing pages.",
|
|
15
|
+
},
|
|
16
|
+
});
|
|
17
|
+
}
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
You can use this parameter to provide extensive information for your use-case:
|
|
21
|
+
|
|
22
|
+
```tsx
|
|
23
|
+
|
|
24
|
+
const context = `## Overview
|
|
25
|
+
We are Google. You help us build Google landing pages.
|
|
26
|
+
|
|
27
|
+
## Brand guidelines
|
|
28
|
+
|
|
29
|
+
Our brand colors are:
|
|
30
|
+
|
|
31
|
+
- #4285F4 (primary)
|
|
32
|
+
- #DB4437
|
|
33
|
+
- #F4B400
|
|
34
|
+
- #0F9D58
|
|
35
|
+
|
|
36
|
+
## Tone of voice
|
|
37
|
+
|
|
38
|
+
- American English
|
|
39
|
+
- ...
|
|
40
|
+
`;
|
|
41
|
+
|
|
42
|
+
export async function POST(request) {
|
|
43
|
+
return puckHandler(request, {
|
|
44
|
+
ai: {
|
|
45
|
+
context,
|
|
46
|
+
},
|
|
47
|
+
});
|
|
48
|
+
}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Context for one-off pages
|
|
52
|
+
|
|
53
|
+
The `context` parameter on [`ai.generate()`](/docs/api-reference/ai/cloud-client/generate#context) allows you to provide additional business information when generating one-off pages:
|
|
54
|
+
|
|
55
|
+
```ts
|
|
56
|
+
|
|
57
|
+
const puck = puckCloud();
|
|
58
|
+
|
|
59
|
+
await puck.ai.generate({
|
|
60
|
+
config,
|
|
61
|
+
context: "We are Google. You help us build Google landing pages.",
|
|
62
|
+
prompt: "Create a page about our maps product",
|
|
63
|
+
});
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## Further reading
|
|
67
|
+
|
|
68
|
+
- [`ai.generate()` API reference](/docs/api-reference/ai/cloud-client/generate)
|
|
69
|
+
- [`puckHandler()` API reference](/docs/api-reference/ai/cloud-client/puck-handler)
|