Skip to content

Commit 28c8809

Browse files
committed
chore: dead-code cleanup and hardening (v0.1.16)
- Fix bin/df profile positional parsing bug. - Remove dead config-to-opencode generator code; move shared command parsing helpers to src/command-utils.ts. - Consolidate DEFAULT_PROTECT constant. - Scrub stale commands/ directory references from docs, README, checklists. - Fix silent guardrail/gate no-ops: add baseDirectory fallback and getStateForSession; fail closed when hook state is missing. - Harden injectConstitution to append to the last system-prompt entry. - Capture host permissions in config hook and respect host-level denies. - Add /df-help slash command and unknown /df-* command handling. - Validate config on load; show TUI toast on parse error. - Add optional OPENCODE_DEV_FRAMEWORK_LOG_FILE debug logging. - Sync AGENTS.md, architecture, config-spec, hook-mapping, restart brief, master plan, testing strategy, and example config with current code. - Add tests/command-utils.test.ts for shared command parsing helpers.
1 parent 80fe6ff commit 28c8809

31 files changed

Lines changed: 507 additions & 351 deletions

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -117,8 +117,8 @@ OpenCode loads the plugin via Bun at runtime, but all development and CI on this
117117
opencode-dev-framework/
118118
├── src/ # Plugin source code
119119
│ ├── index.ts # Plugin entry point
120+
│ ├── command-utils.ts # Shared command parsing helpers
120121
│ ├── config.ts # Config loader
121-
│ ├── config-to-opencode.ts # OpenCode settings generator
122122
│ ├── detect.ts # Project language/tooling auto-detection
123123
│ ├── protect.ts # Guardrail logic
124124
│ ├── lint.ts # Per-edit lint runner

