Conversation
Single published package stays intact — no breaking changes. Subpath exports, hash imports, and CI all updated. Layout: packages/dreamcli/ — library (src, build, tests) apps/docs/ — VitePress docs site tools/gh-project/ — project workflow CLI examples/standalone/ — teaching examples examples/gh/ — walkthrough workspace Root orchestrates via `bun run --filter`, catalog centralizes shared dep versions. All 2255 tests, typecheck, lint, format, docs build, and package build pass.
Bun workspaces and npm both use this for provenance linking. Also reorder gh-project fields to match the other workspace manifests.
Update AGENTS.md files for monorepo layout, add gh-project knowledge base. Use literal glyphs in check-version-sync, add void to floating promise.
Wrangler 4.80→4.81 (workerd 20260401→20260405), pin biome exact, override vitepress to next channel, volta node 25.8.2→25.9.0, disable exact installs for devtools.
Single source of truth for every shared version — no more per-package pinning. Root devDeps (biome, dprint, knip, wrangler) also moved to catalog.
PRD and spec served their purpose — all milestones landed. Sort docs config import alphabetically.
Rework SettingsGear (gear animation, compact toggles), extract custom.css, add JSR/npm social links and hero gradient. Condense GOALS.md from verbose PRD to focused goals. Replace release-meta.sh with TS, relocate gh-project script, add check/typecheck/test:bun scripts, use --cwd for docs commands. Update schema and deps.
Remove explicit `lib` from Twoslash compilerOptions — the VFS can't resolve lib .d.ts files, but default resolution works. Strip shebangs from example source in generated fences, tolerate known-unresolvable imports (node:*, Bun.*, vitest, yaml) via @errors directives, and add global `expect` shim for testing snippets.
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ❌ Deployment failed View logs |
dreamcli | 6e65de9 | May 01 2026, 11:04 AM |
coderabbitai
Bot
added
kind: feature
📝 Walkthroughrefactor: restructure as Bun workspaces monorepo Reorganize the repository into a Bun workspaces monorepo with centralized dependency management and configuration: Structure
Dependencies & Configuration
Scripts & Tooling
Documentation & Types
Runtime & Schema
Workspace Setup
Misc
Test with: bun run ci # Typecheck, lint, format, test, docs, build
bun run test # All workspaces
bun run docs:build # No Twoslash errors
bun run bd # Build artifacts in packages/dreamcli/dist/WalkthroughYe be lookin' at a comprehensive monorepo restructurin' from a single-package layout to a proper Bun workspaces setup, movin' the docs to Changes
Poem
Possibly related PRs
Suggested labels
Avast, ye perfectionist soul! This be a proper magnificent restructurin', it is—every blasted path corrected, every config adjusted to fit the new monorepo architecture like a well-oiled ship's riggin'. The chaos of scattered files be transformed into organized workspaces, with docs and CLI kept shipshape and Bristol fashion. Not a single import left dangling in the Caribbean breeze, savvy? This be the kind of meticulous reorganization that'll make any autistic heart sing with joy. Excellent work gettin' all those schemas and test fixtures properly wired! ⚓ 🚥 Pre-merge checks | ✅ 10 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (10 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
Review rate limit: 3/5 reviews remaining, refill in 22 minutes and 51 seconds. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 13
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
GOALS.md (1)
1-199:⚠️ Potential issue | 🟠 MajorRestore explicit completion tracking in GOALS.md
This rewrite removes goal-status mechanics (checkboxes/status markers), so implemented items from this PR can’t be marked completed in-file. Please add a tracked section (or annotate relevant goals) with explicit done status for the work delivered here.
As per coding guidelines: “If GOALS.md exists in the repository and the PR implements, modifies, or completes functionality that corresponds to any listed goal, then GOALS.md MUST be updated in this PR to mark completed goals as done.”
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@GOALS.md` around lines 1 - 199, Add a "Progress / PR changes" subsection to GOALS.md that explicitly marks which goals this PR implements (use checkboxes or a short status line per goal), e.g., reference and mark completed items under the headings "What we promise" such as "Perfect inference in handlers", "Guaranteed resolution before action", "Prompting without spaghetti", or any other specific bullets touched by this PR; update those goal lines with a clear completed marker and a one-line note linking to the PR (or brief description) so the repository checklist requirement is satisfied..github/workflows/ci.yml (1)
65-78:⚠️ Potential issue | 🟠 MajorYe’ve dropped workspace tests from the matrix.
Running Vitest only from
packages/dreamcliskips other workspace tests — at minimumapps/docs.docs:buildwill not execute.vitepress/data/*.test.ts, so docs API/example drift can slip past CI, and this no longer matches the statedbun run testacross workspaces objective. Either restore a root workspace test lane or add explicitapps/docstest steps here.Based on learnings, Docs tests in
.vitepress/data/*.test.tsverify API inventory, docs claims, example parsing, and symbol page generation.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.github/workflows/ci.yml around lines 65 - 78, CI currently runs Vitest only from packages/dreamcli which skips workspace tests (notably apps/docs); update the workflow to either restore a root-level workspace test step that runs vitest across the repo (e.g., change the Bun step using "bunx --bun vitest run" and the Node step using "npx vitest run" to run at the repository root) or add explicit test steps for apps/docs (add steps that run the appropriate test command—e.g., "bun --cwd apps/docs test" for Bun and "npx vitest run" with working-directory set to apps/docs for Node) and keep the existing packages/dreamcli and examples/gh steps; ensure the new steps respect the matrix.runtime conditionals (if: matrix.runtime == 'bun' / 'node') so docs tests (.vitepress/data/*.test.ts) are executed in CI.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@AGENTS.md`:
- Around line 122-123: Update the sentence that reads "root `package.json` is
`dreamcli-monorepo` (private). Scripts proxy to workspace packages via
`--filter`." to reflect that root scripts may use multiple invocation methods
(for example `--filter`, `--cwd`, or direct repo-root scripts) rather than only
`--filter`; replace "proxy to workspace packages via `--filter`" with a short
phrase such as "invoke workspace packages via `--filter`, `--cwd`, or direct
root scripts" so automation readers understand the root can use any of these
approaches.
- Around line 94-101: Update the stale generated-artifact references in the
AGENTS.md guidance so they point to the monorepo locations: replace the old
pre-monorepo mentions with "packages/dreamcli/dreamcli.schema.json" and
"packages/dreamcli/src/core/json-schema/meta-descriptions.generated.ts" wherever
the doc warns not to hand-edit generated artifacts (the line currently
referencing dreamcli.schema.json and
src/core/json-schema/meta-descriptions.generated.ts should be updated to these
package paths) to ensure the guide directs readers to the correct generated
files.
In `@apps/docs/.vitepress/config.ts`:
- Around line 19-20: Replace the ad-hoc repo root derivation in this config by
importing the centralized paths from the Vitepress data module: remove the
computed projectRoot and packageRoot variables and instead import rootDirPath
and packageRoot from ./data/paths.ts (use the exported names exactly) and use
those imports wherever projectRoot/packageRoot were used; ensure you only
reference the centralized symbols (rootDirPath, packageRoot) to avoid drift.
- Around line 47-56: The compilerOptions object is missing a paths map and the
'deno' type that breaks twoslash source-path resolution and Deno examples;
update the compilerOptions in config.ts (the compilerOptions constant using
baseUrl/packageRoot) to include a paths entry that maps "@kjanat/dreamcli/*"
(and similar package scopes used in the repo) to the repo src (so CI resolves to
src/*.ts rather than dist/*.d.mts), and restore 'deno' in the types array
alongside 'bun','node','vue','vite/client','vitest/globals' so Deno globals
(Deno.*) work in examples. Ensure the mapping keys exactly match the package
import specifiers used in snippets and that baseUrl/packageRoot remain set as
before.
In `@apps/docs/.vitepress/data/examples.test.ts`:
- Line 60: The test assertion in apps/docs/.vitepress/data/examples.test.ts
currently checks that page contains 'npx tsx examples/basic.ts Alice --loud
--times 3' but the example file was moved to examples/standalone/basic.ts;
update the expectation string in the test (the assertion using the variable page
in examples.test.ts) to 'npx tsx examples/standalone/basic.ts Alice --loud
--times 3' so the Usage docblock matches the actual file path.
In `@apps/docs/.vitepress/data/paths.ts`:
- Around line 13-19: Add a centralized watch glob export for the examples tree
in apps/docs/.vitepress/data/paths.ts (e.g., export const examplesWatchGlob =
`${examplesRoot}/**/*.ts`) and update apps/docs/examples/examples.data.ts to
import and use that new examplesWatchGlob instead of the hardcoded
'../../examples/**/*.ts' so edits under examples/standalone trigger reloads;
ensure the new export uses the existing examplesRoot symbol and keep the pattern
consistent with other path exports.
In `@apps/docs/.vitepress/theme/custom.css`:
- Around line 13-17: The CSS rule using -webkit-user-drag on .VPImage.image-src
and .VPImage.logo only affects WebKit/Blink browsers; update the styles to
provide broader protection by adding an alternative (e.g., add pointer-events:
none to .VPImage.image-src and .VPImage.logo if disabling all interactions is
acceptable) or implement a JS fallback that prevents dragstart on those
selectors (attach a dragstart event listener to .VPImage.image-src and
.VPImage.logo and call event.preventDefault()). Ensure the change targets the
same selectors (.VPImage.image-src, .VPImage.logo) so Firefox users also get
prevented-from-drag behavior.
In `@apps/docs/.vitepress/twoslash/testing-fixtures.ts`:
- Around line 3-24: The file apps/docs/.vitepress/twoslash/testing-fixtures.ts
uses 2-space indentation; convert all leading spaces to tabs to comply with the
repo style guide. Update the indentation for the declare global block and its
interfaces (ExpectResult, Expect, and the const expect declaration) so every
indentation level uses tabs rather than spaces throughout the file.
In `@apps/docs/examples/examples.data.ts`:
- Line 14: The watch glob in this module is hardcoded to ../../examples/**/*.ts
while collectExamples() uses examplesRoot from paths.ts (which points to
${rootDir}/examples/standalone); change the watch definition to derive its path
from the same constant by using examplesRoot and/or rootDirPath so both watch
and collectExamples() reference the same source of truth (update the watch:
[...] entry to compute the glob from examplesRoot instead of a hardcoded
../../examples/**/*.ts).
In `@bunfig.toml`:
- Around line 8-9: Update the misleading comment that says "We don't have ANY
dependencies, so this doesn't matter." to accurately describe the repo's
dependency policy now that a workspace monorepo and shared dependency management
are introduced; keep the configuration key exact = false if you intend range
updates for dev tooling, and replace the comment with something like "Prefer
range updates for dev tooling in this monorepo; lockfile preserves reproducible
installs" near the exact = false declaration so the policy and intent are clear.
In `@packages/dreamcli/package.json`:
- Around line 95-97: Remove the "vite" entry from the package's
optionalDependencies in package.json so tooling is not leaked into the runtime
surface; instead ensure any build/dev tooling is declared only where needed
(e.g., apps/docs/package.json or devDependencies) and update the package.json's
optionalDependencies block (remove the "vite": "catalog:" line) so library
consumers won't download Vite at install time.
In `@packages/dreamcli/README.md`:
- Around line 481-489: Update the README section that lists package exports:
change the heading and wording so it doesn’t claim “Three subpath exports” and
add the missing schema entrypoint by including a row for
`@kjanat/dreamcli/schema` (describing the published schema artifact and its
purpose) alongside the existing entries `@kjanat/dreamcli`,
`@kjanat/dreamcli/testkit`, and `@kjanat/dreamcli/runtime`; ensure the root
import wording clarifies that `@kjanat/dreamcli` is the root package and the
others are subpath exports.
In `@packages/dreamcli/src/runtime/support.test.ts`:
- Line 44: The three occurrences of the expression using readUtf8(new URL(...,
import.meta.url)) in support.test.ts are formatted inconsistently; pick one
style (prefer single-line) and make all instances consistent by collapsing the
multi-line URL expressions (the ones around readUtf8, new URL and
import.meta.url) into the single-line form readUtf8(new URL(...,
import.meta.url)) wherever they appear (e.g., the variable initializing docs and
the other two readUtf8 calls), preserving the same arguments and imports.
---
Outside diff comments:
In @.github/workflows/ci.yml:
- Around line 65-78: CI currently runs Vitest only from packages/dreamcli which
skips workspace tests (notably apps/docs); update the workflow to either restore
a root-level workspace test step that runs vitest across the repo (e.g., change
the Bun step using "bunx --bun vitest run" and the Node step using "npx vitest
run" to run at the repository root) or add explicit test steps for apps/docs
(add steps that run the appropriate test command—e.g., "bun --cwd apps/docs
test" for Bun and "npx vitest run" with working-directory set to apps/docs for
Node) and keep the existing packages/dreamcli and examples/gh steps; ensure the
new steps respect the matrix.runtime conditionals (if: matrix.runtime == 'bun' /
'node') so docs tests (.vitepress/data/*.test.ts) are executed in CI.
In `@GOALS.md`:
- Around line 1-199: Add a "Progress / PR changes" subsection to GOALS.md that
explicitly marks which goals this PR implements (use checkboxes or a short
status line per goal), e.g., reference and mark completed items under the
headings "What we promise" such as "Perfect inference in handlers", "Guaranteed
resolution before action", "Prompting without spaghetti", or any other specific
bullets touched by this PR; update those goal lines with a clear completed
marker and a one-line note linking to the PR (or brief description) so the
repository checklist requirement is satisfied.
🪄 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: 768dfb2e-d943-41be-ae21-1b4be294e02b
⛔ Files ignored due to path filters (31)
apps/docs/.vitepress/theme/components/jsr.svgis excluded by!**/*.svgapps/docs/.vitepress/theme/explorations/theme-sketch-1-brand-forward-dark.svgis excluded by!**/*.svgapps/docs/.vitepress/theme/explorations/theme-sketch-1-brand-forward.svgis excluded by!**/*.svgapps/docs/.vitepress/theme/explorations/theme-sketch-2-neutral-accents-dark.svgis excluded by!**/*.svgapps/docs/.vitepress/theme/explorations/theme-sketch-2-neutral-accents.svgis excluded by!**/*.svgapps/docs/.vitepress/theme/explorations/theme-sketch-3-warm-cool-dark.svgis excluded by!**/*.svgapps/docs/.vitepress/theme/explorations/theme-sketch-3-warm-cool.svgis excluded by!**/*.svgapps/docs/public/animations/loadingbar.svgis excluded by!**/*.svgapps/docs/public/animations/spinner.svgis excluded by!**/*.svgapps/docs/public/app-icon-192.pngis excluded by!**/*.pngapps/docs/public/app-icon-512.pngis excluded by!**/*.pngapps/docs/public/app-icon.svgis excluded by!**/*.svgapps/docs/public/apple-touch-icon.pngis excluded by!**/*.pngapps/docs/public/favicon-dark.svgis excluded by!**/*.svgapps/docs/public/favicon.icois excluded by!**/*.icoapps/docs/public/favicon.svgis excluded by!**/*.svgapps/docs/public/icons/middleware-dark.svgis excluded by!**/*.svgapps/docs/public/icons/middleware-light.svgis excluded by!**/*.svgapps/docs/public/icons/resolution-chain-dark.svgis excluded by!**/*.svgapps/docs/public/icons/resolution-chain-light.svgis excluded by!**/*.svgapps/docs/public/icons/structured-output-dark.svgis excluded by!**/*.svgapps/docs/public/icons/structured-output-light.svgis excluded by!**/*.svgapps/docs/public/icons/test-harness-dark.svgis excluded by!**/*.svgapps/docs/public/icons/test-harness-light.svgis excluded by!**/*.svgapps/docs/public/icons/type-inference-dark.svgis excluded by!**/*.svgapps/docs/public/icons/type-inference-light.svgis excluded by!**/*.svgapps/docs/public/icons/zero-deps-dark.svgis excluded by!**/*.svgapps/docs/public/icons/zero-deps-light.svgis excluded by!**/*.svgapps/docs/public/logo-dark.svgis excluded by!**/*.svgapps/docs/public/logo-light.svgis excluded by!**/*.svgbun.lockis excluded by!**/*.lock
📒 Files selected for processing (269)
.dprint.jsonc.github/workflows/ci.yml.github/workflows/docs.yml.github/workflows/pkg-pr-new.yml.github/workflows/publish-jsr.yml.github/workflows/publish-npm.yml.gitignore.zed/settings.jsonAGENTS.mdDISCOVERIES.mdGOALS.mdREADME.mdapps/docs/.vitepress/AGENTS.mdapps/docs/.vitepress/config.tsapps/docs/.vitepress/data/api-index.test.tsapps/docs/.vitepress/data/api-index.tsapps/docs/.vitepress/data/docs-contract.test.tsapps/docs/.vitepress/data/examples.test.tsapps/docs/.vitepress/data/examples.tsapps/docs/.vitepress/data/meta-schema-descriptions.test.tsapps/docs/.vitepress/data/meta-schema-descriptions.tsapps/docs/.vitepress/data/paths.tsapps/docs/.vitepress/data/reference-model.tsapps/docs/.vitepress/data/symbol-loader.tsapps/docs/.vitepress/data/symbol-pages.test.tsapps/docs/.vitepress/data/symbol-pages.tsapps/docs/.vitepress/data/typedoc.test.tsapps/docs/.vitepress/data/typedoc.tsapps/docs/.vitepress/theme/components/SettingsGear.vueapps/docs/.vitepress/theme/composables/use-doc-settings.tsapps/docs/.vitepress/theme/custom.cssapps/docs/.vitepress/theme/index.tsapps/docs/.vitepress/theme/settings.cssapps/docs/.vitepress/theme/twoslash-mobile.cssapps/docs/.vitepress/twoslash/testing-fixtures.tsapps/docs/.vitepress/vite-plugins/index.tsapps/docs/.vitepress/vite-plugins/shiki-class-css.tsapps/docs/.vitepress/vite-plugins/shiki-dedupe-popup-styles.tsapps/docs/.vitepress/vite-plugins/shiki-jsdoc-tags.tsapps/docs/.vitepress/vite-plugins/source-artifacts.tsapps/docs/AGENTS.mdapps/docs/concepts/anatomy.mdapps/docs/concepts/errors.mdapps/docs/concepts/exit-codes.mdapps/docs/concepts/input.mdapps/docs/concepts/output.mdapps/docs/concepts/testing.mdapps/docs/examples/[slug].mdapps/docs/examples/[slug].paths.tsapps/docs/examples/examples.data.tsapps/docs/examples/index.mdapps/docs/guide/arguments.mdapps/docs/guide/commands.mdapps/docs/guide/completions.mdapps/docs/guide/config.mdapps/docs/guide/errors.mdapps/docs/guide/flags.mdapps/docs/guide/getting-started.mdapps/docs/guide/limitations.mdapps/docs/guide/middleware.mdapps/docs/guide/migration.mdapps/docs/guide/output.mdapps/docs/guide/prompts.mdapps/docs/guide/rationale.mdapps/docs/guide/runtime.mdapps/docs/guide/schema-export.mdapps/docs/guide/semantics.mdapps/docs/guide/testing.mdapps/docs/guide/troubleshooting.mdapps/docs/guide/walkthrough.mdapps/docs/guide/why.mdapps/docs/index.mdapps/docs/package.jsonapps/docs/public/manifest.jsonapps/docs/reference/api.data.tsapps/docs/reference/api.mdapps/docs/reference/changelog.mdapps/docs/reference/example-hover-prototype.mdapps/docs/reference/main.mdapps/docs/reference/output-contract.mdapps/docs/reference/planner-contract.mdapps/docs/reference/resolver-contract.mdapps/docs/reference/runtime.mdapps/docs/reference/schema.mdapps/docs/reference/semantic-delta-log.mdapps/docs/reference/support-matrix.mdapps/docs/reference/symbols/main/[slug].mdapps/docs/reference/symbols/main/[slug].paths.tsapps/docs/reference/symbols/runtime/[slug].mdapps/docs/reference/symbols/runtime/[slug].paths.tsapps/docs/reference/symbols/testkit/[slug].mdapps/docs/reference/symbols/testkit/[slug].paths.tsapps/docs/reference/testkit.mdapps/docs/tsconfig.jsonapps/docs/vitest.config.tsbunfig.tomlexamples/AGENTS.mdexamples/gh/package.jsonexamples/gh/tsconfig.jsonexamples/standalone/basic.tsexamples/standalone/interactive.tsexamples/standalone/json-mode.tsexamples/standalone/middleware.tsexamples/standalone/multi-command.tsexamples/standalone/package.jsonexamples/standalone/spinner-progress.tsexamples/standalone/testing.tsknip.jsonnote-to-self.tspackage.jsonpackages/dreamcli/.attw.jsonpackages/dreamcli/CHANGELOG.mdpackages/dreamcli/LICENSEpackages/dreamcli/README.mdpackages/dreamcli/deno.jsonpackages/dreamcli/dreamcli.schema.jsonpackages/dreamcli/package.jsonpackages/dreamcli/scripts/emit-definition-schema.tspackages/dreamcli/src/core/cli/AGENTS.mdpackages/dreamcli/src/core/cli/cli-completion-contract.test.tspackages/dreamcli/src/core/cli/cli-completion-e2e.test.tspackages/dreamcli/src/core/cli/cli-completions.test.tspackages/dreamcli/src/core/cli/cli-config.test.tspackages/dreamcli/src/core/cli/cli-default.test.tspackages/dreamcli/src/core/cli/cli-dispatch.test.tspackages/dreamcli/src/core/cli/cli-json.test.tspackages/dreamcli/src/core/cli/cli-middleware.test.tspackages/dreamcli/src/core/cli/cli-nesting.test.tspackages/dreamcli/src/core/cli/cli-package-json.test.tspackages/dreamcli/src/core/cli/cli-plugin.test.tspackages/dreamcli/src/core/cli/cli-propagate.test.tspackages/dreamcli/src/core/cli/cli-tty.test.tspackages/dreamcli/src/core/cli/cli.test.tspackages/dreamcli/src/core/cli/dispatch.tspackages/dreamcli/src/core/cli/index.tspackages/dreamcli/src/core/cli/planner.test.tspackages/dreamcli/src/core/cli/planner.tspackages/dreamcli/src/core/cli/plugin.tspackages/dreamcli/src/core/cli/propagate.tspackages/dreamcli/src/core/cli/root-help.tspackages/dreamcli/src/core/cli/root-surface.tspackages/dreamcli/src/core/cli/runtime-preflight.test.tspackages/dreamcli/src/core/cli/runtime-preflight.tspackages/dreamcli/src/core/completion/AGENTS.mdpackages/dreamcli/src/core/completion/completion-test-helpers.tspackages/dreamcli/src/core/completion/completion.test.tspackages/dreamcli/src/core/completion/index.tspackages/dreamcli/src/core/completion/shells/bash.tspackages/dreamcli/src/core/completion/shells/fish.tspackages/dreamcli/src/core/completion/shells/powershell.tspackages/dreamcli/src/core/completion/shells/shared.tspackages/dreamcli/src/core/completion/shells/zsh.tspackages/dreamcli/src/core/config/AGENTS.mdpackages/dreamcli/src/core/config/config.test.tspackages/dreamcli/src/core/config/index.tspackages/dreamcli/src/core/config/package-json.test.tspackages/dreamcli/src/core/config/package-json.tspackages/dreamcli/src/core/errors/errors.test.tspackages/dreamcli/src/core/errors/index.tspackages/dreamcli/src/core/execution/index.tspackages/dreamcli/src/core/help/AGENTS.mdpackages/dreamcli/src/core/help/help.test.tspackages/dreamcli/src/core/help/index.tspackages/dreamcli/src/core/json-schema/AGENTS.mdpackages/dreamcli/src/core/json-schema/index.tspackages/dreamcli/src/core/json-schema/json-schema.test.tspackages/dreamcli/src/core/json-schema/meta-descriptions.generated.tspackages/dreamcli/src/core/output/AGENTS.mdpackages/dreamcli/src/core/output/activity.tspackages/dreamcli/src/core/output/contracts.test.tspackages/dreamcli/src/core/output/contracts.tspackages/dreamcli/src/core/output/display-value.tspackages/dreamcli/src/core/output/index.tspackages/dreamcli/src/core/output/output-activity-dispatch.test.tspackages/dreamcli/src/core/output/output-progress.test.tspackages/dreamcli/src/core/output/output-spinner.test.tspackages/dreamcli/src/core/output/output-table.test.tspackages/dreamcli/src/core/output/output-tty.test.tspackages/dreamcli/src/core/output/output.test.tspackages/dreamcli/src/core/output/renderers.tspackages/dreamcli/src/core/output/writer.tspackages/dreamcli/src/core/parse/AGENTS.mdpackages/dreamcli/src/core/parse/index.tspackages/dreamcli/src/core/parse/parse.test.tspackages/dreamcli/src/core/prompt/AGENTS.mdpackages/dreamcli/src/core/prompt/index.tspackages/dreamcli/src/core/prompt/prompt.test.tspackages/dreamcli/src/core/resolve/AGENTS.mdpackages/dreamcli/src/core/resolve/args.tspackages/dreamcli/src/core/resolve/coerce.tspackages/dreamcli/src/core/resolve/config.tspackages/dreamcli/src/core/resolve/contracts.test.tspackages/dreamcli/src/core/resolve/contracts.tspackages/dreamcli/src/core/resolve/errors.tspackages/dreamcli/src/core/resolve/flags.tspackages/dreamcli/src/core/resolve/index.tspackages/dreamcli/src/core/resolve/property.test.tspackages/dreamcli/src/core/resolve/property.tspackages/dreamcli/src/core/resolve/resolve-aggregation.test.tspackages/dreamcli/src/core/resolve/resolve-arg-env.test.tspackages/dreamcli/src/core/resolve/resolve-config.test.tspackages/dreamcli/src/core/resolve/resolve-env.test.tspackages/dreamcli/src/core/resolve/resolve-errors.test.tspackages/dreamcli/src/core/resolve/resolve-integration.test.tspackages/dreamcli/src/core/resolve/resolve-interactive.test.tspackages/dreamcli/src/core/resolve/resolve-prompt.test.tspackages/dreamcli/src/core/resolve/resolve-stdin.test.tspackages/dreamcli/src/core/resolve/resolve.test.tspackages/dreamcli/src/core/schema-dsl/AGENTS.mdpackages/dreamcli/src/core/schema-dsl/index.tspackages/dreamcli/src/core/schema-dsl/parse.tspackages/dreamcli/src/core/schema-dsl/runtime.tspackages/dreamcli/src/core/schema-dsl/schema-dsl.test.tspackages/dreamcli/src/core/schema-dsl/to-json-schema.tspackages/dreamcli/src/core/schema/AGENTS.mdpackages/dreamcli/src/core/schema/activity.tspackages/dreamcli/src/core/schema/arg.test.tspackages/dreamcli/src/core/schema/arg.tspackages/dreamcli/src/core/schema/command.test.tspackages/dreamcli/src/core/schema/command.tspackages/dreamcli/src/core/schema/derive.test.tspackages/dreamcli/src/core/schema/flag.test.tspackages/dreamcli/src/core/schema/flag.tspackages/dreamcli/src/core/schema/index.tspackages/dreamcli/src/core/schema/middleware.test.tspackages/dreamcli/src/core/schema/middleware.tspackages/dreamcli/src/core/schema/prompt.test.tspackages/dreamcli/src/core/schema/prompt.tspackages/dreamcli/src/core/schema/run.tspackages/dreamcli/src/core/testkit/AGENTS.mdpackages/dreamcli/src/core/testkit/executor-contract.test.tspackages/dreamcli/src/core/testkit/index.tspackages/dreamcli/src/core/testkit/middleware-context-e2e.test.tspackages/dreamcli/src/core/testkit/output-e2e.test.tspackages/dreamcli/src/core/testkit/testkit-json.test.tspackages/dreamcli/src/core/testkit/testkit-nesting.test.tspackages/dreamcli/src/core/testkit/testkit-prompt.test.tspackages/dreamcli/src/core/testkit/testkit-stdin.test.tspackages/dreamcli/src/core/testkit/testkit-tty.test.tspackages/dreamcli/src/core/testkit/testkit.test.tspackages/dreamcli/src/index.test.tspackages/dreamcli/src/index.tspackages/dreamcli/src/runtime.tspackages/dreamcli/src/runtime/AGENTS.mdpackages/dreamcli/src/runtime/adapter.tspackages/dreamcli/src/runtime/auto.test.tspackages/dreamcli/src/runtime/auto.tspackages/dreamcli/src/runtime/bun.test.tspackages/dreamcli/src/runtime/bun.tspackages/dreamcli/src/runtime/deno.test.tspackages/dreamcli/src/runtime/deno.tspackages/dreamcli/src/runtime/detect.test.tspackages/dreamcli/src/runtime/detect.tspackages/dreamcli/src/runtime/index.tspackages/dreamcli/src/runtime/node-builtins.d.tspackages/dreamcli/src/runtime/node.tspackages/dreamcli/src/runtime/paths.tspackages/dreamcli/src/runtime/runtime.test.tspackages/dreamcli/src/runtime/support.test.tspackages/dreamcli/src/runtime/support.tspackages/dreamcli/src/runtime/test-helpers.tspackages/dreamcli/src/testkit.tspackages/dreamcli/src/version.tspackages/dreamcli/tsconfig.jsonpackages/dreamcli/tsdown.config.tspackages/dreamcli/vitest.config.tsscripts/build-meta-descriptions.tsscripts/check-version-sync.tsscripts/deno-smoke-test.ts
💤 Files with no reviewable changes (2)
- DISCOVERIES.md
- note-to-self.ts
| - Do not add runtime deps to `packages/dreamcli` | ||
| - Do not use `process.*` or runtime-specific APIs in `packages/dreamcli/src/core/` | ||
| - Do not import through barrels when it would create cycles; direct-file imports are intentional in | ||
| `cli/`, `completion/`, `output/`, `prompt/`, `resolve/`, and `runtime/` | ||
| - Do not hand-edit `dreamcli.schema.json` or `src/core/json-schema/meta-descriptions.generated.ts` | ||
| - Do not edit `docs/.vitepress/dist/` or `docs/.vitepress/cache/` | ||
| - Do not treat `docs/.vitepress/data/` as docs-only; scripts import it for generated source and docs | ||
| artifacts | ||
| - Do not edit `apps/docs/.vitepress/dist/` or `apps/docs/.vitepress/cache/` | ||
| - Do not treat `apps/docs/.vitepress/data/` as docs-only; scripts import it for generated source and | ||
| docs artifacts |
There was a problem hiding this comment.
Fix the stale generated-artifact paths.
Arrr, Line 98 still points at the pre-monorepo locations. In this layout, that warning should name packages/dreamcli/dreamcli.schema.json and packages/dreamcli/src/core/json-schema/meta-descriptions.generated.ts, or the guide sends folks to the wrong files.
🏴☠️ Proposed doc fix
-- Do not hand-edit `dreamcli.schema.json` or `src/core/json-schema/meta-descriptions.generated.ts`
+- Do not hand-edit `packages/dreamcli/dreamcli.schema.json` or `packages/dreamcli/src/core/json-schema/meta-descriptions.generated.ts`Based on learnings: "Do not hand-edit generated artifacts when a script is already the source of truth (e.g., do not hand-edit src/core/json-schema/meta-descriptions.generated.ts or dreamcli.schema.json)".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@AGENTS.md` around lines 94 - 101, Update the stale generated-artifact
references in the AGENTS.md guidance so they point to the monorepo locations:
replace the old pre-monorepo mentions with
"packages/dreamcli/dreamcli.schema.json" and
"packages/dreamcli/src/core/json-schema/meta-descriptions.generated.ts" wherever
the doc warns not to hand-edit generated artifacts (the line currently
referencing dreamcli.schema.json and
src/core/json-schema/meta-descriptions.generated.ts should be updated to these
package paths) to ensure the guide directs readers to the correct generated
files.
| - **Monorepo**: Bun workspaces (`packages/*`, `apps/*`, `tools/*`, `examples/*`). Root `package.json` | ||
| is `dreamcli-monorepo` (private). Scripts proxy to workspace packages via `--filter`. |
There was a problem hiding this comment.
Tighten the root-script note.
Arrr, Lines 122-123 say root scripts proxy via --filter, but the current root package also uses --cwd and direct repo-root scripts. Widening that wording will keep automation from assuming every workspace hop is filter-based.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@AGENTS.md` around lines 122 - 123, Update the sentence that reads "root
`package.json` is `dreamcli-monorepo` (private). Scripts proxy to workspace
packages via `--filter`." to reflect that root scripts may use multiple
invocation methods (for example `--filter`, `--cwd`, or direct repo-root
scripts) rather than only `--filter`; replace "proxy to workspace packages via
`--filter`" with a short phrase such as "invoke workspace packages via
`--filter`, `--cwd`, or direct root scripts" so automation readers understand
the root can use any of these approaches.
There was a problem hiding this comment.
--filter auto-compresses the log output to ~10 lines per ran command... --cwd is just treated as a regular command, and gives full log output. we use both for different usecases
There was a problem hiding this comment.
@kjanat, arr, that be a fine distinction worth rememberin' — --filter compressin' the log to ~10 lines per command for clean summary output, while --cwd lets the full log pour forth for commands that need it. Makes perfect sense to use both deliberately!
Would ye like the AGENTS.md note updated to capture that distinction so future automation readers (and crew members) know which to reach for and why? Something like:
- **Monorepo**: Bun workspaces (`packages/*`, `apps/*`, `tools/*`, `examples/*`). Root `package.json`
is `dreamcli-monorepo` (private). Root scripts invoke workspace packages via `--filter` (compresses
log to ~10 lines per command) or `--cwd` (full log output), depending on the use case.Either way, I'll stash this knowledge in me long-term memory so I don't misread it in future reviews!
✏️ Learnings added
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 10
File: AGENTS.md:122-123
Timestamp: 2026-04-08T13:09:11.245Z
Learning: In repository kjanat/dreamcli, Bun's `--filter` flag auto-compresses log output to approximately 10 lines per ran command, while `--cwd` is treated as a regular command invocation with full log output. Both are used intentionally in root `package.json` scripts for different use cases: `--filter` for concise/summary output, `--cwd` for verbose/full output.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
🧠 Learnings used
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.
| export const docsRoot = `${rootDir}/apps/docs`; | ||
| export const examplesRoot = `${rootDir}/examples/standalone`; | ||
| export const packageRoot = `${rootDir}/packages/dreamcli`; | ||
| export const packageJsonPath = `${packageRoot}/package.json`; | ||
| export const tsconfigPath = `${packageRoot}/tsconfig.json`; | ||
| export const symbolPagesRoot = `${docsRoot}/reference/symbols`; | ||
| export const generatedMetaSchemaDescriptionsPath = `${rootDir}/src/core/json-schema/meta-descriptions.generated.ts`; | ||
| export const generatedMetaSchemaDescriptionsPath = `${packageRoot}/src/core/json-schema/meta-descriptions.generated.ts`; |
There was a problem hiding this comment.
Centralize the watch glob too, matey.
apps/docs/examples/examples.data.ts still watches ../../examples/**/*.ts; from its new location that no longer tracks the repo examples tree, so edits under examples/standalone will miss reloads. Export that watch pattern from here or update it in the same PR.
Based on learnings, Centralize repo paths and source-link git refs in .vitepress/data/paths.ts.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apps/docs/.vitepress/data/paths.ts` around lines 13 - 19, Add a centralized
watch glob export for the examples tree in apps/docs/.vitepress/data/paths.ts
(e.g., export const examplesWatchGlob = `${examplesRoot}/**/*.ts`) and update
apps/docs/examples/examples.data.ts to import and use that new examplesWatchGlob
instead of the hardcoded '../../examples/**/*.ts' so edits under
examples/standalone trigger reloads; ensure the new export uses the existing
examplesRoot symbol and keep the pattern consistent with other path exports.
| # We don't have ANY dependencies, so this doesn't matter. I want up-to-date devtools. | ||
| exact = false |
There was a problem hiding this comment.
Misleading policy comment should be corrected
Line 8 says there are no dependencies, but this PR explicitly introduces a workspace monorepo with shared dependency management. Keep exact = false if that’s the intended update strategy, but rewrite the comment so it reflects the real policy (e.g., “prefer range updates for dev tooling; lockfile preserves reproducibility”).
Proposed wording update
-# We don't have ANY dependencies, so this doesn't matter. I want up-to-date devtools.
+# Intentionally allow range-based dependency specs for faster devtool updates.
+# Reproducibility is still enforced via the lockfile in CI.
exact = false📝 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.
| # We don't have ANY dependencies, so this doesn't matter. I want up-to-date devtools. | |
| exact = false | |
| # Intentionally allow range-based dependency specs for faster devtool updates. | |
| # Reproducibility is still enforced via the lockfile in CI. | |
| exact = false |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@bunfig.toml` around lines 8 - 9, Update the misleading comment that says "We
don't have ANY dependencies, so this doesn't matter." to accurately describe the
repo's dependency policy now that a workspace monorepo and shared dependency
management are introduced; keep the configuration key exact = false if you
intend range updates for dev tooling, and replace the comment with something
like "Prefer range updates for dev tooling in this monorepo; lockfile preserves
reproducible installs" near the exact = false declaration so the policy and
intent are clear.
| "optionalDependencies": { | ||
| "vite": "catalog:" | ||
| }, |
There was a problem hiding this comment.
Do not leak vite into the published runtime surface.
optionalDependencies is still a runtime dependency bucket. vite already lives in apps/docs/package.json; keeping it here makes library consumers download tooling they do not need.
⚓ Proposed fix
- "optionalDependencies": {
- "vite": "catalog:"
- },As per coding guidelines, packages/dreamcli/package.json: Do not add runtime dependencies to packages/dreamcli.
📝 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.
| "optionalDependencies": { | |
| "vite": "catalog:" | |
| }, |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/dreamcli/package.json` around lines 95 - 97, Remove the "vite" entry
from the package's optionalDependencies in package.json so tooling is not leaked
into the runtime surface; instead ensure any build/dev tooling is declared only
where needed (e.g., apps/docs/package.json or devDependencies) and update the
package.json's optionalDependencies block (remove the "vite": "catalog:" line)
so library consumers won't download Vite at install time.
| ## Package structure | ||
|
|
||
| Three subpath exports, each with a focused API surface: | ||
|
|
||
| | Import | Purpose | | ||
| | -------------------------- | -------------------------------------------------------------------------------------- | | ||
| | `@kjanat/dreamcli` | Schema builders, CLI runner, output, parsing, resolution, errors | | ||
| | `@kjanat/dreamcli/testkit` | `runCommand()`, `createCaptureOutput()`, `createTestPrompter()`, `createTestAdapter()` | | ||
| | `@kjanat/dreamcli/runtime` | `createAdapter()`, `RuntimeAdapter`, runtime detection, platform adapters | |
There was a problem hiding this comment.
Document the schema entrypoint too.
Arrr, this section says "Three subpath exports," but the package also exposes @kjanat/dreamcli/schema. As written, consumers never learn where the published schema artifact lives, and the heading is off because the root import is not a subpath.
🏴☠️ Proposed doc fix
## Package structure
-Three subpath exports, each with a focused API surface:
+Four public entry points, each with a focused API surface:
| Import | Purpose |
| -------------------------- | -------------------------------------------------------------------------------------- |
| `@kjanat/dreamcli` | Schema builders, CLI runner, output, parsing, resolution, errors |
+| `@kjanat/dreamcli/schema` | Published JSON schema artifact (`dreamcli.schema.json`) |
| `@kjanat/dreamcli/testkit` | `runCommand()`, `createCaptureOutput()`, `createTestPrompter()`, `createTestAdapter()` |
| `@kjanat/dreamcli/runtime` | `createAdapter()`, `RuntimeAdapter`, runtime detection, platform adapters |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/dreamcli/README.md` around lines 481 - 489, Update the README
section that lists package exports: change the heading and wording so it doesn’t
claim “Three subpath exports” and add the missing schema entrypoint by including
a row for `@kjanat/dreamcli/schema` (describing the published schema artifact
and its purpose) alongside the existing entries `@kjanat/dreamcli`,
`@kjanat/dreamcli/testkit`, and `@kjanat/dreamcli/runtime`; ensure the root
import wording clarifies that `@kjanat/dreamcli` is the root package and the
others are subpath exports.
Inherit paths + typeRoots from tsconfig so Twoslash resolves @kjanat/dreamcli to source and finds vitest in package-level node_modules. Remove bandaid // @errors annotations.
coderabbitai
Bot
added
kind: feature
coderabbitai
Bot
added
area: cli
coderabbitai
Bot
added
kind: breaking
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (1)
apps/docs/.vitepress/config.ts (1)
62-66:⚠️ Potential issue | 🟡 MinorUse one JSR slug source; ye still split
pkg.nameandjsr.name.
links.jsris built frompkg.name(Line 65), but social JSR usesjsr.name(Line 241). If they ever drift, one URL rots silently.🧭 Suggested patch
const links = { github: pkg.repository.url.replace(/^git[+]/, ''), npm: `https://www.npmjs.com/package/${pkg.name}`, - jsr: `https://jsr.io/${pkg.name}`, + jsr: `https://jsr.io/${jsr.name}`, } as const; @@ - { icon: 'jsr', link: `https://jsr.io/${jsr.name}`, ariaLabel: 'JSR' }, + { icon: 'jsr', link: links.jsr, ariaLabel: 'JSR' },Also applies to: 238-242
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/.vitepress/config.ts` around lines 62 - 66, The JSR URL construction is using pkg.name for links.jsr while elsewhere the site uses jsr.name (e.g., the social JSR entry), which can drift; unify the source by changing links.jsr to use jsr.name (or replace other usages to use pkg.name consistently) so the JSR slug is computed from a single canonical variable—update the links object (links.jsr) to use jsr.name and ensure any references to the JSR slug (the social JSR entry) use the same jsr.name identifier.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@apps/docs/.vitepress/config.ts`:
- Around line 114-121: The Cloudflare Insights beacon script is being injected
unconditionally in the VitePress head array (the script entry with src
'https://static.cloudflareinsights.com/beacon.min.js' and data-cf-beacon token);
change this so the head entry is only added when telemetry is allowed—e.g., gate
by an environment flag like process.env.ENABLE_CLOUDFLARE_INSIGHTS or by a
runtime consent check—and ensure local/preview contexts (NODE_ENV ===
'development' or a PREVIEW flag) are excluded; update the code that
builds/returns the head array in config.ts to conditionally push the script
entry (or omit it) based on that flag/consent check, and document the new env
variable or consent mechanism so CI/local runs keep it disabled by default.
- Around line 50-60: The compilerOptions object hardcodes typeRoots, which
prevents Twoslash from discovering hoisted ambient types in Bun monorepos;
remove the typeRoots property from compilerOptions so TypeScript's default
resolution (with baseUrl set to projectRoot) can locate `@types` in the repo root
(update the compilerOptions constant where it's defined and ensure nothing else
depends on typeRoots).
---
Duplicate comments:
In `@apps/docs/.vitepress/config.ts`:
- Around line 62-66: The JSR URL construction is using pkg.name for links.jsr
while elsewhere the site uses jsr.name (e.g., the social JSR entry), which can
drift; unify the source by changing links.jsr to use jsr.name (or replace other
usages to use pkg.name consistently) so the JSR slug is computed from a single
canonical variable—update the links object (links.jsr) to use jsr.name and
ensure any references to the JSR slug (the social JSR entry) use the same
jsr.name identifier.
🪄 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: 413a9850-7c97-46ae-a765-7c5f5f5beead
📒 Files selected for processing (1)
apps/docs/.vitepress/config.ts
📜 Review details
🧰 Additional context used
🧠 Learnings (1)
📓 Common learnings
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:22:00.424Z
Learning: Do not treat `apps/docs/.vitepress/data/` as docs-only; scripts import it for generated source and docs artifacts
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:22:00.424Z
Learning: Do not replace `bun run gh-project:*` commands with ad hoc GitHub project mutations
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:22:00.424Z
Learning: Core library must stay runtime-agnostic; delegate host I/O through `RuntimeAdapter`, `WriteFn`, or `ReadFn` abstractions
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:22:00.424Z
Learning: Use Bun workspaces monorepo structure with packages, apps, tools, and examples directories as separate packages
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:22:08.466Z
Learning: Root `dreamcli.schema.json` is required for docs and must be copied into site output during build
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:22:08.466Z
Learning: Do not assume docs code is isolated from source generation; external scripts like `scripts/build-meta-descriptions.ts` may import it
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:22:13.887Z
Learning: Do not edit generated docs pages when the source of truth is an example file; update the example source instead
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:22:13.887Z
Learning: Do not let examples drift into pseudo-internal usage that real consumers cannot copy
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:22:13.887Z
Learning: Do not treat `.cache/` as source of truth
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:22:13.887Z
Learning: Do not bloat single-file examples with walkthrough-only complexity; move that to `examples/gh`
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:22:35.748Z
Learning: Organize shell completion generators under `shells/` directory with per-shell modules (`bash.ts`, `zsh.ts`, `fish.ts`, `powershell.ts`) and centralize shared logic in `shells/shared.ts`
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:22:35.748Z
Learning: Use a barrel `index.ts` to re-export public API symbols (`generateCompletion()`, per-shell generators, `SHELLS`, `CompletionOptions`, `Shell` type) and dispatch completion generation
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:22:35.748Z
Learning: In `shells/shared.ts`, implement shared infrastructure including `CommandNode` type, `walkCommandTree()` function for traversing nested command groups, string escaping utilities, and `versionTag` handling
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:22:35.748Z
Learning: Each per-shell generator (`generateBashCompletion()`, `generateZshCompletion()`, `generateFishCompletion()`, `generatePowerShellCompletion()`) must receive `CLISchema` and `CompletionOptions`, call `walkCommandTree()`, and emit shell-specific completion functions
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:22:41.607Z
Learning: All I/O flows through a narrow `RuntimeAdapter` surface to keep code testable with virtual filesystems
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:22:41.607Z
Learning: Do not couple config discovery to command schema or resolve precedence logic
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:22:48.906Z
Learning: Help text must be generated from schema metadata; keep formatting rules derived, not duplicated per caller
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:22:48.906Z
Learning: Do not pull TTY or color logic into help formatting; that belongs in output
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:22:48.906Z
Learning: Do not special-case caller behavior when schema metadata already expresses it
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:22:48.906Z
Learning: Do not simplify wrapping or padding without checking narrow alignment regressions in tests
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:22:56.596Z
Learning: Regenerate descriptions via the build script `../../../../../scripts/build-meta-descriptions.ts`; build-time schema description data comes from docs data modules, not hand-maintained constants
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:22:56.596Z
Learning: Ensure the package-level schema artifact is built; the root `dreamcli.schema.json` is emitted from this module's surface
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:23:11.102Z
Learning: Maintain acyclic dependency graph: `writer.ts` <- `contracts.ts` <- `activity.ts` <- `index.ts` -> `writer.ts`, with `renderers.ts` and `display-value.ts` consumed by `index.ts`
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:23:11.102Z
Learning: Implement four output modes (Normal, JSON, Quiet, Non-TTY, Capture) with mode-specific routing: Normal and Non-TTY log to stdout, JSON logs to stderr, Quiet suppresses logs, Capture collects output in arrays
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:23:11.102Z
Learning: Support `ActivityEvent` with 10 distinct variants including separate handling for `progress:increment` and `progress:update` events
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:23:17.360Z
Learning: Keep tokenizer schema-agnostic; resolve/default/env/config behavior belongs elsewhere
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:23:17.360Z
Learning: Do not read env, config, prompts, or defaults in the parse module; that is `resolve/`
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:23:17.360Z
Learning: Do not blur tokenization and parsing responsibilities to simplify a small change
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:23:17.360Z
Learning: Respect the test contract defined in `parse.test.ts` when making changes to the parse module
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:23:26.130Z
Learning: The prompt module is a pluggable engine with terminal and test implementations, not hard-wired terminal code
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:23:37.863Z
Learning: Implement resolution order: CLI argv → environment variable → config file → interactive prompt → default value. First non-undefined source wins; missing required values trigger ValidationError.
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:23:37.863Z
Learning: Use a two-pass architecture: Pass 1 collects CLI → env → config values for all flags. If command has `.interactive()`, invoke it with partial flags. Pass 2 resolves remaining flags via prompt → default → required validation.
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:23:43.680Z
Learning: Keep schema-dsl module layered on top of the schema/ module — schema-dsl consumers define schemas as strings while depending on schema/ flag, arg, and command builders without creating circular dependencies
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:23:55.750Z
Learning: When adding a new flag type: add variant to `FlagKind` union in flag.ts, add factory method on FlagBuilder, update `InferFlag` conditional type, wire through resolve/coerce.ts by adding coercion case in `coerceValue()`, and add tests in flag.test.ts and resolve.test.ts
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-23T05:24:12.084Z
Learning: `ExitError` is thrown by `adapter.exit()` and should be caught by the CLI dispatch layer
🪛 Betterleaks (1.1.2)
apps/docs/.vitepress/config.ts
[high] 119-119: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
🔇 Additional comments (1)
apps/docs/.vitepress/config.ts (1)
10-15: Nice — path centralization here be the right move.Using
./data/paths.tsas the single source of filesystem truth reduces drift across docs/build tooling.Based on learnings, "Do not treat
apps/docs/.vitepress/data/as docs-only; scripts import it for generated source and docs artifacts."
| const compilerOptions = { | ||
| baseUrl: projectRoot, | ||
| lib: tsc.compilerOptions?.lib ?? ['ESNext'], | ||
| paths: tsc.compilerOptions?.paths ?? {}, | ||
| moduleDetection: ModuleDetectionKind.Force, | ||
| module: ModuleKind.ESNext, | ||
| moduleResolution: ModuleResolutionKind.Bundler, | ||
| allowImportingTsExtensions: tsc.compilerOptions?.allowImportingTsExtensions, | ||
| allowImportingTsExtensions: true, | ||
| noEmit: true, | ||
| resolveJsonModule: tsc.compilerOptions?.resolveJsonModule, | ||
| types: [...(tsc.compilerOptions?.types ?? []), 'vitest/globals'], | ||
| resolveJsonModule: true, | ||
| typeRoots: [`${packageRoot}/node_modules/@types`, `${packageRoot}/node_modules`], | ||
| }; |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== Twoslash compilerOptions in docs config =="
rg -n -C3 'compilerOptions|typeRoots|types|baseUrl|paths' apps/docs/.vitepress/config.ts
echo
echo "== Deno global usage in docs/examples/packages =="
rg -nP '\bDeno\.' apps/docs examples packages -g '*.ts' -g '*.md' || true
echo
echo "== Root tsconfig path mappings =="
rg -n -C2 '"paths"|@kjanat/dreamcli' tsconfig.jsonRepository: kjanat/dreamcli
Length of output: 5861
🏁 Script executed:
cat -n apps/docs/.vitepress/data/paths.tsRepository: kjanat/dreamcli
Length of output: 1850
🏁 Script executed:
#!/bin/bash
# Check for `@types` directories at various levels
echo "=== `@types` directories in monorepo ==="
find . -type d -name '@types' -not -path '*/node_modules/*' -not -path '*/.*' 2>/dev/null | head -20
echo
echo "=== Root node_modules/@types (if exists) ==="
ls -la node_modules/@types 2>/dev/null | head -10 || echo "No root node_modules/@types"
echo
echo "=== Check if tsconfig.json has typeRoots ==="
jq '.compilerOptions.typeRoots // "not set"' tsconfig.json
echo
echo "=== Packages/dreamcli tsconfig.json ==="
head -60 packages/dreamcli/tsconfig.json | tail -30Repository: kjanat/dreamcli
Length of output: 726
🏁 Script executed:
#!/bin/bash
echo "=== Current compilerOptions in config.ts (lines 50-60) ==="
sed -n '50,60p' apps/docs/.vitepress/config.ts
echo
echo "=== Check for types array in packages/dreamcli/tsconfig ==="
jq '.compilerOptions.types' packages/dreamcli/tsconfig.json
echo
echo "=== Verify bun/node/deno type packages would be at root ==="
grep -r '"deno"' packages/dreamcli/tsconfig.json packages/dreamcli/package.json || echo "deno type ref in package"Repository: kjanat/dreamcli
Length of output: 1010
Ye be restrictin' Twoslash's type discovery with that hardcoded typeRoots, matey—it'll break in a Bun monorepo.
Batten down the hatches! Line 59 chains typeRoots to packages/dreamcli/node_modules only. But in a Bun monorepo with hoisted dependencies, yer @types (bun, node, deno, vitest) be at the root node_modules. This starves Twoslash of ambient types and scuttles code sample resolution.
With baseUrl already set to the project root, ye can hoist the Jolly Roger and remove that line—TypeScript's default resolution will climb the mast to find types where they actually be.
⚓ Suggested patch
const compilerOptions = {
baseUrl: projectRoot,
paths: tsc.compilerOptions?.paths ?? {},
moduleDetection: ModuleDetectionKind.Force,
module: ModuleKind.ESNext,
moduleResolution: ModuleResolutionKind.Bundler,
allowImportingTsExtensions: true,
noEmit: true,
resolveJsonModule: true,
- typeRoots: [`${packageRoot}/node_modules/@types`, `${packageRoot}/node_modules`],
};📝 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.
| const compilerOptions = { | |
| baseUrl: projectRoot, | |
| lib: tsc.compilerOptions?.lib ?? ['ESNext'], | |
| paths: tsc.compilerOptions?.paths ?? {}, | |
| moduleDetection: ModuleDetectionKind.Force, | |
| module: ModuleKind.ESNext, | |
| moduleResolution: ModuleResolutionKind.Bundler, | |
| allowImportingTsExtensions: tsc.compilerOptions?.allowImportingTsExtensions, | |
| allowImportingTsExtensions: true, | |
| noEmit: true, | |
| resolveJsonModule: tsc.compilerOptions?.resolveJsonModule, | |
| types: [...(tsc.compilerOptions?.types ?? []), 'vitest/globals'], | |
| resolveJsonModule: true, | |
| typeRoots: [`${packageRoot}/node_modules/@types`, `${packageRoot}/node_modules`], | |
| }; | |
| const compilerOptions = { | |
| baseUrl: projectRoot, | |
| paths: tsc.compilerOptions?.paths ?? {}, | |
| moduleDetection: ModuleDetectionKind.Force, | |
| module: ModuleKind.ESNext, | |
| moduleResolution: ModuleResolutionKind.Bundler, | |
| allowImportingTsExtensions: true, | |
| noEmit: true, | |
| resolveJsonModule: true, | |
| }; |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apps/docs/.vitepress/config.ts` around lines 50 - 60, The compilerOptions
object hardcodes typeRoots, which prevents Twoslash from discovering hoisted
ambient types in Bun monorepos; remove the typeRoots property from
compilerOptions so TypeScript's default resolution (with baseUrl set to
projectRoot) can locate `@types` in the repo root (update the compilerOptions
constant where it's defined and ensure nothing else depends on typeRoots).
| [ | ||
| 'script', | ||
| { | ||
| defer: '', | ||
| src: 'https://static.cloudflareinsights.com/beacon.min.js', | ||
| 'data-cf-beacon': '{"token": "ee9b04d68d3740bebb38f5c20629b7c1"}', | ||
| }, | ||
| ], |
There was a problem hiding this comment.
Gate analytics injection by environment/consent, matey.
This beacon script is injected unconditionally. That creates avoidable privacy/compliance risk for local/preview contexts and makes opt-out impossible at config level.
🧰 Tools
🪛 Betterleaks (1.1.2)
[high] 119-119: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apps/docs/.vitepress/config.ts` around lines 114 - 121, The Cloudflare
Insights beacon script is being injected unconditionally in the VitePress head
array (the script entry with src
'https://static.cloudflareinsights.com/beacon.min.js' and data-cf-beacon token);
change this so the head entry is only added when telemetry is allowed—e.g., gate
by an environment flag like process.env.ENABLE_CLOUDFLARE_INSIGHTS or by a
runtime consent check—and ensure local/preview contexts (NODE_ENV ===
'development' or a PREVIEW flag) are excluded; update the code that
builds/returns the head array in config.ts to conditionally push the script
entry (or omit it) based on that flag/consent check, and document the new env
variable or consent mechanism so CI/local runs keep it disabled by default.
Move `package.json` sorting into a dprint plugin and bump the formatting and workspace tooling deps so repo formatting stays consistent in one pass. Stop re-awaiting the resolved TypeDoc git ref and regenerate the affected PowerShell, example, and schema artifacts after the formatter refresh.
coderabbitai
Bot
added
area: schema
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
.gitignore (1)
223-236:⚠️ Potential issue | 🟡 MinorTrim the blast radius: make cache patterns directory-only.
Right now you’re ignoring
__pycache__and.*_cachewithout a trailing/. That can match files as well as directories, which is a little sloppy (aye, I’m a perfectionist pirate).Make them explicitly directory ignores:
🏴☠️ Proposed fix
-__pycache__ -.*_cache +__pycache__/ +.*_cache/🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.gitignore around lines 223 - 236, The ignore entries for __pycache__ and .*_cache are currently written without trailing slashes which can match files as well as directories; update the .gitignore entries by replacing "__pycache__" and ".*_cache" with directory-only patterns "__pycache__/" and ".*_cache/" so they explicitly ignore directories (modify the existing lines in the .gitignore where these symbols appear).examples/pwsh-demo/src/main.ts (1)
26-26:⚠️ Potential issue | 🟡 MinorFix string quoting guideline violation (
"qa's").Repo guideline says: use single quotes for strings in TS. Line 26 currently uses
"qa's"with double quotes, which violates that rule.🏴 Proposed fix
- flag - .enum(['default', 'ops', 'readonly', 'qa ops', "qa's"]) + flag + .enum(['default', 'ops', 'readonly', 'qa ops', 'qa\'s']) .alias('p') .alias('account', { hidden: true }) .describe('Credential profile'),🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@examples/pwsh-demo/src/main.ts` at line 26, The enum value currently uses double quotes ("qa's") which violates the project's single-quote string guideline; update the .enum([...]) array to use single-quoted string for that entry (escape the apostrophe as needed) so the value becomes a single-quoted string consistent with other entries like 'default' and 'ops'.
♻️ Duplicate comments (1)
.zed/settings.json (1)
14-17:⚠️ Potential issue | 🟡 MinorMake the fallback formatter use the same bundled
dprintpath.Line 17 still shells out to bare
dprint, while the LSP block on Lines 45-50 usesbunx. If a deckhand lacks a global install, the fallback formatter keels over even though the primary one works.⚙️ Suggested fix
"formatter": [ { "language_server": { "name": "dprint" } }, // Fallback to the dprint CLI in case the lsp fucks up, which it does sometimes for some reason... - { "external": { "command": "dprint", "arguments": ["fmt", "--stdin", "{buffer_path}"] } } + { "external": { "command": "bunx", "arguments": ["dprint", "fmt", "--stdin", "{buffer_path}"] } } ],#!/bin/bash # Verify the fallback formatter and the LSP are still using different dprint entrypoints. sed -n '14,18p;45,50p' .zed/settings.json rg -n '"dprint": "catalog:"' package.json🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.zed/settings.json around lines 14 - 17, The fallback formatter currently shells out to the bare "dprint" (external.command in the formatter array) which can fail if dprint isn't globally installed; update that external formatter entry to invoke the same bundled dprint entrypoint used by the LSP block (the same invocation string you used in the LSP block around lines 45-50, e.g. the "bunx" based command or the exact bundled path from package.json) so both the language_server { name: "dprint" } and the external formatter use the identical bundled dprint entrypoint.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@apps/docs/guide/getting-started.md`:
- Around line 21-24: Replace the literal backslash-u sequences in the inline
code spans for the runtime versions with actual U+00A0 non-breaking space
characters: change occurrences like `>=\u00a022.22.2`, `>=\u00a01.3`, and
`>=\u00a02.6.0` to use a real NBSP between the comparison operator and the
version string so the rendered text shows a non-breaking space instead of the
visible escape sequence; update the three inline code spans in the "Supported
minimum runtimes:" block accordingly.
In `@apps/docs/guide/runtime.md`:
- Around line 8-13: Replace the literal backslash-u00a0 sequences in the runtime
table entries with actual non‑breaking space characters (U+00A0) so strings like
"Node.js >=\\u00a022.22.2", "Bun >=\\u00a01.3" and "Deno >=\\u00a02.6.0" become
"Node.js >=" + NBSP + "22.22.2", "Bun >=" + NBSP + "1.3", and "Deno >=" + NBSP +
"2.6.0"; update the three occurrences in the table so the markdown renders real
NBSP characters instead of the literal escape sequences.
In `@apps/docs/reference/runtime.md`:
- Around line 63-68: The runtime table contains literal backslash-u sequences
("\u00a0") instead of real non-breaking spaces in the version strings (e.g., the
entries shown as "Node.js >=\u00a022.22.2", "Bun >=\u00a01.3", "Deno
>=\u00a02.6.0"); update those table cells to replace each literal "\u00a0"
sequence with an actual U+00A0 non-breaking space character so the Markdown
renders correctly (edit the table rows where the strings appear, e.g., the
Node.js, Bun, and Deno version cells).
In `@apps/docs/reference/support-matrix.md`:
- Around line 42-44: Replace the literal escape sequences "\u00a0" in the table
entries (e.g., "Node.js >=\u00a022.22.2 runtime support", "Bun >=\u00a01.3
runtime support", "Deno >=\u00a02.6.0 runtime support") with an actual U+00A0
non‑breaking space character so the Markdown renders spacing correctly; search
for the "\u00a0" substrings in the support-matrix table and substitute each with
a real NBSP character (keep the rest of the text unchanged).
---
Outside diff comments:
In @.gitignore:
- Around line 223-236: The ignore entries for __pycache__ and .*_cache are
currently written without trailing slashes which can match files as well as
directories; update the .gitignore entries by replacing "__pycache__" and
".*_cache" with directory-only patterns "__pycache__/" and ".*_cache/" so they
explicitly ignore directories (modify the existing lines in the .gitignore where
these symbols appear).
In `@examples/pwsh-demo/src/main.ts`:
- Line 26: The enum value currently uses double quotes ("qa's") which violates
the project's single-quote string guideline; update the .enum([...]) array to
use single-quoted string for that entry (escape the apostrophe as needed) so the
value becomes a single-quoted string consistent with other entries like
'default' and 'ops'.
---
Duplicate comments:
In @.zed/settings.json:
- Around line 14-17: The fallback formatter currently shells out to the bare
"dprint" (external.command in the formatter array) which can fail if dprint
isn't globally installed; update that external formatter entry to invoke the
same bundled dprint entrypoint used by the LSP block (the same invocation string
you used in the LSP block around lines 45-50, e.g. the "bunx" based command or
the exact bundled path from package.json) so both the language_server { name:
"dprint" } and the external formatter use the identical bundled dprint
entrypoint.
🪄 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: 911ad9fa-50c5-4ef1-87de-c6873c56e658
⛔ Files ignored due to path filters (1)
bun.lockis excluded by!**/*.lock
📒 Files selected for processing (28)
.dprint.jsonc.gitignore.zed/settings.jsonapps/docs/.vitepress/data/typedoc.tsapps/docs/guide/completions.mdapps/docs/guide/getting-started.mdapps/docs/guide/runtime.mdapps/docs/reference/runtime.mdapps/docs/reference/support-matrix.mdexamples/AGENTS.mdexamples/gh/package.jsonexamples/pwsh-demo/src/main.test.tsexamples/pwsh-demo/src/main.tspackage.jsonpackages/dreamcli/CHANGELOG.mdpackages/dreamcli/deno.jsonpackages/dreamcli/src/core/cli/cli-completion-e2e.test.tspackages/dreamcli/src/core/completion/completion.test.tspackages/dreamcli/src/core/completion/shells/powershell.tspackages/dreamcli/src/core/resolve/AGENTS.mdpackages/dreamcli/src/core/resolve/flags.tspackages/dreamcli/src/core/resolve/resolve-prompt.test.tspackages/dreamcli/src/core/schema/AGENTS.mdpackages/dreamcli/src/core/schema/flag.tspackages/dreamcli/src/core/schema/prompt.test.tspackages/dreamcli/src/runtime/auto.test.tspackages/dreamcli/src/runtime/bun.test.tspackages/dreamcli/src/runtime/support.ts
📜 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 (12)
**/*.{ts,tsx,json,md}
📄 CodeRabbit inference engine (AGENTS.md)
Use LF (line feed) for line endings
Files:
apps/docs/reference/support-matrix.mdexamples/pwsh-demo/src/main.test.tsexamples/AGENTS.mdexamples/gh/package.jsonapps/docs/guide/runtime.mdexamples/pwsh-demo/src/main.tsapps/docs/reference/runtime.mdpackages/dreamcli/deno.jsonpackages/dreamcli/src/core/completion/shells/powershell.tsapps/docs/guide/getting-started.mdpackage.json
**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
Use tabs for indentation
Use single quotes for strings
Use semicolons at end of statements
Use
import typefor type-only imports in TypeScriptInclude
.tsextensions in all relative importsUse strict TypeScript with
exactOptionalPropertyTypesenabledUse explicit named re-exports only; no
export *wildcard exports
Files:
examples/pwsh-demo/src/main.test.tsexamples/pwsh-demo/src/main.tspackages/dreamcli/src/core/completion/shells/powershell.ts
**/*.test.ts
📄 CodeRabbit inference engine (AGENTS.md)
Co-locate tests with source files as
*.test.tsusingdescribe()+it()with em dash in suite titlesUse
// ===and// ---section markers in test filesDo not use lifecycle hooks, snapshots, or module mocks in tests
Include trailing newline (
\n) in output assertions
Files:
examples/pwsh-demo/src/main.test.ts
examples/**/*.ts
📄 CodeRabbit inference engine (examples/AGENTS.md)
Examples should import public package exports only, never internal exports from
#internals/*
Files:
examples/pwsh-demo/src/main.test.tsexamples/pwsh-demo/src/main.ts
examples/gh/package.json
📄 CodeRabbit inference engine (examples/AGENTS.md)
Ensure
examples/gh/package.jsonlinks@kjanat/dreamclifrom the workspace and exposes a realghbin
Files:
examples/gh/package.json
apps/docs/{concepts,guide}/**/*.md
📄 CodeRabbit inference engine (apps/docs/AGENTS.md)
Edit prose content in
concepts/,guide/, andindex.mdhand-written Markdown files
Files:
apps/docs/guide/runtime.mdapps/docs/guide/getting-started.md
packages/dreamcli/src/**/*.ts
📄 CodeRabbit inference engine (AGENTS.md)
Include
@moduleJSDoc at the top of source files and mark non-public API with@internal
Files:
packages/dreamcli/src/core/completion/shells/powershell.ts
packages/dreamcli/src/core/**/*.ts
📄 CodeRabbit inference engine (AGENTS.md)
Public API should use factory-first pattern with function names:
cli(),command(),flag.*(),createOutput(),createAdapter()Do not use
process.*or runtime-specific APIs inpackages/dreamcli/src/core/
Files:
packages/dreamcli/src/core/completion/shells/powershell.ts
packages/dreamcli/src/core/{cli,completion,output,prompt,resolve}/**/*.ts
📄 CodeRabbit inference engine (AGENTS.md)
Do not import through barrels in
cli/,completion/,output/,prompt/,resolve/, andruntime/directories when it would create cycles; use direct-file imports
Files:
packages/dreamcli/src/core/completion/shells/powershell.ts
packages/dreamcli/src/core/completion/{shells/**/*.ts,index.ts}
📄 CodeRabbit inference engine (packages/dreamcli/src/core/completion/AGENTS.md)
Split shell completion generators into separate files under
shells/directory with a barrelindex.tsthat re-exports the public API and dispatches viagenerateCompletion()
Files:
packages/dreamcli/src/core/completion/shells/powershell.ts
packages/dreamcli/src/core/completion/shells/{bash,zsh,fish,powershell}.ts
📄 CodeRabbit inference engine (packages/dreamcli/src/core/completion/AGENTS.md)
Implement per-shell completion generators (
generateBashCompletion(),generateZshCompletion(),generateFishCompletion(),generatePowerShellCompletion()) in separate shell-specific files undershells/
Files:
packages/dreamcli/src/core/completion/shells/powershell.ts
packages/dreamcli/src/core/completion/{index.ts,shells/**/*.ts}
📄 CodeRabbit inference engine (packages/dreamcli/src/core/completion/AGENTS.md)
Use
CompletionOptionstype (defined inshells/shared.tsand re-exported throughindex.ts) for completion generator function signatures
Files:
packages/dreamcli/src/core/completion/shells/powershell.ts
🧠 Learnings (11)
📓 Common learnings
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:21:35.628Z
Learning: Do not hand-edit `dreamcli.schema.json` or `src/core/json-schema/meta-descriptions.generated.ts`
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:21:35.628Z
Learning: Do not edit `apps/docs/.vitepress/dist/` or `apps/docs/.vitepress/cache/` directories
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:21:35.628Z
Learning: Do not treat `apps/docs/.vitepress/data/` as docs-only; scripts import it for generated source and docs artifacts
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:21:35.628Z
Learning: Do not replace `bun run gh-project:*` with ad hoc GitHub project mutations
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:21:46.302Z
Learning: Do not patch generated example/reference pages; edit the real source in repo-root `examples/` or `.vitepress/data/` instead
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:21:46.302Z
Learning: Do not assume docs code is isolated from source generation; note that `scripts/build-meta-descriptions.ts` imports docs code
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:21:52.863Z
Learning: Move complex walkthrough logic that exceeds single-file pedagogy to `examples/gh`
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:21:52.863Z
Learning: Do not edit generated docs pages when the source of truth is an example file
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:21:52.863Z
Learning: Do not let examples drift into pseudo-internal usage patterns that real consumers cannot copy
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:21:52.863Z
Learning: Do not treat `.cache/` directory contents as source
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:21:52.863Z
Learning: Update `examples/pwsh-demo` smoke coverage and docs when changing PowerShell install behavior
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:22:17.491Z
Learning: Use `shells/shared.ts` for shared completion infrastructure including `CommandNode`, `walkCommandTree()`, escaping utilities, and `versionTag`, imported directly by per-shell generators
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:22:17.491Z
Learning: Walk the command tree to generate `CommandNode[]` as the intermediate representation before shell-specific code generation in each per-shell generator
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:22:34.704Z
Learning: Help text is generated from schema metadata; keep formatting rules derived, not duplicated per caller
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:22:34.704Z
Learning: Do not pull TTY or color logic into help formatting; that belongs in output layer
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:22:34.704Z
Learning: Do not special-case caller behavior when schema metadata already expresses it
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:22:34.704Z
Learning: Do not simplify wrapping or padding without checking narrow alignment regressions in tests
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:22:39.855Z
Learning: Build-time schema description data comes from docs data modules, not hand-maintained constants
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:22:39.855Z
Learning: Do not forget the package-level schema artifact: build emits root `dreamcli.schema.json` from this surface
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:22:57.675Z
Learning: Maintain a strict dependency graph with no cycles: `writer.ts` <- `contracts.ts` <- `activity.ts` <- `index.ts` -> `writer.ts`, with `renderers.ts` and `display-value.ts` consumed by `index.ts`
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:22:57.675Z
Learning: In output modes, route `log` output to stdout in Normal/Non-TTY/Capture modes, and to stderr in JSON mode; always route `json` output to stdout
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:22:57.675Z
Learning: Route all activity output (spinner/progress) to stderr, not stdout
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:22:57.675Z
Learning: Enforce single active handle at a time: starting a new spinner or progress handle implicitly stops any previously active handle
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:22:57.675Z
Learning: Support `ActivityEvent` with 10 variants including distinct `progress:increment` and `progress:update` event types for testkit assertions
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:22:57.675Z
Learning: Write 49 tests in `output.test.ts` covering OutputChannel log/warn/error methods across all output modes
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:22:57.675Z
Learning: Write 20 tests in `output-tty.test.ts` covering TTY-specific rendering, color output, and formatting behavior
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:22:57.675Z
Learning: Write 16 tests in `output-table.test.ts` covering table output rendering in various output modes
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:22:57.675Z
Learning: Write 45 tests in `output-spinner.test.ts` covering spinner handles across noop/static/TTY/capture tiers with fake timer usage
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:22:57.675Z
Learning: Write 40 tests in `output-progress.test.ts` covering progress handles across noop/static/TTY/capture tiers with fake timer usage
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:22:57.675Z
Learning: Write 32 tests in `output-activity-dispatch.test.ts` covering OutputChannel mode dispatch wiring, activity overlap behavior, and testkit integration
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:23:29.123Z
Learning: Use a two-pass architecture: Pass 1 resolves all flags via CLI → env → config; Pass 2 processes unresolved flags via prompt → default → validation. Insert interactive resolver call between passes if command has .interactive()
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:23:35.276Z
Learning: The schema-dsl module provides string-literal schema definitions with compile-time type inference using the `define()` factory function as the public API in `index.ts`
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:23:35.276Z
Learning: Both compile-time (`parse.ts`) and runtime (`runtime.ts`) parsing paths must produce equivalent results for the same string input — a string that type-checks must also produce correct runtime behavior
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:23:50.422Z
Learning: When adding a new flag type: (1) Add variant to `FlagKind` union in `flag.ts`, (2) Add factory method on `FlagBuilder`, (3) Update `InferFlag` conditional type, (4) Wire through `resolve/coerce.ts` (add coercion case in unified `coerceValue()`), (5) Add tests in `flag.test.ts` + `resolve.test.ts`
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:23:50.422Z
Learning: Note that `.middleware()` drops current handler (type signature changes) — intentional behavior that forces re-registration after middleware addition
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:23:50.422Z
Learning: Create test files for core/schema module: `command.test.ts` (CommandBuilder API, schema, type inference), `flag.test.ts` (FlagBuilder API, kinds, validation), `arg.test.ts` (ArgBuilder API, kinds, validation), `middleware.test.ts` (Middleware factory, context typing), `prompt.test.ts` (Prompt config types), `derive.test.ts` (Type derivation tests)
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:23:59.142Z
Learning: `runCommand(cmd, argv, options?): Promise<RunResult>` is a thin in-process wrapper over the shared executor that captures output, forwards injected execution options, and returns captured output
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:23:59.142Z
Learning: The testkit barrel should be curated at `src/testkit.ts` and exported as a first-class module from `kjanat/dreamcli/testkit` subpath
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:23:59.142Z
Learning: Wire `CaptureOutputChannel` from the output module for output and activity capture in testkit
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-04-29T03:24:10.229Z
Learning: `ExitError` thrown by `adapter.exit()` must be caught by CLI dispatch layer, not propagated
📚 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:
apps/docs/reference/support-matrix.mdexamples/AGENTS.mdapps/docs/guide/runtime.mdapps/docs/reference/runtime.mdapps/docs/guide/getting-started.md
📚 Learning: 2026-02-11T11:57:27.623Z
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 3
File: src/core/cli/cli-completion-e2e.test.ts:9-16
Timestamp: 2026-02-11T11:57:27.623Z
Learning: Enforce explicit .ts extensions in all relative imports for TypeScript source files (enabled by allowImportingTsExtensions and noEmit in tsconfig.json). This applies to both static and dynamic imports. For each TypeScript file, update relative import paths to end with .ts (e.g., './utils/helper' -> './utils/helper.ts'). Ensure tooling (linting/eslint rules or a codemod) flags missing extensions and provides a quick fix. This guideline should cover all TypeScript files in the repo, not just a single test or module.
Applied to files:
examples/pwsh-demo/src/main.test.tsexamples/pwsh-demo/src/main.tspackages/dreamcli/src/core/completion/shells/powershell.ts
📚 Learning: 2026-02-12T15:52:24.166Z
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 4
File: src/core/resolve/resolve-arg-env.test.ts:1-7
Timestamp: 2026-02-12T15:52:24.166Z
Learning: In test files, do not require the module JSDoc tag at the top. This rule applies to all test files, while non-test source files should still require the module tag. Use the pattern **/*.test.{ts,tsx} to cover all test TypeScript test files (adjust if your project uses only .ts tests).
Applied to files:
examples/pwsh-demo/src/main.test.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, require the `module` JSDoc tag only for library source files under `src/` (e.g., `src/**/*.ts`). Files outside `src/` such as runnable demo/example scripts under `examples/` are not considered source code for this rule and should not be required to include `module`.
Applied to files:
examples/pwsh-demo/src/main.test.tsexamples/pwsh-demo/src/main.tspackages/dreamcli/src/core/completion/shells/powershell.ts
📚 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 repo, the explicit type annotation `Readonly<Record<string, string>>` applied to `const` object literals is an intentional documentation/intent pattern. Do not flag it as redundant or unnecessary (e.g., for being inferable) when reviewing TypeScript/TSX files; treat this explicitness as acceptable by design.
Applied to files:
examples/pwsh-demo/src/main.test.tsexamples/pwsh-demo/src/main.tspackages/dreamcli/src/core/completion/shells/powershell.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: For this repository, Windows is explicitly not a supported/targeted platform. During code review, do not raise issues about Windows-specific path separators or normalization differences (e.g., use of `path.sep`, handling forward-slash vs backslash, or `normalize()`-related concerns). These checks should be treated as out-of-scope because the project is intended for Linux/macOS only.
Applied to files:
examples/pwsh-demo/src/main.test.tsexamples/pwsh-demo/src/main.tspackages/dreamcli/src/core/completion/shells/powershell.ts
📚 Learning: 2026-04-16T19:00:34.468Z
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 17
File: examples/pwsh-demo/src/main.test.ts:12-48
Timestamp: 2026-04-16T19:00:34.468Z
Learning: In kjanat/dreamcli, files under the `examples/` directory that are test files (e.g., `examples/**/*.test.ts`) are exempt from the repo-wide test-style conventions that require em dashes in `describe()` suite titles and `// ===` / `// ---` section marker comments. Do not flag missing em dashes in `describe()` titles or missing `// ===` / `// ---` section markers in these `examples/**/*.test.ts` files.
Applied to files:
examples/pwsh-demo/src/main.test.ts
📚 Learning: 2026-04-07T08:45:53.051Z
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 9
File: package.json:121-129
Timestamp: 2026-04-07T08:45:53.051Z
Learning: When reviewing package.json `devEngines`, do not treat EBADDEVENGINES warnings as a breaking issue if the block intentionally uses Bun (e.g., `{ "name": "bun" }`) and the corresponding `onFail` values are soft (`onFail: "warn"` or `onFail: "ignore"`). npm may consider `bun` an invalid/unsupported engine name and warn, but with these `onFail` settings it won’t hard-fail—so the intent should be respected unless `onFail` is set to `fail` or similar hard-failure behavior.
Applied to files:
examples/gh/package.jsonpackage.json
📚 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 kjanat/dreamcli, do not treat the `.zed/settings.json` → `.attw.json` JSON-schema reference (the gist URL owned/controlled by repo maintainer kjanat) as a fragile external dependency. Assume the gist is intentionally maintained by the maintainer and do not recommend moving the schema to the repo or to a “more stable” location in this file.
Applied to files:
.zed/settings.json
📚 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: For Deno/JSR projects using `deno.json`, it is valid to declare public subpath exports that map to JSON files (e.g., `"./schema": "./dreamcli.schema.json"`). During code review, do not flag JSON file subpath exports in `deno.json` as invalid; Deno’s toolchain (e.g., `deno publish --dry-run` / `deno check`) supports JSON exports natively and should be used to confirm validity if needed.
Applied to files:
packages/dreamcli/deno.json
🔇 Additional comments (18)
examples/pwsh-demo/src/main.test.ts (1)
34-44: ☠️ LGTM: stdout expectation formatting is semantically consistentThat
toEqual([...])onresult.stdoutis clean, and the single-line array literal at Line 43 is an equivalent reformat of the expected output (no logic changes). Keeps the test strict about both lines and their trailing\n, which matches the intent of this smoke test.packages/dreamcli/src/core/completion/shells/powershell.ts (1)
321-328: Aye, this PowerShell quoting fix looks solid.Line 321 and Line 328 now correctly emit an explicit empty-string literal and a properly escaped single-quoted completion value, which keeps completion text valid for tricky enum values.
apps/docs/guide/runtime.md (1)
60-66: Arrr, path be shipshape—it resolves correctly from the repo root.Yer import path
./apps/docs/.vitepress/twoslash/testing-fixtures.tssails true when Twoslash interprets it relative to the repo root, which it does. The file exists exactly where ye pointed it. If the path were ever interpreted relative to the markdown file's directory, it'd sink like a landlubber's ship, but Twoslash knows better than that. Everything's in order, me hearty.examples/pwsh-demo/src/main.ts (4)
37-43: LGTM:openout.log formatting-only refactor.The change to a multi-line
out.log(...)call keeps the exact same template string values and nullish-default behavior (flags.profile ?? 'default'). No functional risk here.
59-65: LGTM:deployout.log formatting-only refactor.Same story: the refactor only adjusts formatting of the
out.log(...)call and preserves the string interpolation + defaults (flags.region ?? 'us',flags.strategy ?? 'rolling').
89-92: LGTM:config set --scopeflag formatting-only refactor.The
.flag('scope', ...)structure is reformatted without changing the enum values or default (default('user')).
115-121: LGTM:debug-dump --sectionhidden flag formatting-only refactor.Refactor preserves enum values, default, and description; no behavior change expected.
examples/AGENTS.md (2)
11-15: LGTM: examples layout structure docs updated.The
STRUCTUREsection now clearly calls outstandalone/,gh/, andpwsh-demo/, matching the new guidance. No issues.
19-26: LGTM: “WHERE TO LOOK” table updated for the new paths.Table entries and notes align with the new examples layout expectations (standalone single-feature edits, docs example metadata location, walkthrough package, pwsh demo package, and generated docs trace locations).
examples/gh/package.json (2)
13-15: Good monorepo wiring, finally.Ye kept a real
ghbin exposed and switched@kjanat/dreamclitoworkspace:*, which is exactly what this example needed after the split.As per coding guidelines,
examples/gh/package.jsonmust “link@kjanat/dreamclifrom the workspace and expose a realghbin”.Also applies to: 29-33
23-26: Keeping both typecheck paths is smart.Defaulting to
tsgowhile preservingtypecheck:tscgives ye the shiny new path without losing the boring reliable one. Nice.packages/dreamcli/deno.json (2)
13-13: Aye, this smoke-task path is cleaner now.Pointing the package task at the shared repo-root smoke script kills the split-brain nonsense and keeps one source of truth.
31-32: Schema export and publish shape look sane now.Routing
./schemathroughsrc/schema.tswhile still publishingdreamcli.schema.json,package.json, anddeno.jsongives consumers the typed module without losing the raw artifact.Also applies to: 45-53
.dprint.jsonc (2)
12-19: The formatter routing finally matches the new repo layout.Good. The old root-
docs/assumptions are gone, andapps/docs/twoslash files are being handed to the right formatter instead of getting mauled by the wrong one.Also applies to: 23-24, 33-34, 53-53
57-69: Good call moving package sorting into a real plugin.That’s cleaner than the old ad hoc exec hop, and a damned sight easier to keep consistent.
.zed/settings.json (1)
22-30: These Biome code-action keys are the right cleanup.Nice. Both JavaScript and TypeScript now use the same
source.*action names instead of that crusty mixed naming.package.json (2)
5-23: The root script and catalog surface is finally monorepo-shaped.This stops pretending the repo is one package and pushes build/test/docs/tooling through the right workspace boundaries. Much cleaner.
Also applies to: 36-42, 49-57, 73-99
27-32: Good — ye kept thegh-projectflows behind wrapper scripts.That avoids scattering ad hoc GitHub project mutations around the root scripts like confetti.
Based on learnings, “Do not replace
bun run gh-project:*with ad hoc GitHub project mutations”.
| Supported minimum runtimes: | ||
| Node.js `>= 22.22.2`, | ||
| Bun `>= 1.3`, | ||
| Deno `>= 2.6.0`. | ||
| Node.js `>=\u00a022.22.2`, | ||
| Bun `>=\u00a01.3`, | ||
| Deno `>=\u00a02.6.0`. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
python3 <<'PY'
path = "apps/docs/guide/getting-started.md"
with open(path, "r", encoding="utf-8") as f:
s = f.read()
literal = s.count(r"\u00a0")
nb = s.count("\u00a0")
print("File:", path)
print("literal r'\\u00a0' count:", literal)
print("U+00A0 count:", nb)
PYRepository: kjanat/dreamcli
Length of output: 143
Arrr, those inline code spans be cursed—replace literal \u00a0 with actual non-breaking spaces.
Ye got three instances of literal backslash-u text in yer inline code (lines 21–24), not actual NBSP characters. Readers'll see \u00a0 displayed plain-like on their screens, which be a right mess for documentation. Replace 'em with real U+00A0 non-breaking space characters so the rendering don't look like escape sequences vomited into the text.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apps/docs/guide/getting-started.md` around lines 21 - 24, Replace the literal
backslash-u sequences in the inline code spans for the runtime versions with
actual U+00A0 non-breaking space characters: change occurrences like
`>=\u00a022.22.2`, `>=\u00a01.3`, and `>=\u00a02.6.0` to use a real NBSP between
the comparison operator and the version string so the rendered text shows a
non-breaking space instead of the visible escape sequence; update the three
inline code spans in the "Supported minimum runtimes:" block accordingly.
| | Runtime | Status | Package | | ||
| | ----------------------- | --------- | ------------------------ | | ||
| | Node.js >=\u00a022.22.2 | Supported | `@kjanat/dreamcli` (npm) | | ||
| | Bun >=\u00a01.3 | Supported | `@kjanat/dreamcli` (npm) | | ||
| | Deno >=\u00a02.6.0 | Supported | `@kjanat/dreamcli` (JSR) | | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
python3 <<'PY'
path = "apps/docs/guide/runtime.md"
with open(path, "r", encoding="utf-8") as f:
s = f.read()
literal = s.count(r"\u00a0")
nb = s.count("\u00a0")
print("File:", path)
print("literal r'\\u00a0' count:", literal)
print("U+00A0 count:", nb)
PYRepository: kjanat/dreamcli
Length of output: 135
Fix literal \u00a0 escape sequences to real NBSP characters in the runtime table.
The table contains literal \u00a0 strings (three occurrences) instead of actual Unicode non-breaking spaces (U+00A0). That'll render as visible garbage in the markdown—browsers won't parse it as a space character. Replace each >=\u00a0 with >= followed by an actual NBSP character so the table doesn't look buggered.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apps/docs/guide/runtime.md` around lines 8 - 13, Replace the literal
backslash-u00a0 sequences in the runtime table entries with actual non‑breaking
space characters (U+00A0) so strings like "Node.js >=\\u00a022.22.2", "Bun
>=\\u00a01.3" and "Deno >=\\u00a02.6.0" become "Node.js >=" + NBSP + "22.22.2",
"Bun >=" + NBSP + "1.3", and "Deno >=" + NBSP + "2.6.0"; update the three
occurrences in the table so the markdown renders real NBSP characters instead of
the literal escape sequences.
| | Runtime | Adapter | Notes | | ||
| | ----------------------- | ------------- | ------------------------------ | | ||
| | Node.js >=\u00a022.22.2 | `NodeAdapter` | Full support | | ||
| | Bun >=\u00a01.3 | `BunAdapter` | Delegates to Node adapter | | ||
| | Deno >=\u00a02.6.0 | `DenoAdapter` | Permission-safe Deno namespace | | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
python3 <<'PY'
path = "apps/docs/reference/runtime.md"
with open(path, "r", encoding="utf-8") as f:
s = f.read()
literal = s.count(r"\u00a0")
nb = s.count("\u00a0")
print("File:", path)
print("literal r'\\u00a0' count:", literal)
print("U+00A0 count:", nb)
PYRepository: kjanat/dreamcli
Length of output: 139
Arrr, those \u00a0 markers be literal text, not actual NBSP characters—fix that or yer docs'll render like garbage, matey.
The file contains 3 literal backslash-u sequences (\u00a0) instead of real non-breaking space characters (U+00A0). Markdown renderers won't transmute those literal strings into proper spacing, so yer version strings (>=\u00a0022.22.2 and the like) will display as broken nonsense in the rendered output. Every single row in that runtime table be affected.
Replace each \u00a0 with an actual U+00A0 non-breaking space character so the thing renders proper-like.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apps/docs/reference/runtime.md` around lines 63 - 68, The runtime table
contains literal backslash-u sequences ("\u00a0") instead of real non-breaking
spaces in the version strings (e.g., the entries shown as "Node.js
>=\u00a022.22.2", "Bun >=\u00a01.3", "Deno >=\u00a02.6.0"); update those table
cells to replace each literal "\u00a0" sequence with an actual U+00A0
non-breaking space character so the Markdown renders correctly (edit the table
rows where the strings appear, e.g., the Node.js, Bun, and Deno version cells).
| | Node.js >=\u00a022.22.2 runtime support | Supported | [Runtime Support](/guide/runtime), [`src/runtime/node.ts`](https://github.com/kjanat/dreamcli/blob/master/src/runtime/node.ts), [`docs/reference/runtime.md`](/reference/runtime) | This is the primary adapter implementation. | | ||
| | Bun >=\u00a01.3 runtime support | Supported | [Runtime Support](/guide/runtime), [`src/runtime/bun.ts`](https://github.com/kjanat/dreamcli/blob/master/src/runtime/bun.ts), [`docs/reference/runtime.md`](/reference/runtime) | Bun currently delegates through the Node adapter strategy. | | ||
| | Deno >=\u00a02.6.0 runtime support | Supported | [Runtime Support](/guide/runtime), [`src/runtime/deno.ts`](https://github.com/kjanat/dreamcli/blob/master/src/runtime/deno.ts), [`docs/reference/runtime.md`](/reference/runtime) | Deno support is permission-aware and published through JSR. | |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
python3 <<'PY'
path = "apps/docs/reference/support-matrix.md"
with open(path, "r", encoding="utf-8") as f:
s = f.read()
literal = s.count(r"\u00a0")
nb = s.count("\u00a0")
print("File:", path)
print("literal r'\\u00a0' count:", literal)
print("U+00A0 count:", nb)
PYRepository: kjanat/dreamcli
Length of output: 146
Arrr! Ye didn't actually swap out the literal escape sequences—the \u00a0 characters still be there, not proper NBSPs!
The file still contains literal \u00a0 sequences instead of actual U+00A0 non-breaking space characters. Those three escape sequences at lines 42-44 be needin' proper conversion to real NBSP characters so the markdown renders the spacing true and proper-like. Right now ye be displayin' the actual text escape, not the character it represents—that be a scurvy rendering issue, matey.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apps/docs/reference/support-matrix.md` around lines 42 - 44, Replace the
literal escape sequences "\u00a0" in the table entries (e.g., "Node.js
>=\u00a022.22.2 runtime support", "Bun >=\u00a01.3 runtime support", "Deno
>=\u00a02.6.0 runtime support") with an actual U+00A0 non‑breaking space
character so the Markdown renders spacing correctly; search for the "\u00a0"
substrings in the support-matrix table and substitute each with a real NBSP
character (keep the rest of the text unchanged).
Clamp starter repeat counts to finite integers so generated and documented hello-world CLIs cannot spin forever on `Infinity` or other invalid numeric inputs. Clean up nearby review nits by removing a duplicate prompt test name, dropping an unused scaffold variable, and invoking the PowerShell completion script without redundant string coercion.
Align moved `examples/standalone` usage docs and watch paths so generated example pages and docs data stay in sync after the move. Refresh formatter and workspace tool versions, restore the `@kjanat/dreamcli-docs/vitepress/*` tsconfig alias, and sync DreamCLI's published runtime support metadata to the 2.1.0 / Bun >=1.3 support line.
coderabbitai
Bot
added
kind: feature
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
examples/standalone/middleware.ts (1)
2-11:⚠️ Potential issue | 🟠 Major | ⚡ Quick winAdd
@moduleto the file header JSDoc.Ye updated the header block, but it still misses the required
@moduletag for TS source files. Add it at the top JSDoc block to stay compliant.Proposed patch
/** + * `@module` * Middleware patterns: auth guard, request timing, error handling. * * Demonstrates: typed middleware context, auth guards, short-circuiting, andAs per coding guidelines: "
**/*.{ts,tsx}: Include@moduleJSDoc at the top of source files; mark non-public API with@internal".🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@examples/standalone/middleware.ts` around lines 2 - 11, The top-of-file JSDoc header is missing the required `@module` tag; edit the header comment block at the very top of examples/standalone/middleware.ts and add a line like "@module" (or "@module <name>" if you want an explicit module name) so the file includes the required `@module` JSDoc; if any APIs in this file are non-public, also mark them with `@internal` in their JSDoc blocks.examples/standalone/multi-command.ts (1)
2-17: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick winAdd
@moduleto the file header JSDoc.Arrr, this example docblock be clean, but it still misses the required
@moduletag for TS source files.Suggested patch
/** * Multi-command CLI with nested command groups (git-like). * * Demonstrates: top-level commands, nested groups, version metadata, and * env-backed flags. * * Usage: * npx tsx examples/standalone/multi-command.ts deploy production --force * npx tsx examples/standalone/multi-command.ts deploy production --region eu * DEPLOY_REGION=ap npx tsx examples/standalone/multi-command.ts deploy production * npx tsx examples/standalone/multi-command.ts db migrate --steps 3 * npx tsx examples/standalone/multi-command.ts db seed * npx tsx examples/standalone/multi-command.ts login --token abc123 * npx tsx examples/standalone/multi-command.ts --help * npx tsx examples/standalone/multi-command.ts --version + * + * `@module` */As per coding guidelines,
**/*.{ts,tsx}must “Include@moduleJSDoc at the top of source files.”🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@examples/standalone/multi-command.ts` around lines 2 - 17, Add the required `@module` JSDoc tag to the top-of-file header comment in multi-command.ts: update the existing block comment that documents the example (the file-level docblock) to include a line like "@module" (optionally with the module name) immediately after the opening /** so the file now contains a proper module JSDoc tag as required by the linting rule.examples/standalone/spinner-progress.ts (1)
22-22:⚠️ Potential issue | 🟠 MajorAdd validation to the
--stepsflag to prevent infinite loops and invalid input.The
--stepsflag lacks any bounds checking. Without validation, a scallywag could pass--steps Infinityand send the loop at line 40 into an endless voyage, or pass negative values that cause odd behavior. Thebasic.tsexample already demonstrates the proper pattern — clamp this to finite positive integers like so:const stepCount = Number.isFinite(flags.steps) ? Math.max(1, Math.min(100, Math.floor(flags.steps))) : 5;Then use
stepCountinstead offlags.stepsin the progress bar and loop.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@examples/standalone/spinner-progress.ts` at line 22, The --steps flag needs bounds checking: validate flags.steps from the .flag('steps', ...) definition and derive a safe integer stepCount (e.g., if Number.isFinite(flags.steps) then Math.max(1, Math.min(100, Math.floor(flags.steps))) else 5), then replace uses of flags.steps in the progress bar/loop (the loop that begins around the spinner/progress code at line ~40) with stepCount so the loop iterates a finite positive integer between 1 and 100.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/dreamcli/src/core/resolve/resolve-prompt.test.ts`:
- Line 17: Replace the barrel import of ResolveOptions with a direct-file import
from the resolve directory: change the import that currently references
'./index.ts' to import ResolveOptions from './contracts.ts' in
resolve-prompt.test.ts so the test uses the concrete contracts file and avoids
barrel-induced circular dependencies; locate the existing import statement that
declares ResolveOptions and update its module path to './contracts.ts'.
---
Outside diff comments:
In `@examples/standalone/middleware.ts`:
- Around line 2-11: The top-of-file JSDoc header is missing the required `@module`
tag; edit the header comment block at the very top of
examples/standalone/middleware.ts and add a line like "@module" (or "@module
<name>" if you want an explicit module name) so the file includes the required
`@module` JSDoc; if any APIs in this file are non-public, also mark them with
`@internal` in their JSDoc blocks.
In `@examples/standalone/multi-command.ts`:
- Around line 2-17: Add the required `@module` JSDoc tag to the top-of-file header
comment in multi-command.ts: update the existing block comment that documents
the example (the file-level docblock) to include a line like "@module"
(optionally with the module name) immediately after the opening /** so the file
now contains a proper module JSDoc tag as required by the linting rule.
In `@examples/standalone/spinner-progress.ts`:
- Line 22: The --steps flag needs bounds checking: validate flags.steps from the
.flag('steps', ...) definition and derive a safe integer stepCount (e.g., if
Number.isFinite(flags.steps) then Math.max(1, Math.min(100,
Math.floor(flags.steps))) else 5), then replace uses of flags.steps in the
progress bar/loop (the loop that begins around the spinner/progress code at line
~40) with stepCount so the loop iterates a finite positive integer between 1 and
100.
🪄 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: 45146a09-e667-4209-9a4a-aeb88674b70a
⛔ Files ignored due to path filters (1)
bun.lockis excluded by!**/*.lock
📒 Files selected for processing (20)
.dprint.jsoncapps/docs/examples/[slug].paths.tsapps/docs/examples/examples.data.tsapps/docs/guide/getting-started.mdapps/docs/reference/api.data.tsapps/docs/reference/symbols/main/[slug].paths.tsexamples/pwsh-demo/smoke-powershell.ps1examples/standalone/basic.tsexamples/standalone/interactive.tsexamples/standalone/json-mode.tsexamples/standalone/middleware.tsexamples/standalone/multi-command.tsexamples/standalone/spinner-progress.tsexamples/standalone/testing.tspackage.jsonpackages/dreamcli/README.mdpackages/dreamcli/package.jsonpackages/dreamcli/src/core/resolve/resolve-prompt.test.tspackages/dreamcli/src/core/schema/prompt.test.tspackages/dreamcli/src/runtime/support.test.ts
📜 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 (11)
**/*.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (AGENTS.md)
Use tabs, single quotes, and semicolons; use LF line endings
Use explicit named re-exports only; do not use
export *
Files:
examples/standalone/testing.tspackages/dreamcli/src/core/schema/prompt.test.tsexamples/standalone/middleware.tsexamples/standalone/json-mode.tsexamples/standalone/multi-command.tsexamples/standalone/interactive.tspackages/dreamcli/src/core/resolve/resolve-prompt.test.tsexamples/standalone/spinner-progress.tsapps/docs/reference/symbols/main/[slug].paths.tsexamples/standalone/basic.tsapps/docs/examples/examples.data.tsapps/docs/examples/[slug].paths.tsapps/docs/reference/api.data.tspackages/dreamcli/src/runtime/support.test.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
Use
import typefor type-only importsInclude
.tsextensions in all relative importsEnable strict TypeScript everywhere with
exactOptionalPropertyTypesenabled; use conditional spreads for optional propertiesInclude
@moduleJSDoc at the top of source files; mark non-public API with@internal
Files:
examples/standalone/testing.tspackages/dreamcli/src/core/schema/prompt.test.tsexamples/standalone/middleware.tsexamples/standalone/json-mode.tsexamples/standalone/multi-command.tsexamples/standalone/interactive.tspackages/dreamcli/src/core/resolve/resolve-prompt.test.tsexamples/standalone/spinner-progress.tsapps/docs/reference/symbols/main/[slug].paths.tsexamples/standalone/basic.tsapps/docs/examples/examples.data.tsapps/docs/examples/[slug].paths.tsapps/docs/reference/api.data.tspackages/dreamcli/src/runtime/support.test.ts
examples/standalone/*.ts
📄 CodeRabbit inference engine (examples/AGENTS.md)
Top-level example docblocks must follow a contract: title line, optional prose,
Demonstrates:, andUsage:sectionsKeep single-file examples pedagogical and runnable; focus on public-API only and avoid bloating with walkthrough-only complexity
Files:
examples/standalone/testing.tsexamples/standalone/middleware.tsexamples/standalone/json-mode.tsexamples/standalone/multi-command.tsexamples/standalone/interactive.tsexamples/standalone/spinner-progress.tsexamples/standalone/basic.ts
examples/**/*.ts
📄 CodeRabbit inference engine (examples/AGENTS.md)
Examples should import public package exports only, never import from
#internals/*
Files:
examples/standalone/testing.tsexamples/standalone/middleware.tsexamples/standalone/json-mode.tsexamples/standalone/multi-command.tsexamples/standalone/interactive.tsexamples/standalone/spinner-progress.tsexamples/standalone/basic.ts
packages/dreamcli/src/**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
Keep public API factory-first:
cli(),command(),flag.*(),createOutput(),createAdapter()
Files:
packages/dreamcli/src/core/schema/prompt.test.tspackages/dreamcli/src/core/resolve/resolve-prompt.test.tspackages/dreamcli/src/runtime/support.test.ts
**/*.test.ts
📄 CodeRabbit inference engine (AGENTS.md)
Co-locate tests as
*.test.tsfiles; usedescribe()+it(), em dashes in suite titles,// ===and// ---section markersDo not use lifecycle hooks, snapshots, or module mocks in tests
Files:
packages/dreamcli/src/core/schema/prompt.test.tspackages/dreamcli/src/core/resolve/resolve-prompt.test.tspackages/dreamcli/src/runtime/support.test.ts
packages/dreamcli/src/**/*.test.ts
📄 CodeRabbit inference engine (AGENTS.md)
Include trailing
\nin output assertions
Files:
packages/dreamcli/src/core/schema/prompt.test.tspackages/dreamcli/src/core/resolve/resolve-prompt.test.tspackages/dreamcli/src/runtime/support.test.ts
packages/dreamcli/src/core/**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
Keep core library runtime-agnostic; route all host I/O through
RuntimeAdapter,WriteFn, orReadFnDo not use
process.*or runtime-specific APIs inpackages/dreamcli/src/core/
Files:
packages/dreamcli/src/core/schema/prompt.test.tspackages/dreamcli/src/core/resolve/resolve-prompt.test.ts
packages/dreamcli/src/core/schema/**/*.{ts,tsx}
📄 CodeRabbit inference engine (packages/dreamcli/src/core/schema/AGENTS.md)
Use
Faccumulator pattern:{} & Record<name, InferFlag<...>>grows per.flag()call for flag type accumulationUse
Aaccumulator pattern: same asFaccumulator for.arg()callsUse
Caccumulator pattern:Record<string, never>replaced entirely on first.middleware(), then intersection-grown viaWidenContext<C, Output>Use phantom brand pattern:
Middleware<Output>carries type info at compile time and is erased at runtime; same approach applies to_valueon FlagBuilder/ArgBuilder
Files:
packages/dreamcli/src/core/schema/prompt.test.ts
packages/dreamcli/src/core/{cli,completion,output,prompt,resolve,runtime}/**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
Use direct-file imports instead of barrel imports in
cli/,completion/,output/,prompt/,resolve/, andruntime/to avoid circular dependencies
Files:
packages/dreamcli/src/core/resolve/resolve-prompt.test.ts
apps/docs/examples/*.ts
📄 CodeRabbit inference engine (apps/docs/AGENTS.md)
Example docblocks must follow the contract: title line, optional prose,
Demonstrates:section, andUsage:sectionEdit example docs pages through
../examples/*.tssource files and.vitepress/data/examples.tsrather than patching generated routes indocs/examples/[slug].paths.ts
Files:
apps/docs/examples/examples.data.tsapps/docs/examples/[slug].paths.ts
🧠 Learnings (8)
📓 Common learnings
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:04:21.036Z
Learning: Do not add runtime dependencies to `packages/dreamcli`
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:04:21.036Z
Learning: Treat `apps/docs/.vitepress/data/` as shared between docs and scripts; scripts import it for generated source and docs artifacts
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:04:21.036Z
Learning: Use `bun run gh-project:*` commands instead of ad hoc GitHub project mutations for project workflow automation
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:04:33.130Z
Learning: Do not patch generated example and reference pages when the real source lives in repo-root `examples/` or `.vitepress/data/`
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:04:33.130Z
Learning: Do not assume docs code is isolated from source generation; code like `scripts/build-meta-descriptions.ts` may import docs files
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:04:33.130Z
Learning: Refer to `.vitepress/AGENTS.md` for plugin, theme, and data-pipeline gotchas and implementation details
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:04:41.773Z
Learning: Complex walkthrough-specific functionality should reside in `examples/gh/` rather than in single-file standalone examples
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:04:41.773Z
Learning: Do not edit generated docs pages when the source of truth is an example file; instead edit the example source directly
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:04:41.773Z
Learning: Do not let examples drift into pseudo-internal usage patterns that real consumers cannot copy
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:04:41.773Z
Learning: `examples/gh/` is typechecked and tested separately in CI; edits there carry real consumer signal and must be tested
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:04:41.773Z
Learning: `examples/pwsh-demo/` must maintain end-to-end PowerShell completion coverage and native PowerShell completion execution testing
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:04:41.773Z
Learning: Do not change PowerShell install behavior without updating the `pwsh-demo` smoke coverage and corresponding docs
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:04:41.773Z
Learning: Do not treat `.cache/` directory as a source of truth for examples or documentation
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:05:08.338Z
Learning: Config loading is adapter-driven and side-effect free from the module's perspective, covering both user config discovery and `packageJson()` metadata inference
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:05:08.338Z
Learning: All I/O flows through a narrow `RuntimeAdapter` surface to keep it testable with virtual filesystems
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:05:08.338Z
Learning: Config roots must be plain objects even if a loader can parse other JSON or YAML values
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:05:08.338Z
Learning: JSON must always be built in and ordered first in search-path and loader resolution
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:05:17.180Z
Learning: Help text must be generated from schema metadata; keep formatting rules derived, not duplicated per caller
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:05:17.180Z
Learning: Do not pull TTY or color logic into help formatting; that belongs in output module
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:05:17.180Z
Learning: Do not special-case caller behavior when schema metadata already expresses it
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:05:17.180Z
Learning: Do not simplify wrapping or padding without checking narrow alignment regressions in tests
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:05:24.571Z
Learning: Do not forget the package-level schema artifact; build must emit root `dreamcli.schema.json` from this surface
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:05:33.339Z
Learning: OutputChannel modes (normal, JSON, quiet, non-TTY, capture) must correctly dispatch log/json output and spinner/progress visibility
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:05:33.339Z
Learning: Maintain strict dependency graph with no cycles: writer.ts → contracts.ts → activity.ts → index.ts, with renderers.ts and display-value.ts consumed only by index.ts
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:05:46.179Z
Learning: Perform choice merging before the engine sees config; engines should not infer enum choices themselves
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:05:46.179Z
Learning: Do not move non-TTY gating into the prompt engine; CLI and resolve layer decide when prompts are allowed
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:05:59.852Z
Learning: Implement two-pass architecture: Pass 1 collects CLI -> env -> config values; Pass 2 resolves remaining flags with prompt -> default -> validation after optional interactive resolver invocation
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:06:05.550Z
Learning: Maintain parallel compile-time and runtime string parsing paths in schema-dsl module — compile-time uses template literal types in parse.ts for type inference, runtime uses string-to-builder construction in runtime.ts, and both must produce equivalent results
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:06:05.550Z
Learning: Import CommandBuilder, FlagBuilder, and ArgBuilder from schema/ module in schema-dsl — dependency direction is unidirectional (schema-dsl depends on schema, not vice versa) to prevent circular dependencies
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:06:21.293Z
Learning: When adding a new flag type: (1) Add variant to `FlagKind` union in `flag.ts`, (2) Add factory method on `FlagBuilder`, (3) Update `InferFlag` conditional type, (4) Wire through `resolve/coerce.ts` with a coercion case in unified `coerceValue()`, (5) Add tests in `flag.test.ts` + `resolve.test.ts`
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:06:27.966Z
Learning: `runCommand()` must capture output, forward injected execution options from `RunOptions`, and return a `RunResult` object with exitCode, stdout, stderr, activity, and optional error fields
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:06:48.515Z
Learning: `ExitError` is thrown by `adapter.exit()` and should be caught by CLI dispatch layer
Learnt from: CR
Repo: kjanat/dreamcli
Timestamp: 2026-05-01T11:06:48.515Z
Learning: Runtime module is not truly independent of core — imports `WriteFn` from `core/output/` and `ReadFn` from `core/prompt/`
📚 Learning: 2026-02-11T11:57:27.623Z
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 3
File: src/core/cli/cli-completion-e2e.test.ts:9-16
Timestamp: 2026-02-11T11:57:27.623Z
Learning: Enforce explicit .ts extensions in all relative imports for TypeScript source files (enabled by allowImportingTsExtensions and noEmit in tsconfig.json). This applies to both static and dynamic imports. For each TypeScript file, update relative import paths to end with .ts (e.g., './utils/helper' -> './utils/helper.ts'). Ensure tooling (linting/eslint rules or a codemod) flags missing extensions and provides a quick fix. This guideline should cover all TypeScript files in the repo, not just a single test or module.
Applied to files:
examples/standalone/testing.tspackages/dreamcli/src/core/schema/prompt.test.tsexamples/standalone/middleware.tsexamples/standalone/json-mode.tsexamples/standalone/multi-command.tsexamples/standalone/interactive.tspackages/dreamcli/src/core/resolve/resolve-prompt.test.tsexamples/standalone/spinner-progress.tsapps/docs/reference/symbols/main/[slug].paths.tsexamples/standalone/basic.tsapps/docs/examples/examples.data.tsapps/docs/examples/[slug].paths.tsapps/docs/reference/api.data.tspackages/dreamcli/src/runtime/support.test.ts
📚 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 repo, the explicit type annotation `Readonly<Record<string, string>>` applied to `const` object literals is an intentional documentation/intent pattern. Do not flag it as redundant or unnecessary (e.g., for being inferable) when reviewing TypeScript/TSX files; treat this explicitness as acceptable by design.
Applied to files:
examples/standalone/testing.tspackages/dreamcli/src/core/schema/prompt.test.tsexamples/standalone/middleware.tsexamples/standalone/json-mode.tsexamples/standalone/multi-command.tsexamples/standalone/interactive.tspackages/dreamcli/src/core/resolve/resolve-prompt.test.tsexamples/standalone/spinner-progress.tsapps/docs/reference/symbols/main/[slug].paths.tsexamples/standalone/basic.tsapps/docs/examples/examples.data.tsapps/docs/examples/[slug].paths.tsapps/docs/reference/api.data.tspackages/dreamcli/src/runtime/support.test.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: For this repository, Windows is explicitly not a supported/targeted platform. During code review, do not raise issues about Windows-specific path separators or normalization differences (e.g., use of `path.sep`, handling forward-slash vs backslash, or `normalize()`-related concerns). These checks should be treated as out-of-scope because the project is intended for Linux/macOS only.
Applied to files:
examples/standalone/testing.tspackages/dreamcli/src/core/schema/prompt.test.tsexamples/standalone/middleware.tsexamples/standalone/json-mode.tsexamples/standalone/multi-command.tsexamples/standalone/interactive.tspackages/dreamcli/src/core/resolve/resolve-prompt.test.tsexamples/standalone/spinner-progress.tsapps/docs/reference/symbols/main/[slug].paths.tsexamples/standalone/basic.tsapps/docs/examples/examples.data.tsapps/docs/examples/[slug].paths.tsapps/docs/reference/api.data.tspackages/dreamcli/src/runtime/support.test.ts
📚 Learning: 2026-02-12T15:52:24.166Z
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 4
File: src/core/resolve/resolve-arg-env.test.ts:1-7
Timestamp: 2026-02-12T15:52:24.166Z
Learning: In test files, do not require the module JSDoc tag at the top. This rule applies to all test files, while non-test source files should still require the module tag. Use the pattern **/*.test.{ts,tsx} to cover all test TypeScript test files (adjust if your project uses only .ts tests).
Applied to files:
packages/dreamcli/src/core/schema/prompt.test.tspackages/dreamcli/src/core/resolve/resolve-prompt.test.tspackages/dreamcli/src/runtime/support.test.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, require the `module` JSDoc tag only for library source files under `src/` (e.g., `src/**/*.ts`). Files outside `src/` such as runnable demo/example scripts under `examples/` are not considered source code for this rule and should not be required to include `module`.
Applied to files:
packages/dreamcli/src/core/schema/prompt.test.tspackages/dreamcli/src/core/resolve/resolve-prompt.test.tspackages/dreamcli/src/runtime/support.test.ts
📚 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:
apps/docs/guide/getting-started.mdpackages/dreamcli/README.md
📚 Learning: 2026-04-07T08:45:53.051Z
Learnt from: kjanat
Repo: kjanat/dreamcli PR: 9
File: package.json:121-129
Timestamp: 2026-04-07T08:45:53.051Z
Learning: When reviewing package.json `devEngines`, do not treat EBADDEVENGINES warnings as a breaking issue if the block intentionally uses Bun (e.g., `{ "name": "bun" }`) and the corresponding `onFail` values are soft (`onFail: "warn"` or `onFail: "ignore"`). npm may consider `bun` an invalid/unsupported engine name and warn, but with these `onFail` settings it won’t hard-fail—so the intent should be respected unless `onFail` is set to `fail` or similar hard-failure behavior.
Applied to files:
packages/dreamcli/package.jsonpackage.json
🪛 ast-grep (0.42.1)
packages/dreamcli/src/runtime/support.test.ts
[warning] 23-25: Regular expression constructed from variable input detected. This can lead to Regular Expression Denial of Service (ReDoS) attacks if the variable contains malicious patterns. Use libraries like 'recheck' to validate regex safety or use static patterns.
Context: new RegExp(
${escapeRegExp(displayName)}[\\s\\S]*?>=(?:\\\\u00a0|\\s)*${escapeRegExp(minimum)},
)
Note: [CWE-1333] Inefficient Regular Expression Complexity [REFERENCES]
- https://owasp.org/www-community/attacks/Regular_expression_Denial_of_Service_-_ReDoS
- https://cwe.mitre.org/data/definitions/1333.html
(regexp-from-variable)
🪛 LanguageTool
packages/dreamcli/README.md
[grammar] ~175-~175: Ensure spelling is correct
Context: ... --steps 3 // mycli db seed ``` ## Why dreamcli Most TypeScript CLI frameworks treat the...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🪛 PSScriptAnalyzer (1.25.0)
examples/pwsh-demo/smoke-powershell.ps1
[warning] 44-44: Invoke-Expression is used. Please remove Invoke-Expression from script and find other options instead.
(PSAvoidUsingInvokeExpression)
🔇 Additional comments (32)
examples/standalone/interactive.ts (1)
16-19: Docs path update is correct and consistent with the workspace move.
No concerns here; these usage lines now correctly point toexamples/standalone/interactive.ts.packages/dreamcli/src/core/schema/prompt.test.ts (1)
536-536: Ahoy — clearer test intent, nicely done.Marking this as “at runtime” makes the scope explicit and matches what the test actually exercises. Solid cleanup, matey.
examples/pwsh-demo/smoke-powershell.ps1 (1)
44-44: Aye, this be the right fix for native completion script execution.Switching to direct
Invoke-Expression $nativeCompletionScriptpreserves the generated script content as-is and matches the completion generator’s newline/quoting expectations. Good smoke-test hardening.examples/standalone/json-mode.ts (1)
9-14: Aye, this path correction be clean and correct.The usage commands now correctly target
examples/standalone/json-mode.ts, and the example docblock contract remains intact. Good fix.As per coding guidelines: "
examples/standalone/*.ts: Top-level example docblocks must follow a contract: title line, optional prose,Demonstrates:, andUsage:sections.".dprint.jsonc (4)
12-19: Biome associations are correctly remapped to the new docs location.Aye, this is tidy: Line 14 and Line 15 exclude the moved docs/twoslash paths exactly where they should.
23-23: Markdown/markup exclusions stay in lockstep.Good rigging here—same docs/twoslash exclusions on Line 23 and Line 33 keeps behavior predictable.
Also applies to: 33-33
53-53: Prettier association scope looks right for the workspace layout.Line 53 is a solid catch-all for READMEs plus docs/twoslash markdown/TS formatting.
58-59: Formatter plugin upgrades and sortpackagejson plugin adoption look clean.No leaks in the hull here—this plugin set is coherent with the config changes.
Also applies to: 63-63, 66-66, 68-68
examples/standalone/basic.ts (2)
27-31: Aye, this repeat guard is solid.Finite-check + floor + clamp keeps the example safe from NaN/Infinity/huge-loop nonsense and still easy to teach from.
8-11: Good path fix in the usage header.The usage examples now point to
examples/standalone/basic.ts, which matches the workspace move.packages/dreamcli/src/runtime/support.test.ts (2)
14-28: Good extraction: the matcher helper is cleaner and safer.Escaping runtime fragments before
RegExpconstruction and centralizing the assertion reduced duplication without weakening test intent.
60-63: Nice monorepo path realignment.These reads now correctly target
apps/docs/..., and the shared matcher keeps all three docs checks consistent.Also applies to: 70-75, 81-87
apps/docs/guide/getting-started.md (2)
46-50: Good sync with the example logic.The docs snippet now uses the same
repeatCountsanitization path as the standalone example, so readers copy behavior that’s actually safe.
22-24: Runtime minimum block update looks aligned.This keeps the getting-started runtime section in step with the runtime-support docs/tests.
examples/standalone/testing.ts (1)
9-12: Aye, perfectly squared away, matey!Ye've updated the path references in the docblock to match the new
examples/standalone/location after yer monorepo restructure. The usage instructions be accurate and runnable now, keepin' the example shipshape for landlubbers tryin' to learn the testkit.Fair winds! 🏴☠️
examples/standalone/multi-command.ts (1)
9-16: Nice path correction for the standalone move.Aye, these usage examples now point to
examples/standalone/...consistently and match the monorepo layout.apps/docs/examples/[slug].paths.ts (1)
10-17: Shared data imports and watcher scope look shipshape.Arrr, this aligns the loader with the packaged docs data utilities and the standalone examples watch target.
apps/docs/examples/examples.data.ts (1)
10-14: Good alignment with shared docs pipeline.Aye, the type/value imports are clean, and the watcher now tracks the moved standalone examples path.
Also applies to: 28-28
apps/docs/reference/symbols/main/[slug].paths.ts (1)
13-16: Watcher targets are corrected for the new workspace map.Arrr, this now watches the right source roots for symbol-page regeneration.
apps/docs/reference/api.data.ts (1)
10-12: Solid import migration and watch-path update.Aye, this keeps API data loading in step with the shared docs package and new monorepo paths.
Also applies to: 34-34
packages/dreamcli/package.json (4)
95-97: Thisvitein optionalDependencies issue be already flagged, ye stubborn barnacles!Arrr, I see the previous review already called out that
viteinoptionalDependenciesleaks tooling into the published runtime surface. Library consumers don't need to be downloadin' build tools when theynpm install@kjanat/dreamcli``. Thevitedependency already lives in `apps/docs/package.json` where it belongs.As per the learnings: "Do not add runtime dependencies to
packages/dreamcli".
1-35: Aye, this be a proper package manifest structure!The internal import aliases be well-organized fer development convenience (
#dreamcli,#internals/*,#schema,#package.json), and they align with what theemit-definition-schema.tsscript be expectin'. The schema emission script imports from#dreamcliand#package.json, and these aliases resolve correctly to the source files.The metadata be complete and the repository directory path be accurate fer the monorepo structure.
36-69: The exports map be shipshape, ye perfectionist sea dog!Proper condition ordering with
typesfirst, thenbun/denopointin' to source fer native runtime consumption, anddefaultfallin' back to the built.mjsartifacts. The files whitelist correctly excludes test files and AGENTS.md from the published tarball while includin' the source fer Bun/Deno users.This be exactly how a multi-runtime package should be rigged!
70-80: Scripts be properly rigged fer the build pipeline.The use of
bunx --bun tsdownensures Bun's native performance, and havin' bothtsgo(native TypeScript preview) andtscfer typecheckin' gives ye flexibility. Theprepackhook ensures the build runs before publishin'.packages/dreamcli/README.md (6)
485-493: This "Three subpath exports" discrepancy be already flagged, ye forgetful swabs!Arrr, the previous review already pointed out that this section claims "Three subpath exports" but the package.json actually exports five entry points:
@kjanat/dreamcli(root)@kjanat/dreamcli/runtime@kjanat/dreamcli/testkit@kjanat/dreamcli/schema— MISSING FROM TABLE@kjanat/dreamcli/package.json— (this one can be omitted from docs)Fix the headin' to say "Four public entry points" and add a row fer the schema artifact!
1-70: Arrr, this be some fine documentation, ye literary pirates!The opening example demonstrates the full resolution chain beautifully — from flag declaration through to typed action handler. The badges be properly linked, and the install instructions cover npm, bun, and deno. The collapsible details block fer alternative runtimes be a nice touch fer keepin' things tidy.
The claim "Zero runtime dependencies" better be true, which it will be once ye remove that
vitefrom optionalDependencies in the package.json!
71-174: These quick start examples be worthy of a captain's approval!The single command example shows the defensive repeat count clamping (lines 93-95) — good work preventin' infinite loops and invalid input, ye paranoid perfectionist. The multi-command example demonstrates nested command groups with the
dbgroup containin'migrateandseed. The usage comments at the end be helpful fer landlubbers.Me autistic brain be pleased with the thoroughness here.
175-200: The comparison table be a fine piece of persuasion, matey!The static analysis tool flagged "dreamcli" as a spellin' error at line 175, but that be yer product name, so ignore that landlubber tool's complaint. The comparison table honestly shows where dreamcli excels versus the competition without bein' dishonest about what the others offer.
The tRPC comparison be apt — "the insight was wiring them so types flow end-to-end." That be the treasure here.
388-484: The testing documentation be a thing of beauty!This section demonstrates
runCommand()with every control dimension: basic execution, env resolution, config resolution, prompt answers, and activity event capture. The examples be complete and actually runnable. Me perfectionist heart be singin'!The
RunOptionssummary at lines 482-483 lists all the controllable dimensions clearly. This be what good testkit documentation looks like.
497-508: Runtime support matrix be accurate and matches the package engines.
Documented package.json engines Node.js >= 22.22.2 "node": ">=22.22.2"✓Bun >= 1.3 "bun": ">=1.3"✓Deno >= 2.6.0 "deno": ">=2.6.0"✓The explanation about the
RuntimeAdapterinterface handlin' platform-specific edges be important fer consumers who want to understand how the multi-runtime support works. Good work keepin' the docs in sync with the manifest, ye meticulous pirates!package.json (1)
1-100: Arrr, this be a fine monorepo conversion, matey!The workspace structure be properly rigged for Bun workspaces. The
--filterincantations in yer scripts be idiomatic, the catalog centralizes yer dependency versions like a proper treasure chest, and thedevEnginesblock respects the Bun runtime without hard-failin'. The parallel dev script on line 19 with&andwaitbe a clever bit of shell work for runnin' the build watcher alongside the docs server.Smooth sailin' here, ye scurvy dogs did good work!
examples/standalone/spinner-progress.ts (1)
9-11: Aye, the paths be chartin' true now, matey!Ye've updated the usage examples to reflect the new
examples/standalone/location. Clean as a freshly swabbed deck!
| import { createSchema } from '#internals/core/schema/index.ts'; | ||
| import type { ResolveOptions } from './index.ts'; | ||
| import { COMPATIBLE_PROMPT_KINDS } from './flags.ts'; | ||
| import type { ResolveOptions } from './index.ts'; |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win
Avast! Barrel import in the resolve/ hold violates the coding guidelines, matey!
Ye be importin' ResolveOptions from the barrel (./index.ts), but the guidelines be mighty clear: use direct-file imports in the resolve/ directory to dodge circular dependency krakens.
As per coding guidelines: "Use direct-file imports instead of barrel imports in cli/, completion/, output/, prompt/, resolve/, and runtime/ to avoid circular dependencies"
⚓ Proposed fix — import directly from contracts.ts
-import type { ResolveOptions } from './index.ts';
+import type { ResolveOptions } from './contracts.ts';📝 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.
| import type { ResolveOptions } from './index.ts'; | |
| import type { ResolveOptions } from './contracts.ts'; |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/dreamcli/src/core/resolve/resolve-prompt.test.ts` at line 17,
Replace the barrel import of ResolveOptions with a direct-file import from the
resolve directory: change the import that currently references './index.ts' to
import ResolveOptions from './contracts.ts' in resolve-prompt.test.ts so the
test uses the concrete contracts file and avoids barrel-induced circular
dependencies; locate the existing import statement that declares ResolveOptions
and update its module path to './contracts.ts'.
1 participant
Summary
packages/dreamcli/, docs →apps/docs/, gh-project tool →tools/gh-project/, examples split intoexamples/standalone/andexamples/gh/package.jsoncatalog; bump wrangler, pin biome, add vitepress overriderelease-meta.shwith TypeScriptrelease-meta.ts; modernize CI workflows for new workspace layoutTest plan
bun run cipasses (typecheck + lint + format + meta + test + docs + build)bun run testpasses across all workspacesbun run docs:buildsucceeds without Twoslash errorsbun run bdproduces correct build artifacts inpackages/dreamcli/dist/examples/ghstill typechecks and tests pass