@wix/ditto-codegen-public 1.0.359 → 1.0.361

package/dist/opencode-tools/required-permissions.ts

@@ -8,8 +8,7 @@ export default tool({
     "Pass SCOPE ID format (not human-readable names), e.g. `@wix/data` read → 'SCOPE.DC-DATA.READ', " +
     "write → 'SCOPE.DC-DATA.WRITE', embedded scripts → 'SCOPE.DC-APPS.MANAGE-EMBEDDED-SCRIPTS'. " +
     "Only include scope IDs you have explicitly seen in the Wix SDK documentation (via MCP or " +
-    "loaded skills) — NEVER guess or fabricate them. Omitting a permission is better than " +
-    "inventing one.",
+    "loaded skills) — NEVER guess or fabricate them. If unsure, skip this call entirely.",
   args: {
     permissions: tool.schema
       .array(tool.schema.string())

package/dist/opencode-tools/user-actions.ts

@@ -0,0 +1,19 @@
+import { tool } from "@opencode-ai/plugin";
+
+export default tool({
+  description:
+    "Declare the manual setup steps the user must perform for the generated app to " +
+    "work, as a single markdown string. Call once at the end, only if such setup is " +
+    "required.",
+  args: {
+    output: tool.schema
+      .string()
+      .describe(
+        "The setup steps, as markdown (a short intro line followed by a bulleted or " +
+          "numbered list). Rendered directly to the user.",
+      ),
+  },
+  async execute(args) {
+    return `✓ recorded user actions (${args.output.length} chars)`;
+  },
+});

package/dist/out.js

@@ -10826,7 +10826,7 @@ var require_CodeGenService = __commonJS({
       };
     }
     function toJobOutput(payload) {
-      const { requiredPermissions, files, extensions, error, agentMessage, ...rest } = payload;
+      const { requiredPermissions, files, extensions, error, agentMessage, userActions, ...rest } = payload;
       return {
         requiredPermissions,
         files: files?.map((file) => ({
@@ -10844,6 +10844,7 @@ var require_CodeGenService = __commonJS({
         })),
         error: toApiError(error),
         agentMessage,
+        userActions,
         agentOutput: Object.keys(rest).length > 0 ? rest : void 0
       };
     }
@@ -12247,6 +12248,7 @@ TOOL USAGE:
 - \`uuid\` to generate UUIDs (supports count param for multiple). Do NOT use bash.
 - \`wix-generate\` to scaffold extensions non-interactively (wraps \`wix generate --params\`). Prefer it over hand-writing extension boilerplate. It RETURNS the full contents of every file the CLI created, so trust that output and do NOT \`read\`/\`batch-read\` those files afterward. If it returns a \`FAILED\` block, fix the params per the error and retry. Pass an array to scaffold several extensions in one call.
 - \`required-permissions\` to declare the Wix app permissions the generated code needs. Call it ONCE at the end, and ONLY if permissions are actually needed \u2014 don't call it otherwise (see PERMISSIONS).
+- \`user-actions\` to declare manual steps the user must perform for the app to work. Call it ONCE at the end, and ONLY if there are manual steps \u2014 don't call it otherwise (see USER ACTIONS).
 - File operations \u2014 pick the BATCH tool whenever you have 2+ files; the single-file variants are 5\u201310\xD7 slower:
   - \`batch-write\` to create N new files in one call. NEVER call \`write\` more than once per turn \u2014 use batch-write instead. \`write\` is reserved for single-file creation.
   - \`batch-read\` to read N files in one call. NEVER call \`read\` more than once per turn \u2014 use batch-read instead.
@@ -12265,7 +12267,8 @@ IMPLEMENTATION WORKFLOW:
 4. **Register**: Register all extensions in \`src/extensions.ts\`. Include a \`progress\` call (e.g. "Registering extensions").
 5. **Validate**: Run \`validate\` (typecheck only). Fix any errors and re-validate until tsc passes. Include a \`progress\` call (e.g. "Running type checks"). Then run \`validate({ runBuild: true })\` ONCE to verify the build. Pass \`installDeps: true\` ONLY when you added a new dependency to package.json in this iteration; otherwise omit it (node_modules is pre-installed). Include a \`progress\` call (e.g. "Building project").
 6. **Declare permissions**: If the generated code requires Wix app permissions, call \`required-permissions\` ONCE with their SCOPE IDs (see PERMISSIONS below). Skip this step entirely if no permissions are needed.
-7. **Stop**: STOP immediately. Do NOT refactor, clean up, or verify.
+7. **Declare user actions**: If the user must perform manual steps for the app to work, call \`user-actions\` ONCE with them (see USER ACTIONS below). Skip this step entirely if there are none.
+8. **Stop**: STOP immediately. Do NOT refactor, clean up, or verify.
 
 EFFICIENCY:
 - Always prefer the BATCH variant: \`batch-write\` over multiple \`write\`s, \`batch-read\` over multiple \`read\`s, \`multi-edit\` over multiple \`edit\`s.
@@ -12285,9 +12288,32 @@ Use SCOPE ID format (not human-readable names). Examples:
 - \`@wix/data\` read \u2192 "SCOPE.DC-DATA.READ", write \u2192 "SCOPE.DC-DATA.WRITE"
 - Embedded scripts \u2192 "SCOPE.DC-APPS.MANAGE-EMBEDDED-SCRIPTS"
 
-CRITICAL: Only include permissions that you have explicitly seen in the Wix SDK documentation (via MCP or loaded skills). NEVER guess or fabricate permission scope IDs. If you are unsure which permission a feature requires, look it up in the docs first. Omitting a permission is better than inventing one that does not exist.
+CRITICAL: Only include permissions you have explicitly seen in the Wix SDK documentation (via MCP or loaded skills) \u2014 NEVER guess or infer a scope ID. If you cannot point to where you saw it, do NOT include it. When in doubt, skip the call entirely. A fabricated scope ID will show an error to the user and confuse them; a missing permission is just a warning the user can fix.
 
-Example: \`required-permissions({ permissions: ["SCOPE.DC-DATA.READ", "SCOPE.DC-DATA.WRITE"] })\``;
+Example: \`required-permissions({ permissions: ["SCOPE.DC-DATA.READ", "SCOPE.DC-DATA.WRITE"] })\`
+
+USER ACTIONS:
+After the final \`validate\` pass and before you Stop, call the \`user-actions\` tool ONCE ONLY if the app needs the user to perform manual setup for it to ACTUALLY WORK. This includes setup OUTSIDE Wix (third-party API keys, connecting an external account, registering a webhook elsewhere) AND setup INSIDE Wix that you could not do in code (e.g. creating a Wix Triggered Email template, configuring a Wix Automation, adding a value in Secrets Manager). If there is no such setup, do NOT call the tool at all.
+Pass the steps in the \`output\` arg as a single markdown string \u2014 it is rendered directly to the user, so keep it concise and user-facing (a short intro line followed by a bulleted or numbered list). Example:
+"After installing the app, complete these steps:\\n\\n1. **Add your Stripe secret key** \u2014 open the app's settings and paste your Stripe secret key.\\n2. **Create the stock-alert email template** \u2014 in your Wix dashboard, create a Triggered Email template so subscribers receive the alert email."
+
+AUDIENCE \u2014 be explicit about WHO performs each step. Two audiences exist: (1) the APP DEVELOPER (working in Dev Center / the app's own settings), and (2) the SITE OWNER who INSTALLS the app on their site (the merchant with the real Stripe account, their own Wix dashboard, etc.). Most third-party credentials and dashboard setup (their API key, creating a Triggered Email template in their dashboard, configuring an automation) are done by the INSTALLING site owner \u2014 not the developer. When a step is for the installing user, phrase it that way: start it with "After installing the app, \u2026" or "The site owner must \u2026", so it's clear it happens post-install on the installer's site. Use developer-facing phrasing only for steps the developer genuinely performs.
+
+CRITICAL \u2014 a user action is something the USER does in a dashboard, UI, or external system. It is NEVER a coding task. Do NOT ask the user to write, add, or modify code, call an API from the codebase, wire up logic, or "finish" an implementation \u2014 that is YOUR job. If a step can be done in code, you MUST do it now, not declare it. (E.g. if a feature needs to send an email, write the sending code yourself; only the dashboard email-template setup is a user action.)
+
+CRITICAL \u2014 declare ONLY steps the app REQUIRES to function as built. Do NOT include optional customizations, "for future" tweaks, nice-to-haves, or steps for an alternative path you did not implement. Every action must be mandatory for the app to work.
+
+CRITICAL \u2014 NEVER declare anything about permissions or scopes as a user action (e.g. "add SCOPE.DC-STORES.READ-PRODUCTS in Dev Center", "grant the X permission"). Permissions are declared ONLY through the \`required-permissions\` tool and handled by Wix's own flows. A permission/scope step must never appear in user-actions, no matter where it's performed.
+
+If a feature only works once the user does required manual setup (e.g. you logged a notification intent because the actual email needs a Triggered Email template), you MUST declare that step here \u2014 do NOT bury it in prose or leave it unsaid.
+
+Do NOT include the steps Wix already handles through its own flows:
+- ANYTHING about permissions or scopes \u2014 adding, granting, enabling, or configuring a permission/scope, whether in Dev Center or the dashboard. These are declared EXCLUSIVELY via the \`required-permissions\` tool.
+- Releasing a new app version.
+- Publishing the site.
+Also do NOT include things you already did in code (created files, registered extensions) or things the app does automatically on install. In particular, a site plugin configured with \`installation: { autoAdd: true }\` is placed on its slot automatically \u2014 NEVER tell the user to add it in the Editor. Only declare manual placement for slots that don't support auto-add (e.g. the checkout page).
+
+Example: \`user-actions({ output: "To finish setting up your app:\\n\\n1. **Add your Stripe secret key** \u2014 open the app settings and paste it." })\``;
   }
 });
 
@@ -12674,6 +12700,7 @@ var require_parser = __commonJS({
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.parseRequiredPermissions = parseRequiredPermissions;
+    exports2.parseUserActions = parseUserActions;
     exports2.parseFilesChanged = parseFilesChanged;
     exports2.parseAnswerText = parseAnswerText;
     exports2.createEmptyUsageStats = createEmptyUsageStats;
@@ -12705,6 +12732,23 @@ var require_parser = __commonJS({
       }
       return permissions;
     }
+    function parseUserActions(output) {
+      let markdown = "";
+      const lines = output.split("\n");
+      for (const line of lines) {
+        if (!line.trim())
+          continue;
+        const event = (0, types_1.tryParseJson)(line);
+        if (!event || event.type !== "tool_use" || event.part?.tool !== "user-actions" || event.part.state?.status !== "completed") {
+          continue;
+        }
+        const declared = event.part.state.input?.output;
+        if (typeof declared !== "string")
+          continue;
+        markdown = declared;
+      }
+      return markdown;
+    }
     function parseFilesChanged(output) {
       const filesChanged = [];
       const seenPaths = /* @__PURE__ */ new Set();
@@ -13167,6 +13211,7 @@ var require_result_builder = __commonJS({
         exitCode: null,
         stdout,
         stderr,
+        userActions: (0, parser_1.parseUserActions)(stdout),
         error: new ditto_codegen_types_12.TimeoutError(message),
         durationMs: Date.now() - startTime,
         requiredPermissions: [],
@@ -13181,6 +13226,7 @@ var require_result_builder = __commonJS({
         exitCode: code,
         stdout,
         stderr,
+        userActions: (0, parser_1.parseUserActions)(stdout),
         error: code !== 0 ? new ditto_codegen_types_12.ProcessExecutionError(`Code generation process exited unexpectedly (exit code ${code})`, {
           processType: ditto_codegen_types_12.ProcessType.EXECUTION,
           exitCode: code ?? void 0,
@@ -13199,6 +13245,7 @@ var require_result_builder = __commonJS({
         exitCode: null,
         stdout,
         stderr,
+        userActions: (0, parser_1.parseUserActions)(stdout),
         error: new ditto_codegen_types_12.ProcessExecutionError(`Failed to start code generation process: ${errorMessage}`, {
           processType: ditto_codegen_types_12.ProcessType.SPAWN,
           stderr
@@ -13346,6 +13393,7 @@ var require_executor = __commonJS({
         if (!isRetryableFailure) {
           const finalResult2 = {
             ...result,
+            userActions: (0, parser_1.parseUserActions)(accumulatedStdout),
             filesChanged: (0, parser_1.parseFilesChanged)(accumulatedStdout),
             usage: accumulatedUsage,
             skillsUsed: accumulatedSkills
@@ -13366,6 +13414,7 @@ var require_executor = __commonJS({
       });
       const finalResult = {
         ...lastResult,
+        userActions: (0, parser_1.parseUserActions)(accumulatedStdout),
         filesChanged: (0, parser_1.parseFilesChanged)(accumulatedStdout),
         usage: accumulatedUsage,
         skillsUsed: Array.from(accumulatedSkills)
@@ -13448,6 +13497,7 @@ var require_executor = __commonJS({
             exitCode: null,
             stdout: state.stdout,
             stderr: state.stderr,
+            userActions: (0, parser_1.parseUserActions)(state.stdout),
             error: new ditto_codegen_types_12.ProcessExecutionError(`Code generation process failed to run: ${error instanceof Error ? error.message : String(error)}`, {
               processType: ditto_codegen_types_12.ProcessType.EXECUTION,
               cause: error
@@ -13748,7 +13798,9 @@ var require_codegen_flow_helpers = __commonJS({
       await codeGenerationService_12.codeGenerationService.updateJob(jobContext.jobId, payload);
     }
     async function updateParentTaskStatus(jobContext, status, error) {
-      await codeGenerationService_12.codeGenerationService.updateTask(jobContext.jobId, jobContext.taskId, status, error ? { error: (0, utils_1.serializeError)(error) } : {});
+      await codeGenerationService_12.codeGenerationService.updateTask(jobContext.jobId, jobContext.taskId, status, {
+        ...error ? { error: (0, utils_1.serializeError)(error) } : {}
+      });
     }
     function getOutputPath() {
       const outputDir = process.env.OUTPUT_PATH || DEFAULT_OUTPUT_PATH;
@@ -18966,6 +19018,7 @@ var require_opencode_init = __commonJS({
         await (0, inject_created_by_1.injectCreatedByIntoExtensionFiles)(outputPath, extensions.created);
         await (0, codegen_flow_helpers_12.updateJobPayload)(localJobContext, {
           requiredPermissions: result.requiredPermissions,
+          userActions: result.userActions,
           files,
           ...agentOutput,
           extensions
@@ -19149,6 +19202,7 @@ var require_opencode_iterate = __commonJS({
         await (0, inject_created_by_1.injectCreatedByIntoExtensionFiles)(outputPath, extensions.created);
         await (0, codegen_flow_helpers_12.updateJobPayload)(localJobContext, {
           requiredPermissions: result.requiredPermissions,
+          userActions: result.userActions,
           files,
           ...agentOutput,
           extensions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/ditto-codegen-public",
-  "version": "1.0.359",
+  "version": "1.0.361",
   "description": "AI-powered Wix CLI app generator - standalone executable",
   "scripts": {
     "build": "node build.mjs",
@@ -29,5 +29,5 @@
     "esbuild": "^0.27.2",
     "vitest": "^4.0.16"
   },
-  "falconPackageHash": "359e16ff3223fa5f085d7a83fd81fa8b04c7aa55f5e38602790b2b8f"
+  "falconPackageHash": "7b4f927c3fdd53219a51a891cc6b6828c72bd0ebe13e7d33b7da4cd1"
 }