From 8f1d72c1ebba9be0c0e246c72cd6ab75a245eb81 Mon Sep 17 00:00:00 2001 From: ketd <94940923+ketd@users.noreply.github.com> Date: Wed, 4 Nov 2026 00:25:24 -0500 Subject: [PATCH] feat: add prebuilt workbench runtime exports --- .agents/skills/floatboat-workbench/SKILL.md | 2 +- .../floatboat-workbench/references/runtime.md | 4 + .../references/verification.md | 6 + .github/workflows/build.yml | 33 + AGENTS.md | 2 +- PUBLICATION.md | 11 +- README.md | 16 +- README.zh-CN.md | 20 +- VERIFICATION.md | 14 + app/ENGINEERING.md | 2 + app/src/ui/App.tsx | 2 +- app/tests/preview.test.ts | 16 + app/workbench.preview.json | 16 + compatibility.json | 5 +- docs/maintenance.md | 6 + docs/runtime-packages.md | 37 + package.json | 7 +- pnpm-lock.yaml | 1004 +++++++++++++++++ provenance.json | 110 +- tests/authoring.test.mjs | 3 + tests/runtime-package.test.mjs | 166 +++ tests/skills.test.mjs | 1 + tooling/build.mjs | 6 +- tooling/cli.mjs | 30 +- tooling/compiler/publication-code.ts | 74 ++ tooling/compiler/publication-notices.ts | 53 + tooling/compiler/runtime-artifact.ts | 239 ++++ tooling/compiler/worker.ts | 74 +- tooling/contracts/workbenchCompilation.ts | 1 + tooling/contracts/workbenchDistribution.ts | 35 + tooling/contracts/workbenchTransfer.ts | 4 +- tooling/package.mjs | 15 +- tooling/runtime-package.mjs | 59 + tooling/transfer/WorkbenchTransferArchive.ts | 9 +- 34 files changed, 2028 insertions(+), 54 deletions(-) create mode 100644 .github/workflows/build.yml create mode 100644 app/tests/preview.test.ts create mode 100644 app/workbench.preview.json create mode 100644 docs/runtime-packages.md create mode 100644 tests/runtime-package.test.mjs create mode 100644 tooling/compiler/publication-code.ts create mode 100644 tooling/compiler/publication-notices.ts create mode 100644 tooling/compiler/runtime-artifact.ts create mode 100644 tooling/contracts/workbenchDistribution.ts create mode 100644 tooling/runtime-package.mjs diff --git a/.agents/skills/floatboat-workbench/SKILL.md b/.agents/skills/floatboat-workbench/SKILL.md index a0929c7..6c437ea 100644 --- a/.agents/skills/floatboat-workbench/SKILL.md +++ b/.agents/skills/floatboat-workbench/SKILL.md @@ -21,7 +21,7 @@ The template works **without Floatboat**. Use the repository CLI for this checko Choose values from the user's business goal. `registryName` is a readable English coordinate; display names may be Chinese. Read [engineering](references/engineering.md) and [design](references/design.md) when creating the application; maintain `app/ENGINEERING.md` and `app/DESIGN.md` with the decisions used. 3. For Connector integrations, start a compatible Floatboat client and discover exact contracts with `pnpm workbench:catalog providers/actions/describe`; read [connected services](references/connected-services.md). Do not guess Action IDs or copy native-provider parameters. Implement the requested flow in `app/src/`, using the references below for the domains touched. Keep manifest declarations synchronized with implemented behavior. Use `app/sdk/*.d.mts` after the first check, or `sdk/*.mts` before generation, for exact signatures. 4. Run `pnpm workbench:check` and `pnpm test`. Then run `pnpm dev`, open the complete printed URL and exercise the real primary flow, persistence and failure states. Source saves are checked and reloaded automatically; see [runtime](references/runtime.md) for failure recovery and single-run preview. Use [verification](references/verification.md) to distinguish build, business, visual and Host results. -5. When handing off an application, run `pnpm run package` (alias of `pnpm workbench:pack`), report the resulting `.fbworkbench` path and explain **Floatboat → My → Workbenches → Import workbench**. Export creates a source package for a new Host installation; see repository `docs/platform.md` for dependency setup and authorization. Publishing, changing repository visibility or selecting a license requires the corresponding user request. +5. For delivery, use `pnpm build` to validate distribution output. Run `pnpm workbench:pack` for editable source or `pnpm workbench:pack -- --runtime` when the user requests prebuilt delivery without source. Runtime export applies business-module obfuscation and requires a compatible Floatboat v3 runtime importer; it excludes business data. Read [build and delivery](../../../docs/runtime-packages.md) for the output contract and limitations. Maintain `app/workbench.preview.json` with fictional responses matching the real page/API and render its ready marker after loading; source export includes this cover fixture. Report the actual artifact path and **Floatboat → My → Workbenches → Import workbench**. Publishing, changing repository visibility or selecting a license requires the corresponding user request. ## Read only the relevant topics diff --git a/.agents/skills/floatboat-workbench/references/runtime.md b/.agents/skills/floatboat-workbench/references/runtime.md index ad05355..4a0b4e0 100644 --- a/.agents/skills/floatboat-workbench/references/runtime.md +++ b/.agents/skills/floatboat-workbench/references/runtime.md @@ -7,6 +7,8 @@ Use Node 22.16+ within 22.x and the pnpm version pinned in package.json. The rep | Create | Initialize `app/manifest.json` with `pnpm workbench:init` | `create_workbench_project` returns the owned absolute source directory | | Read guidance | `pnpm workbench:guide -- --topic runtime` | `get_workbench_authoring_guide` | | Check | `pnpm workbench:check` | `check_workbench_project` | +| Distribution build | `pnpm build`, optionally `-- --obfuscate` | Managed publishing builds follow Host rules | +| Runtime-only export | `pnpm workbench:pack -- --runtime` | Import v3 without source compilation | | Test | `pnpm test` uses `app/tests/*.test.ts` | Run project tests using the available Host toolchain | | Run | `pnpm dev`; source saves trigger checked live reload | `workbench_runtime open` applies the current source | | Show UI | Open the complete URL printed by the preview | `workbench.open` shows the registered Workspace panel | @@ -35,3 +37,5 @@ await app.listen(); Register routes before `listen`. Route handlers receive `request`, `url`, `params`, `body`, `database` and `host`; validate JSON bodies as unknown. `app.resources` resolves declared files. `app.action` handles declared Host actions. `app.trackTask` tracks local work and `app.tasks()` exposes its recorded state; use the [Agent API](agent.md) when tools and reasoning are needed. Preview startup owns `FLOATBOAT_WORKBENCH_CONFIG`. Pages and the local Host SDK use ordinary loopback URLs without connection credentials; direct navigation and refresh work without a token. Keep local configuration out of application source and exports. The Node process has the developer's OS permissions; local endpoint access is not a filesystem sandbox. Preview data persists at `.local/data//` and shutdown preserves it. + +Distribution output, restricted-source behavior and cover demonstration data are defined in [build and delivery](../../../../docs/runtime-packages.md). diff --git a/.agents/skills/floatboat-workbench/references/verification.md b/.agents/skills/floatboat-workbench/references/verification.md index 58608e7..4819544 100644 --- a/.agents/skills/floatboat-workbench/references/verification.md +++ b/.agents/skills/floatboat-workbench/references/verification.md @@ -23,3 +23,9 @@ Manifest changes need check/pack validation even when the UI is unchanged. For d | Preview exits | Inspect the application exception and startup output; the Node version footer alone is not the cause | Report changed behavior, checks actually run, preview/export instructions and unverified integrations. Avoid treating generated code, a successful build or a ready HTTP server as completed business/visual acceptance. + +## Runtime delivery and cover capture + +For prebuilt delivery, run `pnpm build` and `pnpm workbench:pack -- --runtime`. Verify the v3 archive has a runtime descriptor, SDK and migrations but no source, node_modules, source maps or local data. Test an unpacked copy outside the template dependency tree. Report full Desktop import and browser checks separately from Node tests. Existing source export and explicit data migration remain available; runtime export rejects data inclusion. + +Maintain `app/workbench.preview.json` with fictional responses for every page request, matching the implemented schemas. Render its `readyTestId` only after the page is populated. Source export carries this fixture for Floatboat's cover capture; runtime export omits it. Build success alone does not prove the fixture or screenshot is correct. See [build and delivery](../../../../docs/runtime-packages.md). diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml new file mode 100644 index 0000000..d6605fa --- /dev/null +++ b/.github/workflows/build.yml @@ -0,0 +1,33 @@ +name: Build workbench template +on: + pull_request: + push: + branches: [main] + workflow_dispatch: +permissions: + contents: read +jobs: + build: + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - uses: actions/checkout@v4 + - uses: pnpm/action-setup@v4 + - uses: actions/setup-node@v4 + with: + node-version: 22.22.2 + cache: pnpm + - run: pnpm install --frozen-lockfile --ignore-scripts + - run: pnpm skills:check + - run: pnpm workbench:check + - run: pnpm test + - run: pnpm test:tooling + - run: pnpm build + - run: pnpm workbench:pack + - run: pnpm workbench:pack -- --runtime + - uses: actions/upload-artifact@v4 + with: + name: workbench-packages + path: artifacts/*.fbworkbench + if-no-files-found: error + retention-days: 7 diff --git a/AGENTS.md b/AGENTS.md index 5dc58af..0dac0b9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,4 +12,4 @@ Build the user's business app in `app/`. Read `app/REQUIREMENTS.md` and preserve - Changes to `sdk/` or `tooling/` affect the development platform; read [maintenance](docs/maintenance.md) and run the relevant tooling tests. Generated output is not the editing surface. - `.agents/skills/floatboat-workbench/` is the guidance source. Generate the `.claude/skills/floatboat-workbench/SKILL.md` compatibility entry with `pnpm skills:sync`; verify it with `pnpm skills:check`. The Claude entry points to the same content and has no separate reference copies. -The repository is privately hosted under floatboatai. Publishing it or choosing an open-source license remains an owner decision; see [PUBLICATION.md](PUBLICATION.md). Exporting an application is not a store submission. +Repository visibility and licensing remain owner decisions; see [PUBLICATION.md](PUBLICATION.md). For distribution builds, runtime-only packages or cover demonstration data, read [build and delivery](docs/runtime-packages.md). Exporting an application is not a store submission. diff --git a/PUBLICATION.md b/PUBLICATION.md index 76e9de6..8769e3b 100644 --- a/PUBLICATION.md +++ b/PUBLICATION.md @@ -1,12 +1,7 @@ # Publication status -This development repository is hosted privately at [floatboatai/floatboat-workbench-template](https://github.com/floatboatai/floatboat-workbench-template). The owner has explicitly chosen to keep it private for now. It is not an open-source release, no open-source license has been selected, and package manifests remain private. The Desktop/Backend licenses and visibility are unchanged. +This repository contains the selected standalone Workbench template, SDK and build tooling. Repository visibility is controlled by its owner. The package manifests remain `private: true` to prevent accidental npm publication; that field does not describe GitHub visibility. This update does not select a software license. -Before public release: +`provenance.json` records the source snapshots and adapted files used by the standalone tooling. Its historical private-development labels describe the original extraction, not current GitHub visibility. Review the recorded scope and dependency notices when distributing template changes; access to this repository does not authorize copying unrelated Desktop or Backend code. -- Obtain the owner's explicit decision to make the repository public and select licenses for the template and included SDK/compiler/protocol sources; add the approved LICENSE text and copyright attribution. -- Review `provenance.json` and the actual files. It records selected source hashes, including locally modified source; it is not a claim that the private base commit alone reproduces this candidate. -- Review public dependency license notices and add the required third-party notices. No embedded Node binary, installed dependency tree, authoring reference corpus or private Git history is included in the candidate source. -- Run clean-install and preview/export checks on each supported operating system and review credentials/source contents before public release. - -Do not infer permission to publish all Desktop or Backend code from their package metadata. Only the selected standalone candidate is in scope for the future publication decision. +Runtime exports retain third-party notices and any application LICENSE supplied by its author. They exclude installed dependencies, source maps and preview data. A file export is not a marketplace submission, license grant or authenticated platform build. diff --git a/README.md b/README.md index aed451b..08a7106 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Floatboat workbench template -Create a workbench with Codex, Claude Code or another coding tool. Run its React page, Node HTTP service and SQLite locally without installing Floatboat. Development is hosted in the private [floatboatai/floatboat-workbench-template](https://github.com/floatboatai/floatboat-workbench-template) repository. It is not open source and no open-source license has been selected; see [publication status](PUBLICATION.md). +Create a workbench with Codex, Claude Code or another coding tool. Run its React page, Node HTTP service and SQLite locally without installing Floatboat. The repository is hosted at [floatboatai/floatboat-workbench-template](https://github.com/floatboatai/floatboat-workbench-template); see [publication status](PUBLICATION.md) for licensing. [中文说明](README.zh-CN.md) · [Agent instructions](AGENTS.md) · [Authoring skill](.agents/skills/floatboat-workbench/SKILL.md) @@ -75,3 +75,17 @@ The package contains application source, migrations, tests, declared fixed resou Platform features are a separate integration: [connection boundary](docs/platform.md). Application metadata and releases: [manifest contract](docs/manifest.md). Toolchain changes and license readiness: [maintenance](docs/maintenance.md). For external resource snapshots, pass `--bindings .local/export-bindings.json`; see [resource export](docs/resources.md#模板-cli-导出外部资源) for the mapping and `--include-data`. + +## Distribution builds + +```sh +pnpm build +pnpm workbench:build -- --obfuscate +pnpm workbench:pack -- --runtime +``` + +`build` produces the compiled server and UI in `app/dist/`. Runtime export creates `artifacts/--runtime.fbworkbench`: a v3 package with bundled dependencies, SDK, migrations and declared fixed resources, but no application source, node_modules, source maps or business data. A compatible Floatboat client installs it without recompiling or downloading npm dependencies. Runtime export always obfuscates business modules; obfuscation is not encryption. + +The original source-package command remains the default. Runtime export rejects `--include-data` and does not submit a store listing. See [build and delivery](docs/runtime-packages.md) for compatibility and boundaries. Repository CI builds and tests both package kinds and retains them in the `workbench-packages` Actions artifact. + +Keep `app/workbench.preview.json` synchronized with actual API/page contracts using fictional data. Show `workbench-preview-ready` after the real page renders; Floatboat uses this fixture for cover capture. Source exports include it; runtime exports omit it. diff --git a/README.zh-CN.md b/README.zh-CN.md index b43fe55..c3bcc76 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,6 +1,6 @@ # 工作台模板 -让 Codex、Claude Code 等外部 AI 工具创建工作台。无需安装 Floatboat，就能运行真实 React 页面、Node HTTP 服务和 SQLite。仓库托管在 [floatboatai/floatboat-workbench-template](https://github.com/floatboatai/floatboat-workbench-template)，目前为私有仓库，暂不开源，也未选择开源许可证；详见 [公开状态](PUBLICATION.md)。 +让 Codex、Claude Code 等外部 AI 工具创建工作台。无需安装 Floatboat，就能运行真实 React 页面、Node HTTP 服务和 SQLite。仓库托管在 [floatboatai/floatboat-workbench-template](https://github.com/floatboatai/floatboat-workbench-template)，许可状态见 [PUBLICATION.md](PUBLICATION.md)。 ## 创建和预览 @@ -39,7 +39,23 @@ node tooling/guide.mjs --topic runtime runtime 主题提供 Host 创建工具与模板本地命令的对应关系；其他主题覆盖工程、页面设计、数据库、依赖资源、模型、Agent、ASR、Workflow、连接服务、日程和自动化。只维护 `.agents` 真源，用 `pnpm skills:sync` 生成 Claude 入口，`pnpm skills:check` 检查主题、链接和入口一致性。 -## 交付 +## 构建与仅运行包 + +```sh +pnpm build # 检查并构建服务端、页面和依赖 +pnpm workbench:build -- --obfuscate # 对业务模块启用混淆 +pnpm workbench:pack -- --runtime # 导出混淆后的仅运行包 +``` + +构建产物位于 `app/dist/`。仅运行包输出为 `artifacts/<名称>-<版本>-runtime.fbworkbench`，包含运行文件、SDK、迁移、固定资源和依赖许可声明，不带源码、node_modules、source map 或业务数据。支持 v3 运行包的 Floatboat 客户端可直接导入运行，无需在用户机器安装 npm 依赖或编译。 + +普通 `pnpm workbench:pack` 仍导出源码包。仅运行包默认使用与商店一致的业务混淆方案；混淆不是加密，不能保证无法逆向。仅运行包不支持 `--include-data`，也不会自动上架。详见 [构建与运行包契约](docs/runtime-packages.md)。 + +页面/API 变化时同步维护 `app/workbench.preview.json` 的虚构演示数据，真实页面加载后显示 `workbench-preview-ready` 标记，供 Floatboat 发布时自动截图。源码包保留演示数据，仅运行包排除它。 + +GitHub Actions 会执行构建、测试并生成两类包，下载入口在 workflow 的 `workbench-packages` artifact 中。 + +## 源码包交付 在模板仓库根目录执行： diff --git a/VERIFICATION.md b/VERIFICATION.md index d81272e..25edd0a 100644 --- a/VERIFICATION.md +++ b/VERIFICATION.md @@ -1,5 +1,19 @@ # Local verification — 2026-09-18 +## Runtime build and delivery — 2026-11-04 + +Validated on macOS arm64, Node 22.22.2 and pnpm 10.22.0: + +- Frozen install with install scripts disabled; guidance synchronization/check passed. +- `workbench:check`, `pnpm test` (2 tests), `pnpm build`, `pnpm build -- --obfuscate`, and both source/runtime CLI exports passed. +- `pnpm test:tooling`: 34 tests passed, including the original source/data delivery flows and the new runtime test. Runtime output runs from an OS temporary directory outside the template with no node_modules; actual HTTP, React server dependency, WASM streaming, resource/dependency preservation, hash integrity and source exclusion are checked. +- Source and runtime package source hashes match, including business files under `src/sdk/`; only the generated root SDK is excluded. +- The generated runtime package was imported by real Desktop project/transfer/build/lifecycle/process services from `dfb6765e0`. It activated successfully, `prepareImport` was not called, no source directory was created, and its API and obfuscated UI rendered in Chromium. +- The Desktop static cover preview rendered the template fixture at 1280px and 375px, reached `workbench-preview-ready`, produced no page errors and did not overflow. This path uses mocked API responses and does not start the business server or access its data. + +The cross-repository checks used isolated temporary Host storage and databases. They do not prove a full Electron UI import journey, a live store submission, account entitlements, or native Windows behavior. Repository GitHub Actions provides the standalone Linux build/test/package gate; its final status is recorded in the PR. + + ## 2026-09-20 Remote-clone application and Electron handoff Pushed live preview and Connector SDK/guidance to the private template repository (`6269987`), cloned that remote revision into a separate application checkout and built a project delivery workbench with CRUD, SQLite, fixed assets, managed delivery files and a bundled deterministic Workflow. diff --git a/app/ENGINEERING.md b/app/ENGINEERING.md index 5cf25ba..e984b0b 100644 --- a/app/ENGINEERING.md +++ b/app/ENGINEERING.md @@ -10,3 +10,5 @@ The business app root is this directory. Run the authoring commands from the rep - Keep runtime dependency versions and lockfiles aligned; see `../docs/maintenance.md`. Native extensions do not belong in the application profile. - Add tests for business boundaries and persistence behavior, using temporary data rather than the user's preview database. Test files live under `tests/` and are run by `pnpm test` from the repository root. - Host calls are optional and require actual authorization. Show unavailable/error states and consult `../docs/platform.md`; preserve execution-unknown errors rather than retrying potentially completed external mutations blindly. + +- Distribution builds and runtime packages follow `../docs/runtime-packages.md`. Keep `workbench.preview.json` responses synchronized with the actual page/API and show the ready marker after rendering fictional preview data. diff --git a/app/src/ui/App.tsx b/app/src/ui/App.tsx index d6ff3b7..9f3c1e9 100644 --- a/app/src/ui/App.tsx +++ b/app/src/ui/App.tsx @@ -23,7 +23,7 @@ export function App() { return () => { disposed = true; }; }, [request]); return ( -
+