‎README.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ reimplemented as an OpenCode-native plugin.
2424
(up to `gate.max_blocks` times) so the agent must fix the failures. In older
2525
versions the gate reports loudly via `session.idle`.
2626
- **Custom tools.** `dev_framework_init` scaffolds project-level agents,
27-
skills, commands, and config; `dev_framework_set_profile` changes the profile
27+
skills, local rules directory, and config; `dev_framework_set_profile` changes the profile
2828
in-session without restarting; `dev_framework_status` reports the current
2929
profile, guardrails, gate, and tracked changed files.
3030
- **CLI installer.** `df init` auto-detects your language and writes a config
@@ -193,6 +193,12 @@ npm run test
193193
npm run build
194194
```
195195

196+
For persistent debug traces, set `OPENCODE_DEV_FRAMEWORK_LOG_FILE`:
197+
198+
```bash
199+
OPENCODE_DEV_FRAMEWORK_LOG_FILE=/tmp/odf.log opencode run
200+
```
201+
196202
See `AGENTS.md` and `docs/plans/` for the architecture and implementation
197203
plan.
198204

‎bin/df‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
#!/usr/bin/env node
22
// df — opencode-dev-framework CLI installer.
3-
// Scaffold project-level agents, skills, commands, and config into a repo.
3+
// Scaffold project-level agents, skills, local rules, and config into a repo.
44

55
import { readFile } from "node:fs/promises";
66
import { dirname, join } from "node:path";
@@ -56,6 +56,9 @@ async function main() {
5656
return;
5757
}
5858

59+
const flags = new Set(args.slice(1).filter((arg) => arg.startsWith("--")));
60+
const positional = args.slice(1).filter((arg) => !arg.startsWith("--"));
61+
5962
if (command === "profile") {
6063
const profile = positional[0];
6164
const profileDir = resolveTargetDir(positional[1]);
@@ -79,8 +82,6 @@ async function main() {
7982
return;
8083
}
8184

82-
const flags = new Set(args.slice(1).filter((arg) => arg.startsWith("--")));
83-
const positional = args.slice(1).filter((arg) => !arg.startsWith("--"));
8485
const targetDir = resolveTargetDir(positional[0]);
8586

8687
if (command === "init" && flags.has("--skip-existing") && flags.has("--overwrite-existing")) {

‎docs/plans/00-restart-brief.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Use this file to get back up to speed in a new session.
66

77
- **Name:** `opencode-dev-framework`
88
- **Local path:** `~/opencode-dev-framework`
9-
- **GitHub repo:** `github.com/<user>/opencode-dev-framework` (push the local repo when ready)
9+
- **GitHub repo:** `github.com/jwitmann/opencode-dev-framework` (push the local repo when ready)
1010
- **npm package:** `opencode-dev-framework`
1111
- **License:** MIT
1212
- **Inspiration:** `anticomputer/dev-framework` (GitHub Copilot CLI plugin). This is an independent, OpenCode-native implementation.

‎docs/plans/01-master-plan.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,8 @@ Initialize npm/TypeScript project, CI, directory structure, and basic build/test
6262

6363
### Phase 2 — Core plugin
6464

65-
Implement config loading, native OpenCode settings generation, guardrail hooks, per-edit lint hook, completion gate, and constitution injection.
65+
Implement config loading, guardrail hooks, per-edit lint hook, completion gate,
66+
constitution injection, and the `df` CLI for scaffolding and profile switching.
6667

6768
### Phase 3 — Tests & docs
6869

‎docs/plans/02-architecture.md‎

Lines changed: 16 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -52,17 +52,18 @@ The package may export a single default plugin or multiple named plugins. Use on
5252

5353
| Module | Responsibility |
5454
|---|---|
55+
| `src/command-utils.ts` | Shared command parsing helpers (tokenize commands, normalize per-extension command maps). |
5556
| `src/config.ts` | Load and merge `.opencode-dev-framework.yml` and `.dev-framework.yml`, resolve profile defaults, validate with Zod. |
56-
| `src/config-to-opencode.ts` | Helper that translates framework config into OpenCode-native-style `permission` / `formatter` fragments. The plugin does **not** inject these automatically (it enforces guardrails in `tool.execute.before` and does not rewrite `opencode.json`); the fragments are available for users who want to copy them manually. |
5757
| `src/detect.ts` | Detect the project's language and tooling from root files for `df init`. |
5858
| `src/protect.ts` | Implement `tool.execute.before` guardrails for protected paths and dangerous commands. |
5959
| `src/lint.ts` | Implement per-edit checks on `file.edited`, with optional `pre-commit` fallback. |
6060
| `src/gate.ts` | Implement the completion gate and changed-file tracking. |
6161
| `src/rules.ts` | Load and inject constitution / project rules via `experimental.chat.system.transform`. |
6262
| `src/tools.ts` | Custom tools (`dev_framework_init`, `dev_framework_set_profile`, `dev_framework_status`). |
63-
| `src/registry.ts` | Module-level hook state registry (avoids closure-capture issues in OpenCode's Effect runtime). |
63+
| `src/registry.ts` | Module-level hook state registry (avoids closure-capture issues in OpenCode's Effect runtime). Captures base directory and host permission snapshots. |
64+
| `src/format-status.ts` | Shared status renderer for `dev_framework_status` tool and `/df-status` slash command. |
6465
| `src/installer.ts` | Template copy and detected-config generation used by `bin/df` and the `dev_framework_init` tool. |
65-
| `src/logger.ts` | Structured logging wrapper around `client.app.log()`. |
66+
| `src/logger.ts` | Structured logging wrapper around `client.app.log()` with optional file fallback. |
6667
| `src/types.ts` | Shared TypeScript types and interfaces. |
6768

6869
## Host abstraction
@@ -101,15 +102,19 @@ opencode session starts
101102

102103
## Tool guardrails
103104

104-
Use native `permission` config as the primary defense and the plugin hook for clearer messaging:
105+
The plugin applies guardrails directly in `tool.execute.before`:
105106

106-
1. `config-to-opencode.ts` emits suggested `permission.edit` rules from `protect`
107-
globs. Users can copy these into their `opencode.json` if desired.
108-
2. `tool.execute.before` acts as a belt-and-suspenders check and throws a clearer
109-
error message when the plugin denies a call.
107+
1. `protect.ts` matches file-edit and shell tools against the configured `protect`
108+
globs and the dangerous-command list.
109+
2. The `config` hook captures the host's permission snapshot from OpenCode's
110+
effective config and stores it in hook state. When the host already denies a
111+
tool/target, the plugin skips its own block to avoid redundant or conflicting
112+
denials.
113+
3. The hook throws a clear `[opencode-dev-framework] ...` error when the plugin
114+
denies a call.
110115

111116
The plugin does not modify `opencode.json` on disk and does not contribute
112-
permissions at runtime. It applies guardrails directly in the hook.
117+
permissions at runtime.
113118

114119
## Completion gate
115120

@@ -138,6 +143,7 @@ in-memory state, so no LLM prompt interpretation is required.
138143
- `/df-profile` — switch the active profile.
139144
- `/df-status` — show the current profile, guardrails, gate, and tracked changed
140145
files.
146+
- `/df-help` — list the available slash commands.
141147

142148
The project template directory no longer contains command files; only agents,
143149
skills, and the local rules directory are copied by `df init`.
@@ -152,7 +158,7 @@ skills, and the local rules directory are copied by `df init`.
152158
{
153159
"main": "dist/index.js",
154160
"types": "dist/index.d.ts",
155-
"files": ["dist", "bin", "commands", "rules", "templates"]
161+
"files": ["dist", "bin", "rules", "templates"]
156162
}
157163
```
158164

