Re-found core surfaces and source-backed docs - #9
Conversation
Turn the re-foundation spec into an execution-ready PRD and persist a tracked backlog so the architecture and docs overhaul can progress in ordered, multi-session work.
Wrap GitHub project updates in a DreamCLI/Bun helper so PRD task flows can keep project state and .opencode progress in sync without ad hoc gh commands. Document the session-start discovery rule and exact project-helper commands so future agents update the board consistently.
Support parser-only hidden flag aliases so CLI migrations can accept legacy forms without surfacing them in help, completions, suggestions, or generated schema metadata. Add build-time collision validation for canonical, local alias, and propagated alias surfaces so nested command trees fail early instead of silently shadowing conflicting flag forms.
Keep hidden long aliases in bash completion's internal parser so legacy migration flags still complete enum values and skip their operands correctly without reappearing in candidate lists.
source <(cmd completions zsh) called _arguments outside completion context because the script ended with `_funcname "$@"`. Replace with `compdef _funcname cmd` so the function is registered, not invoked.
Extract the parse, resolve, plugin, and handler pipeline into one internal executor module so later CLI and testkit routing work can share behavior without re-extracting the execution contract.
Publish the JSON Schema describing dreamcli CLI definitions so editors and validators can autocomplete and lint command trees, flags, args, prompts, and constraints against a canonical contract.
Replace hand-written enum values in the JSON meta-schema with spreads from FLAG_KINDS, ARG_KINDS, FLAG_PRESENCES, ARG_PRESENCES, and PROMPT_KINDS arrays. Adding a new kind or presence value now updates the meta-schema automatically. VitePress buildEnd hook writes the schema to dist/schemas/cli/v1.json so it's served at the documented $schema URL.
…types and runtime AST Replace hand-maintained JSON Schema $defs in the definition meta-schema with DSL string definitions parsed to AST then converted to JSON Schema. Adding or changing a schema shape now requires editing one DSL string instead of keeping type-level and runtime definitions in sync manually. The DSL supports objects, arrays, unions, literals, refs (@name), Record<K, V>, optional properties, and integer — enough to express the full CLI definition contract. Compile-time Parse<T> infers TypeScript types from the same string the runtime parser consumes.
Ship `dreamcli.schema.json` at package root with registry-specific `$id` (npm via jsdelivr, JSR via jsr.io) — detected by runtime, no flags needed. Version derived from `package.json`, `$schema` URL uses the named export path so both registries serve the same clean URL. JSR workflow no longer runs a full bun build; emits the schema directly under Deno. VitePress buildEnd hook removed — schema lives on CDN, not the docs site.
Generate raw TypeDoc JSON plus a DreamCLI-owned normalized model so future symbol pages and schema-description work can render against a stable docs seam instead of raw TypeDoc reflection shape.
Make the flag/arg shared-property decision explicit by limiting the shared resolver model to overlapping coercion kinds. This removes the fake arg-to-flag schema bridge while keeping precedence and fallback semantics separate where they genuinely differ.
Replace hand-written type comments in the arguments, flags, and middleware guides with ^? queries so the compiler renders the actual inferred types.
Brand-forward, neutral-accents, and warm-cool palettes — each with light and dark variants — to evaluate before committing to a final docs theme.
Split monolithic type-showcase snippets into per-type sections using InferArg/InferFlag helpers so the compiler renders each inferred type in its own focused block. Replace ASCII resolution charts with mermaid flowcharts and wire dark-mode-aware theming (MutationObserver re-renders on class toggle). Streamline reference-page type queries to import-line hover. Also: add vite to optionalDependencies + tsconfig types, hide copy buttons on mermaid blocks, use bash fences for CLI examples.
Set instantMove + disposeTimeout:0 on desktop so floating-vue reuses the popper instance when sliding between hover targets instead of stacking multiple open popups.
Include signatures and indexSignatures in renderMembersSection and
renderReflectionType so callable/indexed interface members render
instead of producing empty {}. Key fillMissingCommentsFromSiblings
by sourcePath to prevent cross-symbol comment collisions. Add
aria-haspopup and aria-labelledby to SettingsGear, scope Escape to
the menu component. Add dirty flag to ensureSchema so edits during
in-flight builds trigger a follow-up pass. Fix jsonMode
comment/value mismatch in testing guide.
coderabbitai
Bot
added
kind: feature
![coderabbitai[bot]](https://cdn.github.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/guide/flags.md (1)
249-271: 🧹 Nitpick | 🔵 TrivialPropagation example be functional but has an oddity!
The example demonstrates
.propagate()correctly, showing how the verbose flag be inherited by subcommands.However, ye've got an empty
// ---cut-start--- / // ---cut-end---section at lines 263-264 that be hidin' nothin'. Either fill it with somethin' to hide or remove it entirely, mate!⚓ Clean up the empty cut section
.action(({ flags, out }) => { if (flags.verbose) { out.info('Verbose mode enabled'); } }); -// ---cut-start--- -// ---cut-end--- cli('mycli').command(🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/guide/flags.md` around lines 249 - 271, The docs example contains an empty cut marker block between // ---cut-start--- and // ---cut-end--- which serves no purpose; remove those two lines or replace them with relevant hidden content. Edit the Propagation example around the command('start')/nested and cli('mycli') snippet and either delete the empty cut markers or populate them with the intended hidden code so the example is clean and consistent with .propagate() usage for the verbose flag.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/.vitepress/data/symbol-pages.ts`:
- Around line 427-437: The default value for includeDefault in renderParameter
is currently true but every caller passes false; change the default to false by
updating the function signature of renderParameter to use includeDefault = false
so callers that omit the argument behave like existing call sites, and verify
the rest-parameter handling and optional/default logic in renderParameter remain
unchanged (function name: renderParameter, parameter: includeDefault).
In `@docs/.vitepress/theme/index.ts`:
- Around line 248-269: In renderMermaidBlocks, don't set
pre.dataset['mermaidRendered'] before mermaid.default.render completes; instead
move the dataset flag assignment to after a successful render and wrap the
render call in a try/catch so failures don't leave the <pre> marked as rendered
or produce unhandled rejections; specifically, in function renderMermaidBlocks
handle await mermaid.default.render(id, source) inside a try block, only on
success create/replace the container and then set pre.dataset['mermaidRendered']
= '', and in the catch log or ignore the error and leave the original pre intact
so future runs can retry.
- Around line 181-182: The code currently points MERMAID_CDN at a floating
jsDelivr URL and types mermaidReady as Promise<typeof import('mermaid')>, which
mismatches the runtime source; change the runtime to use the pinned local
package instead by removing/ignoring MERMAID_CDN and replacing CDN fetch logic
with a dynamic import('mermaid') (or a static import if preferred) so
mermaidReady is assigned to import('mermaid') directly; update any other
occurrences that load MERMAID_CDN (including the block around mermaidReady
initialization and the similar code at lines referenced 240-245) to use the
local package import to ensure reproducible, offline- and CSP-friendly loading.
In `@docs/.vitepress/theme/settings.css`:
- Around line 13-34: The CSS-only reorder using .VPNavBar .content-body
.settings-gear (and related .appearance/.social-links/.extra) breaks keyboard
and screen-reader focus because the SettingsGear component is still mounted via
the nav-bar-content-after slot; move the SettingsGear DOM node to the correct
position in the nav bar instead of using CSS order: update the nav-bar markup
where SettingsGear is rendered (the component named SettingsGear and its mount
point nav-bar-content-after) so the gear element is placed in DOM order between
the appearance toggle and social-links, and remove the .settings-gear order rule
from settings.css to restore logical focus order.
In `@docs/.vitepress/vite-plugins/source-artifacts.ts`:
- Around line 71-92: The watcher currently only triggers ensureSchema() for
files under src (handled by handleSrcChange using rootDir and debounceTimer), so
changes to the generator (e.g., scripts/emit-definition-schema.ts) are ignored;
update the file-change logic to also detect the generator file(s) — extend
handleSrcChange (or add a new check) to call ensureSchema() when the changed
file matches the generator path(s) like 'scripts/emit-definition-schema.ts' (or
a scripts/ directory glob), and keep the same debounce/error handling and
server.watcher.on('change'|'add'|'unlink') setup so generator edits trigger
ensureSchema() just like src edits.
In `@package.json`:
- Around line 121-129: Remove the entire devEngines block (the "devEngines"
object containing "packageManager" and "runtime" keys) from package.json because
devEngines.packageManager.name and devEngines.runtime.name set to "bun" will
cause npm to hard-fail; rely on the existing top-level packageManager entry
(packageManager: "bun@1.3.11") instead to express the Bun requirement via
Corepack and avoid the nested devEngines configuration.
---
Outside diff comments:
In `@docs/guide/flags.md`:
- Around line 249-271: The docs example contains an empty cut marker block
between // ---cut-start--- and // ---cut-end--- which serves no purpose; remove
those two lines or replace them with relevant hidden content. Edit the
Propagation example around the command('start')/nested and cli('mycli') snippet
and either delete the empty cut markers or populate them with the intended
hidden code so the example is clean and consistent with .propagate() usage for
the verbose flag.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Organization UI (inherited)
Review profile: ASSERTIVE
Plan: Pro
Run ID: 80b6cbe7-5e52-4bae-b5e6-dcd37eb61709
⛔ Files ignored due to path filters (7)
bun.lockis excluded by!**/*.lockdocs/.vitepress/theme/explorations/theme-sketch-1-brand-forward-dark.svgis excluded by!**/*.svgdocs/.vitepress/theme/explorations/theme-sketch-1-brand-forward.svgis excluded by!**/*.svgdocs/.vitepress/theme/explorations/theme-sketch-2-neutral-accents-dark.svgis excluded by!**/*.svgdocs/.vitepress/theme/explorations/theme-sketch-2-neutral-accents.svgis excluded by!**/*.svgdocs/.vitepress/theme/explorations/theme-sketch-3-warm-cool-dark.svgis excluded by!**/*.svgdocs/.vitepress/theme/explorations/theme-sketch-3-warm-cool.svgis excluded by!**/*.svg
📒 Files selected for processing (19)
docs/.vitepress/data/symbol-pages.tsdocs/.vitepress/data/typedoc.tsdocs/.vitepress/theme/components/SettingsGear.vuedocs/.vitepress/theme/index.tsdocs/.vitepress/theme/settings.cssdocs/.vitepress/vite-plugins/source-artifacts.tsdocs/guide/arguments.mddocs/guide/commands.mddocs/guide/config.mddocs/guide/errors.mddocs/guide/flags.mddocs/guide/middleware.mddocs/guide/rationale.mddocs/guide/semantics.mddocs/guide/testing.mddocs/guide/walkthrough.mddocs/reference/main.mddocs/reference/runtime.mdpackage.json
📜 Review details
⏰ Context from checks skipped due to timeout of 18000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Workers Builds: dreamcli
🧰 Additional context used
📓 Path-based instructions (1)
{package.json,pyproject.toml,setup.py,Cargo.toml,go.mod,pom.xml,build.gradle,VERSION}
📄 CodeRabbit inference engine (Custom checks)
If any source code files (excluding tests, docs, CI, markdown, or comments-only changes) are modified, a version field MUST be updated in one of the following files if present in the repo: package.json, pyproject.toml, setup.py, Cargo.toml, go.mod, pom.xml, build.gradle, or a VERSION file
Files:
package.json
🧠 Learnings (17)
📓 Common learnings
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 9
File: docs/guide/runtime.md:61-61
Timestamp: 2026-04-06T20:07:00.266Z
Learning: In the kjanat/dreamcli repository, docs/guide/runtime.md (and other `ts twoslash` code blocks in docs/) use the Twoslash `// ---cut---` directive to hide setup/fixture imports from the rendered output while still making those symbols available for type checking. Specifically, fixture imports like `import { regionCmd } from './docs/.vitepress/twoslash/testing-fixtures.ts'` should be placed before `// ---cut---` so they do not appear in the rendered docs page.
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 9
File: examples/json-mode.ts:2-15
Timestamp: 2026-04-06T11:26:11.173Z
Learning: The `module` JSDoc requirement applies only to TypeScript source files under `src/` in the kjanat/dreamcli repository. Files under `examples/` are runnable demo/example scripts and are NOT required to have a `module` JSDoc tag.
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 9
File: docs/.vitepress/theme/index.ts:1-16
Timestamp: 2026-04-06T11:28:55.224Z
Learning: In the kjanat/dreamcli repository, the `module` JSDoc tag requirement applies ONLY to TypeScript source files under `src/`. Files under `docs/` (including `docs/.vitepress/**` theme, plugin, data, and composable files) are part of the VitePress docs pipeline and are NOT required to have a `module` tag.
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 9
File: examples/spinner-progress.ts:2-12
Timestamp: 2026-04-06T11:25:57.444Z
Learning: In the kjanat/dreamcli repository, the `module` JSDoc tag requirement applies only to TypeScript source files under `src/`. Files under `examples/` are example/documentation scripts and should NOT be flagged for missing `module` tags.
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 9
File: package.json:81-81
Timestamp: 2026-04-06T18:37:53.014Z
Learning: In the kjanat/dreamcli repository, `dreamcli.schema.json` is automatically emitted on every tsdown run via the `hooks['build:prepare']` callback in `tsdown.config.ts`, which calls `emitDefinitionSchema()` from `scripts/emit-definition-schema.ts`. Do NOT flag `prepack` or other tsdown-based scripts as missing schema emission — it is already guaranteed by the tsdown prepare hook.
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 9
File: package.json:63-66
Timestamp: 2026-04-06T18:39:45.969Z
Learning: In the kjanat/dreamcli repository, `vitepressnext` in npm scripts (e.g., `docs:build`, `docs:dev`, `docs:preview`, `dev`) is intentional and required. The project pins VitePress to a pre-release alpha version (`^2.0.0-alpha.17`) published only under the `next` dist-tag. Do NOT suggest removing `next` from VitePress invocations — doing so would cause `bunx` to resolve the stable 1.x channel instead, breaking the docs build.
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 9
File: examples/middleware.ts:2-11
Timestamp: 2026-04-06T11:26:04.030Z
Learning: In the kjanat/dreamcli repository, the `module` JSDoc tag requirement applies only to library source files under `src/`. Example scripts in the `examples/` directory are runnable demos, not source code, and do not require a `module` tag.
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 9
File: deno.json:26-40
Timestamp: 2026-04-06T11:48:17.901Z
Learning: In the kjanat/dreamcli repository (and in general for JSR/Deno), `deno.json` exports DO support JSON files as public subpath exports (e.g., `"./schema": "./dreamcli.schema.json"`). Deno's toolchain (`deno publish`, `deno check`) handles JSON exports natively. Do NOT flag JSON file subpath exports in `deno.json` as invalid — `deno publish --dry-run` confirms they work correctly.
📚 Learning: 2026-04-06T11:26:11.173Z
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 9
File: examples/json-mode.ts:2-15
Timestamp: 2026-04-06T11:26:11.173Z
Learning: The `module` JSDoc requirement applies only to TypeScript source files under `src/` in the kjanat/dreamcli repository. Files under `examples/` are runnable demo/example scripts and are NOT required to have a `module` JSDoc tag.
Applied to files:
docs/guide/config.mddocs/guide/errors.mddocs/guide/commands.mddocs/guide/middleware.mddocs/guide/walkthrough.mddocs/guide/arguments.mddocs/reference/main.mddocs/.vitepress/vite-plugins/source-artifacts.tsdocs/reference/runtime.mddocs/guide/flags.mddocs/guide/testing.mdpackage.jsondocs/.vitepress/theme/index.tsdocs/.vitepress/data/typedoc.ts
📚 Learning: 2026-04-06T20:07:00.266Z
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 9
File: docs/guide/runtime.md:61-61
Timestamp: 2026-04-06T20:07:00.266Z
Learning: In kjanat/dreamcli documentation, for Twoslash `ts twoslash` code blocks, use the `// ---cut---` directive to hide setup/fixture imports from the rendered output while keeping the symbols available for TypeScript type checking. Ensure fixture/setup imports (e.g., `import { regionCmd } from './docs/.vitepress/twoslash/testing-fixtures.ts'`) are placed before `// ---cut---` so they are excluded from the published docs page but still participate in type checking.
Applied to files:
docs/guide/config.mddocs/guide/semantics.mddocs/guide/errors.mddocs/guide/commands.mddocs/guide/middleware.mddocs/guide/walkthrough.mddocs/guide/rationale.mddocs/guide/arguments.mddocs/reference/main.mddocs/reference/runtime.mddocs/guide/flags.mddocs/guide/testing.md
📚 Learning: 2026-04-06T11:25:57.444Z
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 9
File: examples/spinner-progress.ts:2-12
Timestamp: 2026-04-06T11:25:57.444Z
Learning: In the kjanat/dreamcli repository, the `module` JSDoc tag requirement applies only to TypeScript source files under `src/`. Files under `examples/` are example/documentation scripts and should NOT be flagged for missing `module` tags.
Applied to files:
docs/guide/config.mddocs/guide/errors.mddocs/guide/commands.mddocs/guide/middleware.mddocs/guide/walkthrough.mddocs/guide/arguments.mddocs/reference/main.mddocs/.vitepress/vite-plugins/source-artifacts.tsdocs/reference/runtime.mddocs/guide/flags.mddocs/guide/testing.mdpackage.jsondocs/.vitepress/theme/index.ts
📚 Learning: 2026-04-06T11:28:55.224Z
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 9
File: docs/.vitepress/theme/index.ts:1-16
Timestamp: 2026-04-06T11:28:55.224Z
Learning: In the kjanat/dreamcli repository, the `module` JSDoc tag requirement applies ONLY to TypeScript source files under `src/`. Files under `docs/` (including `docs/.vitepress/**` theme, plugin, data, and composable files) are part of the VitePress docs pipeline and are NOT required to have a `module` tag.
Applied to files:
docs/guide/config.mddocs/guide/errors.mddocs/guide/commands.mddocs/reference/main.mddocs/.vitepress/vite-plugins/source-artifacts.tspackage.jsondocs/.vitepress/theme/index.tsdocs/.vitepress/data/typedoc.ts
📚 Learning: 2026-04-06T11:26:04.030Z
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 9
File: examples/middleware.ts:2-11
Timestamp: 2026-04-06T11:26:04.030Z
Learning: In the kjanat/dreamcli repository, the `module` JSDoc tag requirement applies only to library source files under `src/`. Example scripts in the `examples/` directory are runnable demos, not source code, and do not require a `module` tag.
Applied to files:
docs/guide/config.mddocs/guide/errors.mddocs/guide/commands.mddocs/guide/walkthrough.mddocs/reference/main.mddocs/.vitepress/vite-plugins/source-artifacts.tsdocs/guide/testing.mdpackage.jsondocs/.vitepress/theme/index.ts
📚 Learning: 2026-04-06T18:37:53.014Z
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 9
File: package.json:81-81
Timestamp: 2026-04-06T18:37:53.014Z
Learning: In the kjanat/dreamcli repository, `dreamcli.schema.json` is automatically emitted on every tsdown run via the `hooks['build:prepare']` callback in `tsdown.config.ts`, which calls `emitDefinitionSchema()` from `scripts/emit-definition-schema.ts`. Do NOT flag `prepack` or other tsdown-based scripts as missing schema emission — it is already guaranteed by the tsdown prepare hook.
Applied to files:
docs/guide/config.mddocs/guide/errors.mddocs/guide/commands.mddocs/reference/main.mddocs/.vitepress/vite-plugins/source-artifacts.tspackage.json
📚 Learning: 2026-04-06T18:36:42.932Z
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 9
File: scripts/emit-definition-schema.ts:15-16
Timestamp: 2026-04-06T18:36:42.932Z
Learning: In the kjanat/dreamcli repo, named imports from JSON files (e.g., `import { name as jsrName } from '../deno.json' with { type: 'json' }`) are valid in scripts run directly by Bun. TypeScript's `resolveJsonModule` synthesizes named exports from JSON object keys, and Bun's native TypeScript handling supports this pattern. Do NOT flag named imports from JSON files as invalid in Bun-executed TypeScript scripts — they work correctly even with `with { type: 'json' }` import attributes.
Applied to files:
docs/guide/config.mddocs/guide/walkthrough.mddocs/reference/main.mddocs/.vitepress/vite-plugins/source-artifacts.tspackage.json
📚 Learning: 2026-04-06T18:24:44.371Z
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 9
File: docs/reference/api.md:8-8
Timestamp: 2026-04-06T18:24:44.371Z
Learning: In the kjanat/dreamcli repository, explicit `Readonly<Record<string, string>>` type annotations on `const` object literals are acceptable and intentional. Do not flag these as redundant or unnecessary — the author prefers the explicitness for documentation/intent purposes.
Applied to files:
docs/guide/config.md
📚 Learning: 2026-04-06T11:20:59.078Z
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 9
File: .github/workflows/publish-npm.yml:36-36
Timestamp: 2026-04-06T11:20:59.078Z
Learning: In the kjanat/dreamcli repository, the difference between `bun run ci` (in publish-npm.yml) and `bun --bun run ci` (in publish-jsr.yml) is intentional: npm publishing runs CI under Bun's Node.js-compatible layer to verify Node.js consumer behavior, while JSR publishing forces Bun's native runtime with `--bun` for Bun/Deno-native validation.
Applied to files:
docs/guide/config.mddocs/guide/walkthrough.mdpackage.json
📚 Learning: 2026-02-10T16:25:08.867Z
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 1
File: AGENTS.md:12-12
Timestamp: 2026-02-10T16:25:08.867Z
Learning: In repository kjanat/dreamcli, prefer using the filename syntax (e.g., GOALS.md) when referencing files in Markdown documentation, and treat references that do not follow this style as non-issues. This pattern applies to all Markdown files across the project.
Applied to files:
docs/guide/config.mddocs/guide/semantics.mddocs/guide/errors.mddocs/guide/commands.mddocs/guide/middleware.mddocs/guide/walkthrough.mddocs/guide/rationale.mddocs/guide/arguments.mddocs/reference/main.mddocs/reference/runtime.mddocs/guide/flags.mddocs/guide/testing.md
📚 Learning: 2026-04-06T20:07:00.266Z
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 9
File: docs/guide/runtime.md:61-61
Timestamp: 2026-04-06T20:07:00.266Z
Learning: In the kjanat/dreamcli repository, docs/guide/runtime.md (and other `ts twoslash` code blocks in docs/) use the Twoslash `// ---cut---` directive to hide setup/fixture imports from the rendered output while still making those symbols available for type checking. Specifically, fixture imports like `import { regionCmd } from './docs/.vitepress/twoslash/testing-fixtures.ts'` should be placed before `// ---cut---` so they do not appear in the rendered docs page.
Applied to files:
docs/.vitepress/theme/settings.cssdocs/.vitepress/vite-plugins/source-artifacts.tsdocs/.vitepress/theme/components/SettingsGear.vuepackage.jsondocs/.vitepress/theme/index.tsdocs/.vitepress/data/symbol-pages.ts
📚 Learning: 2026-04-06T18:39:45.969Z
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 9
File: package.json:63-66
Timestamp: 2026-04-06T18:39:45.969Z
Learning: In the kjanat/dreamcli repository, `vitepressnext` in npm scripts (e.g., `docs:build`, `docs:dev`, `docs:preview`, `dev`) is intentional and required. The project pins VitePress to a pre-release alpha version (`^2.0.0-alpha.17`) published only under the `next` dist-tag. Do NOT suggest removing `next` from VitePress invocations — doing so would cause `bunx` to resolve the stable 1.x channel instead, breaking the docs build.
Applied to files:
docs/guide/commands.mddocs/guide/walkthrough.mddocs/reference/main.mddocs/.vitepress/vite-plugins/source-artifacts.tsdocs/guide/testing.mdpackage.jsondocs/.vitepress/theme/index.ts
📚 Learning: 2026-04-06T11:48:17.901Z
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 9
File: deno.json:26-40
Timestamp: 2026-04-06T11:48:17.901Z
Learning: In the kjanat/dreamcli repository (and in general for JSR/Deno), `deno.json` exports DO support JSON files as public subpath exports (e.g., `"./schema": "./dreamcli.schema.json"`). Deno's toolchain (`deno publish`, `deno check`) handles JSON exports natively. Do NOT flag JSON file subpath exports in `deno.json` as invalid — `deno publish --dry-run` confirms they work correctly.
Applied to files:
docs/reference/main.mdpackage.json
📚 Learning: 2026-04-06T18:38:38.679Z
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 9
File: scripts/emit-definition-schema.ts:20-26
Timestamp: 2026-04-06T18:38:38.679Z
Learning: In the kjanat/dreamcli repository, `scripts/emit-definition-schema.ts` uses `typeof globalThis.Deno !== 'undefined'` to pick the correct registry `$id` (JSR URL vs npm CDN URL) when emitting `dreamcli.schema.json`. This is intentional and correct: `.github/workflows/publish-jsr.yml` explicitly runs the script via `deno run -A scripts/emit-definition-schema.ts`, ensuring Deno is the runtime for JSR builds. Do NOT flag this runtime-detection pattern as incorrect or raise $id/$schema mismatch concerns — the CI workflow enforces the right runtime context for each publish target.
Applied to files:
docs/.vitepress/vite-plugins/source-artifacts.tsdocs/reference/runtime.mdpackage.jsondocs/.vitepress/theme/index.ts
📚 Learning: 2026-04-06T18:40:01.263Z
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 9
File: docs/.vitepress/vite-plugins/source-artifacts.ts:62-83
Timestamp: 2026-04-06T18:40:01.263Z
Learning: In the kjanat/dreamcli repository, Windows is NOT a supported or targeted platform. Do NOT raise Windows-specific path separator/normalization issues (e.g., path.sep, forward-slash vs backslash, normalize() concerns) in code reviews — the project deliberately targets Linux/macOS only.
Applied to files:
docs/.vitepress/vite-plugins/source-artifacts.ts
📚 Learning: 2026-04-06T11:32:59.137Z
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 9
File: .zed/settings.json:49-52
Timestamp: 2026-04-06T11:32:59.137Z
Learning: In the kjanat/dreamcli repository, the `.zed/settings.json` file references a JSON schema for `.attw.json` via a gist URL owned by the repo maintainer (kjanat). Do not flag this as a fragile external dependency — the maintainer controls the gist and it is intentional. Do not suggest moving it to the repo or a "more stable" location.
Applied to files:
docs/.vitepress/vite-plugins/source-artifacts.tspackage.json
🪛 ast-grep (0.42.1)
docs/.vitepress/theme/index.ts
[warning] 266-266: Direct HTML content assignment detected. Modifying innerHTML, outerHTML, or using document.write with unsanitized content can lead to XSS vulnerabilities. Use secure alternatives like textContent or sanitize HTML with libraries like DOMPurify.
Context: container.innerHTML = svg
Note: [CWE-79] Improper Neutralization of Input During Web Page Generation [REFERENCES]
- https://www.dhairyashah.dev/posts/why-innerhtml-is-a-bad-idea-and-how-to-avoid-it/
- https://cwe.mitre.org/data/definitions/79.html
(unsafe-html-content-assignment)
[warning] 282-282: Direct HTML content assignment detected. Modifying innerHTML, outerHTML, or using document.write with unsanitized content can lead to XSS vulnerabilities. Use secure alternatives like textContent or sanitize HTML with libraries like DOMPurify.
Context: container.innerHTML = svg
Note: [CWE-79] Improper Neutralization of Input During Web Page Generation [REFERENCES]
- https://www.dhairyashah.dev/posts/why-innerhtml-is-a-bad-idea-and-how-to-avoid-it/
- https://cwe.mitre.org/data/definitions/79.html
(unsafe-html-content-assignment)
[warning] 318-318: Direct HTML content assignment detected. Modifying innerHTML, outerHTML, or using document.write with unsanitized content can lead to XSS vulnerabilities. Use secure alternatives like textContent or sanitize HTML with libraries like DOMPurify.
Context: el.innerHTML = original
Note: [CWE-79] Improper Neutralization of Input During Web Page Generation [REFERENCES]
- https://www.dhairyashah.dev/posts/why-innerhtml-is-a-bad-idea-and-how-to-avoid-it/
- https://cwe.mitre.org/data/definitions/79.html
(unsafe-html-content-assignment)
[warning] 320-320: Direct HTML content assignment detected. Modifying innerHTML, outerHTML, or using document.write with unsanitized content can lead to XSS vulnerabilities. Use secure alternatives like textContent or sanitize HTML with libraries like DOMPurify.
Context: el.innerHTML = original.replace(NPX_TSX_RE, runtime)
Note: [CWE-79] Improper Neutralization of Input During Web Page Generation [REFERENCES]
- https://www.dhairyashah.dev/posts/why-innerhtml-is-a-bad-idea-and-how-to-avoid-it/
- https://cwe.mitre.org/data/definitions/79.html
(unsafe-html-content-assignment)
[warning] 266-266: Direct modification of innerHTML or outerHTML properties detected. Modifying these properties with unsanitized user input can lead to XSS vulnerabilities. Use safe alternatives or sanitize content first.
Context: container.innerHTML = svg
Note: [CWE-79] Improper Neutralization of Input During Web Page Generation [REFERENCES]
- https://owasp.org/www-community/xss-filter-evasion-cheatsheet
- https://cwe.mitre.org/data/definitions/79.html
(dom-content-modification)
[warning] 282-282: Direct modification of innerHTML or outerHTML properties detected. Modifying these properties with unsanitized user input can lead to XSS vulnerabilities. Use safe alternatives or sanitize content first.
Context: container.innerHTML = svg
Note: [CWE-79] Improper Neutralization of Input During Web Page Generation [REFERENCES]
- https://owasp.org/www-community/xss-filter-evasion-cheatsheet
- https://cwe.mitre.org/data/definitions/79.html
(dom-content-modification)
[warning] 318-318: Direct modification of innerHTML or outerHTML properties detected. Modifying these properties with unsanitized user input can lead to XSS vulnerabilities. Use safe alternatives or sanitize content first.
Context: el.innerHTML = original
Note: [CWE-79] Improper Neutralization of Input During Web Page Generation [REFERENCES]
- https://owasp.org/www-community/xss-filter-evasion-cheatsheet
- https://cwe.mitre.org/data/definitions/79.html
(dom-content-modification)
[warning] 320-320: Direct modification of innerHTML or outerHTML properties detected. Modifying these properties with unsanitized user input can lead to XSS vulnerabilities. Use safe alternatives or sanitize content first.
Context: el.innerHTML = original.replace(NPX_TSX_RE, runtime)
Note: [CWE-79] Improper Neutralization of Input During Web Page Generation [REFERENCES]
- https://owasp.org/www-community/xss-filter-evasion-cheatsheet
- https://cwe.mitre.org/data/definitions/79.html
(dom-content-modification)
🪛 LanguageTool
docs/guide/rationale.md
[grammar] ~3-~3: Ensure spelling is correct
Context: ...cture Rationale This page explains why dreamcli is shaped the way it is. Use it when t...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🔇 Additional comments (66)
docs/guide/errors.md (4)
7-11: Scoped import migration is clean and example setup is valid.This snippet is clear, compiles as shown, and aligns with the package rename.
32-42: Type-safety demo is precise and testable.Intentional type failure is correctly encoded for twoslash validation.
46-51: Error-type import block is consistent with the section narrative.No issues; symbols map directly to the documented categories below.
62-74: Type-guard example is well-structured and actionable.The control-flow narrowing reads correctly and demonstrates intended error handling clearly.
docs/guide/middleware.md (2)
67-75: Middleware parameter documentation matches the contract.The documented handler params (including
ctxandnext) align with the schema contract and are accurate.
21-21: crypto.randomUUID() resolves properly—no fix needed.The
cryptoglobal is available through the"node"type already configured in tsconfig.json, which the VitePress Twoslash config inherits.Date.now()works fine in the same blocks without an explicit import, and so doescrypto.randomUUID(). No docs build fragility here, matey.> Likely an incorrect or invalid review comment.docs/guide/semantics.md (2)
95-100: The Mermaid replacements preserve semantics and improve maintainability.These diagrams stay faithful to the documented precedence/masking rules and are easier to keep in sync than ASCII blocks.
Also applies to: 133-139, 189-193
42-49: Twoslash examples are consistently scoped and source-aligned.Good conversion to
ts twoslashwith explicit imports from@kjanat/dreamcli.Also applies to: 104-113, 143-147
docs/guide/rationale.md (2)
40-42: Execution-pipeline rationale is accurate and well-grounded.The statement that CLI entrypoints and
runCommand()share one executor matches the current code paths.
53-67: Clear articulation of product boundaries and source-backed docs strategy.This section explains trade-offs crisply and aligns with the repo’s contract-first direction.
Also applies to: 94-111
docs/guide/arguments.md (7)
7-19: Arrr, clean as a freshly swabbed deck!The String arg example be shipshape — proper imports from
@kjanat/dreamcli, solid Twoslash ^? query, and the type inference will display correctly. No barnacles here!
21-33: Another treasure worth keepin'!Number arg example follows the same sound pattern. Type inference will show
numberas expected. Well done, matey!
35-47: Aye, custom arg be properly rigged!The URL parser example demonstrates the custom arg pattern perfectly. Type inference will resolve to
URL. This be good code!
49-64: Declaration example be battle-ready!The multiline arg formatting be easier on the eyes, and the
type Args = typeof argspattern shows the full args shape. Good choice for demonstrating the complete picture!
74-105: Required vs Optional be crystal clear!Both examples demonstrate the presence modifiers correctly. The required arg will show
string, optional will showstring | undefined. Perfect for teachin' the crew!
107-123: Variadic args be properly configured!The .variadic() example shows the array collection pattern clearly. Type will resolve to
readonly string[]. Smooth sailin'!
130-169: Env and STDIN examples be shipshape!Both the environment fallback and STDIN patterns be demonstrated clearly with proper multiline formatting. The resolution chain be well explained in the surrounding text. These examples will serve the docs well!
docs/guide/flags.md (5)
8-96: Flag type examples be expertly crafted, ye scallywag!All six flag types (String, Number, Boolean, Enum, Array, Custom) use the Twoslash
// ---cut---directive correctly — hidin' the setup from rendered output while keepin' types available for inference. The ^? queries will display clean without clutter. This be fine work!
105-132: Modifier chain be complete and clear!Shows every modifier in the toolkit — alias, describe, default, required, env, config, prompt, deprecated, propagate. This be a solid reference for the crew!
149-160: Resolution chain example be properly ordered!CLI → env → config → prompt → default, just like the flowchart shows. The enum with all modifiers demonstrates the full resolution pipeline. Well done!
170-230: Required vs Optional section be comprehensive!Four examples showing presence and default behavior — optional, defaulted, required, and boolean. Types will infer correctly for each case. The boolean defaulting to
falsebe especially important to demonstrate!
232-244: Custom parsing with validation be well demonstrated!Shows both parsing (new URL) and validation (protocol check) in one example. Error handling be clear. Good teachin' material!
docs/guide/commands.md (6)
10-23: Single command example be solid as a ship's keel!Clean demonstration of the minimal CLI pattern with command, args, flags, and action. Perfect for new sailors!
29-46: Multi-command pattern be well presented!Shows how to compose multiple commands into a CLI with version and description. Clear progression from single to multi!
52-69: Command groups be properly nested!The
group('db')pattern be demonstrated clearly with migrate and seed subcommands. Good explanation of the nesting pattern!
73-100: Configuration examples be shipshape!The multiline
.example()formatting be easier to read, and the default command pattern with separate constants be clear and composable. Well done!
120-141: Action handler example be thorough!Shows all available parameters (args, flags, ctx, meta, out) with inline explanations. The prettier-ignore directive be properly hidden from rendered output. This be a good reference!
143-159: Async action example be well structured!Declares the deploy function signature first, then demonstrates awaiting it in the action handler. Clean pattern for teaching async handlers!
docs/guide/testing.md (6)
8-19: Basic testing example be clean and correct!Fixture import be properly hidden with
// ---cut---, and the test pattern be clear. Good introduction to the testkit!
21-55: RunOptions examples be perfect, ye fixed the contradiction!The multiple
runCommandcalls each demonstrate a different option clearly. And aye, thejsonMode: truenow matches the comment "simulate --json mode" — that past issue be resolved! Well done, matey!
57-69: Options table be accurate!The
envtype correctly showsRecord<string, string | undefined>matching the actual RunOptions interface. Table be comprehensive and correct!
71-91: Prompt testing examples be thorough!Shows both happy path (answers array) and cancellation path (PROMPT_CANCEL). The promptCmd fixture be properly imported and hidden. Good coverage!
93-110: Activity event assertions be correct!The activityCmd fixture calls
spinner.succeed('Done')which emits a 'spinner:succeed' event, so the assertion be accurate. This demonstrates activity testing well!
112-126: Captured output type example be accurate!The Pick<RunResult, ...> correctly extracts the output-related fields, and the note about activity being separate be helpful. Type inference will work correctly!
docs/guide/walkthrough.md (11)
47-58: Step 1 be a solid start!Simple single-command CLI demonstrating the basics. Perfect for beginnin' the walkthrough!
67-135: Step 2 be well structured with reusable snippets!The
// twoslash include walkthrough-pr-setupdirective creates a reusable snippet, and the PR filtering logic with enum flags be demonstrated clearly. Good teaching progression!
161-186: Step 3 demonstrates out.table() perfectly!Reuses the PR setup with
@include, then shows the table rendering pattern. The mapping to display columns be clear!
209-265: Step 4 groups be properly organized!Shows auth, pr, and issue groups with subcommands, then assembles them into the CLI. Good demonstration of the grouping pattern!
290-325: Step 5 arguments and error handling be excellent!Positional arg parsing, error handling with CLIError properties, and dual JSON/human output modes — all demonstrated clearly. Well done!
339-434: Step 6 context derivation be thoroughly explained!Both derive() and middleware() patterns be shown side-by-side, with clear explanation of when to use each. The requireAuth helper be reusable. Excellent teaching!
452-482: Step 7 helper composition be brilliant!The tokenFlag() and authedCommand() helpers demonstrate excellent abstraction — reusable flag and command patterns. The resolution chain (flag → env → prompt) be built into the helper. Smart teaching!
513-565: Step 8 interactive prompts be well demonstrated!The .interactive() pattern with conditional prompts based on the decision flag be perfect for guided workflows. Shows when to use .interactive() vs .prompt()!
590-645: Step 9 spinner example be smooth!Shows the spinner lifecycle with async operations, and properly handles both TTY (spinner) and JSON mode output. The .required() on prompted flags be correct!
656-706: Step 10 testing examples be comprehensive!Shows basic runs, error cases, env injection, and prompt answers. All imports from examples/gh/src/docs.ts be valid. The testkit patterns be well demonstrated!
715-759: Final assembly be complete and correct!All command imports be valid, groups be properly composed, and the CLI be fully assembled. This brings the whole walkthrough together perfectly!
docs/.vitepress/vite-plugins/source-artifacts.ts (1)
26-48: Aye, this single-flight rebuild path finally behaves.
buildingPromiseplusdirtySchemagives ye one in-flight run and one queued rerun, so the schema stops laggin’ a change behind when edits land mid-build. Clean fix.docs/.vitepress/data/typedoc.ts (8)
1-225: Aye, these type definitions be shipshape and seaworthy!The discriminated union fer
NormalizedApiTypecovers all the TypeDoc type variants proper-like, andNormalizedApiGroupChildnow carries thereflectionIdas it should. Consistentnullhandling throughout—me perfectionist heart be pleased.
226-292: This here normalization pipeline be well-charted, matey.The flow from raw TypeDoc to normalized model be clean: deduplication via
seen, best-reflection picking fer duplicate names, and comment backfilling fer re-exports. Arrr, a fine piece of work!
299-317: Arrr, ye fixed the identity keying! Me heart soars like a seagull!The composite key
${entry.sourcePath}::${entry.name}be the proper way to identify true siblings across entrypoints. No more differentFoos looting each other's documentation like scallywags.
319-340: LGTM!Proper error handling when TypeDoc conversion fails, and sensible filtering of test files. The GitHub link template be hardcoded to this here repo, which be fine fer now.
355-411: This normalization function be thorough as a ship's inventory before a long voyage!All reflection properties be handled proper-like with safe
'in'checks. The groups get their children passed fer ID resolution—exactly what the previous review demanded. Well done, ye scurvy dog!
534-549: Aye, ye kept the reflection IDs aboard! That there past review issue be properly addressed.Group children now carry both
reflectionIdandname, resolved by ID end-to-end. No more duplicate names collapsin' onto the first child like a poorly rigged sail.
654-673: LGTM!Defensive handling of unknown literal values and proper reference target normalization. These helpers be solid as barnacles on a hull.
551-652: Shiver me timbers, the switch be exhaustive as it stands, matey. TypeScript's strict mode already catches missin' cases at compile time through exhaustiveness checkin' on yer discriminated union—no need fer a default case. Addin' one would only mask errors if TypeDoc ever adds new type kinds, lettin' 'em sneak through as 'unknown' instead of blowin' up proper-like. This here code be solid; the strictness be keepin' ye safe from future surprises.docs/.vitepress/data/symbol-pages.ts (9)
31-135: This collision-aware slug logic be navigatin' the treacherous waters of case-insensitive file systems like a seasoned captain!Ye detect collisions by lowercase key, then disambiguate with the kind suffix while preservin' the original casin'. The route and file path generation be deterministic and consistent. Arrr, well done!
137-168: LGTM!Clean composition of page sections with proper null filtering. The metadata header be informative and the conditional source link be a nice touch.
272-303: Ye finally included them signatures and index signatures, ye stubborn sea dog!The
allMembersnow be the proper union ofchildren,signatures, andindexSignatures. AndmergeUngroupedMembersensures nothin' gets tossed overboard. This addresses the past review concern about container signatures bein' lost.
517-537: Type literals now render their full crew of members!Signatures and index signatures be properly included alongside children. No more empty
{}when the actual members be hidin' in the signatures array.
454-499: LGTM!Comprehensive type rendering that handles all the
NormalizedApiTypevariants. Since this union be defined in yer own codebase (typedoc.ts), the exhaustive switch be safe—TypeScript will holler if ye add a new kind without handlin' it here.
694-696: Arrr, ye fixed the newline escapin'! Me heart be singin' a sea shanty of joy!All them newline variants be replaced with
<br>, and pipes be properly escaped. No more markdown tables breakin' like a ship on the rocks.
597-614: LGTM!The example links be collected proper-like, grouped by symbol ID. The type widenin' from mutable to readonly be safe since these arrays be constructed fresh and never escape mutably.
616-692: LGTM!These helper functions be lean and mean like a well-crewed vessel. The
renderExampleBlockbe clever enough to detect existing code fences—no double-wrapping disasters here.
1-29: LGTM!Clean module structure with proper JSDoc and a well-defined
GeneratedSymbolPageinterface. The exports be organized fer consumption by the broader docs pipeline.package.json (2)
2-3: Aye, the major bump be the right call.With the public surface shifting this hard,
2.0.0fits.As per coding guidelines, "If any source code files (excluding tests, docs, CI, markdown, or comments-only changes) are modified, a version field MUST be updated in one of the following files if present in the repo: package.json, pyproject.toml, setup.py, Cargo.toml, go.mod, pom.xml, build.gradle, or a VERSION file"
35-40:⚠️ Potential issue | 🟠 Majornpm will ship yer root
exports(source .ts files), not the dist manifest—publishConfig is dead in the water for npm publish.The
prepackhook runs tsdown to build dist/, aye, but npm'spublishcommand uses the root package.json as-is. npm does NOT supportpublishConfig.exportsoverrides—that's a myth. Yer rootexportsfield points straight to./src/index.tswhilepublishConfig.exportshas the built dist files, but npm consumers will fetch the root exports only. They'll walk the plank with source-only bundles unless ye either move the correct exports to root or generate and publish a dist/package.json instead.Check
.github/workflows/publish-npm.ymlline 38: straightnpm publishwith no manifest rewrite. Thefilesfield includes bothsrcanddist, but that doesn't matter if yer rootexportspoints to source.⛔ Skipped due to learnings
Learnt from: kjanat Repo: kjanat/dreamcli PR: 9 File: .github/workflows/publish-npm.yml:36-36 Timestamp: 2026-04-06T11:20:59.078Z Learning: In the kjanat/dreamcli repository, the difference between `bun run ci` (in publish-npm.yml) and `bun --bun run ci` (in publish-jsr.yml) is intentional: npm publishing runs CI under Bun's Node.js-compatible layer to verify Node.js consumer behavior, while JSR publishing forces Bun's native runtime with `--bun` for Bun/Deno-native validation.Learnt from: kjanat Repo: kjanat/dreamcli PR: 9 File: deno.json:26-40 Timestamp: 2026-04-06T11:48:17.901Z Learning: In the kjanat/dreamcli repository (and in general for JSR/Deno), `deno.json` exports DO support JSON files as public subpath exports (e.g., `"./schema": "./dreamcli.schema.json"`). Deno's toolchain (`deno publish`, `deno check`) handles JSON exports natively. Do NOT flag JSON file subpath exports in `deno.json` as invalid — `deno publish --dry-run` confirms they work correctly.Learnt from: kjanat Repo: kjanat/dreamcli PR: 9 File: scripts/emit-definition-schema.ts:20-26 Timestamp: 2026-04-06T18:38:38.679Z Learning: In the kjanat/dreamcli repository, `scripts/emit-definition-schema.ts` uses `typeof globalThis.Deno !== 'undefined'` to pick the correct registry `$id` (JSR URL vs npm CDN URL) when emitting `dreamcli.schema.json`. This is intentional and correct: `.github/workflows/publish-jsr.yml` explicitly runs the script via `deno run -A scripts/emit-definition-schema.ts`, ensuring Deno is the runtime for JSR builds. Do NOT flag this runtime-detection pattern as incorrect or raise $id/$schema mismatch concerns — the CI workflow enforces the right runtime context for each publish target.Learnt from: kjanat Repo: kjanat/dreamcli PR: 9 File: package.json:63-66 Timestamp: 2026-04-06T18:39:45.969Z Learning: In the kjanat/dreamcli repository, `vitepressnext` in npm scripts (e.g., `docs:build`, `docs:dev`, `docs:preview`, `dev`) is intentional and required. The project pins VitePress to a pre-release alpha version (`^2.0.0-alpha.17`) published only under the `next` dist-tag. Do NOT suggest removing `next` from VitePress invocations — doing so would cause `bunx` to resolve the stable 1.x channel instead, breaking the docs build.Learnt from: kjanat Repo: kjanat/dreamcli PR: 9 File: scripts/emit-definition-schema.ts:15-16 Timestamp: 2026-04-06T18:36:42.932Z Learning: In the kjanat/dreamcli repo, named imports from JSON files (e.g., `import { name as jsrName } from '../deno.json' with { type: 'json' }`) are valid in scripts run directly by Bun. TypeScript's `resolveJsonModule` synthesizes named exports from JSON object keys, and Bun's native TypeScript handling supports this pattern. Do NOT flag named imports from JSON files as invalid in Bun-executed TypeScript scripts — they work correctly even with `with { type: 'json' }` import attributes.Learnt from: kjanat Repo: kjanat/dreamcli PR: 9 File: package.json:81-81 Timestamp: 2026-04-06T18:37:53.014Z Learning: In the kjanat/dreamcli repository, `dreamcli.schema.json` is automatically emitted on every tsdown run via the `hooks['build:prepare']` callback in `tsdown.config.ts`, which calls `emitDefinitionSchema()` from `scripts/emit-definition-schema.ts`. Do NOT flag `prepack` or other tsdown-based scripts as missing schema emission — it is already guaranteed by the tsdown prepare hook.Learnt from: kjanat Repo: kjanat/dreamcli PR: 9 File: examples/json-mode.ts:2-15 Timestamp: 2026-04-06T11:26:11.173Z Learning: The `module` JSDoc requirement applies only to TypeScript source files under `src/` in the kjanat/dreamcli repository. Files under `examples/` are runnable demo/example scripts and are NOT required to have a `module` JSDoc tag.Learnt from: kjanat Repo: kjanat/dreamcli PR: 9 File: examples/middleware.ts:2-11 Timestamp: 2026-04-06T11:26:04.030Z Learning: In the kjanat/dreamcli repository, the `module` JSDoc tag requirement applies only to library source files under `src/`. Example scripts in the `examples/` directory are runnable demos, not source code, and do not require a `module` tag.Learnt from: kjanat Repo: kjanat/dreamcli PR: 9 File: examples/spinner-progress.ts:2-12 Timestamp: 2026-04-06T11:25:57.444Z Learning: In the kjanat/dreamcli repository, the `module` JSDoc tag requirement applies only to TypeScript source files under `src/`. Files under `examples/` are example/documentation scripts and should NOT be flagged for missing `module` tags.Learnt from: kjanat Repo: kjanat/dreamcli PR: 9 File: docs/.vitepress/theme/index.ts:1-16 Timestamp: 2026-04-06T11:28:55.224Z Learning: In the kjanat/dreamcli repository, the `module` JSDoc tag requirement applies ONLY to TypeScript source files under `src/`. Files under `docs/` (including `docs/.vitepress/**` theme, plugin, data, and composable files) are part of the VitePress docs pipeline and are NOT required to have a `module` tag.docs/reference/main.md (1)
366-371:⚠️ Potential issue | 🟡 MinorThese
// ---cut---lines gut the rendered examples.Arrr, the published page will hide the imports/setup but still show
parseYaml,parseTOML, andadapterbeing used out of nowhere. Keep only true fixture code above the cut, or drop the cut here so the reference examples stay copy-pasteable.Based on learnings: in kjanat/dreamcli docs,
// ---cut---is meant to hide setup/fixture code while keeping the visible snippet coherent for readers.Also applies to: 383-392
⛔ Skipped due to learnings
Learnt from: kjanat Repo: kjanat/dreamcli PR: 9 File: docs/guide/runtime.md:61-61 Timestamp: 2026-04-06T20:07:00.266Z Learning: In the kjanat/dreamcli repository, docs/guide/runtime.md (and other `ts twoslash` code blocks in docs/) use the Twoslash `// ---cut---` directive to hide setup/fixture imports from the rendered output while still making those symbols available for type checking. Specifically, fixture imports like `import { regionCmd } from './docs/.vitepress/twoslash/testing-fixtures.ts'` should be placed before `// ---cut---` so they do not appear in the rendered docs page.Learnt from: kjanat Repo: kjanat/dreamcli PR: 9 File: examples/json-mode.ts:2-15 Timestamp: 2026-04-06T11:26:11.173Z Learning: The `module` JSDoc requirement applies only to TypeScript source files under `src/` in the kjanat/dreamcli repository. Files under `examples/` are runnable demo/example scripts and are NOT required to have a `module` JSDoc tag.Learnt from: kjanat Repo: kjanat/dreamcli PR: 9 File: examples/spinner-progress.ts:2-12 Timestamp: 2026-04-06T11:25:57.444Z Learning: In the kjanat/dreamcli repository, the `module` JSDoc tag requirement applies only to TypeScript source files under `src/`. Files under `examples/` are example/documentation scripts and should NOT be flagged for missing `module` tags.Learnt from: kjanat Repo: kjanat/dreamcli PR: 9 File: scripts/emit-definition-schema.ts:15-16 Timestamp: 2026-04-06T18:36:42.932Z Learning: In the kjanat/dreamcli repo, named imports from JSON files (e.g., `import { name as jsrName } from '../deno.json' with { type: 'json' }`) are valid in scripts run directly by Bun. TypeScript's `resolveJsonModule` synthesizes named exports from JSON object keys, and Bun's native TypeScript handling supports this pattern. Do NOT flag named imports from JSON files as invalid in Bun-executed TypeScript scripts — they work correctly even with `with { type: 'json' }` import attributes.Learnt from: kjanat Repo: kjanat/dreamcli PR: 9 File: package.json:81-81 Timestamp: 2026-04-06T18:37:53.014Z Learning: In the kjanat/dreamcli repository, `dreamcli.schema.json` is automatically emitted on every tsdown run via the `hooks['build:prepare']` callback in `tsdown.config.ts`, which calls `emitDefinitionSchema()` from `scripts/emit-definition-schema.ts`. Do NOT flag `prepack` or other tsdown-based scripts as missing schema emission — it is already guaranteed by the tsdown prepare hook.Learnt from: kjanat Repo: kjanat/dreamcli PR: 9 File: deno.json:26-40 Timestamp: 2026-04-06T11:48:17.901Z Learning: In the kjanat/dreamcli repository (and in general for JSR/Deno), `deno.json` exports DO support JSON files as public subpath exports (e.g., `"./schema": "./dreamcli.schema.json"`). Deno's toolchain (`deno publish`, `deno check`) handles JSON exports natively. Do NOT flag JSON file subpath exports in `deno.json` as invalid — `deno publish --dry-run` confirms they work correctly.
| function renderParameter(parameter: NormalizedApiNode, includeDefault = true): string { | ||
| const optional = isOptionalNode(parameter); | ||
| const type = parameter.type === null ? 'unknown' : renderType(parameter.type); | ||
| const defaultValue = | ||
| includeDefault && parameter.defaultValue !== null ? ` = ${parameter.defaultValue}` : ''; | ||
| if (parameter.type?.kind === 'rest') { | ||
| return `...${parameter.name}: ${renderType(parameter.type.elementType)}[]`; | ||
| } | ||
|
|
||
| return `${parameter.name}${optional && !defaultValue ? '?' : ''}: ${type}${defaultValue}`; | ||
| } |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Arrr, the rest parameter be properly rendered now with its []!
And the optional logic be correct—no more blasphemous name?: T = value in declaration output. The !defaultValue check ensures ? only appears when there's no default.
However, me perfectionist eye spots that includeDefault = true be the default, yet every caller in this file passes false explicitly. Consider flippin' the default to match actual usage, ye scallywag.
🧹 Align default with actual usage
-function renderParameter(parameter: NormalizedApiNode, includeDefault = true): string {
+function renderParameter(parameter: NormalizedApiNode, includeDefault = false): string {📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| function renderParameter(parameter: NormalizedApiNode, includeDefault = true): string { | |
| const optional = isOptionalNode(parameter); | |
| const type = parameter.type === null ? 'unknown' : renderType(parameter.type); | |
| const defaultValue = | |
| includeDefault && parameter.defaultValue !== null ? ` = ${parameter.defaultValue}` : ''; | |
| if (parameter.type?.kind === 'rest') { | |
| return `...${parameter.name}: ${renderType(parameter.type.elementType)}[]`; | |
| } | |
| return `${parameter.name}${optional && !defaultValue ? '?' : ''}: ${type}${defaultValue}`; | |
| } | |
| function renderParameter(parameter: NormalizedApiNode, includeDefault = false): string { | |
| const optional = isOptionalNode(parameter); | |
| const type = parameter.type === null ? 'unknown' : renderType(parameter.type); | |
| const defaultValue = | |
| includeDefault && parameter.defaultValue !== null ? ` = ${parameter.defaultValue}` : ''; | |
| if (parameter.type?.kind === 'rest') { | |
| return `...${parameter.name}: ${renderType(parameter.type.elementType)}[]`; | |
| } | |
| return `${parameter.name}${optional && !defaultValue ? '?' : ''}: ${type}${defaultValue}`; | |
| } |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/.vitepress/data/symbol-pages.ts` around lines 427 - 437, The default
value for includeDefault in renderParameter is currently true but every caller
passes false; change the default to false by updating the function signature of
renderParameter to use includeDefault = false so callers that omit the argument
behave like existing call sites, and verify the rest-parameter handling and
optional/default logic in renderParameter remain unchanged (function name:
renderParameter, parameter: includeDefault).
Ship the re-foundation work as 2.0.0. This lands the schema DSL, the @kjanat/dreamcli package and schema export, fish and PowerShell completions, and the source-backed docs stack. It also hardens the release, docs, and CI pipeline around the new surface.
2 participants
Summary
@kjanat/dreamcli, shipping ESM-only exports, hardening CI/publish/docs workflows, adding thegh-projecthelper, and refreshing the changelog plus local AGENTS knowledge bases