e10-ebuilder-prototype 0.5.0

package/docs/PROTOCOL.md

@@ -0,0 +1,299 @@
+# Contract v5 — e10-ebuilder-prototype 0.5.0
+
+Product, npm package, CLI and Skill share this name. Node >=22.5, TypeScript/ESM,
+pinned playwright-core and installed Chrome. No LLM calls in CLI: host AI generates
+business HTML from CLI jobs. Authentication and persistent namespaces retain existing
+E10_PAGE_CAPTURE_HOME/CHROME and .e10-page-capture identifiers.
+
+## Entry and scope
+
+User-facing intent: 根据应用 ID 或后台应用地址生成应用原型，包含已发布菜单中的页面、建模列表和流程页面。
+`run|init --app-id ID --dir DIR` or `--app-url URL` accepts a complete backend app URL
+http(s)://origin/sp/ebdapp/<entrance>/<appId>/... . IDs remain strings; numeric URL/ID
+inputs must agree. URL credentials are rejected; the parsed origin must match the
+authenticated environment. Credentials are never persisted in task files or prompts.
+
+New tasks set menuRequired, siteRequired and htmlRequired. Discovery reads
+GET /api/cusapp/app/allMenus?appId=ID&terminalType=PC&isFront=0 and app/info?id=ID.
+Prefer ebAppMenus; fall back to cusAppMenus only if absent. Never concatenate them.
+Published menus alone define navigation and generation scope. Exclude system recycle
+and settings and denied branches. Preserve menu IDs/names, stable showOrder, hierarchy,
+default selection and duplicate names. Pure groups remain if supported children exist.
+Cycles, duplicate IDs and conflicting target/membership data fail explicitly.
+Unsupported menu types are listed in skippedMenus, not silently rendered as other types.
+
+PAGE menu targets resolve metadata through /api/bs/ebuilder/page/list?appid=ID, selecting
+only published IDs. PAGE, ECODE_HTML and ECODE_REACT building types share the same
+capture pipeline. Repeated page targets share one PNG/HTML but retain menu entrances.
+SEARCH uses its referenced traditional list. VIEWPORT with NList tabs uses its exact
+host page ID and the known data.page.comps[1].config contract. LAYOUT and recognized
+direct EB URLs preserve object, list, layout and view/add/edit mode. Supported combined
+URLs resolve getCombMenus by container menu ID, retain ordered tabs, reject nested or
+empty unsupported combinations. URL parsing never follows external hosts.
+Form object membership uses /api/bs/ebuilder/form/obj/getList/ID?apid=ID. Inventory is
+for membership, not navigation. A form menu key is its menu ID (combined child uses
+parentKey-childMenuId); objId, underlying formId and listId are not interchangeable.
+
+## Commands and state
+
+Commands: init, next, discover, collect, capture, run, retry, status, pack, doctor;
+html next|accept|fail|retry; auth set|status|profile list|current|use NAME.
+Auth set supports --base-url, --eteamsid-stdin and --eteamsid. JSON returns one final
+object; progress uses stderr. Normal operations expose next, errors expose fix.
+Exit 0 = normal/DONE, 2 = PARTIAL, 1 = blocking error.
+
+NEW -> WAITING_AUTH or DISCOVER -> COLLECT -> CAPTURE -> HTML -> PACKAGE -> DONE/PARTIAL.
+run discovers, collects form configs, captures pages and then hands off to the host.
+After accepted HTML, run/pack creates the offline application. HTML/pack do not read
+auth or revisit the source. status/next are read-only. Task binds appId, origin and a
+hash of tenant/user identity; another identity cannot continue it.
+
+Atomic state and receipts live under DIR/.e10-page-capture; artifacts under DIR/artifacts.
+Short CLI transactions are locked. Interrupted collection/capture and generation can
+resume; completed files must match hashes. Failed sources retry explicitly with retry;
+html retry only resets failed generation. Pending source or HTML work blocks packaging.
+Collection/capture/generation failures allow explicit PARTIAL, with failed menu destinations.
+No state flag alone proves completion. Final entry, destinations and ZIP are verified.
+Existing tasks without menuRequired retain their legacy all-resource/placeholder workflow;
+new menu semantics require a new directory. No automatic migration.
+
+## Modeling-list and layout collection
+
+Collection uses E10Client with in-memory auth, same-origin requests, redirects denied,
+30s request deadlines and integer-safe JSON parsing. Form API independent deployment
+rewrites only /api/ebuilder{appId}/form routes. Common metadata and file routes retain
+original prefixes. Menu jobs use bounded concurrency and shared per-object metadata.
+
+Traditional lists collect listInit, base info, columns, order, search, statistics,
+conditions where configured and list buttons. NList retains the exact component config.
+Fields preserve IDs, main/detail grouping, config and system/custom classification;
+select/radio/checkbox/cascader options are collected. Cascaders with only first-level
+options carry a warning. Unknown/malformed primary configs fail that menu.
+
+Existing data lookup requests at most one reference row per object; business row values
+are not persisted in source JSON. With a record, exportDataDetailPDF(exportHtml=true)
+may create a reference file, downloaded only as private input. Default collection reads business records only. New-task --allow-temporary-records explicitly
+allows one uniquely marked temporary reference per form attempt when existing reference
+export is unavailable. Construct only verified simple field keys/options; required complex
+fields can reject seeding and permit fallback. Journal before creation, verify returned ID
+and marker, collect layout/default and explicit mode buttons before finally cleanup. Verify
+exact-ID deletion by a subsequent read. No bulk/conditional deletion, extra business objects
+or recycle-bin clearing. Unknown creation is reconciled by an exact marker lookup (at most
+two rows), never by replaying creation. Unknown deletion only gets read verification; a
+remaining record blocks further writes instead of replaying deletion. Pending/uncertain
+journals block collection success, HTML allocation and pack. Resume processes journals first.
+The flag is persisted; default read-only tasks use a new directory to enable it. Exported
+reference HTML and record provenance stay private. Finished prototypes remain offline only. Without usable reference HTML, layout.source
+is fields and warnings describe fallback. Custom layout menus do not turn a default
+export into evidence of exact custom layout. Reference HTML is untrusted data for host
+reconstruction, never executed or directly embedded. ZIP excludes these private inputs.
+
+Buttons are scoped by app/object/list and independently by layout/mode/record context.
+Keep enable/hidden/positions/actions plus source paths and raw config. Empty arrays mean
+no configured buttons; unavailable is distinct and cannot borrow another mode's buttons.
+Configuration count is not visible toolbar count. List display conditions and action
+chains are interpreted by host AI as local mock behavior, not executed on the server.
+Reference failures become explicit warnings; primary metadata failures fail collection;
+auth loss always aborts the phase, retaining interrupted receipts for resume.
+
+## Page capture
+
+Capture defaults: concurrency 4 (1..8 override), PC 1440x900, mobile 390x844,
+CSS pixel scale 1, initial navigation/rendering deadline 10 seconds, 1 additional retry for non-timeout errors; timeouts fail immediately, stabilization
+window 800ms, page height limit 50000px, pixel limit 60M. No timeout is treated as ready.
+Readiness uses either page entrance/configuration or meaningful content bound to the requested
+EB page (including cached content after platform reload), visible loading indicators, fonts,
+visible images and an 800ms content/layout stabilization window. Only EBuilder page
+and component data (/api/ebuilder/) and custom component assets (/ecodestatic/)
+block on pending requests. Global shell/background traffic does not block screenshots,
+and document.readyState=interactive is sufficient when the page content is ready. Authentication failures remain blocking errors.
+A verified zero-component configuration with the platform's 暂无内容 placeholder is
+valid page content. Stable business/resource errors, broken visible images and the
+verified terminal-unavailable placeholder are captured as displayed, with warnings.
+Success means the screenshot preserves the page state, not that its business logic is healthy.
+Ancestor clipping excludes hidden carousel slides from visible-image checks. The platform
+.weapp-de-sourcecode-render container is supported alongside ordinary ebpage_<id> roots.
+Its primary same-origin /sp/chtml/ iframe is the page body: lazy scroll and expand its full
+content before capturing the outer page. An ordinary embedded website iframe is checked for document/font/image readiness and stable content, then preserved
+at its designed viewport; its internal website is not expanded. Post-capture validation checks content retention and PNG dimensions (4px rounding tolerance);
+small layout-only changes and background request activity do not fail a screenshot.
+There is no automatic click of tabs, pagination or collapsed business panels.
+Virtual lists or unreadable canvas evidence produce an explicit diagnostic outcome,
+not a claim of complete capture. Screenshots represent the current requested page.
+
+Capture results: pending/running/succeeded/failed, with optional warnings[]. Every attempt records stage, reason,
+timing and readiness evidence. A failed page may have a diagnostic PNG in diagnostics/;
+it never appears as a verified page PNG. Credentials/headers/bodies are not diagnostics.
+PNG bytes are committed only after post-capture integrity checks. Close each page
+in finally with bounded cleanup. Batch cleanup failures cannot yield DONE.
+
+Loading timeout is 10000ms by default; readiness proceeds immediately when observed signals stabilize.
+Timeouts are final for that run. After initial readiness, each scroll readiness wait has a fresh 10000ms budget.
+PNG encoding/validation has a separate 10000ms limit; an attempt has a loading-budget + 130s hard cap;
+resource cleanup and optional diagnostics are outside the loading deadline.
+
+
+## Mixed host HTML protocol
+
+html next is a short locked transaction after all source jobs are terminal. It returns
+up to settings.concurrency jobs total (default 4), including resumed running tokens.
+Each job has kind, pageId, token, name, outputPath, reviewDirectory and prompt.
+Page jobs use screenshotPath and PNG digest, prompt version 2. Form jobs use sourcePath,
+runtimePath and form-input digest, prompt version 4, plus contextPath (bounded lossless
+configuration fragments), guidePath (complete form generation rules), navigationPath (published
+route mapping), and relatedPath (verified objects and metadata fragment paths for explicit relations). Form pageId is the menu key.
+The coordinator tracks live tokens and serializes CLI operations; workers only generate
+HTML and perform local visual QA. Host parallel capability governs actual AI parallelism;
+when unavailable, process sequentially and report honestly. No model subprocess/API.
+
+html accept --kind page|form --page-id ID --token TOKEN reads the fixed draft path.
+Kind defaults to page for compatibility. Validate membership, source digest, token,
+UTF-8, document structure, body and common static external resources. Form acceptance
+injects the canonical CLI runtime in head. Commit artifacts/<pageId>.html or
+artifacts/form-html/<menuKey>.html with SHA-256. Successful same-token accept is idempotent.
+Invalid drafts stay running; fail records terminal failure; retry resets failed jobs.
+html retry with an explicit --kind/--page-id resets that target (including accepted HTML)
+for requested visual correction, invalidating its token and archive while retaining source data.
+Changed source/corrupted HTML creates a new token, rejecting stale completions.
+No implicit generation expiry; source rendering's 10s budget does not apply to AI.
+
+Prompts require real standalone DOM, inline CSS/JS/SVG, full-image inspection for pages,
+config inspection for forms, populated consistent Mock data and local interactions.
+No whole-image substitute, remote modules/resources/API, extra shell, or parent/top
+navigation. Host must render/inspect and disclose missing QA or approximated configs.
+Static acceptance is not a visual similarity or arbitrary JavaScript correctness proof.
+Status reports pageHtml, collection, formHtml and aggregate html. Pending includes running.
+
+## Fixed offline shell and shared form data
+
+CLI owns the business-blue shell, failure/legacy placeholders and fixed E10FormStore
+transport; host generates business HTML. Full field/control, list-mode, CRUD, detail, comment/log
+and action-chain expectations ship in templates/form-guide.md, ported from the supplied package. No Preview/Design/Settings top action row.
+Index displays actual published menu hierarchy, search, collapsible groups and mobile
+navigation. Preserve shell, replace only its iframe with relative local HTML. New routes
+are #menu/<key> and combined #menu/<key>?tab=<childKey>; support history and reload.
+No fetch/local web server. Content has responsive 20/16/12px outer spacing. Forms and
+pages can also be opened standalone. Legacy tasks retain their #page/#form routes.
+
+E10FormStore.load(initial), save(state), reset(initial), navigate(menuKey,params), parameters() exchange JSON with the active
+shell iframe only, scoped to appId:objId. forObject(objId) exposes load/save/reset for explicit
+relations to other collected objects in the application's published scope. The injected
+object allowlist and shell catalog reject unknown objects and other applications; each
+object retains separate records, comments and logs. Host code uses relatedPath for target
+field metadata and the returned local data for relations and aggregates, without guessed
+relationships or borrowed button scopes. LocalStorage plus in-memory fallback; standalone
+uses local storage, host unavailable falls back after 1s. Payloads limited to 2M characters.
+Navigation only targets known published menus (including combination tabs), preserving the
+shell and passing bounded JSON to the destination; standalone navigation reports unavailable.
+Schema: {schema:1,records:[{id:string,fields:object,details?:object}],comments:[],logs:[]}.
+Fields bind to field IDs. Generated menus use returned shared records instead of fresh
+private copies; unrelated applications/objects remain isolated. Storage availability is
+browser dependent; in-memory fallback lasts the current session only.
+
+Form initialization must set window.__E10_FORM_READY__=true after data/rendering. Pack
+renders generated form HTML offline at 1440x900, waits ready and checks page errors before
+PNG. Rendering failures mark that HTML failed and block the pack attempt, allowing html
+retry or subsequent explicit PARTIAL packaging. Owned Pages, contexts and Chrome close
+in finally; cleanup failures cannot yield DONE.
+
+## Delivery and privacy
+
+Manifest schema 4 maps original menus to generated artifacts, skipped menus and separate
+source/HTML statuses. Pages use page/<pageId>/<pageId>.html and name PNG. Forms use
+form/<menuKey>/<menuKey>.html and name PNG. Form PNGs are generated from local HTML,
+marked pngKind=generated; failed placeholders are explicit, never successful business pages.
+ZIP root: index.html + page/ + form/ + manifest.json (+ diagnostics on capture failures).
+Name: 应用页面-<appId>.zip. Same-name menus retain their identities. Filename cleanup protects
+Windows reserved names and separators; page PNG collisions append IDs. entry/archive
+return absolute paths. Pack uses an explicit allowlist, not a recursive task-directory ZIP.
+Exclude credentials, form-input JSON, layout references, real reference record IDs, drafts,
+tokens and task state. Manifest carries hashes and specific warnings, not private configs.
+DONE covers supported targets; unsupported skipped menu types still require disclosure.
+
+## Runtime distribution
+
+The npm package and Skill installers use https://registry.npmjs.org/ for public
+distribution. Dependencies retain their pinned versions and integrity checks; no
+internal registry is required for installation. Publishing requires explicit user
+authorization and remains separate from local package creation and verification.
+
+Windows runtime (0.1.2): the CLI and bootstrap share runtime-support.mjs. Environment
+names are read without case sensitivity on Windows; auth and bootstrap use the same
+product state root. npm is resolved to an absolute entry (including WorkBuddy's Node
+installation), JavaScript entries run through the current Node, cmd/bat shims use
+ComSpec with literal arguments. npm update notifier and inherited host session hooks
+are removed only from npm children. Local tarballs are copied to the managed release
+before installation and removed afterwards. Windows timeouts/interrupts terminate
+only the exact owned process tree via taskkill /pid /t /f.
+
+System Chrome is found in system/per-user locations or E10_PAGE_CAPTURE_CHROME (an
+existing absolute executable path). A fresh persistent profile is created solely for
+the tool; capture workers still use independent Pages and shared terminal contexts.
+Chrome profile/artifact directories are explicitly owned. Recursive cleanup runs in
+an exact-target helper with a 30s Windows budget (15s elsewhere), followed by an
+absence check; browser close has the same platform budgets. These are cleanup limits,
+not the 10s initial page-rendering limit. File replacement retries temporary sharing
+violations for at most 750ms and never deletes the old destination first.
+
+Skill archives contain four runtime files: SKILL.md, product.json, scripts/bootstrap.mjs,
+scripts/runtime-support.mjs; local editions additionally contain the npm tarball.
+Windows native acceptance: npm run test:windows, from the target Windows host/WorkBuddy
+environment. macOS simulated Windows branches do not count as native Windows acceptance.
+
+
+## Workflow menus and associated forms (0.5.0)
+
+WORKFLOW pageId or /sp/ebdfpage/workflow/{appId}_{category} selects one of todo, done,
+mine, share, subordinates, all, draft, monitor, newflow. LINK and combined child paths
+are supported, app/type/category conflicts fail; BASE/monitor alone remains unsupported.
+Only published entrances generate jobs. FormPage.kind=workflow has workflowType and no
+single objId; it retains kind=form receipts, queue slots, acceptance and delivery paths.
+
+Only when collecting workflow menus, query once per collection pass:
+POST /api/bs/ebuilder/flow/approval/getApprovalListDatasByAppId?apid=ID&cid=ID,
+body {appId:ID,viewType:"",sortParams:[],searchParamData:{}}. No independent-deployment
+prefix rewriting for this common API. data.data contains configurations, not instances.
+Validate workflowid/objId and known application membership; formid is not objId.
+Preserve configuration status 1/5 without filtering, and multiple workflows per object.
+Skip non-EB or unverified/conflicting object memberships with reasons. Duplicate workflow
+IDs with different configurations fail. Empty arrays yield generated empty states;
+API/primary dependency failures produce failed collection, never fabricated templates.
+
+Workflow dependencies reuse field/options/layout collection (ordinary menus first), including
+forms lacking ordinary menus. Do not enumerate their lists or collect ordinary mode buttons
+for workflow-only dependencies. Existing-reference export/optional temporary-record lifecycle
+is unchanged; no real workflow initiation or approval API exists. Private workflow-catalog.json
+records ready/unavailable; each hashed workflow input embeds its catalog, dependency snapshots,
+scoped preset buttons, preset and warnings. Successful receipts have kind=workflow and
+objectIds instead of objId. These dependencies join the relatedPath/runtime allowlist but
+never produce additional navigation. Dependency locations are explicit in relatedPath.
+
+Workflow host jobs use promptVersion=5, workflow guidePath plus layoutGuidePath, and inject
+canonical form and workflow runtimes. Presets are prototype-workflow-preset/mockOnly, not
+claims of source-button permissions. Newflow uses grouped cards; other categories use fixed
+columns/tabs/filters, not custom form fields. Host generates DOM and controls; CLI performs
+no LLM inference and ships no universal workflow frontend renderer. Generation requirements
+include complete associated forms, actual search/filter/paging and action handling.
+
+E10WorkflowStore owns local instance transitions under appId:workflow. Instances have unique
+IDs and fields.workflowId/objId/recordId; comments/logs use instanceId. Actor/participants,
+current/next nodes and history are simulated. Done uses handledBy, todo active pendingIds,
+mine initiatorId, share sharedWith, subordinates simulated pending relationships, draft own
+drafts; all excludes drafts, monitor additionally requires the explicit simulated monitorable flag. Batch submission validates the entire selection, requires
+confirmation, records current-user handling and advances to a simulated next node, remaining
+active. New applications/own drafts use saveApplication, jointly storing the associated form
+record and instance; cancelled edits do not call it. References are read from shared object
+stores. Favorites, followed markers, read flags and comments persist; reset requires confirmation.
+
+Offline storage v2 persists all touched objects for one application as a single localStorage
+snapshot. Existing v1 object keys are read on first access for compatibility. E10FormStore.commit
+validates all entries before replacing the snapshot; workflow/form updates cannot partially
+commit. Storage unavailable uses session memory, with no persistence guarantee. Both shell
+and standalone transport use the same fixed implementation. Shell accepts only its active,
+available form iframe and known scopes, including dependencies of available workflow pages;
+ordinary pages cannot write the workflow scope. Unknown/cross-app targets reject. Regular
+object payloads and total commit payloads remain limited to 2M characters. No source requests.
+
+Manifest schema 4 gains optional workflowType for form entries; workflow receipts do not
+invent an objId. Fixed shell template version 7 preserves existing navigation behavior. Pack
+verifies initialization/rendering for workflows using __E10_FORM_READY__ just like forms.

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "e10-ebuilder-prototype",
+  "version": "0.5.0",
+  "description": "Generate offline E10 application prototypes from published page, modeling-list and workflow menus",
+  "type": "module",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.5"
+  },
+  "bin": {
+    "e10-ebuilder-prototype": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "docs/PROTOCOL.md"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node scripts/clean.mjs && tsc && node scripts/sync-skill-runtime.mjs",
+    "test": "npm run build && node scripts/test.mjs",
+    "test:package": "node scripts/test-package.mjs",
+    "test:windows": "node scripts/test-windows.mjs",
+    "pack:skill": "node scripts/package-skill.mjs",
+    "prepack": "npm run build",
+    "format": "prettier --write src test scripts integrations/workbuddy-skill/scripts",
+    "format:check": "prettier --check src test scripts integrations/workbuddy-skill/scripts"
+  },
+  "dependencies": {
+    "@napi-rs/keyring": "1.3.0",
+    "parse5": "7.2.1",
+    "playwright-core": "1.62.1",
+    "yazl": "3.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "22.10.0",
+    "@types/yazl": "3.3.0",
+    "prettier": "3.3.3",
+    "typescript": "5.7.2"
+  }
+}