coalesce-create-app
Use when building, changing, or debugging a Coalesce workspace app — a small local web app in a Transform workspace's apps/<id>/ folder that Coalesce Desktop or coa serve runs and opens as a tab from the Build rail's Apps menu (dashboards, modelers, generators, review tools over the workspace's nodes and YAML). Covers the runtime contract (node <file> start script, PORT and WORKSPACE_DIR, no npm), the sandboxed <app>.localhost origin, reading and writing workspace files safely, running coa from an app, and testing.
- License 许可
- MIT
- 最近更新
- 2026-11-11
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- coalesce-create-app
- description
- Use when building, changing, or debugging a Coalesce workspace app — a small local web app in a Transform workspace's apps/<id>/ folder that Coalesce Desktop or coa serve runs and opens as a tab from the Build rail's Apps menu (dashboards, modelers, generators, review tools over the workspace's nodes and YAML). Covers the runtime contract (node <file> start script, PORT and WORKSPACE_DIR, no npm), the sandboxed <app>.localhost origin, reading and writing workspace files safely, running coa from an app, and testing.
02 资源文件 1
- 参考文档reference/template.md7.6 KB
03 SKILL.md 正文
<!-- coalesce-node-managed: true -->
Create a Coalesce workspace app
A workspace app is a folder apps/<appId>/ inside a Transform workspace
(the folder with data.yml) containing a package.json and a Node server.
When the workspace is open in Coalesce Desktop or coa serve, the watch server
lists every such folder under Apps on the Build rail. Opening one starts
its server on demand and shows it in a canvas tab, in an iframe served from the
app's own origin. The app reads and writes the workspace on disk, so whatever
it saves shows up in Coalesce and in git like any other edit.
Apps run only in local mode (Desktop or coa serve), never in the cloud
Coalesce app.
If the app reads or writes Coalesce files (nodes/, jobs/, nodeTypes/,
locations.yml), also load coalesce-pipelines for the file formats and
authoring rules.
The runtime contract
These rules come from the watch server's app manager. Break one and the app fails to start or never appears.
| Rule | Detail |
|---|---|
| Discovery | Every non-hidden folder in apps/ with a parseable package.json is an app. The folder name is the app id. Folders starting with . are ignored. |
| Menu label | name from package.json, else the folder name. description is shown too. |
| Start script | scripts.start must be exactly node <file> [args]. It is not run by npm or a shell, so no npm, npx, vite, &&, pipes, quotes, $VARS, globs, or ~. Anything else fails with "Unsupported start script". |
| No install step | Nothing runs npm install, and node_modules/ is not consulted for you. Use Node built-ins, or bundle dependencies into one committed file (see Dependencies). |
| Runtime | Coalesce's own Node: Electron's Node (v24 at the time of writing) in Desktop, or whatever Node runs coa under coa serve. Write for Node 20+ and use only built-ins (http, fs, path, child_process, crypto, global fetch). No native .node addons. |
| Environment | Always read PORT (the port to listen on) and WORKSPACE_DIR (absolute workspace root). Don't hardcode a port or work out the workspace from the app's own path. The rest of the parent environment is inherited; in Desktop PATH can be the bare system one (/usr/bin:/bin:...). Working directory is the app folder. |
| Readiness | Coalesce polls GET http://localhost:$PORT/ every 0.5 s for 15 s; any HTTP response counts. Listen at once and do slow work (scans, warehouse calls) after listening or per request. |
| Lifetime | Started on first open, kept running across tab switches, stopped when Coalesce or coa serve exits. A crashed app restarts on its next request. Editing server.js does not restart a running app (see Test it). |
| Logs | stdout and stderr go to the Coalesce log as [App:<appId>]. If the app exits before it is ready, the tail of stderr is shown in the tab. |
| Host name | Served at http://<label>.localhost:<watch port>/, where <label> is the app id lowercased with every run of other characters turned into -. Two folders whose ids map to the same label collide and neither opens. Use a lowercase [a-z0-9-] id and make name the same. |
The sandbox the UI runs in
The tab is an iframe with sandbox="allow-scripts allow-same-origin allow-forms allow-popups" on the app's own origin. In practice:
- No access to Coalesce.
window.parentis cross-origin: the app cannot read Coalesce's DOM, theme, storage, auth, selection, or the watch API from the browser. - Blocked:
alert,confirm,prompt(noallow-modals; they return immediately without showing), file downloads (noallow-downloads; save output into the workspace instead), and navigating the top window. - Allowed: scripts, forms,
fetchto the app's own server, its ownlocalStorage, andwindow.open/target="_blank"links. - Theme: follow
prefers-color-scheme. The app cannot read Coalesce's light/dark setting. - Paths: the app is served at
/of its own origin. Root-relative (/api/...) and relative URLs both work; no<base>tricks or/proxyprefixes are needed (those were for the old path-prefixed proxy). - Coalesce refuses requests to
<label>.localhostfrom other websites, but the app also listens directly onlocalhost:$PORT, and that port has no guard. See the next section.
Guard the app's own port
The app's port (localhost:$PORT) is reachable from any page in the user's
browser, not just from Coalesce. The template includes three checks so only
the app's own page can use it; keep them:
Hostis a loopback name (localhost,127.0.0.1,[::1], or*.localhost), which rules out DNS rebinding. Requests through Coalesce keep their<label>.localhosthost, so they pass.- Writes are same-origin JSON. Anything other than
GET/HEADneedsContent-Type: application/jsonand aSec-Fetch-Siteofsame-originor none (curlsends none). Have the UI set the content type on writes, and don't change state on aGET. - No CORS headers.
These checks cover browser pages. Other programs on the machine aren't in scope, since they can already read the workspace directly.
Render workspace content as text
Node names, descriptions and SQL come from git, and the app's own page is
trusted to write. Put workspace values on the page with textContent (or a
framework's default escaping) rather than innerHTML or HTML built from a
template string, as the template's table does. Don't eval or require
workspace files.
Run commands without a shell
Use execFile or spawn with an argument array, as the
coa snippet does, rather than exec or
shell: true. Check values that become arguments (node names, locations,
selectors) against a simple pattern such as ^[A-Za-z0-9_]+$, and return a
400 otherwise.
Keep secrets on the server
- Anything an app writes to the workspace ends up in git, so read API keys
from a file outside it (such as
~/.config/<appId>/) or an environment variable. Desktop opened from the Dock or Finder doesn't see shell profile variables, so a file is more reliable there. - Keep keys out of responses, pages and logs, and don't read
~/.coa/config. - If the app sends workspace content to an outside service, say which service and what is sent in its README and UI, and send it only when the user asks. Check with the user before building one.
Step 0 — Orient
ls apps/for existing apps and id collisions. Apps run with the user's permissions when opened, so read any app you didn't write before starting it.- If
~/.coalesce/desktop/agent.jsonexists,serving.portis the port apps are served on. Otherwise use the portcoa serveprinted. - Decide where the app writes:
nodes/,jobs/andsubgraphs/followcoalesce-pipelinesand need the user's OK.- Never
data.yml,workspace.yml,environments/,.coa/or~/.coa/config.
Step 1 — Scaffold
Write the three files in reference/template.md into
apps/<appId>/ verbatim, and set name (same as the folder) and
description in package.json. The template already handles loopback
listening, the port checks and workspace path checks (wsPath()).
Step 2 — Build the server
- Answer
GET /fast; it's the readiness probe. - Read workspace files per request so the app sees edits made in Coalesce.
coalesce-pipelinesdocuments the node and node type file shapes. - Return JSON errors with a 4xx status, and log to stdout/stderr.
Running coa from an app
coa usually isn't on PATH in Desktop. Resolve it from agent.json:
const { execFile } = require("child_process");
const os = require("os"), fs = require("fs"), path = require("path");
function coaCommand() {
try {
const a = JSON.parse(fs.readFileSync(path.join(os.homedir(), ".coalesce/desktop/agent.json"), "utf-8"));
const [cmd, ...pre] = a.coa.runInvocation;
return { cmd, pre, env: { ...process.env, ...a.coa.env } };
} catch {
return { cmd: "coa", pre: [], env: process.env };
}
}
function runCoa(args) {
const { cmd, pre, env } = coaCommand();
return new Promise((resolve) =>
execFile(cmd, [...pre, ...args, "-d", process.env.WORKSPACE_DIR], { env, maxBuffer: 20 << 20 }, (err, stdout, stderr) =>
resolve({ ok: !err, stdout, stderr })));
}
// e.g. await runCoa(["--json", "validate"]); stdout holds the JSON even when ok is false
Stick to read-only commands (validate, describe, --dry-run).
Step 3 — Build the UI
- Plain HTML/JS is usually enough. A framework build must be committed as static files; nothing builds inside Coalesce.
fetch("/api/...")withcontent-type: application/jsonon writes, and workspace values rendered withtextContent.- Show errors inline (no dialogs), follow
prefers-color-scheme, and fill the tab's height.
Dependencies
Prefer none. Otherwise bundle into one committed file and start that:
npx esbuild server.src.js --bundle --platform=node --target=node20 --outfile=dist/server.js
Step 4 — Test it
- Standalone:
PORT=4310 WORKSPACE_DIR="$WORKSPACE" node server.js, thencurl localhost:4310/and open it in a browser. - Check
scripts.startisnode <file>,node --checkpasses, andnamematches the folder. - In Coalesce: Build › Apps › your app (reload the page to see a new app).
Restart Coalesce or
coa serveafter server changes; UI changes only need a tab reload. Start failures are shown in the tab.
Step 5 — Commit
Stage the app folder per coalesce-git-publication.
Commit and push only with the user's approval.
Approval gates
- Without asking: reading the workspace, scaffolding the requested app,
running it standalone, read-only
coacommands. - ASK FIRST: apps that write
nodes/,jobs/,subgraphs/or other shared config, or send workspace content to an outside service; changing another app; adding dependencies; committing; pushing. - NEVER: have an app run deploy, refresh, init or profile commands, read
~/.coa/config, listen beyond loopback, or reach into the Coalesce page.
04 同仓库更多 Skills
coalesce-transform-mcp-install
Use when installing, connecting, or troubleshooting the hosted Coalesce Transform MCP server in an MCP client (Claude Code, Claude Desktop, Cursor, VS Code, Cortex Code) — endpoint URL, access token handling, registration, and verification. Not for coa CLI auth (use coalesce-cloud-api).
coalesce-sql-transformation
Use when editing the SQL inside existing Coalesce V2 node files (.sql) — changing column expressions, joins, filters, CTEs, inline column annotations, or ref() macros. Not for creating/deleting node files (use coalesce-pipeline-structure).
coalesce-review-risk
Use when reviewing Coalesce pipeline changes for correctness, impact, and risk before approval — READ-ONLY analysis of diffs, coa validate/dry-run evidence, and downstream blast radius. Never edits files or runs warehouse-mutating commands.
coalesce-rename-node-cascade
Rename a Coalesce node and cascade the new name through every downstream ref(), job selector, and subgraph selector, with quote-agnostic matching and validation.
coalesce-quality-test-authoring
Decide which data quality tests a table, view or model needs, and write them in whatever test format the project already uses (dbt, SYNQ YAML, SQLMesh audits, Soda, Great Expectations, custom SQL, and so on). Use it when asked to add, suggest, review or extend data tests for a warehouse asset, or when a change to a model should come with tests.
coalesce-pipelines
Use when working in a Coalesce Transform repository (data.yml + nodes/ with <LOCATION>-<NAME>.sql/.yml files) — building, editing, validating, or running data transformation pipelines with the coa CLI, including editing V1 .yml nodes and shared config (data.yml, locations, environments, jobs, node types). Start here; it routes to the more specific coalesce-* skills.