@draht/coding-agent 2026.7.30 → 2026.9.5-1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +154 -0
- package/README.md +46 -2
- package/agents/debugger.md +12 -1
- package/agents/git-committer.md +1 -0
- package/agents/implementer.md +20 -0
- package/agents/investigator.md +75 -0
- package/agents/reviewer.md +7 -0
- package/agents/spec-reviewer.md +66 -0
- package/agents/verifier.md +4 -3
- package/bin/draht-tools.cjs +472 -41
- package/dist/agents/debugger.md +12 -1
- package/dist/agents/git-committer.md +1 -0
- package/dist/agents/implementer.md +20 -0
- package/dist/agents/investigator.md +75 -0
- package/dist/agents/reviewer.md +7 -0
- package/dist/agents/spec-reviewer.md +66 -0
- package/dist/agents/verifier.md +4 -3
- package/dist/cli/args.d.ts +10 -0
- package/dist/cli/args.d.ts.map +1 -1
- package/dist/cli/args.js +69 -2
- package/dist/cli/args.js.map +1 -1
- package/dist/cli/attach-mode.d.ts +61 -0
- package/dist/cli/attach-mode.d.ts.map +1 -1
- package/dist/cli/attach-mode.js +243 -5
- package/dist/cli/attach-mode.js.map +1 -1
- package/dist/cli/credential-print.d.ts +1 -1
- package/dist/cli/credential-print.d.ts.map +1 -1
- package/dist/cli/credential-print.js +5 -4
- package/dist/cli/credential-print.js.map +1 -1
- package/dist/config.d.ts +9 -0
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +31 -4
- package/dist/config.js.map +1 -1
- package/dist/core/agent-session-runtime.d.ts +17 -1
- package/dist/core/agent-session-runtime.d.ts.map +1 -1
- package/dist/core/agent-session-runtime.js +87 -30
- package/dist/core/agent-session-runtime.js.map +1 -1
- package/dist/core/agent-session-services.d.ts +1 -1
- package/dist/core/agent-session-services.d.ts.map +1 -1
- package/dist/core/agent-session-services.js +1 -0
- package/dist/core/agent-session-services.js.map +1 -1
- package/dist/core/agent-session.d.ts +35 -16
- package/dist/core/agent-session.d.ts.map +1 -1
- package/dist/core/agent-session.js +149 -64
- package/dist/core/agent-session.js.map +1 -1
- package/dist/core/auth-storage.d.ts +5 -1
- package/dist/core/auth-storage.d.ts.map +1 -1
- package/dist/core/auth-storage.js +72 -15
- package/dist/core/auth-storage.js.map +1 -1
- package/dist/core/builtins/checkpoints.d.ts +20 -0
- package/dist/core/builtins/checkpoints.d.ts.map +1 -0
- package/dist/core/builtins/checkpoints.js +161 -0
- package/dist/core/builtins/checkpoints.js.map +1 -0
- package/dist/core/builtins/duet.d.ts +26 -0
- package/dist/core/builtins/duet.d.ts.map +1 -0
- package/dist/core/builtins/duet.js +660 -0
- package/dist/core/builtins/duet.js.map +1 -0
- package/dist/core/builtins/index.d.ts.map +1 -1
- package/dist/core/builtins/index.js +7 -1
- package/dist/core/builtins/index.js.map +1 -1
- package/dist/core/builtins/subagent.d.ts +24 -4
- package/dist/core/builtins/subagent.d.ts.map +1 -1
- package/dist/core/builtins/subagent.js +278 -35
- package/dist/core/builtins/subagent.js.map +1 -1
- package/dist/core/checkpoints/checkpoint-cli.d.ts +17 -0
- package/dist/core/checkpoints/checkpoint-cli.d.ts.map +1 -0
- package/dist/core/checkpoints/checkpoint-cli.js +78 -0
- package/dist/core/checkpoints/checkpoint-cli.js.map +1 -0
- package/dist/core/checkpoints/checkpoint-manager.d.ts +294 -0
- package/dist/core/checkpoints/checkpoint-manager.d.ts.map +1 -0
- package/dist/core/checkpoints/checkpoint-manager.js +865 -0
- package/dist/core/checkpoints/checkpoint-manager.js.map +1 -0
- package/dist/core/checkpoints/rewind.d.ts +141 -0
- package/dist/core/checkpoints/rewind.d.ts.map +1 -0
- package/dist/core/checkpoints/rewind.js +246 -0
- package/dist/core/checkpoints/rewind.js.map +1 -0
- package/dist/core/compaction/branch-summarization.d.ts +1 -1
- package/dist/core/compaction/branch-summarization.d.ts.map +1 -1
- package/dist/core/compaction/branch-summarization.js +9 -4
- package/dist/core/compaction/branch-summarization.js.map +1 -1
- package/dist/core/compaction/compaction.d.ts +5 -0
- package/dist/core/compaction/compaction.d.ts.map +1 -1
- package/dist/core/compaction/compaction.js +25 -4
- package/dist/core/compaction/compaction.js.map +1 -1
- package/dist/core/extensions/index.d.ts +1 -1
- package/dist/core/extensions/index.d.ts.map +1 -1
- package/dist/core/extensions/index.js.map +1 -1
- package/dist/core/extensions/loader.d.ts.map +1 -1
- package/dist/core/extensions/loader.js +83 -20
- package/dist/core/extensions/loader.js.map +1 -1
- package/dist/core/extensions/runner.d.ts +13 -2
- package/dist/core/extensions/runner.d.ts.map +1 -1
- package/dist/core/extensions/runner.js +37 -2
- package/dist/core/extensions/runner.js.map +1 -1
- package/dist/core/extensions/types.d.ts +189 -6
- package/dist/core/extensions/types.d.ts.map +1 -1
- package/dist/core/extensions/types.js.map +1 -1
- package/dist/core/http-dispatcher.d.ts.map +1 -1
- package/dist/core/http-dispatcher.js +7 -0
- package/dist/core/http-dispatcher.js.map +1 -1
- package/dist/core/index.d.ts +1 -1
- package/dist/core/index.d.ts.map +1 -1
- package/dist/core/index.js.map +1 -1
- package/dist/core/keybindings.d.ts +5 -0
- package/dist/core/keybindings.d.ts.map +1 -1
- package/dist/core/keybindings.js +1 -0
- package/dist/core/keybindings.js.map +1 -1
- package/dist/core/model-registry.d.ts +3 -2
- package/dist/core/model-registry.d.ts.map +1 -1
- package/dist/core/model-registry.js +8 -8
- package/dist/core/model-registry.js.map +1 -1
- package/dist/core/model-resolver.d.ts.map +1 -1
- package/dist/core/model-resolver.js +34 -7
- package/dist/core/model-resolver.js.map +1 -1
- package/dist/core/model-runtime.d.ts +7 -1
- package/dist/core/model-runtime.d.ts.map +1 -1
- package/dist/core/model-runtime.js +30 -10
- package/dist/core/model-runtime.js.map +1 -1
- package/dist/core/multi-agent/permission-gate.d.ts.map +1 -1
- package/dist/core/multi-agent/permission-gate.js +4 -3
- package/dist/core/multi-agent/permission-gate.js.map +1 -1
- package/dist/core/multi-agent/worktree.d.ts +2 -0
- package/dist/core/multi-agent/worktree.d.ts.map +1 -1
- package/dist/core/multi-agent/worktree.js +2 -2
- package/dist/core/multi-agent/worktree.js.map +1 -1
- package/dist/core/package-manager.d.ts +7 -1
- package/dist/core/package-manager.d.ts.map +1 -1
- package/dist/core/package-manager.js +21 -44
- package/dist/core/package-manager.js.map +1 -1
- package/dist/core/permission-relay/index.d.ts +19 -0
- package/dist/core/permission-relay/index.d.ts.map +1 -0
- package/dist/core/permission-relay/index.js +49 -0
- package/dist/core/permission-relay/index.js.map +1 -0
- package/dist/core/permission-relay/relay-ui-context.d.ts +39 -0
- package/dist/core/permission-relay/relay-ui-context.d.ts.map +1 -0
- package/dist/core/permission-relay/relay-ui-context.js +788 -0
- package/dist/core/permission-relay/relay-ui-context.js.map +1 -0
- package/dist/core/permission-relay/types.d.ts +222 -0
- package/dist/core/permission-relay/types.d.ts.map +1 -0
- package/dist/core/permission-relay/types.js +15 -0
- package/dist/core/permission-relay/types.js.map +1 -0
- package/dist/core/pi-manifest.d.ts +14 -0
- package/dist/core/pi-manifest.d.ts.map +1 -0
- package/dist/core/pi-manifest.js +35 -0
- package/dist/core/pi-manifest.js.map +1 -0
- package/dist/core/project-trust.js +2 -2
- package/dist/core/project-trust.js.map +1 -1
- package/dist/core/resource-loader.d.ts +21 -0
- package/dist/core/resource-loader.d.ts.map +1 -1
- package/dist/core/resource-loader.js +101 -24
- package/dist/core/resource-loader.js.map +1 -1
- package/dist/core/sandbox/bash-operations.d.ts +149 -0
- package/dist/core/sandbox/bash-operations.d.ts.map +1 -0
- package/dist/core/sandbox/bash-operations.js +163 -0
- package/dist/core/sandbox/bash-operations.js.map +1 -0
- package/dist/core/sandbox/env.d.ts +83 -0
- package/dist/core/sandbox/env.d.ts.map +1 -0
- package/dist/core/sandbox/env.js +123 -0
- package/dist/core/sandbox/env.js.map +1 -0
- package/dist/core/sandbox/executor.d.ts +104 -0
- package/dist/core/sandbox/executor.d.ts.map +1 -0
- package/dist/core/sandbox/executor.js +92 -0
- package/dist/core/sandbox/executor.js.map +1 -0
- package/dist/core/sandbox/index.d.ts +36 -0
- package/dist/core/sandbox/index.d.ts.map +1 -0
- package/dist/core/sandbox/index.js +36 -0
- package/dist/core/sandbox/index.js.map +1 -0
- package/dist/core/sandbox/linux.d.ts +121 -0
- package/dist/core/sandbox/linux.d.ts.map +1 -0
- package/dist/core/sandbox/linux.js +260 -0
- package/dist/core/sandbox/linux.js.map +1 -0
- package/dist/core/sandbox/policy.d.ts +142 -0
- package/dist/core/sandbox/policy.d.ts.map +1 -0
- package/dist/core/sandbox/policy.js +297 -0
- package/dist/core/sandbox/policy.js.map +1 -0
- package/dist/core/sandbox/real-path.d.ts +112 -0
- package/dist/core/sandbox/real-path.d.ts.map +1 -0
- package/dist/core/sandbox/real-path.js +158 -0
- package/dist/core/sandbox/real-path.js.map +1 -0
- package/dist/core/sandbox/seatbelt-profile.d.ts +95 -0
- package/dist/core/sandbox/seatbelt-profile.d.ts.map +1 -0
- package/dist/core/sandbox/seatbelt-profile.js +239 -0
- package/dist/core/sandbox/seatbelt-profile.js.map +1 -0
- package/dist/core/sandbox/seatbelt.d.ts +95 -0
- package/dist/core/sandbox/seatbelt.d.ts.map +1 -0
- package/dist/core/sandbox/seatbelt.js +154 -0
- package/dist/core/sandbox/seatbelt.js.map +1 -0
- package/dist/core/sandbox/self-test.d.ts +109 -0
- package/dist/core/sandbox/self-test.d.ts.map +1 -0
- package/dist/core/sandbox/self-test.js +369 -0
- package/dist/core/sandbox/self-test.js.map +1 -0
- package/dist/core/sandbox/spawn.d.ts +33 -0
- package/dist/core/sandbox/spawn.d.ts.map +1 -0
- package/dist/core/sandbox/spawn.js +87 -0
- package/dist/core/sandbox/spawn.js.map +1 -0
- package/dist/core/sdk.d.ts.map +1 -1
- package/dist/core/sdk.js +3 -1
- package/dist/core/sdk.js.map +1 -1
- package/dist/core/session-manager.d.ts +60 -1
- package/dist/core/session-manager.d.ts.map +1 -1
- package/dist/core/session-manager.js +53 -6
- package/dist/core/session-manager.js.map +1 -1
- package/dist/core/settings-manager.d.ts +21 -0
- package/dist/core/settings-manager.d.ts.map +1 -1
- package/dist/core/settings-manager.js +36 -16
- package/dist/core/settings-manager.js.map +1 -1
- package/dist/core/skills.d.ts +3 -1
- package/dist/core/skills.d.ts.map +1 -1
- package/dist/core/skills.js +19 -6
- package/dist/core/skills.js.map +1 -1
- package/dist/core/slash-commands.d.ts.map +1 -1
- package/dist/core/slash-commands.js +1 -0
- package/dist/core/slash-commands.js.map +1 -1
- package/dist/core/soak/soak-log.d.ts +298 -0
- package/dist/core/soak/soak-log.d.ts.map +1 -0
- package/dist/core/soak/soak-log.js +660 -0
- package/dist/core/soak/soak-log.js.map +1 -0
- package/dist/core/soak/soak-reader.d.ts +60 -0
- package/dist/core/soak/soak-reader.d.ts.map +1 -0
- package/dist/core/soak/soak-reader.js +106 -0
- package/dist/core/soak/soak-reader.js.map +1 -0
- package/dist/core/socket-server/discovery.d.ts +78 -1
- package/dist/core/socket-server/discovery.d.ts.map +1 -1
- package/dist/core/socket-server/discovery.js +356 -37
- package/dist/core/socket-server/discovery.js.map +1 -1
- package/dist/core/socket-server/index.d.ts +10 -4
- package/dist/core/socket-server/index.d.ts.map +1 -1
- package/dist/core/socket-server/index.js +6 -3
- package/dist/core/socket-server/index.js.map +1 -1
- package/dist/core/socket-server/permission-delivery.d.ts +125 -0
- package/dist/core/socket-server/permission-delivery.d.ts.map +1 -0
- package/dist/core/socket-server/permission-delivery.js +152 -0
- package/dist/core/socket-server/permission-delivery.js.map +1 -0
- package/dist/core/socket-server/permission-registry.d.ts +301 -0
- package/dist/core/socket-server/permission-registry.d.ts.map +1 -0
- package/dist/core/socket-server/permission-registry.js +410 -0
- package/dist/core/socket-server/permission-registry.js.map +1 -0
- package/dist/core/socket-server/permission-relay.d.ts +81 -0
- package/dist/core/socket-server/permission-relay.d.ts.map +1 -0
- package/dist/core/socket-server/permission-relay.js +528 -0
- package/dist/core/socket-server/permission-relay.js.map +1 -0
- package/dist/core/socket-server/safe-text.d.ts +83 -0
- package/dist/core/socket-server/safe-text.d.ts.map +1 -0
- package/dist/core/socket-server/safe-text.js +277 -0
- package/dist/core/socket-server/safe-text.js.map +1 -0
- package/dist/core/socket-server/session-integration.d.ts +65 -2
- package/dist/core/socket-server/session-integration.d.ts.map +1 -1
- package/dist/core/socket-server/session-integration.js +434 -32
- package/dist/core/socket-server/session-integration.js.map +1 -1
- package/dist/core/socket-server/socket-client.d.ts +21 -2
- package/dist/core/socket-server/socket-client.d.ts.map +1 -1
- package/dist/core/socket-server/socket-client.js +52 -1
- package/dist/core/socket-server/socket-client.js.map +1 -1
- package/dist/core/socket-server/socket-server.d.ts +152 -1
- package/dist/core/socket-server/socket-server.d.ts.map +1 -1
- package/dist/core/socket-server/socket-server.js +775 -26
- package/dist/core/socket-server/socket-server.js.map +1 -1
- package/dist/core/socket-server/types.d.ts +106 -2
- package/dist/core/socket-server/types.d.ts.map +1 -1
- package/dist/core/socket-server/types.js +13 -1
- package/dist/core/socket-server/types.js.map +1 -1
- package/dist/core/system-prompt.d.ts.map +1 -1
- package/dist/core/system-prompt.js +8 -9
- package/dist/core/system-prompt.js.map +1 -1
- package/dist/core/tools/bash.d.ts +1 -1
- package/dist/core/tools/bash.d.ts.map +1 -1
- package/dist/core/tools/bash.js +5 -2
- package/dist/core/tools/bash.js.map +1 -1
- package/dist/core/tools/edit.d.ts.map +1 -1
- package/dist/core/tools/edit.js +17 -2
- package/dist/core/tools/edit.js.map +1 -1
- package/dist/core/tools/find.d.ts +3 -0
- package/dist/core/tools/find.d.ts.map +1 -1
- package/dist/core/tools/find.js +11 -18
- package/dist/core/tools/find.js.map +1 -1
- package/dist/core/trust-manager.d.ts +6 -4
- package/dist/core/trust-manager.d.ts.map +1 -1
- package/dist/core/trust-manager.js +55 -21
- package/dist/core/trust-manager.js.map +1 -1
- package/dist/extensions/index.d.ts.map +1 -1
- package/dist/extensions/index.js +5 -1
- package/dist/extensions/index.js.map +1 -1
- package/dist/extensions/llama/provider.d.ts.map +1 -1
- package/dist/extensions/llama/provider.js +5 -1
- package/dist/extensions/llama/provider.js.map +1 -1
- package/dist/extensions/stub-provider/index.d.ts +9 -0
- package/dist/extensions/stub-provider/index.d.ts.map +1 -0
- package/dist/extensions/stub-provider/index.js +13 -0
- package/dist/extensions/stub-provider/index.js.map +1 -0
- package/dist/extensions/stub-provider/provider.d.ts +77 -0
- package/dist/extensions/stub-provider/provider.d.ts.map +1 -0
- package/dist/extensions/stub-provider/provider.js +193 -0
- package/dist/extensions/stub-provider/provider.js.map +1 -0
- package/dist/hooks/gsd/draht-quality-gate.js +3 -3
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/main.d.ts.map +1 -1
- package/dist/main.js +242 -45
- package/dist/main.js.map +1 -1
- package/dist/modes/interactive/components/config-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/config-selector.js +3 -2
- package/dist/modes/interactive/components/config-selector.js.map +1 -1
- package/dist/modes/interactive/components/extension-selector.d.ts +49 -0
- package/dist/modes/interactive/components/extension-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/extension-selector.js +202 -5
- package/dist/modes/interactive/components/extension-selector.js.map +1 -1
- package/dist/modes/interactive/components/session-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/session-selector.js +10 -2
- package/dist/modes/interactive/components/session-selector.js.map +1 -1
- package/dist/modes/interactive/components/settings-selector.d.ts +2 -0
- package/dist/modes/interactive/components/settings-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/settings-selector.js +10 -0
- package/dist/modes/interactive/components/settings-selector.js.map +1 -1
- package/dist/modes/interactive/components/tool-execution.d.ts.map +1 -1
- package/dist/modes/interactive/components/tool-execution.js +10 -1
- package/dist/modes/interactive/components/tool-execution.js.map +1 -1
- package/dist/modes/interactive/components/tree-selector.d.ts +20 -2
- package/dist/modes/interactive/components/tree-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/tree-selector.js +21 -5
- package/dist/modes/interactive/components/tree-selector.js.map +1 -1
- package/dist/modes/interactive/interactive-mode.d.ts +97 -3
- package/dist/modes/interactive/interactive-mode.d.ts.map +1 -1
- package/dist/modes/interactive/interactive-mode.js +394 -24
- package/dist/modes/interactive/interactive-mode.js.map +1 -1
- package/dist/modes/rpc/rpc-mode.d.ts.map +1 -1
- package/dist/modes/rpc/rpc-mode.js +165 -7
- package/dist/modes/rpc/rpc-mode.js.map +1 -1
- package/dist/modes/rpc/rpc-types.d.ts +68 -1
- package/dist/modes/rpc/rpc-types.d.ts.map +1 -1
- package/dist/modes/rpc/rpc-types.js.map +1 -1
- package/dist/prompts/commands/atomic-commit.md +1 -12
- package/dist/prompts/commands/brainstorm.md +12 -15
- package/dist/prompts/commands/create-verification-skill.md +108 -0
- package/dist/prompts/commands/discuss-phase.md +3 -14
- package/dist/prompts/commands/execute-phase.md +3 -11
- package/dist/prompts/commands/fix.md +41 -18
- package/dist/prompts/commands/grill.md +66 -0
- package/dist/prompts/commands/init-project.md +5 -15
- package/dist/prompts/commands/map-codebase.md +1 -13
- package/dist/prompts/commands/new-project.md +5 -15
- package/dist/prompts/commands/next-milestone.md +1 -13
- package/dist/prompts/commands/orchestrate.md +1 -1
- package/dist/prompts/commands/pause-work.md +1 -13
- package/dist/prompts/commands/plan-phase.md +2 -11
- package/dist/prompts/commands/progress.md +0 -13
- package/dist/prompts/commands/quick.md +3 -11
- package/dist/prompts/commands/resolve-conflicts.md +71 -0
- package/dist/prompts/commands/resume-work.md +0 -13
- package/dist/prompts/commands/review.md +4 -13
- package/dist/prompts/commands/triage.md +159 -0
- package/dist/prompts/commands/verify-work.md +4 -14
- package/dist/prompts/commands/why.md +135 -0
- package/dist/skills/atomic-reasoning/SKILL.md +115 -0
- package/dist/skills/blast-radius/SKILL.md +55 -0
- package/dist/skills/epistemics/SKILL.md +99 -0
- package/dist/skills/hexagon-animation/SKILL.md +49 -0
- package/dist/skills/hexagon-animation/generate.mjs +81 -0
- package/dist/skills/hexagon-animation/template.html +361 -0
- package/dist/skills/typescript-discipline/SKILL.md +50 -0
- package/dist/skills/typescript-discipline/references/patterns.md +294 -0
- package/dist/skills/unslop/SKILL.md +101 -0
- package/dist/utils/canonical-path.d.ts +28 -0
- package/dist/utils/canonical-path.d.ts.map +1 -0
- package/dist/utils/canonical-path.js +90 -0
- package/dist/utils/canonical-path.js.map +1 -0
- package/dist/utils/child-process.d.ts +12 -1
- package/dist/utils/child-process.d.ts.map +1 -1
- package/dist/utils/child-process.js +25 -8
- package/dist/utils/child-process.js.map +1 -1
- package/dist/utils/clipboard.d.ts +1 -1
- package/dist/utils/clipboard.d.ts.map +1 -1
- package/dist/utils/clipboard.js +22 -2
- package/dist/utils/clipboard.js.map +1 -1
- package/dist/utils/exif-orientation.d.ts.map +1 -1
- package/dist/utils/exif-orientation.js +2 -3
- package/dist/utils/exif-orientation.js.map +1 -1
- package/dist/utils/paths.d.ts +2 -7
- package/dist/utils/paths.d.ts.map +1 -1
- package/dist/utils/paths.js +13 -15
- package/dist/utils/paths.js.map +1 -1
- package/dist/utils/shell.d.ts.map +1 -1
- package/dist/utils/shell.js +6 -4
- package/dist/utils/shell.js.map +1 -1
- package/dist/utils/tools-manager.d.ts.map +1 -1
- package/dist/utils/tools-manager.js +3 -5
- package/dist/utils/tools-manager.js.map +1 -1
- package/docs/attachable-sessions.md +79 -0
- package/docs/compaction.md +21 -21
- package/docs/containerization.md +23 -23
- package/docs/custom-provider.md +16 -16
- package/docs/development.md +9 -9
- package/docs/docs.json +6 -2
- package/docs/duet.md +42 -0
- package/docs/extensions.md +58 -58
- package/docs/index.md +10 -10
- package/docs/json.md +7 -7
- package/docs/keybindings.md +6 -5
- package/docs/llama-cpp.md +6 -6
- package/docs/models.md +6 -6
- package/docs/packages.md +43 -43
- package/docs/prompt-templates.md +4 -4
- package/docs/providers.md +12 -12
- package/docs/quickstart.md +32 -32
- package/docs/rpc.md +83 -12
- package/docs/sdk.md +15 -15
- package/docs/security.md +18 -18
- package/docs/session-format.md +35 -13
- package/docs/sessions.md +17 -14
- package/docs/settings.md +25 -18
- package/docs/shell-aliases.md +2 -2
- package/docs/skills.md +12 -11
- package/docs/terminal-setup.md +12 -12
- package/docs/termux.md +6 -6
- package/docs/themes.md +11 -11
- package/docs/tmux.md +4 -4
- package/docs/tui.md +5 -5
- package/docs/usage.md +50 -50
- package/docs/windows.md +2 -2
- package/examples/extensions/overlay-qa-tests.ts +3 -3
- package/hooks/gsd/draht-quality-gate.js +3 -3
- package/package.json +11 -10
- package/prompts/commands/atomic-commit.md +1 -12
- package/prompts/commands/brainstorm.md +12 -15
- package/prompts/commands/create-verification-skill.md +108 -0
- package/prompts/commands/discuss-phase.md +3 -14
- package/prompts/commands/execute-phase.md +3 -11
- package/prompts/commands/fix.md +41 -18
- package/prompts/commands/grill.md +66 -0
- package/prompts/commands/init-project.md +5 -15
- package/prompts/commands/map-codebase.md +1 -13
- package/prompts/commands/new-project.md +5 -15
- package/prompts/commands/next-milestone.md +1 -13
- package/prompts/commands/orchestrate.md +1 -1
- package/prompts/commands/pause-work.md +1 -13
- package/prompts/commands/plan-phase.md +2 -11
- package/prompts/commands/progress.md +0 -13
- package/prompts/commands/quick.md +3 -11
- package/prompts/commands/resolve-conflicts.md +71 -0
- package/prompts/commands/resume-work.md +0 -13
- package/prompts/commands/review.md +4 -13
- package/prompts/commands/triage.md +159 -0
- package/prompts/commands/verify-work.md +4 -14
- package/prompts/commands/why.md +135 -0
- package/skills/atomic-reasoning/SKILL.md +115 -0
- package/skills/blast-radius/SKILL.md +55 -0
- package/skills/epistemics/SKILL.md +99 -0
- package/skills/hexagon-animation/SKILL.md +49 -0
- package/skills/hexagon-animation/generate.mjs +81 -0
- package/skills/hexagon-animation/template.html +361 -0
- package/skills/typescript-discipline/SKILL.md +50 -0
- package/skills/typescript-discipline/references/patterns.md +294 -0
- package/skills/unslop/SKILL.md +101 -0
- package/dist/prompts/agents/build.md +0 -86
- package/dist/prompts/agents/plan.md +0 -79
- package/dist/prompts/agents/verify.md +0 -69
- package/prompts/agents/build.md +0 -86
- package/prompts/agents/plan.md +0 -79
- package/prompts/agents/verify.md +0 -69
|
@@ -0,0 +1,361 @@
|
|
|
1
|
+
<!doctype html>
|
|
2
|
+
<html lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="utf-8" />
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
6
|
+
<title>hexagon flow</title>
|
|
7
|
+
<style>
|
|
8
|
+
html, body { margin: 0; padding: 0; height: 100%; background: #000; overflow: hidden; }
|
|
9
|
+
canvas { display: block; width: 100vw; height: 100vh; }
|
|
10
|
+
#hud {
|
|
11
|
+
position: fixed; left: 12px; bottom: 10px;
|
|
12
|
+
font: 11px/1.4 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
|
|
13
|
+
color: rgba(255, 255, 255, 0.35); user-select: none; pointer-events: none;
|
|
14
|
+
letter-spacing: 0.04em;
|
|
15
|
+
}
|
|
16
|
+
</style>
|
|
17
|
+
</head>
|
|
18
|
+
<body>
|
|
19
|
+
<canvas id="c"></canvas>
|
|
20
|
+
<div id="hud"></div>
|
|
21
|
+
<script>
|
|
22
|
+
"use strict";
|
|
23
|
+
|
|
24
|
+
// Config baked in by generate.mjs. Any field may be omitted; URL params win over
|
|
25
|
+
// baked values, and everything left unset is randomized per page load.
|
|
26
|
+
// Fields: { seed, palette, radius, speed }
|
|
27
|
+
const BAKED_CONFIG = /*__CONFIG__*/ null /*__END_CONFIG__*/;
|
|
28
|
+
|
|
29
|
+
// ── seeded rng ──────────────────────────────────────────────────────────────
|
|
30
|
+
function mulberry32(a) {
|
|
31
|
+
return function () {
|
|
32
|
+
a |= 0;
|
|
33
|
+
a = (a + 0x6d2b79f5) | 0;
|
|
34
|
+
let t = Math.imul(a ^ (a >>> 15), 1 | a);
|
|
35
|
+
t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
|
|
36
|
+
return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
|
|
37
|
+
};
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
// ── palettes ────────────────────────────────────────────────────────────────
|
|
41
|
+
const PALETTES = [
|
|
42
|
+
{ name: "abyss", bg0: "#04060c", bg1: "#0a1226", low: "#122c4d", high: "#6ee7ff", glow: "#aef4ff" },
|
|
43
|
+
{ name: "magma", bg0: "#0a0404", bg1: "#1c0909", low: "#43110e", high: "#ffab4a", glow: "#ffd9a0" },
|
|
44
|
+
{ name: "acid", bg0: "#040805", bg1: "#0a1a0f", low: "#12381f", high: "#a8ff6b", glow: "#dcffb8" },
|
|
45
|
+
{ name: "synth", bg0: "#0a0512", bg1: "#180b2e", low: "#3a1560", high: "#ff6ec7", glow: "#ffb3e2" },
|
|
46
|
+
{ name: "royal", bg0: "#04050f", bg1: "#0b0f2b", low: "#1a2470", high: "#93a6ff", glow: "#ccd6ff" },
|
|
47
|
+
{ name: "ember", bg0: "#080505", bg1: "#170d08", low: "#3c1a08", high: "#ff5c3d", glow: "#ffb59e" },
|
|
48
|
+
{ name: "mono", bg0: "#050505", bg1: "#101010", low: "#232323", high: "#f2f2f2", glow: "#ffffff" },
|
|
49
|
+
{ name: "teal", bg0: "#030808", bg1: "#082020", low: "#0d4242", high: "#4affd0", glow: "#c2ffee" },
|
|
50
|
+
];
|
|
51
|
+
|
|
52
|
+
function hexToRgb(h) {
|
|
53
|
+
const n = parseInt(h.slice(1), 16);
|
|
54
|
+
return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
|
|
55
|
+
}
|
|
56
|
+
function lerpRgb(a, b, t) {
|
|
57
|
+
return [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, a[2] + (b[2] - a[2]) * t];
|
|
58
|
+
}
|
|
59
|
+
function shade(c, f) {
|
|
60
|
+
return [c[0] * f, c[1] * f, c[2] * f];
|
|
61
|
+
}
|
|
62
|
+
function css(c, alpha) {
|
|
63
|
+
return "rgba(" + (c[0] | 0) + "," + (c[1] | 0) + "," + (c[2] | 0) + "," + (alpha === undefined ? 1 : alpha) + ")";
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
// ── parameters (baked config < url params, everything else from seed) ───────
|
|
67
|
+
const params = new URLSearchParams(location.search);
|
|
68
|
+
function pick(key) {
|
|
69
|
+
const raw = params.get(key);
|
|
70
|
+
if (raw !== null && raw !== "" && Number.isFinite(Number(raw))) return Number(raw);
|
|
71
|
+
if (BAKED_CONFIG && Number.isFinite(BAKED_CONFIG[key])) return BAKED_CONFIG[key];
|
|
72
|
+
return undefined;
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
let seed = pick("seed");
|
|
76
|
+
if (seed === undefined) seed = (Math.random() * 0xffffffff) >>> 0;
|
|
77
|
+
seed = seed >>> 0;
|
|
78
|
+
|
|
79
|
+
let world = null;
|
|
80
|
+
|
|
81
|
+
function buildWorld() {
|
|
82
|
+
const rng = mulberry32(seed);
|
|
83
|
+
|
|
84
|
+
const paletteIndex =
|
|
85
|
+
pick("palette") !== undefined
|
|
86
|
+
? ((pick("palette") | 0) % PALETTES.length + PALETTES.length) % PALETTES.length
|
|
87
|
+
: (rng() * PALETTES.length) | 0;
|
|
88
|
+
|
|
89
|
+
const radius = Math.max(3, Math.min(16, pick("radius") !== undefined ? pick("radius") | 0 : 6 + ((rng() * 5) | 0)));
|
|
90
|
+
const speedScale = pick("speed") !== undefined ? pick("speed") : 0.75 + rng() * 0.7;
|
|
91
|
+
|
|
92
|
+
// hex grid, flat-top axial coordinates
|
|
93
|
+
const cells = [];
|
|
94
|
+
for (let q = -radius; q <= radius; q++) {
|
|
95
|
+
for (let r = -radius; r <= radius; r++) {
|
|
96
|
+
if (Math.abs(q + r) > radius) continue;
|
|
97
|
+
const x = 1.5 * q;
|
|
98
|
+
const y = Math.sqrt(3) * (r + q / 2);
|
|
99
|
+
cells.push({ q, r, x, y });
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
const w = {
|
|
104
|
+
rng,
|
|
105
|
+
radius,
|
|
106
|
+
cells,
|
|
107
|
+
palette: PALETTES[paletteIndex],
|
|
108
|
+
paletteIndex,
|
|
109
|
+
// camera
|
|
110
|
+
theta0: rng() * Math.PI * 2,
|
|
111
|
+
rotSpeed: (rng() * 2 - 1) * 0.045 * speedScale,
|
|
112
|
+
// geometry
|
|
113
|
+
gap: 0.86 + rng() * 0.1,
|
|
114
|
+
zFactor: 0.9,
|
|
115
|
+
baseH: 0.55 + rng() * 0.4,
|
|
116
|
+
amp: 1.4 + rng() * 1.9,
|
|
117
|
+
// noise field
|
|
118
|
+
noiseFreq: 0.3 + rng() * 0.35,
|
|
119
|
+
noiseSpeed: (0.28 + rng() * 0.45) * speedScale,
|
|
120
|
+
noiseMix: 0.55 + rng() * 0.3,
|
|
121
|
+
// traveling wave
|
|
122
|
+
waveAngle: rng() * Math.PI * 2,
|
|
123
|
+
waveK: 0.35 + rng() * 0.6,
|
|
124
|
+
waveSpeed: (0.7 + rng() * 1.1) * speedScale,
|
|
125
|
+
// light
|
|
126
|
+
lightAngle: rng() * Math.PI * 2,
|
|
127
|
+
};
|
|
128
|
+
w.waveMix = 1 - w.noiseMix;
|
|
129
|
+
w.lo = hexToRgb(w.palette.low);
|
|
130
|
+
w.hi = hexToRgb(w.palette.high);
|
|
131
|
+
w.glow = hexToRgb(w.palette.glow);
|
|
132
|
+
w.light = [Math.cos(w.lightAngle) * 0.8, Math.sin(w.lightAngle) * 0.8, 0.6];
|
|
133
|
+
const ll = Math.hypot(w.light[0], w.light[1], w.light[2]);
|
|
134
|
+
w.light = w.light.map((v) => v / ll);
|
|
135
|
+
// max center distance from origin, used to fit the grid on screen at any rotation
|
|
136
|
+
w.extent = radius * Math.sqrt(3) + 2;
|
|
137
|
+
return w;
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
// ── value noise (3d, seeded) ────────────────────────────────────────────────
|
|
141
|
+
function hash3(ix, iy, iz) {
|
|
142
|
+
let h = (ix * 374761393 + iy * 668265263 + iz * 1440662683 + (seed | 0) * 974711) | 0;
|
|
143
|
+
h = Math.imul(h ^ (h >>> 13), 1274126177);
|
|
144
|
+
h ^= h >>> 16;
|
|
145
|
+
return (h >>> 0) / 4294967295;
|
|
146
|
+
}
|
|
147
|
+
function smooth(t) {
|
|
148
|
+
return t * t * (3 - 2 * t);
|
|
149
|
+
}
|
|
150
|
+
function noise3(x, y, z) {
|
|
151
|
+
const ix = Math.floor(x), iy = Math.floor(y), iz = Math.floor(z);
|
|
152
|
+
const fx = smooth(x - ix), fy = smooth(y - iy), fz = smooth(z - iz);
|
|
153
|
+
let v = 0;
|
|
154
|
+
for (let dz = 0; dz <= 1; dz++) {
|
|
155
|
+
for (let dy = 0; dy <= 1; dy++) {
|
|
156
|
+
for (let dx = 0; dx <= 1; dx++) {
|
|
157
|
+
const wgt =
|
|
158
|
+
(dx ? fx : 1 - fx) * (dy ? fy : 1 - fy) * (dz ? fz : 1 - fz);
|
|
159
|
+
v += wgt * hash3(ix + dx, iy + dy, iz + dz);
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
return v;
|
|
164
|
+
}
|
|
165
|
+
function fbm3(x, y, z) {
|
|
166
|
+
let v = 0, a = 0.55, f = 1, sum = 0;
|
|
167
|
+
for (let i = 0; i < 3; i++) {
|
|
168
|
+
v += a * noise3(x * f, y * f, z * f);
|
|
169
|
+
sum += a;
|
|
170
|
+
a *= 0.5;
|
|
171
|
+
f *= 2.03;
|
|
172
|
+
}
|
|
173
|
+
return v / sum;
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
// ── rendering ───────────────────────────────────────────────────────────────
|
|
177
|
+
const canvas = document.getElementById("c");
|
|
178
|
+
const ctx = canvas.getContext("2d");
|
|
179
|
+
const hud = document.getElementById("hud");
|
|
180
|
+
|
|
181
|
+
let W = 0, H = 0, DPR = 1;
|
|
182
|
+
function resize() {
|
|
183
|
+
DPR = Math.min(2, window.devicePixelRatio || 1);
|
|
184
|
+
W = window.innerWidth;
|
|
185
|
+
H = window.innerHeight;
|
|
186
|
+
canvas.width = Math.round(W * DPR);
|
|
187
|
+
canvas.height = Math.round(H * DPR);
|
|
188
|
+
}
|
|
189
|
+
window.addEventListener("resize", resize);
|
|
190
|
+
resize();
|
|
191
|
+
|
|
192
|
+
const ISO_X = Math.cos(Math.PI / 6); // 0.866
|
|
193
|
+
const ISO_Y = 0.5;
|
|
194
|
+
|
|
195
|
+
function heightAt(w, x, y, t) {
|
|
196
|
+
const n = fbm3(x * w.noiseFreq, y * w.noiseFreq, t * w.noiseSpeed);
|
|
197
|
+
const wave =
|
|
198
|
+
0.5 + 0.5 * Math.sin((x * Math.cos(w.waveAngle) + y * Math.sin(w.waveAngle)) * w.waveK - t * w.waveSpeed);
|
|
199
|
+
return w.baseH + w.amp * (n * w.noiseMix + wave * w.waveMix);
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
let t = 0;
|
|
203
|
+
let last = performance.now();
|
|
204
|
+
let paused = false;
|
|
205
|
+
|
|
206
|
+
function frame(now) {
|
|
207
|
+
const dt = Math.min(0.05, (now - last) / 1000);
|
|
208
|
+
last = now;
|
|
209
|
+
if (!paused) t += dt;
|
|
210
|
+
|
|
211
|
+
const w = world;
|
|
212
|
+
const theta = w.theta0 + w.rotSpeed * t;
|
|
213
|
+
const cosT = Math.cos(theta), sinT = Math.sin(theta);
|
|
214
|
+
|
|
215
|
+
// fit grid to screen for any rotation angle
|
|
216
|
+
const maxH = w.baseH + w.amp;
|
|
217
|
+
const S = Math.min(
|
|
218
|
+
(W * 0.92) / (2 * Math.SQRT2 * ISO_X * w.extent),
|
|
219
|
+
(H * 0.88) / (Math.SQRT2 * w.extent + maxH * w.zFactor),
|
|
220
|
+
);
|
|
221
|
+
const zS = S * w.zFactor;
|
|
222
|
+
const cx = W / 2;
|
|
223
|
+
const cy = H * 0.55;
|
|
224
|
+
|
|
225
|
+
ctx.setTransform(DPR, 0, 0, DPR, 0, 0);
|
|
226
|
+
|
|
227
|
+
// background
|
|
228
|
+
const bg = ctx.createRadialGradient(cx, cy * 0.8, 0, cx, cy * 0.8, Math.max(W, H) * 0.75);
|
|
229
|
+
bg.addColorStop(0, w.palette.bg1);
|
|
230
|
+
bg.addColorStop(1, w.palette.bg0);
|
|
231
|
+
ctx.fillStyle = bg;
|
|
232
|
+
ctx.fillRect(0, 0, W, H);
|
|
233
|
+
|
|
234
|
+
// shared rotated corner directions (flat-top hexagon) + screen offsets
|
|
235
|
+
const corners = [];
|
|
236
|
+
for (let i = 0; i < 6; i++) {
|
|
237
|
+
const a = (Math.PI / 3) * i;
|
|
238
|
+
const dx = Math.cos(a) * w.gap, dy = Math.sin(a) * w.gap;
|
|
239
|
+
const rx = dx * cosT - dy * sinT;
|
|
240
|
+
const ry = dx * sinT + dy * cosT;
|
|
241
|
+
corners.push({
|
|
242
|
+
sx: (rx - ry) * ISO_X * S,
|
|
243
|
+
sy: (rx + ry) * ISO_Y * S,
|
|
244
|
+
normalAngle: a + Math.PI / 6, // outward normal of edge i -> i+1, before rotation
|
|
245
|
+
});
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
// polygon centroid is 0,0; outward screen normal of edge i is away from origin
|
|
249
|
+
const edges = [];
|
|
250
|
+
for (let i = 0; i < 6; i++) {
|
|
251
|
+
const a = corners[i], b = corners[(i + 1) % 6];
|
|
252
|
+
const ex = b.sx - a.sx, ey = b.sy - a.sy;
|
|
253
|
+
let nx = ey, ny = -ex;
|
|
254
|
+
const mx = (a.sx + b.sx) / 2, my = (a.sy + b.sy) / 2;
|
|
255
|
+
if (nx * mx + ny * my < 0) { nx = -nx; ny = -ny; }
|
|
256
|
+
const na = a.normalAngle + theta;
|
|
257
|
+
const n3 = [Math.cos(na), Math.sin(na), 0];
|
|
258
|
+
const lambert = Math.max(0, n3[0] * w.light[0] + n3[1] * w.light[1]);
|
|
259
|
+
edges.push({ i, visible: ny > 0, shade: 0.22 + 0.5 * lambert });
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
// project and depth sort
|
|
263
|
+
const drawList = [];
|
|
264
|
+
for (const cell of w.cells) {
|
|
265
|
+
const rx = cell.x * cosT - cell.y * sinT;
|
|
266
|
+
const ry = cell.x * sinT + cell.y * cosT;
|
|
267
|
+
const h = heightAt(w, cell.x, cell.y, t);
|
|
268
|
+
drawList.push({
|
|
269
|
+
sx: cx + (rx - ry) * ISO_X * S,
|
|
270
|
+
sy: cy + (rx + ry) * ISO_Y * S,
|
|
271
|
+
depth: rx + ry,
|
|
272
|
+
h,
|
|
273
|
+
});
|
|
274
|
+
}
|
|
275
|
+
drawList.sort((a, b) => a.depth - b.depth);
|
|
276
|
+
|
|
277
|
+
const hRange = w.amp;
|
|
278
|
+
for (const d of drawList) {
|
|
279
|
+
const topY = d.sy - d.h * zS;
|
|
280
|
+
const hNorm = Math.max(0, Math.min(1, (d.h - w.baseH) / hRange));
|
|
281
|
+
const topColor = lerpRgb(w.lo, w.hi, hNorm);
|
|
282
|
+
|
|
283
|
+
// side faces (screen extrusion is straight down, so only "downward" edges show)
|
|
284
|
+
for (const e of edges) {
|
|
285
|
+
if (!e.visible) continue;
|
|
286
|
+
const a = corners[e.i], b = corners[(e.i + 1) % 6];
|
|
287
|
+
ctx.beginPath();
|
|
288
|
+
ctx.moveTo(d.sx + a.sx, topY + a.sy);
|
|
289
|
+
ctx.lineTo(d.sx + b.sx, topY + b.sy);
|
|
290
|
+
ctx.lineTo(d.sx + b.sx, d.sy + b.sy);
|
|
291
|
+
ctx.lineTo(d.sx + a.sx, d.sy + a.sy);
|
|
292
|
+
ctx.closePath();
|
|
293
|
+
ctx.fillStyle = css(shade(topColor, e.shade));
|
|
294
|
+
ctx.fill();
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
// top face
|
|
298
|
+
ctx.beginPath();
|
|
299
|
+
ctx.moveTo(d.sx + corners[0].sx, topY + corners[0].sy);
|
|
300
|
+
for (let i = 1; i < 6; i++) ctx.lineTo(d.sx + corners[i].sx, topY + corners[i].sy);
|
|
301
|
+
ctx.closePath();
|
|
302
|
+
ctx.fillStyle = css(shade(topColor, 0.9 + 0.35 * hNorm));
|
|
303
|
+
ctx.fill();
|
|
304
|
+
|
|
305
|
+
// glow rim on the tallest cells
|
|
306
|
+
if (hNorm > 0.62) {
|
|
307
|
+
ctx.strokeStyle = css(w.glow, (hNorm - 0.62) * 1.6);
|
|
308
|
+
ctx.lineWidth = 1;
|
|
309
|
+
ctx.lineJoin = "round";
|
|
310
|
+
ctx.stroke();
|
|
311
|
+
}
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
requestAnimationFrame(frame);
|
|
315
|
+
}
|
|
316
|
+
|
|
317
|
+
// ── controls ────────────────────────────────────────────────────────────────
|
|
318
|
+
function updateHud() {
|
|
319
|
+
hud.textContent =
|
|
320
|
+
"seed " + seed + " \u00b7 " + world.palette.name + " \u00b7 [r]eseed [p]alette [space] pause";
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
function setUrl() {
|
|
324
|
+
const u = new URLSearchParams(location.search);
|
|
325
|
+
u.set("seed", String(seed));
|
|
326
|
+
u.set("palette", String(world.paletteIndex));
|
|
327
|
+
history.replaceState(null, "", "?" + u.toString());
|
|
328
|
+
}
|
|
329
|
+
|
|
330
|
+
function reseed() {
|
|
331
|
+
seed = (Math.random() * 0xffffffff) >>> 0;
|
|
332
|
+
params.delete("palette");
|
|
333
|
+
if (BAKED_CONFIG) delete BAKED_CONFIG.palette;
|
|
334
|
+
params.delete("seed");
|
|
335
|
+
if (BAKED_CONFIG) delete BAKED_CONFIG.seed;
|
|
336
|
+
world = buildWorld();
|
|
337
|
+
setUrl();
|
|
338
|
+
updateHud();
|
|
339
|
+
}
|
|
340
|
+
|
|
341
|
+
window.addEventListener("keydown", (ev) => {
|
|
342
|
+
if (ev.key === "r" || ev.key === "R") reseed();
|
|
343
|
+
else if (ev.key === "p" || ev.key === "P") {
|
|
344
|
+
params.set("palette", String((world.paletteIndex + 1) % PALETTES.length));
|
|
345
|
+
world = buildWorld();
|
|
346
|
+
setUrl();
|
|
347
|
+
updateHud();
|
|
348
|
+
} else if (ev.key === " ") {
|
|
349
|
+
paused = !paused;
|
|
350
|
+
ev.preventDefault();
|
|
351
|
+
}
|
|
352
|
+
});
|
|
353
|
+
canvas.addEventListener("pointerdown", reseed);
|
|
354
|
+
|
|
355
|
+
world = buildWorld();
|
|
356
|
+
setUrl();
|
|
357
|
+
updateHud();
|
|
358
|
+
requestAnimationFrame(frame);
|
|
359
|
+
</script>
|
|
360
|
+
</body>
|
|
361
|
+
</html>
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: typescript-discipline
|
|
3
|
+
description: TypeScript type-system discipline — make illegal states unrepresentable with discriminated unions, build types constructively instead of guarding loose ones, brand semantic primitives, parse external data once at the boundary and trust types inside, keep functions total and strengthen a type only where partiality appears, make the compiler enforce exhaustiveness. Use when reading or editing any .ts or .tsx file, designing a type or function signature, reviewing a TypeScript diff, or deciding whether an `any`, an `as` cast, or a non-null `!` is acceptable.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# TypeScript Discipline
|
|
7
|
+
|
|
8
|
+
The type checker is a proof assistant. Used well, it eliminates impossible states, mismatched primitives, and unhandled variants at compile time; every case the types let you ignore is a runtime failure the compiler could have stopped. Prefer defining errors out of existence over proliferating handlers — unrepresentable states, total functions, and boundary parsing are the tools for that.
|
|
9
|
+
|
|
10
|
+
Two layers: the principles below hold in any statically-typed language; the rule table and `./references/patterns.md` ground them in TypeScript syntax.
|
|
11
|
+
|
|
12
|
+
## Principles
|
|
13
|
+
|
|
14
|
+
- **Make illegal states unrepresentable.** Model variants as a discriminated union, not as a bag of optional fields where contradictory combinations compile. The canonical anti-pattern: `{ completed: boolean; completedAt?: Date }` admits `completed: true` with `completedAt: undefined`, which means nothing. Derive the boolean from a single source (`completedAt !== null`) or model the variants explicitly: `{ kind: 'open' } | { kind: 'done'; at: Date }`. If a bug ever forces the question "wait, can this combination actually happen?", the type is too loose.
|
|
15
|
+
- **Types are constructions, not restrictions.** Build the type up from the values you want instead of carving them out of a looser type with runtime checks. A non-empty list is a head plus a rest, not a list with a length check. A valid time range is a start plus a duration, not two timestamps you must keep ordered. No representation is privileged — pick the shape that cannot build the illegal value, then expose the interface callers need on top of it.
|
|
16
|
+
- **Brand semantic primitives.** A `UserId` and an `OrderId` are both strings underneath but must not be interchangeable. Brand them, validate once at creation, trust the type downstream.
|
|
17
|
+
- **External data is untyped until parsed.** RPC payloads, JSON, CLI args, config files, environment variables, database rows: each gets a parse function at the boundary that turns unstructured input into the typed domain model. Validation lives at that boundary, once — inside the system there is typed data, no re-validation deep in call chains, and business logic in pure functions the boundary shell calls.
|
|
18
|
+
- **Don't lie to the compiler.** Casts and assertions that bypass the checker are runtime crashes waiting to happen. If the compiler can't prove a fact, prove it — validate, narrow, refine the model — or accept that the cast is a hazard you are choosing to carry. The cast buried today is the postmortem written next week.
|
|
19
|
+
- **Exhaustive matching is the compiler's job.** A match over a sum type must fail compilation when a new variant is added without a case, so the compiler tells the next author every place that needs updating.
|
|
20
|
+
- **Derive types from authoritative schemas.** When a protocol buffer, OpenAPI spec, GraphQL schema, or database migration already defines a shape, derive from it instead of hand-rolling a parallel type. Manual duplication drifts.
|
|
21
|
+
- **Strengthen a type only where partiality appears.** A runtime assertion, a null check, or a "should never happen" throw marks the spot where a type is too weak — push that check up into the type, then stop. The type system's job is to track the cases each use site must handle, not to describe the data as precisely as possible. `sum` of an empty list is 0, so it takes the plain list; `head` of an empty list has no answer, so it demands the non-empty one. Extra precision beyond totality costs reuse and ceremony and buys no safety.
|
|
22
|
+
|
|
23
|
+
## Rules (TypeScript syntax)
|
|
24
|
+
|
|
25
|
+
| Rule | Summary |
|
|
26
|
+
|------|---------|
|
|
27
|
+
| Discriminated unions | Model variants with a `kind` literal discriminant so impossible states can't be represented. No optional-field bags. |
|
|
28
|
+
| Branded types | Brand primitives with `& { readonly __brand: "X" }` so they can't be mixed up. Validate once at creation. |
|
|
29
|
+
| Constructive modeling | Build the shape so the illegal value can't be constructed: `[T, ...T[]]` for non-empty, `[T, T][]` for even length, `start` plus `duration` for a range. Not a runtime guard, not a wish for refinement types. |
|
|
30
|
+
| Simplest total type | Keep `T[]` while every operation on it stays total. Strengthen to a non-empty type only where the loose type forces a `!`, a cast, or a "should never happen" throw. |
|
|
31
|
+
| `unknown` over `any` | External data is `unknown`. `any` disables type checking everywhere it touches. |
|
|
32
|
+
| No `as` casts | Every `as` is a potential runtime crash. Cast only after validation has earned it. |
|
|
33
|
+
| Narrowing hierarchy | Discriminant switch > `in` operator > `typeof`/`instanceof` > user-defined type guard > `as`. |
|
|
34
|
+
| Type guards | Must verify the claim. A lying guard is worse than `as` — the bug hides behind a name that says it's safe. Name them `isX` or `hasX`. |
|
|
35
|
+
| Exhaustiveness | Assign to a `never`-typed local in default arms so the compiler errors when a new variant is added. |
|
|
36
|
+
| `satisfies` over `as` | Validates the value without widening literal types. |
|
|
37
|
+
| Boundary validation | Parse where data crosses in — into a named domain type, once. `Record<string, unknown>` (however spelled) stops at that parse. Inside: trust the types, no redundant re-validation, logic in pure functions the boundary shell calls. |
|
|
38
|
+
| Schema-derived types | Reach for `Pick`/`Omit`/`Parameters`/`ReturnType`/`Awaited`/`typeof` before declaring a new interface. |
|
|
39
|
+
| Object args | Pass objects, not positional arguments, so call sites are self-documenting. Skip on hot paths (per-frame render, tokenizers, parsers). |
|
|
40
|
+
|
|
41
|
+
Worked don't/do examples for every rule: `./references/patterns.md`.
|
|
42
|
+
|
|
43
|
+
## Self-Checks
|
|
44
|
+
|
|
45
|
+
- "Can I write a comment explaining when this combination of fields is valid?" If yes, the type is too loose — split it into a discriminated union.
|
|
46
|
+
- "Do two function arguments share a primitive type but mean different things?" Brand them.
|
|
47
|
+
- "Where did this `any`, this `as`, this `!` come from?" Trace it to the boundary and validate there instead.
|
|
48
|
+
- "If a new variant is added next month, will the compiler point at every place that needs a case?" If not, the match isn't exhaustive.
|
|
49
|
+
- "Is this type duplicating a shape another file or schema owns?" Derive instead.
|
|
50
|
+
- "Am I strengthening this type to keep an operation total, or just to be more precise?" If nothing would otherwise throw, keep the plain type.
|