‎docs/plans/03-config-spec.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,8 @@ Controls enforcement intensity:
2828
|---|---|---|---|
2929
| `off` | — | — | — |
3030
| `advisory` | lint feedback | runs & reports, **never blocks** | warns |
31-
| `standard` | lint feedback | **reports** failing type-check/tests | **denies** protected edits |
32-
| `strict` | lint feedback | also reports lint failures on changed files | **denies** protected edits |
31+
| `standard` | lint feedback | **blocks up to `max_blocks`** when checks fail | **denies** protected edits |
32+
| `strict` | lint feedback | also lints changed files; **blocks up to `max_blocks`** | **denies** protected edits |
3333

3434
### `commands`
3535

@@ -223,7 +223,7 @@ commands:
223223
protect:
224224
- .env*
225225
- go.sum
226-
- bin/
226+
- bin/**
227227
228228
on_edit:
229229
format: true

‎docs/plans/04-hook-mapping.md‎

Lines changed: 25 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -30,14 +30,16 @@ project directory.
3030
3. Read `rules` files, local override directory, and any auto-discovered style guides.
3131
4. Inject the concatenated rules into the system prompt.
3232

33-
### Native `permission` config (generated, not injected automatically)
33+
### Native `permission` config
3434

35-
**Purpose:** Suggest rules that block edits to protected paths and dangerous commands.
35+
**Purpose:** OpenCode's own permission model is the primary defense. The plugin
36+
reads the host's effective `permission` config at load time and respects host
37+
denies: when OpenCode already denies a tool/target, the plugin skips its own
38+
block to avoid redundant/conflicting denials.
3639

37-
**How:** The plugin does not rewrite `opencode.json` on disk and does not contribute
38-
permissions at runtime. It applies guardrails in `tool.execute.before`. Users can
39-
use `config-to-opencode.ts` to generate suggested `permission` rules and copy
40-
them into their `opencode.json` if desired.
40+
**How:** The plugin does not rewrite `opencode.json` on disk and does not
41+
contribute permissions at runtime. It applies guardrails in `tool.execute.before`
42+
and uses `command-utils.ts` helpers for command parsing.
4143

4244
### `tool.execute.before`
4345

@@ -53,6 +55,10 @@ them into their `opencode.json` if desired.
5355
- `off` profile: do nothing.
5456
- `advisory` profile: log a warning but do not throw.
5557
- `standard`/`strict` profile: throw an error with a clear message to deny the tool call.
58+
- If hook state cannot be resolved for a session, the hook fails closed (denies)
59+
rather than silently allowing the tool call.
60+
- When the host permission model already denies the tool/target, the plugin
61+
skips its own block to avoid redundant/conflicting denials.
5662

5763
### `file.edited`
5864

@@ -98,30 +104,33 @@ gate failure in `standard`/`strict`, pushes a concise synthetic user message up
98104
to `gate.max_blocks` times before standing down. `session.idle` remains the
99105
fallback on older OpenCode versions.
100106

101-
### `/df-verify`, `/df-profile`, `/df-status` custom commands
107+
### `/df-verify`, `/df-profile`, `/df-status`, `/df-help` custom commands
102108

103-
**Purpose:** Let the user run the gate on demand, switch profile, or inspect
104-
plugin state.
109+
**Purpose:** Let the user run the gate on demand, switch profile, inspect
110+
plugin state, or list commands.
105111

106112
**Definition:** registered programmatically via the `config` hook and handled in
107113
`command.execute.before`. OpenCode does not load slash commands from plugin
108114
packages, but a plugin can add them to the effective config at runtime.
109115

110116
```typescript
111117
config: async (opencodeConfig) => {
112-
(opencodeConfig as any).command ??= {};
113-
(opencodeConfig as any).command["df-status"] = {
118+
const typedConfig = opencodeConfig as { command?: Record<string, { template?: string; description?: string }> };
119+
typedConfig.command ??= {};
120+
typedConfig.command["df-status"] = {
114121
template: "",
115122
description: "Show the current dev-framework state",
116123
};
117-
// ...df-verify, df-profile
124+
// ...df-verify, df-profile, df-help
118125
},
119126
```
120127

121-
The `command.execute.before` hook looks up the session's hook state and returns
122-
the result as a text part. `/df-verify` runs `runGate` directly; `/df-profile`
123-
edits the config file, clears the cache, reloads the config, and updates the
124-
in-memory hook state; `/df-status` renders the live state.
128+
The `command.execute.before` hook looks up the session's hook state (falling
129+
back to the project `baseDirectory` when the session has not been mapped yet)
130+
and returns the result as a text part. `/df-verify` runs `runGate` directly;
131+
`/df-profile` edits the config file, clears the cache, reloads the config, and
132+
updates the in-memory hook state; `/df-status` renders the live state. Unknown
133+
`/df-*` commands return a hint to use `/df-help`.
125134

126135
**Update (v0.1.15):** migrated from markdown command templates (under
127136
`templates/.opencode/commands/`) to plugin-registered, handler-backed slash

‎docs/plans/05-implementation-checklist.md‎

Lines changed: 26 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,9 @@ Use this as the source of truth during implementation. Check items off as they a
3232
- Disable rules that conflict with Prettier/Biome if needed.
3333
- [x] 1.8 Create directory structure
3434
- `src/`
35-
- `commands/`
35+
- `bin/`
3636
- `rules/`
37+
- `templates/`
3738
- `tests/`
3839
- `examples/go-service/`
3940
- [x] 1.9 Add GitHub Actions workflow `.github/workflows/ci.yml`
@@ -125,8 +126,8 @@ Use this as the source of truth during implementation. Check items off as they a
125126
- Call gate.
126127
- On failure, emit loud structured log.
127128
- [x] 5.4 Add `/df-verify` command
128-
- Create `commands/df-verify.md`.
129-
- Optionally expose a custom tool `devFramework_verify`. (skipped — optional; see 08-notes.md)
129+
- Original plan: create `commands/df-verify.md`. Later superseded by
130+
plugin-registered slash commands (Phase 17).
130131
- [x] 5.5 Unit tests for gate
131132
- passes when all green
132133
- reports failure when test fails
@@ -198,8 +199,8 @@ Use this as the source of truth during implementation. Check items off as they a
198199
- [x] 10.1 Verify CI passes on every checklist item.
199200
- `.github/workflows/ci.yml` (Node 22) runs format, lint, lint:md,
200201
typecheck, test, and build; all pass locally. `npm pack --dry-run`
201-
confirms the published tarball contains `dist/`, `commands/`, `rules/`,
202-
`README.md`, and `LICENSE`.
202+
confirms the published tarball contains `dist/`, `bin/`, `rules/`,
203+
`templates/`, `README.md`, and `LICENSE`.
203204
- [x] 10.2 Add npm publish workflow secrets instructions to docs.
204205
- Covered by `docs/plans/07-publishing.md` (npm token + `NPM_TOKEN`
205206
GitHub secret).
@@ -295,7 +296,26 @@ Use this as the source of truth during implementation. Check items off as they a
295296
- [x] 17.4 Remove `templates/.opencode/commands/*.md` command templates.
296297
- [x] 17.5 Update README, AGENTS.md, architecture, hook mapping, installer tests.
297298
- [x] 17.6 Add tests for `config` and `command.execute.before` hooks.
298-
- [ ] 17.7 Bump version to `0.1.15` and tag.
299+
- [x] 17.7 Bump version to `0.1.15` and tag.
300+
301+
## Phase 18 — Dead-code cleanup and hardening (v0.1.16)
302+
303+
- [x] 18.1 Fix `bin/df profile` `positional` reference-order bug.
304+
- [x] 18.2 Remove dead `src/config-to-opencode.ts` generator code; move shared
305+
command parsing helpers to `src/command-utils.ts`.
306+
- [x] 18.3 Consolidate `DEFAULT_PROTECT` constant (config.ts source of truth).
307+
- [x] 18.4 Scrub stale `commands/` directory references from docs, README,
308+
checklists, and architecture snippets.
309+
- [x] 18.5 Fix silent guardrail/gate no-ops: add `baseDirectory` fallback and
310+
`getStateForSession`; fail closed when hook state is missing.
311+
- [x] 18.6 Harden `injectConstitution` to append to the last system entry and
312+
keep the prompt compact.
313+
- [x] 18.7 Capture host permissions in the `config` hook and respect host-level
314+
denies in guardrail checks.
315+
- [x] 18.8 Add `/df-help` slash command and unknown `/df-*` command response.
316+
- [x] 18.9 Validate config on load; show TUI toast on parse error; add optional
317+
`OPENCODE_DEV_FRAMEWORK_LOG_FILE` debug logging.
318+
- [ ] 18.10 Run full validation suite, bump to `v0.1.16`, commit, tag.
299319

300320
## Notes for the implementer
301321

‎docs/plans/06-testing-strategy.md‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,17 +17,20 @@ Recommendation: `vitest` because it has excellent TypeScript support and runs in
1717

1818
```text
1919
tests/
20+
├── command-utils.test.ts
21+
├── commands.test.ts
2022
├── config.test.ts
21-
├── config-to-opencode.test.ts
2223
├── detect.test.ts
24+
├── gate.test.ts
2325
├── installer.test.ts
24-
├── protect.test.ts
2526
├── lint.test.ts
26-
├── gate.test.ts
27+
├── logger.test.ts
28+
├── protect.test.ts
2729
├── rules.test.ts
30+
├── smoke.test.ts
31+
├── stopping.test.ts
2832
├── tools.test.ts
29-
├── host.test.ts
30-
└── smoke.test.ts
33+
└── (host.test.ts if host.ts grows beyond trivial spawn wrapper)
3134
```
3235

3336
## Stub host

0 commit comments

Comments
 (0)