t1k:cocos:omarchy:pod-build
| Field | Value |
|---|---|
| Module | omarchy |
| Version | 0.4.2 |
| Effort | medium |
| Tools | Bash, Read |
Keywords: build copy project, cocos headless build windows guest, cocos mcp guest launch, cocos web build guest, creator cli build, ebusy node_modules build, missing class build scene, pod build, pod sync, pull web-mobile build, stale build bundle, winpodx build
How to invoke
Section titled “How to invoke”/t1k:cocos:omarchy:pod-build[sync | launch | build | pull | verify-bundle | verify-stale | serve]Pod build: host project -> guest Creator -> web build -> host
Section titled “Pod build: host project -> guest Creator -> web build -> host”Cocos Creator runs in the winpodx Windows guest (t1k-cocos-omarchy-winpodx set it up). This skill is the repeatable loop on top of
it: push the host working tree in, start Creator with the MCP extension, drive a CLI web build on a separate copy, pull the build
back, prove it carries your change. Scripts are Python (winpodx is a Python package; the guest agent is reached through its
AgentClient) and carry no project names: everything is an environment variable (scripts/pod_common.py documents each one).
S=.claude/skills/t1k-cocos-omarchy-pod-build/scriptsexport POD_LOCAL_PROJECT=<host project root, the folder with assets/>export POD_GUEST_PROJECT='C:\CocosProjects\<Name>' # authoring copy; the build copy defaults to <same>Buildexport POD_START_SCENE=db://assets/<path>.scene # build onlyLoop (order is the contract)
Section titled “Loop (order is the contract)”python3 -I $S/pod_sync.py- always first. Host -> guest authoring copy (chunked, sha256-verified, manifest-checked). It listsGUEST-ONLY:guest assets the project no longer has;--prunedeletes them (a removed/renamed file otherwise survives and breaks the build). Resumable delta: a host state file (~/.cache/t1k/pod_sync/,POD_SYNC_STATE_DIR) records every file the guest confirmed, so a run sends only added/changed files in ~1 MiB batches and re-running the SAME command after a timeout, outage or Ctrl-C continues where it stopped;--fullresends everything,--dry-runprints themode:/plan:lines and writes nothing. Exit codes:0VERIFIED;1VERIFICATION FAILED (a real mismatch: only the mismatching entries leave the state, so the next run resends just those) or a failed--prune;3VERIFICATION UNKNOWN (the guest’s verify reply was empty, cut off orcount=0/0, retried--retriestimes; the state is KEPT, re-run the same command once the host is quieter, it resends nothing). Never treat3as a pass or as a reason to--full. Details and the failure modes: gotchas (references/gotchas.md).python3 -I $S/pod_launch.py- Creator on the authoring copy with the MCP extension autostarting; wait for the port to answer.$S/mcp_call.py <tool> '<json>'then drives the editor (it refuses when the editor has another project open).- Editor work (prefabs, scenes): see prefab authoring via MCP (
references/prefab-authoring-via-mcp.md); save in the editor. python3 -I $S/pod_build.py sync- guest authoring copy -> guest build copy (never from the host). When robocopy purged anything (or its summary is unreadable, or with--wipe-library) it then runsclean-stale(wipes the build copy’slibrary\andtemp\, so the asset DB cannot keep a deleted asset);clean-stalealso runs alone and refuses while a Creator holds the copy.python3 -I $S/pod_build.py build- headless build on the build copy; the editor on the authoring copy stays open (two Creators on one project corrupt it). Exit 0 only when the log, not Creator’s exit code, says it is good.python3 -I $S/pod_build.py pull <dir>thenverify-bundle <dir> --token <symbol-or-component-id> ...- a token you know must be in the build (a symbol you just added; a component class id from the source scene). Thenpython3 -I $S/pod_build.py verify-stale <dir> --repo $POD_LOCAL_PROJECT [--bundle resources]: exit 0 clean, 1 lists built asset paths the repo no longer has, 2 could not verify (never a pass). Only thenserve <dir>.
--dry-run on every pod_build.py subcommand prints the guest script without running it. Add POD_BUILD_PACKAGES='{"<pkg>":{...}}'
for per-package build options. build --target <id> builds a platform target of the project’s extensions/platform-manager/dist/ci-targets.json
(web-mobile rows only; an unknown id is an error; set POD_TARGET_PACKAGE to the build-config package key that takes the target); a
non-local target then runs the page-injection post-step in the guest, because Creator writes index.html itself and without it a portal
build ships without its vendor script. The guest node on PATH is unverified. Both the failure signatures and why each guard exists are in
gotchas (references/gotchas.md): read it before trusting a green build.
- Never print or read the winpodx agent token; the scripts do not. Never put a project name, token or keystore in these scripts or
their tests (a test enforces the first two).
*.keystoreis excluded from the sync. pod_build.pynever kills a process and never writes to the authoring copy. A build that fails on script-load errors is retried once after clearing the build copy’stemp\programming(--retries 0turns that off).- Tests:
bun test tests/pod-build.test.cjsandbun test tests/pod-delta.test.cjs(no guest needed; they cover log parsing, config, dry-runs, sync filtering, prune, the resumable delta transport against a fake guest,clean-stale,verify-bundleandverify-stale). What needs a live guest (the chunk transfer, Creator itself) is NOT covered; say so when reporting.