Pointers for an automated setup agent picking this repo up on a fresh
machine. The per-subproject AGENTS.md files (e.g. nemoclaw_agent/)
cover subsystem specifics; this file only documents cross-cutting
conventions that aren't obvious from the code.
Always run npx tsc --noEmit in any package you edited under
heb-sdk-unofficial/packages/ before committing or pushing. The
fork's CI runs typecheck on PRs and a failure forces a re-roll of
dev/stack plus another parent-pointer bump.
cd heb-sdk-unofficial/packages/heb-mcp # or heb-sdk, heb-auth, etc.
npx tsc --noEmit
If tsc complains it can't find heb-auth-unofficial or heb-sdk-unofficial,
the workspace deps haven't been built yet — see the Vendor overlay
section below for the build sequence (the same dist/ files those
commands produce are what makes the workspace imports resolve).
Watch out for implicit any in .map callbacks when the SDK's
exported types resolve to any in some build configurations. Annotate
explicitly — e.g. products.map((p: any, i: number) => …) — rather
than relying on inference. This bit us once when heb-sdk's dist
didn't ship full type info and noImplicitAny rejected callbacks that
typechecked fine against the source tree.
The heb-sdk-unofficial/ submodule is our fork of the upstream SDK,
vendored as source for the HEB MCP server. Each in-flight change
against upstream lives on its own PR branch off main so each one
can be opened as an independent pull request. The parent repo does not
track any PR branch directly — instead it tracks a dedicated
integration branch that merges them.
| Branch | Purpose |
|---|---|
main |
Fork default; tracks upstream |
feat/<topic> (e.g. feat/checkout-cart-commit, feat/product-image) |
One branch per in-flight PR, always off main |
dev/stack |
Octopus merge of every active feat/* branch |
The parent's submodule pointer always references the tip of
dev/stack. That keeps git clone --recurse-submodules resolvable
from origin alone — no extra fetch config, no local-only SHAs.
cd heb-sdk-unofficial
git fetch origin
git switch -c feat/<topic> origin/main
# ... commits ...
git push -u origin feat/<topic>
# re-roll the integration branch
git switch dev/stack
git reset --hard origin/main
git merge --no-ff feat/checkout-cart-commit feat/product-image feat/<topic> \
-m "merge feat/* branches for local dev stack"
git push --force-with-lease origin dev/stack
# bump the parent pointer
cd ..
git add heb-sdk-unofficial
git commit -m "chore(heb-sdk): roll dev/stack to include feat/<topic>"
Delete the feature branch locally + on origin, re-roll dev/stack off
fresh origin/main, push, and bump the parent pointer.
heb/ depends on heb-sdk-unofficial via npm by name, but at build
time heb/Dockerfile overlays the vendored heb/vendor/heb-sdk-dist/
directory onto node_modules/heb-sdk-unofficial/dist/. This exists
because our SDK changes aren't published to npm yet.
Any time you change the SDK, rebuild and refresh the overlay:
cd heb-sdk-unofficial/packages/heb-sdk
pnpm install # one-time per machine
npx tsup src/index.ts --format cjs,esm --clean --tsconfig tsconfig.json
npx tsc --declaration --emitDeclarationOnly --outDir dist
cp dist/src/*.d.ts dist/src/*.d.ts.map dist/
rm -rf ../../../heb/vendor/heb-sdk-dist/*
cp -r dist/* ../../../heb/vendor/heb-sdk-dist/
cd ../../../heb && docker compose up -d --build
The full dist/ (bundled index.js/index.cjs + per-file .d.ts
files) must be committed alongside the submodule pointer bump —
otherwise a fresh Docker build would pick up stale code.
git clone --recurse-submodules https://github.com/dkaygithub/local_agent.git
cd local_agent
# sanity check: submodule should be on detached HEAD at dev/stack's tip
git -C heb-sdk-unofficial log --oneline -1
If --recurse-submodules was forgotten: git submodule update --init --recursive.
Any one-off script written during a session lives in dbg/ before it
runs (never in /tmp or arbitrary paths). Repeatable smoke tests stay
checked in; genuinely single-use scratch gets deleted on cleanup.