singularity-forge/CLAUDE.md

Claude Code — Dev Guide for singularity-forge

See AGENTS.md for SF planning conventions and the promote-only state rule. The foundational product contract is ADR-0000: SF Is a Purpose-to-Software Compiler.

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:

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 vitest — no pre-compilation step needed.

# Run a specific test file (fast, no coverage overhead):
npx vitest run src/resources/extensions/sf/tests/<name>.test.ts --config vitest.config.ts

# Run the full SF extension test suite:
npm run test:unit

# Run only tests affected by recent changes (fast feedback loop):
npx vitest run --changed --config vitest.config.ts

# Watch mode for active development:
npx vitest --config vitest.config.ts

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.

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.