2026-04-25 18:56:03 +02:00
|
|
|
|
# Claude Code — Dev Guide for singularity-foundry
|
|
|
|
|
|
|
|
|
|
|
|
## Build pipeline (MUST READ before editing extension source)
|
|
|
|
|
|
|
|
|
|
|
|
Source TypeScript files under `src/resources/extensions/sf/` are **not loaded
|
|
|
|
|
|
directly at runtime**. The loader (`src/loader.ts`) resolves extension entry
|
|
|
|
|
|
points from `dist/resources/extensions/sf/` (compiled `.js`) and copies them
|
|
|
|
|
|
to `~/.sf/agent/extensions/sf/` via `initResources`. Editing a `.ts` source
|
|
|
|
|
|
file has **no effect** until you recompile:
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
npm run copy-resources # tsc --project tsconfig.resources.json + file copy
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
This clears and rebuilds `dist/resources/` in one shot. Expect ~60–90 s on
|
|
|
|
|
|
first run; subsequent runs reuse tsc's incremental cache if you keep one.
|
|
|
|
|
|
|
|
|
|
|
|
The `dist-redirect.mjs` resolver (used by tests and `dev-cli.js`) only
|
|
|
|
|
|
redirects `.js → .ts` for imports whose `parentURL` is inside `/src/`. Files
|
|
|
|
|
|
loaded from `~/.sf/agent/extensions/sf/` (compiled JS) are **not** redirected.
|
|
|
|
|
|
|
|
|
|
|
|
## Running tests
|
|
|
|
|
|
|
|
|
|
|
|
**Use the lightweight `--test` runner, not `npm run test:coverage`.**
|
|
|
|
|
|
|
|
|
|
|
|
The coverage runner (`c8` + `--cpu-prof` + `--heap-prof`) spawns 10–15 heavy
|
|
|
|
|
|
worker processes per invocation. If a background run is killed or times out,
|
|
|
|
|
|
those workers are left alive, saturating all CPUs (~700% observed).
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# Run a specific test file (fast, no coverage overhead):
|
|
|
|
|
|
node --import ./src/resources/extensions/sf/tests/resolve-ts.mjs \
|
|
|
|
|
|
--experimental-strip-types \
|
|
|
|
|
|
--test src/resources/extensions/sf/tests/<name>.test.ts
|
|
|
|
|
|
|
|
|
|
|
|
# Run the full SF extension test suite:
|
|
|
|
|
|
npm test
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
If the machine feels slow, check for stray workers:
|
|
|
|
|
|
```bash
|
|
|
|
|
|
ps aux | grep "heap-prof-interval" | grep -v grep
|
|
|
|
|
|
# Kill them: ... | awk '{print $2}' | xargs kill -9
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-04-25 23:20:15 +02:00
|
|
|
|
**Do not use Python for one-off JSON/hash work.** The resource fingerprint in
|
|
|
|
|
|
`~/.sf/agent/managed-resources.json` is computed by Node's SHA-256 — Python's
|
|
|
|
|
|
`hashlib` produces a different result for the same files, which breaks the
|
|
|
|
|
|
fast-path check in `initResources` and causes a 30-60 s full resync on every
|
|
|
|
|
|
launch. Use `node -e` (or `jq`) for any shell-level JSON/hash operations in
|
|
|
|
|
|
this repo.
|
|
|
|
|
|
|
2026-04-25 18:56:03 +02:00
|
|
|
|
## Key directories
|
|
|
|
|
|
|
|
|
|
|
|
| Path | Purpose |
|
|
|
|
|
|
|------|---------|
|
|
|
|
|
|
| `src/resources/extensions/sf/` | Extension TypeScript source (edit here) |
|
|
|
|
|
|
| `dist/resources/extensions/sf/` | Compiled output (rebuilt by `copy-resources`) |
|
|
|
|
|
|
| `~/.sf/agent/extensions/sf/` | Installed copy (synced from dist on startup) |
|
|
|
|
|
|
| `src/resources/extensions/sf/prompts/` | Prompt templates (`.md`) |
|
|
|
|
|
|
| `src/resources/extensions/sf/tests/dist-redirect.mjs` | Module resolver hook for tests |
|
|
|
|
|
|
|
|
|
|
|
|
## Template variables
|
|
|
|
|
|
|
|
|
|
|
|
When adding a new `{{variable}}` to a prompt template in `prompts/`, you must:
|
|
|
|
|
|
|
|
|
|
|
|
1. Pass it in every `loadPrompt("template-name", { ..., newVar })` call site
|
|
|
|
|
|
(`auto-prompts.ts` is the main one for execute-task).
|
|
|
|
|
|
2. Add it (with a sensible placeholder value) to any test that calls
|
|
|
|
|
|
`loadPrompt("template-name", {...})` — see
|
|
|
|
|
|
`src/resources/extensions/sf/tests/plan-slice-prompt.test.ts`.
|
|
|
|
|
|
3. Run `npm run copy-resources` to land the change in dist.
|
|
|
|
|
|
|
|
|
|
|
|
`loadPrompt` throws at runtime if any `{{var}}` in the template has no
|
|
|
|
|
|
corresponding key in the vars object — this is intentional to catch
|
|
|
|
|
|
template/code drift early.
|
