openyida 2026.10.12-beta.2 → 2026.10.13

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Alibaba Group Holding Limited
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+MIT License
+
+Copyright (c) 2026 Alibaba Group Holding Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.

package/README.md

@@ -118,6 +118,7 @@ The agent can then call OpenYida commands to create the application, generate so
 | [Codex](https://openai.com/codex/) | Full support |
 | [Claude Code](https://claude.ai/code) | Full support |
 | [MuleRun](https://mulerun.com) | Full support |
+| [OpenCode](https://opencode.ai) | Full support |
 | [Cursor](https://cursor.com/) | Full support |
 | [Visual Studio Code](https://code.visualstudio.com/) | Full support |
 | QwenWork（千问办公） | Full support |
@@ -162,6 +163,18 @@ openyida/
 
 For a user-facing list of supported features and matching CLI commands, see [OpenYida 功能完整列表](https://demo.aliwork.com/o/openyida/helpCenter?openyidaPath=capabilities).
 
+### Style Selection and Optional Previews
+
+Only show reference previews when the user explicitly requests them. Style choices use the host's supported ask_human tool on every platform.
+
+```bash
+openyida sample yida-design theme-preview --theme-ids app-sage,app-teal,app-terminal,app-platinum --output .cache/theme-preview.html --json
+```
+
+This creates a read-only HTML gallery of all requested themes: titles and images only, four to six columns on desktop, fewer on narrow screens, with no row limit. It has no selection controls and refuses to overwrite existing files. Open it with the host's preview tools; raw HTML is not guaranteed to render in chat. QwenWork may alternatively prepare the same read-only template with `sample yida-design theme-selector --json` and pass its returned relative `widget_path` to `qoder_show_widget`. Neither preview path submits a choice.
+
+Ready style questions join the same ask_human call as other necessary questions; split only for dependencies or host limits. Pop art is omitted unless explicitly requested or the primary task is showcase-oriented. Previewing app-pop requires --pop-art-context explicit-request or showcase, based on that evidence.
+
 ### Application and Form Management
 
 ```bash
@@ -403,6 +416,8 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 | `openyida design-plan materialize <build-plan.json> [--from-preview \| --business-file <json> --visual-file <json>] [--output-dir <dir>] [--rebase-parts] [--check] [--json]` | Generate or update plan documents and theme with consistency checks |
 | `openyida design-plan patch <build-plan.json> --set <path=value> [--set <path=value> ...] [--materialize] [--output-dir <dir>] [--json]` | Patch plan fields and optionally sync documents and theme |
 | `openyida update-app <appType> [--name "..."] [--desc "..."] [--icon <name>] [--icon-color <color>] [--colour <key>] [--theme-color <color>] [--theme-file <css>] [--confirm-legacy-app-style] [--disable-custom-theme] [--nav-theme light\|dark\|white\|gray] [--logo-source appIcon\|customImage] [--layout side\|top\|l_shape] [--hide-app-nav\|--show-app-nav]` | Update app info |
+| `openyida app-theme snapshot <appType> --output-dir <new-dir> [--json]` | Archive application theme settings and CSS (read-only) |
+| `openyida app-theme restore <appType> --snapshot <before.json> --expected-current <after.json> [--check \| --confirm --output-dir <new-dir>] [--json]` | Check or restore an application theme snapshot (supported exact values only) |
 | `openyida upgrade-app-theme <appType> --explicit-request [--confirm \| --prepare --output-dir <dir>] [--json]` | Upgrade an AI-built legacy app theme (explicit request and ask_human confirmation required) |
 | `openyida app-online <appType> [--to-ding-app-center] [--show-app-center]` | Enable a Yida app |
 | `openyida app-offline <appType> [--to-ding-app-center] [--show-app-center]` | Disable a Yida app |
@@ -522,11 +537,10 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 |---------|-------------|
 | `openyida commands [--json]` | Output machine-readable command manifest |
 | `openyida agent-capabilities [--json] [--summary-json\|--compact]` | Output one-shot agent capability snapshot |
-| `openyida agent <doctor\|diagnose\|status\|connect\|run\|disconnect\|logout\|logs> [options]` | Connect a local Agent (Go runtime, development preview) |
 | `openyida a2a <serve\|agent-card> [options]` | Start local read-only A2A adapter or print Agent Card |
 | `openyida bridge start [--token <pair-token>] [--port 6736] [--origin https://demo.aliwork.com] [--open\|--no-open]` | Start OpenYida local web bridge service |
 | `openyida copy [--force]` | Copy project working directory |
-| `openyida sample [--list] [<skill> <name>] [--output <file-or-directory>] [--var KEY=VALUE ...] [--design-file <design.md>] [--style-id <themeId\|free-creative>]` | Output code samples/templates |
+| `openyida sample [--list] [<skill> <name>] [--output <file-or-directory>] [--var KEY=VALUE ...] [--design-file <design.md>] [--style-id <themeId\|free-creative>] [--theme-ids <id,...>] [--pop-art-context <explicit-request\|showcase>]` | Output code samples/templates |
 | `openyida doctor [--fix]` | Environment diagnostics & auto-fix |
 | `openyida db-seq-fix [--fix]` | Detect and repair PostgreSQL sequence drift |
 | `openyida formula evaluate <formula\|file> [--schema file]` | Static-check Yida formula syntax and field refs |
@@ -591,31 +605,6 @@ Form field definitions can include `alias` or `componentAlias` to populate Yida
 
 `openyida integration create` supports form events (`insert`, `update`, `delete`, `comment`) and approval events (`processFinish`, `activityTask`; aliases: `approval`, `approvalNode`). Approval events require `--approval-actions agree,disagree,terminated`; `activityTask` also requires `--approval-node-ids <nodeId,...>`. Passing `--process-code` selects a full graph replacement and now requires explicit `--replace`; it is not a safe update. `integration update` currently performs capability detection only: because full platform `processJson` + `viewJson` readback is unproven, it writes a redacted local probe artifact and returns `PLATFORM_PROBE_REQUIRED` before authentication, spec reading, or remote writes. It does not edit a flow.
 
-### Local Agent development preview
-
-`openyida agent` is a thin Node launcher for a separately supplied Go runtime. Node does not connect to the agent service or manage provider sessions. Platform runtime packages are **not published** in this preview; no Go executable is discovered on `PATH` and no provider is installed or invoked by Node.
-
-The Local Agent Beta production allowlist contains macOS and Windows only. Linux remains supported by the ordinary OpenYida CLI and by the explicit development-runtime workflow below, but Linux Local Agent packages are not published and production `connect`/`run` are rejected until native acceptance is complete.
-
-```bash
-openyida agent doctor --json
-openyida agent doctor --development-runtime --runtime-path /absolute/path/openyida-runtime --runtime-manifest /absolute/path/runtime-manifest.json
-openyida agent connect --development-runtime --runtime-path /absolute/path/openyida-runtime --runtime-manifest /absolute/path/runtime-manifest.json --endpoint https://agent.example.test --endpoint-id configured-platform-id
-openyida agent run --development-runtime --runtime-path /absolute/path/openyida-runtime --runtime-manifest /absolute/path/runtime-manifest.json --endpoint https://agent.example.test --endpoint-id configured-platform-id --provider qoder --provider-path /absolute/path/qodercli
-```
-
-Development manifest v1 specifies runtime version, protocol `1`, Node-style OS/architecture names, and `binary: {file, sha256}`; it requires the explicit `--development-runtime` flag. This is an integrity check, **not a publisher signature**. The production loader requires a strictly validated v2 manifest, exact approved platform-package version/digest, and an Ed25519 signature over the original manifest bytes using trust roots bundled in the Node host. The release catalog is currently empty: no production signing key or package is implied to exist. See the [launcher contract](lib/agent/PROTOCOL.md).
-
-`connect` supports two equivalent enrollment entries. CLI-first opens the Yida browser approval page and returns through a state/PKCE-protected loopback callback. Web-first copies one five-minute command containing `--enroll`; the token is single-use and carries no business authority. Neither path reads or uploads an ordinary OpenYida login profile.
-
-One installation may connect to multiple organizations. Node keeps only a shared Installation ID at the installation root; each organization authorization gets an isolated private Connection state directory, device credentials, journals, control socket, and frozen bundle. `agent connect` keeps the new Connection online in the foreground, while `agent run`, `status`, `disconnect`, and `logout` enumerate every valid Connection. Each Connection registers all locally discovered Qoder and Codex Runtimes, and the web UI selects computer, CLI, and model.
-
-For each attempt, Go injects `OPENYIDA_MANAGED_RUN=1`, the cloud user/corp/app/run/attempt context, and a fixed-value Tianshu task grant with an initial 60-minute lease. The CLI uses that grant instead of local auth and sends scope-correlation headers. While the authenticated device connection and server-side Run remain active, yida-agent can renew the same bearer server-to-server; the CLI cannot renew it and never receives a task refresh token. Tianshu independently checks the grant against the requested app and rejects application creation, identity/environment changes, arbitrary batches, and cross-application requests. `formUuid` remains optional per-turn page-focus context, so one app-bound session can work across pages in that application. Without `OPENYIDA_MANAGED_RUN`, existing login, token refresh, and command behavior are unchanged.
-
-Before `connect` or `run`, Node now freezes the verified runtime bytes, CLI, full production dependency closure, and packaged Skills into a private content-addressed bundle. Source changes during copying fail closed. Existing bundles are verified, never silently repaired or garbage-collected by Node, and survive replacement/removal of the original npm directory. Go owns active/session references and version activation; the external Node executable and provider installations are not copied or managed by npm. A separate parent-watch pipe and a 15-second stop grace prevent normal config EOF from being mistaken for parent death; an unconfirmed forced stop remains unknown.
-
-This is not an OS sandbox or an authorization boundary against arbitrary shell code. Production signing/release infrastructure, full Go/provider recovery and upgrade acceptance, and OS/architecture-specific provider E2E are not claimed by these fake-process tests. Auto-update is disabled for `agent` and managed invocations; ordinary CLI commands neither spawn nor download the runtime.
-
 ## Agent Skills
 
 The `yida-skills/` directory is the source skill library used by OpenYida during development and distributed with the npm package.

package/bin/yida.js

@@ -24,8 +24,6 @@ const { COMMAND_GROUPS, buildCommandManifest, findCommandSuggestion } = require(
 const command = process.argv[2];
 const args = process.argv.slice(3);
 const rawArgs = process.argv.slice(3);
-const { beginCommandReceipt } = require('../lib/agent/command-receipt');
-let commandReceipt;
 
 function shouldUseEnvManagement(argsList) {
   const subCommand = argsList[0];
@@ -573,26 +571,6 @@ function assertNoUnsupportedLegacyLoginFlags(...argLists) {
 }
 
 async function main() {
-  const { assertManagedInvocation, resolveManagedHelp } = require('../lib/agent/managed-run');
-  const { readManagedContext } = require('../lib/agent/managed-context');
-  if (readManagedContext() && [command, ...rawArgs].some(arg => arg === '--help' || arg === '-h')) {
-    assertManagedInvocation(command, rawArgs);
-    const entries = resolveManagedHelp(command, rawArgs, { t, version: currentVersion });
-    // Managed help is static and local: no Receipt, auth, update, first-run
-    // guide or business command module may run on this path.
-    commandReceipt = { finish() {} };
-    if (rawArgs.includes('--json')) {
-      console.log(JSON.stringify({ name: 'openyida', version: currentVersion, commands: entries }, null, 2));
-    } else {
-      printCommandUsage(...entries.flatMap(entry => [entry.usage, entry.description, ...(entry.examples || [])]));
-    }
-    return;
-  }
-  commandReceipt = beginCommandReceipt({ command, args: rawArgs });
-  process.once('exit', code => {
-    try {commandReceipt.finish(code);} catch {process.exitCode = 1;}
-  });
-  assertManagedInvocation(command, rawArgs);
   applyQuietFlag();
   applyGlobalEnvironmentFlags();
 
@@ -641,12 +619,6 @@ async function main() {
       break;
     }
 
-    case 'agent': {
-      const { run } = require('../lib/agent/cmd');
-      await run(args);
-      break;
-    }
-
     case 'mcp': {
       const { runStdioServer } = require('../lib/mcp/server');
       runStdioServer();
@@ -922,8 +894,8 @@ async function main() {
       if (args.length < 4) {
         throwCliUsage(t('cli.form_config_usage'), t('cli.form_config_example'));
       }
-      const { run: runUpdateFormConfig } = require('../lib/app/update-form-config');
-      await runUpdateFormConfig(args);
+      process.argv = [process.argv[0], process.argv[1], ...args];
+      require('../lib/app/update-form-config');
       break;
     }
 
@@ -942,6 +914,11 @@ async function main() {
       break;
     }
 
+    case 'app-theme': {
+      await require('../lib/app/app-theme').run(args);
+      break;
+    }
+
     case 'upgrade-app-theme': {
       await require('../lib/app/upgrade-app-theme').run(args);
       break;
@@ -1314,9 +1291,7 @@ async function main() {
 }
 
 main()
-  .then(() => { commandReceipt.finish(process.exitCode || 0); })
   .catch((err) => {
-    try {commandReceipt?.finish(err && err.exitCode ? err.exitCode : 1);} catch { /* Intent remains recoverable. */ }
     if (shouldUseStructuredErrorOutput(err, args)) {
       console.error(JSON.stringify(toErrorPayload(err), null, 2));
     } else if (isCliError(err)) {

package/lib/app/app-theme.js

@@ -0,0 +1,289 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const https = require('https');
+const querystring = require('querystring');
+const { httpGet, httpPost, requestWithAutoLogin } = require('../core/utils');
+const { createAuthRef } = require('../core/yida-client');
+const { throwCommandError, throwUsage } = require('../core/command-errors');
+const { t } = require('../core/i18n');
+const { parseThemeContext } = require('./upgrade-app-theme');
+
+// Deliberately exclude business configuration, theme migration flags and app metadata.
+const KEYS = ['COLOUR', 'THEME_COLOR', 'NAV_THEME', 'LAY_OUT_DIRECTION', 'NAVTYPE',
+  'HIDE_APP_NAV', 'LOGO_SOURCE', 'HOMEPAGELOGO', 'CUSTOM_THEME_STYLE'];
+const MODE_KEYS = ['APP_THEME_MODE', 'CREATED_WITH_MODERN_THEME'];
+const MAX_BYTES = 20 * 1024 * 1024;
+const fail = (code, details) => throwCommandError(t('app_theme.' + code.toLowerCase()), { code, details });
+const hash = value => crypto.createHash('sha256').update(value).digest('hex');
+function canonical(value) {
+  if (Array.isArray(value)) { return '[' + value.map(canonical).join(',') + ']'; }
+  if (value && typeof value === 'object') {
+    return '{' + Object.keys(value).sort().map(key => JSON.stringify(key) + ':' + canonical(value[key])).join(',') + '}';
+  }
+  return JSON.stringify(value);
+}
+const digest = value => hash(canonical(value));
+const equal = (a, b) => canonical(a) === canonical(b);
+const appIdValid = value => typeof value === 'string' && /^[A-Za-z0-9_-]+$/.test(value);
+const exactKeys = (value, keys) => value && typeof value === 'object' && !Array.isArray(value) && equal(Object.keys(value).sort(), [...keys].sort());
+
+function parseArgs(args = []) {
+  const params = { action: args[0] };
+  if (['--help', '-h'].includes(args[0])) { return { help: true }; }
+  if (!['snapshot', 'restore'].includes(params.action)) { throwUsage(t('app_theme.usage')); }
+  const values = { '--output-dir': 'outputDir', '--snapshot': 'snapshot', '--expected-current': 'expectedCurrent' };
+  const flags = { '--json': 'json', '--help': 'help', '-h': 'help', '--check': 'check', '--confirm': 'confirm' };
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    const field = values[arg] || flags[arg];
+    if (field && params[field] !== undefined) { throwUsage(t('cli_argument.invalid', arg)); }
+    if (values[arg] && args[i + 1] && !args[i + 1].startsWith('-')) { params[field] = args[++i]; }
+    else if (flags[arg]) { params[field] = true; }
+    else if (!arg.startsWith('-') && !params.appType) { params.appType = arg; }
+    else { throwUsage(t('cli_argument.invalid', arg)); }
+  }
+  if (params.help) { return params; }
+  validateParams(params);
+  return params;
+}
+
+function validateParams(p) {
+  if (!appIdValid(p.appType) || !['snapshot', 'restore'].includes(p.action) ||
+      (p.action === 'snapshot' && (!p.outputDir || p.snapshot || p.expectedCurrent || p.check || p.confirm)) ||
+      (p.action === 'restore' && (!p.snapshot || !p.expectedCurrent || (p.check && p.confirm) || (p.confirm && !p.outputDir)))) {
+    throwUsage(t('app_theme.usage'));
+  }
+}
+
+function identity(appType, auth) {
+  let url;
+  try { url = new URL(auth.baseUrl); } catch (_) { fail('APP_THEME_IDENTITY_INVALID'); }
+  if (!auth.corpId || !['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+    fail('APP_THEME_IDENTITY_INVALID');
+  }
+  return { appType, corpId: auth.corpId, baseUrl: url.href.replace(/\/$/, '') };
+}
+
+async function configRequest(appType, auth, endpoint, fields, target = identity(appType, auth)) {
+  return requestWithAutoLogin(current => {
+    if (!equal(target, identity(appType, current))) { fail('APP_THEME_IDENTITY_INVALID'); }
+    return httpPost(current.baseUrl, `/${encodeURIComponent(appType)}/query/app/${endpoint}.json`,
+      querystring.stringify({ appType, ...fields, _csrf_token: current.csrfToken }));
+  }, auth);
+}
+
+async function readState(appType, auth) {
+  const target = identity(appType, auth);
+  const html = await requestWithAutoLogin(current => httpGet(current.baseUrl,
+    `/${appType}/admin`, { _stamp: Date.now() }, { responseType: 'text' }), auth);
+  const context = parseThemeContext(html, ['appType', 'corpId', 'appThemeEnable', 'appThemeMode']);
+  if (context.appType !== target.appType || context.corpId !== target.corpId) { fail('APP_THEME_IDENTITY_INVALID'); }
+  const response = await requestWithAutoLogin(current => httpGet(current.baseUrl,
+    `/${appType}/query/app/getAppIncludingAecpInfo.json`, { appKey: appType, _stamp: Date.now() }), auth);
+  const app = response?.content;
+  if (response?.success !== true || !app || typeof app !== 'object' || typeof app.icon !== 'string') {
+    fail('APP_THEME_SNAPSHOT_INVALID');
+  }
+  const config = {};
+  const modes = {};
+  for (const key of [...KEYS, ...MODE_KEYS]) {
+    const result = await configRequest(appType, auth, 'getSingleConfig', { key });
+    const empty = exactKeys(result?.content, []);
+    if (result?.success !== true || (result.content !== null && typeof result.content !== 'string' && !empty)) {
+      fail('APP_THEME_READ_FAILED', { key });
+    }
+    (KEYS.includes(key) ? config : modes)[key] = empty ? null : result.content;
+  }
+  if (!equal(target, identity(appType, auth))) { fail('APP_THEME_IDENTITY_INVALID'); }
+  return { identity: target, config, protected: { modes, appThemeEnable: context.appThemeEnable,
+    appThemeMode: context.appThemeMode, icon: app.icon } };
+}
+
+function styleOf(state) {
+  const raw = state.config.CUSTOM_THEME_STYLE;
+  if (raw === null || raw === '') { return null; }
+  let style;
+  try { style = JSON.parse(raw); } catch (_) { fail('APP_THEME_SNAPSHOT_INVALID'); }
+  if (!style || Array.isArray(style) || typeof style !== 'object' ||
+      Object.keys(style).some(key => !['enabled', 'iframePropagation', 'cssUrl', 'cssFileName'].includes(key)) ||
+      ['enabled', 'iframePropagation'].some(key => Object.hasOwn(style, key) && typeof style[key] !== 'boolean') ||
+      ['cssUrl', 'cssFileName'].some(key => Object.hasOwn(style, key) && typeof style[key] !== 'string') ||
+      (style.enabled === true && !style.cssUrl)) { fail('APP_THEME_SNAPSHOT_INVALID'); }
+  return style;
+}
+
+// CSS is fetched without Yida credentials. Redirects, oversized files and HTML/login bodies fail closed.
+function downloadCss(url) {
+  return new Promise((resolve, reject) => {
+    let parsed;
+    try { parsed = new URL(url); } catch (_) { reject(new Error(t('app_theme.app_theme_css_unavailable'))); return; }
+    if (parsed.protocol !== 'https:' || parsed.username || parsed.password || parsed.hash) {
+      reject(new Error(t('app_theme.app_theme_css_unavailable'))); return;
+    }
+    const request = https.get(parsed, { headers: { Accept: 'text/css' } }, response => {
+      if (response.statusCode !== 200 || !/^text\/css(?:;|$)/i.test(response.headers['content-type'] || '')) {
+        response.resume(); reject(new Error(t('app_theme.app_theme_css_unavailable'))); return;
+      }
+      const chunks = [];
+      let length = 0;
+      response.on('data', chunk => {
+        length += chunk.length;
+        if (length > MAX_BYTES) { request.destroy(new Error(t('app_theme.app_theme_css_unavailable'))); }
+        else { chunks.push(chunk); }
+      });
+      response.on('error', reject);
+      response.on('end', () => {
+        const bytes = Buffer.concat(chunks);
+        if (!bytes.length || /<\s*(?:!doctype|html|script)\b/i.test(bytes.toString('utf8'))) {
+          reject(new Error(t('app_theme.app_theme_css_unavailable')));
+        } else { resolve(bytes); }
+      });
+    });
+    request.setTimeout(15000, () => request.destroy(new Error(t('app_theme.app_theme_css_unavailable'))));
+    request.on('error', reject);
+  });
+}
+
+function newDirectory(dir) {
+  const absolute = path.resolve(dir);
+  fs.mkdirSync(path.dirname(absolute), { recursive: true });
+  try { fs.mkdirSync(absolute, { mode: 0o700 }); }
+  catch (_) { fail('APP_THEME_OUTPUT_EXISTS'); }
+  return absolute;
+}
+function writeJson(file, value, exclusive = false) {
+  fs.writeFileSync(file, JSON.stringify(value, null, 2) + '\n', { mode: 0o600, flag: exclusive ? 'wx' : 'w' });
+}
+
+function capabilities(state) {
+  return { restorableKeys: KEYS.filter(key => typeof state.config[key] === 'string' && state.config[key].trim()),
+    cannotClearKeys: KEYS.filter(key => !state.config[key]?.trim()),
+    protectedFields: ['icon', 'appThemeEnable', 'appThemeMode', ...MODE_KEYS],
+    scope: 'application-theme-config', supportsPageRestore: false, supportsIconRestore: false };
+}
+
+async function snapshot(p, auth, fetchCss = downloadCss) {
+  validateParams({ ...p, action: 'snapshot' });
+  const dir = newDirectory(p.outputDir);
+  const state = await readState(p.appType, auth);
+  const style = styleOf(state);
+  let css = null;
+  if (style?.cssUrl) {
+    const bytes = await fetchCss(style.cssUrl);
+    fs.writeFileSync(path.join(dir, 'theme.css'), bytes, { mode: 0o600, flag: 'wx' });
+    css = { file: 'theme.css', sha256: hash(bytes), bytes: bytes.length };
+  }
+  if (!equal(state, await readState(p.appType, auth))) { fail('APP_THEME_CONFLICT'); }
+  const data = { version: 1, createdAt: new Date().toISOString(), state, css };
+  const document = { ...data, sha256: digest(data) };
+  const file = path.join(dir, 'snapshot.json');
+  writeJson(file, document, true);
+  loadSnapshot(file); // Re-read actual local bytes before claiming a usable backup.
+  return { success: true, snapshot: file, fingerprint: digest(state), ...capabilities(state), runtimeVerified: false };
+}
+
+function loadSnapshot(file) {
+  try {
+    if (!fs.lstatSync(file).isFile() || fs.statSync(file).size > MAX_BYTES) { throw new Error(); }
+    const doc = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const { sha256, ...data } = doc;
+    const state = data.state;
+    if (!exactKeys(doc, ['version', 'createdAt', 'state', 'css', 'sha256']) || data.version !== 1 ||
+        typeof data.createdAt !== 'string' || sha256 !== digest(data) ||
+        !exactKeys(state, ['identity', 'config', 'protected']) ||
+        !exactKeys(state.identity, ['appType', 'corpId', 'baseUrl']) || !appIdValid(state.identity.appType) ||
+        !equal(state.identity, identity(state.identity.appType, state.identity)) ||
+        !exactKeys(state.config, KEYS) || !exactKeys(state.protected, ['modes', 'appThemeEnable', 'appThemeMode', 'icon']) ||
+        !exactKeys(state.protected.modes, MODE_KEYS) ||
+        Object.values({ ...state.config, ...state.protected.modes }).some(v => v !== null && typeof v !== 'string') ||
+        ['icon', 'appThemeEnable', 'appThemeMode'].some(k => typeof state.protected[k] !== 'string')) { throw new Error(); }
+    const style = styleOf(state);
+    if (style?.cssUrl) {
+      if (!exactKeys(data.css, ['file', 'sha256', 'bytes']) || data.css.file !== 'theme.css') { throw new Error(); }
+      const cssFile = path.join(path.dirname(file), 'theme.css');
+      if (!fs.lstatSync(cssFile).isFile() || fs.statSync(cssFile).size > MAX_BYTES) { throw new Error(); }
+      const bytes = fs.readFileSync(cssFile);
+      if (!bytes.length || hash(bytes) !== data.css.sha256 || bytes.length !== data.css.bytes) { throw new Error(); }
+    } else if (data.css !== null) { throw new Error(); }
+    return doc;
+  } catch (_) { fail('APP_THEME_SNAPSHOT_INVALID'); }
+}
+
+function planRestore(before, after) {
+  const blockers = [];
+  if (!equal(before.identity, after.identity)) { blockers.push({ reason: 'identity_mismatch' }); }
+  if (!equal(before.protected, after.protected)) { blockers.push({ reason: 'protected_fields_changed' }); }
+  const changes = KEYS.filter(key => before.config[key] !== after.config[key]).map(key => ({ key, value: before.config[key] }));
+  for (const { key, value } of changes) {
+    if (value === null || !value.trim()) { blockers.push({ key, reason: 'cannot_restore_absent_or_empty_value' }); }
+  }
+  return { changes, blockers };
+}
+
+async function restore(p, auth, fetchCss = downloadCss) {
+  validateParams({ ...p, action: 'restore' });
+  const before = loadSnapshot(p.snapshot);
+  const after = loadSnapshot(p.expectedCurrent);
+  if (!equal(before.state.identity, identity(p.appType, auth)) || !equal(after.state.identity, identity(p.appType, auth))) {
+    fail('APP_THEME_IDENTITY_INVALID');
+  }
+  const plan = planRestore(before.state, after.state);
+  const current = await readState(p.appType, auth);
+  if (!equal(current, after.state)) { fail('APP_THEME_CONFLICT'); }
+  if (plan.changes.some(({ key }) => key === 'CUSTOM_THEME_STYLE') && before.css) {
+    try {
+      if (hash(await fetchCss(styleOf(before.state).cssUrl)) !== before.css.sha256) { throw new Error(); }
+    } catch (_) { plan.blockers.push({ reason: 'original_css_unavailable_or_changed' }); }
+  }
+  const report = { success: true, canRestore: !plan.blockers.length, changes: plan.changes.map(({ key }) => key),
+    blockers: plan.blockers, verificationScope: 'application-theme-config', runtimeVerified: false };
+  if (p.confirm !== true) { return { ...report, checkOnly: true }; }
+  if (plan.blockers.length) { fail('APP_THEME_RESTORE_BLOCKED', report); }
+  const dir = newDirectory(p.outputDir);
+  const journalFile = path.join(dir, 'restore.json');
+  const journal = { version: 1, identity: current.identity, targetFingerprint: digest(before.state),
+    expectedFingerprint: digest(after.state), status: 'prepared', attemptedKey: null, verifiedWrites: [] };
+  writeJson(journalFile, journal, true);
+  let expected = current;
+  try {
+    for (const change of plan.changes) {
+      // No server-side compare-and-swap exists. Check the complete tracked state before every write.
+      if (!equal(expected, await readState(p.appType, auth))) { fail('APP_THEME_CONFLICT'); }
+      journal.status = 'writing';
+      journal.attemptedKey = change.key;
+      writeJson(journalFile, journal);
+      const response = await configRequest(p.appType, auth, 'updateSingleConfig', change, before.state.identity);
+      if (response?.success !== true || response.content !== true) { fail('APP_THEME_WRITE_FAILED'); }
+      expected = { ...expected, config: { ...expected.config, [change.key]: change.value } };
+      if (!equal(expected, await readState(p.appType, auth))) { fail('APP_THEME_VERIFY_FAILED'); }
+      journal.verifiedWrites.push(change.key);
+      journal.attemptedKey = null;
+      writeJson(journalFile, journal);
+    }
+    if (!equal(before.state, await readState(p.appType, auth))) { fail('APP_THEME_VERIFY_FAILED'); }
+    journal.status = 'restored';
+    writeJson(journalFile, journal);
+    return { ...report, changed: plan.changes.length > 0, verified: true, journal: journalFile };
+  } catch (error) {
+    journal.status = 'failed_or_unknown';
+    journal.errorCode = error.code || 'APP_THEME_WRITE_FAILED';
+    try { journal.observedState = await readState(p.appType, auth); } catch (_) { journal.readbackFailed = true; }
+    try { writeJson(journalFile, journal); } catch (_) { /* The pre-write journal remains available. */ }
+    fail('APP_THEME_RESTORE_INCOMPLETE', { journal: journalFile, attemptedKey: journal.attemptedKey,
+      verifiedWrites: journal.verifiedWrites, cause: journal.errorCode });
+  }
+}
+
+async function run(args) {
+  const params = parseArgs(args);
+  if (params.help) { console.log(t('app_theme.usage')); return; }
+  const auth = createAuthRef();
+  const result = await (params.action === 'snapshot' ? snapshot(params, auth) : restore(params, auth));
+  console.log(JSON.stringify(result, null, 2));
+  return result;
+}
+
+module.exports = { run, parseArgs, snapshot, restore, loadSnapshot, planRestore, downloadCss, KEYS, MODE_KEYS };

package/lib/app/check-prd-completeness.js

@@ -9,9 +9,8 @@ const { auditAssetExecution } = require('../asset/asset-execution');
 const { fetchFormPageList } = require('./form-navigation');
 
 const CHECKABLE_RESOURCE_KINDS = new Set(['display-page', 'normal-form', 'process-form']);
-const APP_TYPE_OPTIONS = Object.freeze(['--app-type', '--appType', '--app_type']);
 
-function parseArgs(args = [], options = {}) {
+function parseArgs(args = []) {
   const parsed = {
     prdPath: '',
     appType: '',
@@ -20,29 +19,20 @@ function parseArgs(args = [], options = {}) {
     help: false,
   };
 
-  const seen = new Set();
   for (let index = 0; index < args.length; index++) {
     const arg = args[index];
-    const key = APP_TYPE_OPTIONS.includes(arg) ? 'appType'
-      : ['--build-manifest', '--manifest'].includes(arg) ? 'buildManifestPath' : arg;
-    if (options.strict && arg.startsWith('-') && seen.has(key)) {
-      throwUsage(t('check_prd_completeness.usage'), t('check_prd_completeness.example'));
-    }
-    if (options.strict && arg.startsWith('-')) {seen.add(key);}
     if (arg === '--help' || arg === '-h') {
       parsed.help = true;
     } else if (arg === '--json') {
       parsed.json = true;
-    } else if (APP_TYPE_OPTIONS.includes(arg) && args[index + 1] && (!options.strict || !args[index + 1].startsWith('-'))) {
+    } else if ((arg === '--app-type' || arg === '--appType' || arg === '--app_type') && args[index + 1]) {
       parsed.appType = args[index + 1];
       index++;
-    } else if ((arg === '--build-manifest' || arg === '--manifest') && args[index + 1] && (!options.strict || !args[index + 1].startsWith('-'))) {
+    } else if ((arg === '--build-manifest' || arg === '--manifest') && args[index + 1]) {
       parsed.buildManifestPath = args[index + 1];
       index++;
-    } else if (!arg.startsWith(options.strict ? '-' : '--') && !parsed.prdPath) {
+    } else if (!arg.startsWith('--') && !parsed.prdPath) {
       parsed.prdPath = arg;
-    } else if (options.strict) {
-      throwUsage(t('check_prd_completeness.usage'), t('check_prd_completeness.example'));
     }
   }
 
@@ -637,7 +627,6 @@ async function run(args = []) {
 }
 
 module.exports = {
-  APP_TYPE_OPTIONS,
   evaluatePrdCompleteness,
   extractResources,
   loadBuildManifest,

package/lib/app/create-form/batch.js

@@ -6,7 +6,6 @@ const crypto = require('crypto');
 const { execFile } = require('child_process');
 const { CliError } = require('../../core/cli-error');
 const { t } = require('../../core/i18n');
-const { redactSensitive } = require('../../core/redact');
 const { usage, hint } = require('../../core/chalk');
 const { assertNoEmojiInText, assertNoEmojiInValue } = require('../../core/no-emoji-guard');
 const { normalizeYidaLocale } = require('../../core/yida-i18n');
@@ -195,6 +194,11 @@ function mergeCommandOutput(stdout, stderr, failed) {
   return { ...stdoutOutput, ...stderrOutput };
 }
 
+function boundedDiagnostic(value) {
+  const text = String(value || '').trim();
+  return text.length > 4000 ? text.slice(-4000) : text;
+}
+
 function expectedReadbackFields(fields) {
   const expected = [];
   for (const field of Array.isArray(fields) ? fields : []) {
@@ -261,38 +265,14 @@ function buildDeliveryUrls(baseUrl, appType, formUuid) {
 
 function execute(args, { execFile: execFileImpl = execFile } = {}) {
   return new Promise((resolve, reject) => {
-    const flags = ['--json', '--quiet'].filter(flag => !args.includes(flag));
-    execFileImpl(process.execPath, [path.resolve(__dirname, '../../../bin/yida.js'), ...args, ...flags], {
+    execFileImpl(process.execPath, [path.resolve(__dirname, '../../../bin/yida.js'), ...args, '--quiet'], {
       env: { ...process.env, YIDA_QUIET: '1' }, timeout: 180000, maxBuffer: 8 * 1024 * 1024,
     }, (error, stdout, stderr) => {
       const output = mergeCommandOutput(stdout, stderr, Boolean(error));
       if (error || !output || typeof output !== 'object' || output.success === false) {
-        const failure = parseOutput(stderr);
-        const source = failure?.success === false ? failure : output;
-        // Child errors are written to stderr. Keep only bounded, redacted
-        // diagnostics and a known created ID, never Node's argv-bearing error.
-        let message = String(source?.errorMsg || source?.error || source?.message || stderr || 'Missing command result');
-        const grant = process.env.OPENYIDA_AGENT_TASK_GRANT;
-        if (grant) { message = message.split(grant).join('***'); }
-        // Diagnostics may contain embedded or incomplete JSON, not a plain
-        // object. Reuse the shared sensitive-key rules, then discard the tail
-        // rather than attempting to recover a possibly nested secret value.
-        for (const match of message.matchAll(/["']([^"'\r\n]{1,128})["']\s*:/g)) {
-          let key;
-          try { key = JSON.parse(`"${match[1]}"`); } catch { key = match[1].replace(/\\/g, ''); }
-          if (redactSensitive({ [key]: 'sensitive-value' })[key] !== 'sensitive-value') {
-            message = `${message.slice(0, match.index)}[REDACTED]`;
-            break;
-          }
-        }
-        message = redactSensitive(message).slice(0, 2048);
-        const errorCode = /^[A-Z][A-Z0-9_]{0,127}$/.test(source?.errorCode || error?.code || '')
-          ? source?.errorCode || error.code : undefined;
-        const formUuid = [source?.formUuid, source?.details?.formUuid, output?.formUuid, output?.details?.formUuid]
-          .find(value => typeof value === 'string' && /^FORM[a-zA-Z0-9_-]{1,128}$/.test(value));
-        const safeOutput = { success: false, errorMsg: message,
-          ...(errorCode ? { errorCode } : {}), ...(formUuid ? { formUuid } : {}) };
-        reject(Object.assign(new Error(message), { output: safeOutput }));
+        reject(Object.assign(new Error(
+          output?.errorMsg || output?.error || output?.message || boundedDiagnostic(stderr) || error?.message || 'Missing command result'
+        ), { output }));
       } else { resolve(output); }
     });
   });
@@ -326,7 +306,6 @@ async function schedule(forms, concurrency, results, worker, save) {
           results[form.key] = { ...output, status: 'success' };
         }, error => {
           results[form.key] = { ...results[form.key], status: 'failed', error: error.message,
-            ...(error.output?.errorCode ? { errorCode: error.output.errorCode } : {}),
             ...((error.output?.formUuid || error.output?.details?.formUuid) ? { formUuid: error.output.formUuid || error.output.details.formUuid } : {}) };
           // A create may persist the form before a later schema/readback stage fails.
           // Retry that known UUID once inside the same authoritative batch so its