@forinda/kickjs-cli 8.15.0 → 8.16.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/agent-docs-BVFt7K8T.mjs +591 -0
- package/dist/agent-docs-BVFt7K8T.mjs.map +1 -0
- package/dist/agent-docs-DBLN2Mp9.mjs +590 -0
- package/dist/{build-gqxIH3D8.mjs → build-BKGmBYPE.mjs} +3 -3
- package/dist/{build-gqxIH3D8.mjs.map → build-BKGmBYPE.mjs.map} +1 -1
- package/dist/{build-Czsf4CBN.mjs → build-BmjXHtAh.mjs} +2 -2
- package/dist/{builtins-6euI1-lN.mjs → builtins-C-qFcIBD.mjs} +2 -2
- package/dist/{builtins-xahWxQLw.mjs → builtins-NIDfVClB.mjs} +59 -59
- package/dist/cli.mjs +2 -2
- package/dist/{config-DCM2vXUJ.mjs → config-C881BGnv.mjs} +2 -2
- package/dist/{config-8jdSKLKJ.mjs → config-CgoZjmsu.mjs} +3 -3
- package/dist/{config-8jdSKLKJ.mjs.map → config-CgoZjmsu.mjs.map} +1 -1
- package/dist/{doctor-CwGU9orm.mjs → doctor-CWP1-2fB.mjs} +9 -9
- package/dist/{doctor-CwGU9orm.mjs.map → doctor-CWP1-2fB.mjs.map} +1 -1
- package/dist/{fullstack-9HywHQL-.mjs → fullstack-BPB6BkL8.mjs} +13 -13
- package/dist/{fullstack-9HywHQL-.mjs.map → fullstack-BPB6BkL8.mjs.map} +1 -1
- package/dist/{fullstack-BmIFnryN.mjs → fullstack-_0qGKsG7.mjs} +9 -9
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +2 -2
- package/dist/{plugin-BjmLRF7t.mjs → plugin-KpSiVmlT.mjs} +2 -2
- package/dist/{plugin-DLZP4hZ0.mjs → plugin-_Xkj7vNO.mjs} +2 -2
- package/dist/project-CO9buk5F.mjs +133 -0
- package/dist/project-CO9buk5F.mjs.map +1 -0
- package/dist/project-qHDV333j.mjs +132 -0
- package/dist/{project-root-Dk8r8FMi.mjs → project-root-BAZV1qId.mjs} +3 -3
- package/dist/{project-root-Dk8r8FMi.mjs.map → project-root-BAZV1qId.mjs.map} +1 -1
- package/dist/{project-root-8DH00M-b.mjs → project-root-DdPFoCw6.mjs} +2 -2
- package/dist/{rolldown-runtime-CRasMkPY.mjs → rolldown-runtime-B0Wm12ok.mjs} +1 -1
- package/dist/{run-plugins-R0bVf_nK.mjs → run-plugins-DLCZx7uc.mjs} +67 -67
- package/dist/run-plugins-DLCZx7uc.mjs.map +1 -0
- package/dist/{typegen-DNufBmjE.mjs → typegen-B8uRTy_3.mjs} +4 -4
- package/dist/{typegen-BZ8cQ1YM.mjs → typegen-DGq3DowV.mjs} +5 -5
- package/dist/{typegen-BZ8cQ1YM.mjs.map → typegen-DGq3DowV.mjs.map} +1 -1
- package/dist/{types-DOcxTXlP.mjs → types-CokUufqE.mjs} +1 -1
- package/package.json +4 -4
- package/templates/base/files/_dot_vscode/extensions.json +3 -0
- package/templates/base/files/kick.config.ts +4 -0
- package/templates/base/skills/add-adapter.txt +56 -0
- package/templates/base/skills/add-module.txt +53 -0
- package/templates/base/skills/add-plugin.txt +69 -0
- package/templates/base/skills/bootstrap-export.txt +21 -0
- package/templates/base/skills/cli-commands-cheatsheet.txt +46 -0
- package/templates/base/skills/cli-plugin.txt +61 -0
- package/templates/base/skills/context-contributor.txt +73 -0
- package/templates/base/skills/deny-list.txt +44 -0
- package/templates/base/skills/deploy.txt +99 -0
- package/templates/base/skills/docs-lookup.txt +40 -0
- package/templates/base/skills/env-wiring-check.txt +44 -0
- package/templates/base/skills/guard-vs-middleware-vs-contributor.txt +95 -0
- package/templates/base/skills/query-parsing-list-endpoint.txt +48 -0
- package/templates/base/skills/refresh-agent-docs.txt +27 -0
- package/templates/base/skills/route-flags.txt +73 -0
- package/templates/base/skills/thin-entry-file.txt +49 -0
- package/templates/base/skills/use-asset-manager.txt +61 -0
- package/templates/base/skills/write-controller-test.txt +63 -0
- package/templates/feature-views/feature.json +21 -0
- package/templates/feature-views/files/src/adapters/views.ts +5 -0
- package/templates/feature-views/files/src/views/home.kick +3 -0
- package/templates/feature-views/files/src/views/layouts/main.kick +13 -0
- package/templates/feature-views/files/src/views.ts +9 -0
- package/templates/feature-views/skills/views-forms.txt +68 -0
- package/templates/feature-views/skills/views.txt +49 -0
- package/templates/fullstack-root/files/_dot_vscode/extensions.json +3 -0
- package/dist/agent-docs-CrVQtJgn.mjs +0 -932
- package/dist/agent-docs-D7K6R5C3.mjs +0 -933
- package/dist/agent-docs-D7K6R5C3.mjs.map +0 -1
- package/dist/package-manager-9XxrErw1.mjs +0 -11
- package/dist/package-manager-Dwaolesm.mjs +0 -12
- package/dist/package-manager-Dwaolesm.mjs.map +0 -1
- package/dist/project-CFi3NvO9.mjs +0 -136
- package/dist/project-CFi3NvO9.mjs.map +0 -1
- package/dist/project-CO0D8B0V.mjs +0 -135
- package/dist/run-plugins-R0bVf_nK.mjs.map +0 -1
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@forinda/kickjs-cli",
|
|
3
|
-
"version": "8.
|
|
3
|
+
"version": "8.16.1",
|
|
4
4
|
"description": "CLI for KickJS — project scaffolding, DDD module generation, dev/build/start",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"kickjs",
|
|
@@ -41,9 +41,9 @@
|
|
|
41
41
|
"oxfmt": "^0.72.0",
|
|
42
42
|
"picocolors": "^1.1.1",
|
|
43
43
|
"pluralize": "^8.0.0",
|
|
44
|
-
"@forinda/kickjs": "10.
|
|
45
|
-
"@forinda/kickjs-
|
|
46
|
-
"@forinda/kickjs-
|
|
44
|
+
"@forinda/kickjs": "10.13.1",
|
|
45
|
+
"@forinda/kickjs-db": "8.11.3",
|
|
46
|
+
"@forinda/kickjs-cli-kit": "0.1.3"
|
|
47
47
|
},
|
|
48
48
|
"devDependencies": {
|
|
49
49
|
"@swc/core": "^1.16.18",
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { defineConfig } from '@forinda/kickjs-cli'
|
|
2
|
+
// @kick:imports
|
|
2
3
|
|
|
3
4
|
export default defineConfig({
|
|
4
5
|
pattern: '{{template}}',
|
|
@@ -10,6 +11,9 @@ export default defineConfig({
|
|
|
10
11
|
// Pinned so `kick add` and other dep-installing commands always use the
|
|
11
12
|
// project's intended package manager, regardless of which lockfile exists.
|
|
12
13
|
packageManager: '{{packageManager}}',
|
|
14
|
+
plugins: [
|
|
15
|
+
// @kick:config-plugin
|
|
16
|
+
],
|
|
13
17
|
modules: {
|
|
14
18
|
dir: 'src/modules',
|
|
15
19
|
// @kick:repo
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: kickjs-add-adapter
|
|
3
|
+
description: Use when wiring a single-concern lifecycle integration (Swagger, DevTools, Sentry, Redis client).
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
**Steps**:
|
|
7
|
+
1. `kick g adapter <name>` to scaffold the boilerplate, OR install via `kick add <package>` for first-party adapters.
|
|
8
|
+
2. The generated file uses `defineAdapter()` — never `class implements AppAdapter`.
|
|
9
|
+
3. Add the adapter instance (note the parens) to `src/adapters/index.ts` — don't inline in `src/index.ts`.
|
|
10
|
+
4. Pick the right hook and middleware phase deliberately.
|
|
11
|
+
5. Verify with `kick dev` that the adapter's lifecycle logs fire.
|
|
12
|
+
|
|
13
|
+
**Canonical shape** — factory closure owns instance state:
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
export const RedisAdapter = defineAdapter<RedisConfig>({
|
|
17
|
+
name: 'RedisAdapter',
|
|
18
|
+
defaults: { url: 'redis://localhost' },
|
|
19
|
+
build: (config) => {
|
|
20
|
+
const client = createClient(config.url)
|
|
21
|
+
return {
|
|
22
|
+
beforeStart: ({ container }) => {
|
|
23
|
+
container.registerInstance(REDIS_CLIENT, client)
|
|
24
|
+
},
|
|
25
|
+
afterStart: () => client.connect(),
|
|
26
|
+
shutdown: () => client.quit(),
|
|
27
|
+
}
|
|
28
|
+
},
|
|
29
|
+
})
|
|
30
|
+
|
|
31
|
+
// In src/adapters/index.ts:
|
|
32
|
+
export const adapters = [RedisAdapter({ url: getEnv('REDIS_URL') })] // <-- note parens
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
**Lifecycle hook decision tree**:
|
|
36
|
+
- `beforeMount` — register early routes that should bypass middleware (health, docs UI).
|
|
37
|
+
- `beforeStart` — DI ready, server not listening yet. **Use this for `container.registerInstance(...)` calls** so they work under `createTestApp` too.
|
|
38
|
+
- `afterStart` — server has `ctx.server` available. Only use for things that need a listening server (Socket.IO upgrades, port logging). **Doesn't fire under `createTestApp`.**
|
|
39
|
+
- `shutdown` — runs concurrently via `Promise.allSettled`, so one failure doesn't block siblings (but errors are swallowed — log inside).
|
|
40
|
+
|
|
41
|
+
**Middleware phases** (see `MiddlewarePhase` JSDoc):
|
|
42
|
+
`beforeGlobal` | `afterGlobal` (default) | `beforeRoutes` | `afterRoutes` (fires only on fall-through — matched routes that respond skip it).
|
|
43
|
+
|
|
44
|
+
**Multi-instance** — `.scoped('cache', { url: ... })` makes `name` become `RedisAdapter:cache`. **Deferred config** — `.async({ inject, useFactory })` for config that depends on DI-resolved services.
|
|
45
|
+
|
|
46
|
+
**Red flags**:
|
|
47
|
+
- `bootstrap({ adapters: [MyAdapter] })` — passed the factory, not the instance. Call it: `MyAdapter()`.
|
|
48
|
+
- Inlining the adapter list directly in `src/index.ts` — entry file should stay thin.
|
|
49
|
+
- Returning a plain object instead of going through `defineAdapter()` — type inference for `config` will be wrong.
|
|
50
|
+
- Using `.async()` for an adapter that returns `middleware()` / `contributors()` / `beforeMount()` / `onRouteMount()` — those hooks have already run by the time `.async()` resolves and are silently skipped.
|
|
51
|
+
- Cross-adapter ordering via array position when it's load-bearing — use `dependsOn: ['OtelAdapter']`; cycles throw `MountCycleError` at boot.
|
|
52
|
+
- Using an adapter when the integration ships **modules + DI bindings + middleware** together → that's a plugin. Promote to `definePlugin()` (see `add-plugin` skill).
|
|
53
|
+
|
|
54
|
+
**Nuances**:
|
|
55
|
+
- `AdapterContext.server` is `undefined` outside `afterStart`.
|
|
56
|
+
- `shutdown` errors are swallowed by `Promise.allSettled` — wrap in try/catch and log if you care.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: kickjs-add-module
|
|
3
|
+
description: Use when the user asks to add a new feature module (controller + service + repo + DTOs).
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
**Trigger phrases**: "add a users module", "scaffold tasks", "new feature for X".
|
|
7
|
+
|
|
8
|
+
**Steps**:
|
|
9
|
+
1. Run `kick g module <name>` (use plural form if the project pluralizes — check `kick.config.ts`).
|
|
10
|
+
2. Verify the new folder under `src/modules/<name>/` contains `<name>.module.ts` (filename suffix is mandatory for Vite HMR).
|
|
11
|
+
3. Confirm the module appears in `src/modules/index.ts` exports — generator does this automatically; verify if you bypassed it.
|
|
12
|
+
4. Open `<name>.dto.ts` and tighten the Zod schemas to real fields (the generator emits placeholders).
|
|
13
|
+
5. Run `kick typecheck` and `{{pm}} run test` before claiming done.
|
|
14
|
+
|
|
15
|
+
**Canonical module shape** — `defineModule` factory, never `class implements AppModule`:
|
|
16
|
+
|
|
17
|
+
```ts
|
|
18
|
+
export const TodosModule = defineModule({
|
|
19
|
+
name: 'TodosModule',
|
|
20
|
+
build: () => ({
|
|
21
|
+
register(container) {
|
|
22
|
+
container.registerFactory(TODO_REPO, () => createTodoRepository())
|
|
23
|
+
},
|
|
24
|
+
routes() {
|
|
25
|
+
return { path: '/todos', controller: TodosController }
|
|
26
|
+
},
|
|
27
|
+
}),
|
|
28
|
+
})
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
The module file MUST include `import.meta.glob([...], { eager: true })` for every `@Controller` / `@Service` / `@Repository` / `@Component` class — without it, decorators never fire and DI silently resolves to `undefined` (or routes vanish). Use **recursive** patterns (`./**/*.controller.ts`) so the glob keeps working when you nest files into sub-folders (`controllers/`, `presentation/`, …). If you reorganise and a class stops loading, `kick typegen` flags it as orphaned and `kick typegen --fix` patches the glob for you.
|
|
32
|
+
|
|
33
|
+
**Multiple route sets / versioning** — `routes()` may return an array with per-entry `version` override:
|
|
34
|
+
|
|
35
|
+
```ts
|
|
36
|
+
routes() {
|
|
37
|
+
return [
|
|
38
|
+
{ path: '/todos', controller: TodosController }, // /api/v1/todos
|
|
39
|
+
{ path: '/todos', version: 2, controller: TodosV2Controller }, // /api/v2/todos
|
|
40
|
+
]
|
|
41
|
+
}
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
**Conditional / per-tenant mounting** — use `bootstrap({ setup(registry) { registry.mount(...) } })`, not the static `modules` array.
|
|
45
|
+
|
|
46
|
+
**Composition** — `defineModules().mount(TodosModule()).mount(UsersModule())` (fluent) or `AppModuleEntry[]` (array form).
|
|
47
|
+
|
|
48
|
+
**Red flags** (stop and ask):
|
|
49
|
+
- File created as `<name>.ts` instead of `<name>.module.ts` — Vite plugin's `*.module.[tj]sx?` glob doesn't pick it up; every save becomes a full restart.
|
|
50
|
+
- `@Controller('/path')` with a path argument — `@Controller()` takes no arguments; the prefix goes in the module's `routes().path`.
|
|
51
|
+
- `TodosModule` instead of `TodosModule()` for a module that takes config — refused, since the bare name would silently select the defaults. A module with no config accepts either, but prefer the invoked form for consistency.
|
|
52
|
+
- `routes()` returning `router: …` when a `controller:` would do — controller form is required for OpenAPI/Swagger introspection.
|
|
53
|
+
- Module not registered in `src/modules/index.ts`.
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: kickjs-add-plugin
|
|
3
|
+
description: Use when scaffolding a feature that bundles modules + DI + middleware + adapters together (auth, monitoring suite, multi-tenant scaffolding).
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
**When plugin > adapter**: a plugin is the right answer when the integration ships **more than one** of: a module, a DI binding, middleware, or another adapter. If you have a single hook (`beforeStart`) and no other contributions, use `defineAdapter` instead.
|
|
7
|
+
|
|
8
|
+
**Canonical shape**:
|
|
9
|
+
|
|
10
|
+
```ts
|
|
11
|
+
import { definePlugin } from '@forinda/kickjs'
|
|
12
|
+
|
|
13
|
+
export const AuthPlugin = definePlugin({
|
|
14
|
+
name: 'AuthPlugin',
|
|
15
|
+
defaults: { tokenTtl: '1h' },
|
|
16
|
+
build: (config, { name }) => ({
|
|
17
|
+
modules: () => [AuthModule()],
|
|
18
|
+
adapters: () => [JwtAdapter({ ttl: config.tokenTtl })],
|
|
19
|
+
middleware: () => [requestIdMiddleware()],
|
|
20
|
+
register(container) {
|
|
21
|
+
container.registerFactory(TOKEN_SIGNER, () => createSigner(config))
|
|
22
|
+
},
|
|
23
|
+
contributors() {
|
|
24
|
+
return [LoadCurrentUser.registration]
|
|
25
|
+
},
|
|
26
|
+
onReady({ server }) {
|
|
27
|
+
log.info(`AuthPlugin listening on port ${server.address().port}`)
|
|
28
|
+
},
|
|
29
|
+
}),
|
|
30
|
+
})
|
|
31
|
+
|
|
32
|
+
// In bootstrap:
|
|
33
|
+
bootstrap({ plugins: [AuthPlugin({ tokenTtl: getEnv('TOKEN_TTL') })] }) // <-- parens
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
**Inline plugin literal** — the canonical answer for one-off DI bindings. There's no top-level `register:` on `bootstrap` itself:
|
|
37
|
+
|
|
38
|
+
```ts
|
|
39
|
+
bootstrap({
|
|
40
|
+
plugins: [{ name: 'vector-store', register(c) { c.registerInstance(VECTOR_STORE, store) } }],
|
|
41
|
+
})
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
**Execution order** (memorize):
|
|
45
|
+
plugin `register()` → plugin `middleware()` → plugin `modules()` + user modules → plugin `adapters()` + user adapters → server listens → plugin `onReady()`.
|
|
46
|
+
|
|
47
|
+
**Static vs dynamic modules**: `modules()` returning an array is introspectable (Swagger, DevTools see it). `setup(registry)` is imperative — pick the latter when the module set depends on resolved config.
|
|
48
|
+
|
|
49
|
+
**Multi-instance** — `.scoped('users', { url })`; derive unique DI tokens from `ctx.name` inside `build`:
|
|
50
|
+
|
|
51
|
+
```ts
|
|
52
|
+
build: (config, { name }) => ({
|
|
53
|
+
register(c) {
|
|
54
|
+
c.registerInstance(createToken(`cache/${name}`), client)
|
|
55
|
+
},
|
|
56
|
+
})
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
**Precedence**: plugin contributors land at `'adapter'` precedence — beat global, lose to module/class/method same-key.
|
|
60
|
+
|
|
61
|
+
**Red flags**:
|
|
62
|
+
- `bootstrap({ plugins: [AuthPlugin] })` — passed factory. Call it: `AuthPlugin()`.
|
|
63
|
+
- Reaching for a plugin when an adapter would do (no modules, no DI bindings, no contributors) — overkill; use `defineAdapter()`.
|
|
64
|
+
- `.async()` plugin that depends on `modules()` / `middleware()` / `adapters()` / `contributors()` — those are dropped. `.async()` only resolves `register()` + `onReady()`.
|
|
65
|
+
- Confusing CLI plugins (`defineCliPlugin` from `@forinda/kickjs-cli`) with runtime plugins (`definePlugin` from `@forinda/kickjs`) — different surfaces, different registration sites.
|
|
66
|
+
- `dependsOn: ['SomePlugin']` referring to a plugin not in the boot list — throws `MissingMountDepError` at boot.
|
|
67
|
+
|
|
68
|
+
**Nuances**:
|
|
69
|
+
- `definition` is `Object.freeze`'d metadata; useful for version checks (`compare(AuthPlugin.definition.version, '1.2.0')`) — not mountable.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: kickjs-bootstrap-export
|
|
3
|
+
description: Use when HMR is silently doing full restarts on every save, or createTestApp can't find the app handle.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
**Check** `src/index.ts`'s last line:
|
|
7
|
+
|
|
8
|
+
```ts
|
|
9
|
+
// CORRECT — Vite plugin + createTestApp import the named `app` symbol
|
|
10
|
+
export const app = await bootstrap({ ... })
|
|
11
|
+
|
|
12
|
+
// WRONG — HMR degrades to full restart, createTestApp loses the handle
|
|
13
|
+
await bootstrap({ ... })
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
The Vite plugin imports the named `app` symbol via `virtual:kickjs/app`; testing helpers do too. Without the export, both fall back to slower paths (full restart on save, mock handle in tests) **without warning**.
|
|
17
|
+
|
|
18
|
+
**Red flags**:
|
|
19
|
+
- A bare `await bootstrap(...)` with no `export` — fix by adding `export const app =`.
|
|
20
|
+
- Re-assigning `app` later in the file (`app = somethingElse`) — Vite imports by reference at module-load time; reassignments don't propagate.
|
|
21
|
+
- Multiple files calling `bootstrap()` — only the entry should. Tests use `createTestApp` instead.
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: kickjs-cli-commands-cheatsheet
|
|
3
|
+
description: Use as a quick reference for the most common kick CLI workflows — scaffolding, dev/build/start, generation, inspection.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
**Top commands**:
|
|
7
|
+
- `kick new <name>` — start a new project (prompts for template / repo / pm).
|
|
8
|
+
- `kick dev` — local dev server with Vite HMR.
|
|
9
|
+
- `kick build` — production bundle via Vite.
|
|
10
|
+
- `kick start` — run the built artifact (`NODE_ENV=production` auto-set).
|
|
11
|
+
- `kick g module <name>` — add a feature module; structure follows `pattern` in `kick.config.ts`.
|
|
12
|
+
- `kick g scaffold <Name> <field:type>...` — full CRUD module from field definitions.
|
|
13
|
+
- `kick g guard <name>` / `kick g middleware <name>` / `kick g contributor <name>` — the three "before the handler" shapes. A guard is a middleware by convention, NOT a separate primitive.
|
|
14
|
+
- `kick add <pkg>` — install optional packages (auto-resolves peer deps + package manager).
|
|
15
|
+
- `kick g --list` — list every available generator (built-ins + plugin-shipped).
|
|
16
|
+
- `kick info` — environment / version dump for bug reports.
|
|
17
|
+
- `kick inspect` — introspect a running app: routes, middleware, adapters, DI graph.
|
|
18
|
+
|
|
19
|
+
**Useful flag combos**:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
kick new my-api --yes # CI-safe: minimal + inmemory, no prompts
|
|
23
|
+
kick new my-api -t rest --pm {{pm}} --no-git --install # Fully scriptable REST scaffold
|
|
24
|
+
kick new . --yes --force # Scaffold into current dir, clear existing files
|
|
25
|
+
kick g scaffold Post title:string body:text:optional # Shell-safe optional field syntax
|
|
26
|
+
kick g agents -f --only skills # Refresh just the skills after upgrade
|
|
27
|
+
kick add queue:bullmq # Package + peer deps (bullmq + ioredis) in one shot
|
|
28
|
+
kick inspect --port 4000 --json # Machine-readable route/adapter dump
|
|
29
|
+
kick g config --force --repo postgres # Drop a kick.config.ts into a legacy project
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
**Lesser-known, high-value**:
|
|
33
|
+
- `kick inspect --watch` — live route/middleware/adapter table that re-renders on hot reload; faster than re-curling `/_debug`.
|
|
34
|
+
- `kick g agents -f` — regenerates `CLAUDE.md` (root) and `.agents/AGENTS.md` / `GEMINI.md` / `COPILOT.md` + every `.agents/skills/<slug>/SKILL.md` from the current CLI templates.
|
|
35
|
+
- `kick dev:debug` — same flags as `kick dev` but opens a Node inspector port for IDE attach.
|
|
36
|
+
- `kick list --all` (alias `kick ls --all`) — full optional-package catalog at this CLI version.
|
|
37
|
+
- `kick typegen --watch` — standalone typegen watcher when `kick dev` isn't running.
|
|
38
|
+
- `kick check` — preflight gate (typecheck + lint + format) before commit.
|
|
39
|
+
- `kick codemod` — automated AST-level migration between framework versions.
|
|
40
|
+
|
|
41
|
+
**Red flags**:
|
|
42
|
+
- Using globally-installed `@forinda/kickjs-cli` while contributing to the monorepo — `pnpm link --global` from `packages/cli` so generators match the framework.
|
|
43
|
+
- Writing `"name:type?"` for optional scaffold fields — `?` is a shell glob in bash/zsh; use `name:type:optional`.
|
|
44
|
+
- Running `kick new <name> --yes` in a non-empty directory expecting it to wipe — `--yes` aborts without `--force`; pair them when destruction is intended.
|
|
45
|
+
- Skipping `kick g config` on a legacy project then wondering why generators ignore `modules.dir` / `modules.repo`.
|
|
46
|
+
- Editing `kick.config.ts` with deprecated top-level `modulesDir` / `defaultRepo` / `schemaDir` / `pluralize` instead of the nested `modules` block.
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: kickjs-cli-plugin
|
|
3
|
+
description: Use when adding a kick <name> command, a kick g <name> generator, or a typegen emitter to this project or a package it ships.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
A CLI plugin contributes commands, generators and typegen emitters to the
|
|
7
|
+
`kick` CLI. Every built-in command ships as one, so the contract is the same
|
|
8
|
+
one the framework uses.
|
|
9
|
+
|
|
10
|
+
**Steps**:
|
|
11
|
+
1. Write the plugin. All four contribution kinds are optional:
|
|
12
|
+
```ts
|
|
13
|
+
// kick-tool.ts
|
|
14
|
+
import { defineCliPlugin } from '@forinda/kickjs-cli'
|
|
15
|
+
|
|
16
|
+
export const toolPlugin = (options: { watch?: boolean } = {}) =>
|
|
17
|
+
defineCliPlugin({
|
|
18
|
+
// Stable id, unique across plugins — it names the plugin in conflict errors.
|
|
19
|
+
name: 'my-tool',
|
|
20
|
+
// Declarative: same shape as kick.config.ts `commands`.
|
|
21
|
+
commands: [{ name: 'db:migrate', description: 'Apply migrations', steps: 'node ./scripts/migrate.js' }],
|
|
22
|
+
// Programmatic: full commander API, when you need options or subcommands.
|
|
23
|
+
register(program, ctx) {
|
|
24
|
+
program
|
|
25
|
+
.command('my-tool')
|
|
26
|
+
.description('Do the thing')
|
|
27
|
+
.option('--watch', 'Watch mode')
|
|
28
|
+
.action(async () => {
|
|
29
|
+
ctx.log(`running in ${ctx.projectRoot}`)
|
|
30
|
+
// ctx.config is the loaded kick.config.ts
|
|
31
|
+
})
|
|
32
|
+
},
|
|
33
|
+
})
|
|
34
|
+
```
|
|
35
|
+
2. Register it in `kick.config.ts`:
|
|
36
|
+
```ts
|
|
37
|
+
import { toolPlugin } from './kick-tool'
|
|
38
|
+
|
|
39
|
+
export default defineConfig({ plugins: [toolPlugin()] })
|
|
40
|
+
```
|
|
41
|
+
3. Check it is loaded, per contribution kind: `kick --help` lists a command,
|
|
42
|
+
`kick g --list` lists a generator, `kick typegen` runs an emitter. A
|
|
43
|
+
plugin that fails to load takes the whole CLI down with a conflict error,
|
|
44
|
+
so silence here means the config never referenced it.
|
|
45
|
+
|
|
46
|
+
**Which kind to use**: `commands` for a shell one-liner, `register` for
|
|
47
|
+
options / subcommands / async work, `generators` (`defineGenerator`) for
|
|
48
|
+
`kick g <name>` scaffolders, `typegens` for a file under `.kickjs/types/`.
|
|
49
|
+
|
|
50
|
+
**Red flags**:
|
|
51
|
+
- Confusing this with a runtime plugin: `defineCliPlugin` (from
|
|
52
|
+
`@forinda/kickjs-cli`) extends the CLI; `definePlugin` (from
|
|
53
|
+
`@forinda/kickjs`) hooks the running app. They share nothing.
|
|
54
|
+
- Claiming a command name a built-in owns (`build:netlify`, `typegen`,
|
|
55
|
+
`generate`) — duplicate declarative names are a startup conflict, and
|
|
56
|
+
`register` has no conflict detection at all, so it silently loses. Namespace
|
|
57
|
+
your own (`my-tool:build`).
|
|
58
|
+
- Doing real work inside `register` — it runs at CLI startup for every
|
|
59
|
+
command, so it must only register. Put the work in the action.
|
|
60
|
+
- Importing heavy dependencies at module scope. `await import()` them inside
|
|
61
|
+
the action, so an unrelated `kick dev` does not pay for them.
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: kickjs-context-contributor
|
|
3
|
+
description: Use when a middleware's only job is to set ctx values consumed elsewhere — replace with defineHttpContextDecorator (HTTP) or defineContextDecorator (transport-agnostic).
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
**Pattern** (HTTP — most common):
|
|
7
|
+
|
|
8
|
+
```ts
|
|
9
|
+
import { defineHttpContextDecorator, type RequestContext } from '@forinda/kickjs'
|
|
10
|
+
|
|
11
|
+
// Augment ContextMeta — required for ctx.get('tenant') to be typed
|
|
12
|
+
declare module '@forinda/kickjs' {
|
|
13
|
+
interface ContextMeta {
|
|
14
|
+
tenant: { id: string; name: string }
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
// The `declare module` block above is all you need for typed `ctx.get`.
|
|
19
|
+
|
|
20
|
+
const LoadTenant = defineHttpContextDecorator({
|
|
21
|
+
key: 'tenant',
|
|
22
|
+
deps: { repo: TENANT_REPO }, // typed DI
|
|
23
|
+
resolve: (ctx, { repo }) => repo.findById(ctx.req.headers['x-tenant-id'] as string),
|
|
24
|
+
})
|
|
25
|
+
|
|
26
|
+
const LoadProject = defineHttpContextDecorator({
|
|
27
|
+
key: 'project',
|
|
28
|
+
dependsOn: ['tenant'], // typo'd key = tsc error
|
|
29
|
+
resolve: (ctx) => projectsRepo.find(ctx.get('tenant')!.id, ctx.params.id),
|
|
30
|
+
})
|
|
31
|
+
|
|
32
|
+
@LoadTenant
|
|
33
|
+
@LoadProject
|
|
34
|
+
@Get('/projects/:id')
|
|
35
|
+
getProject(ctx: RequestContext) {
|
|
36
|
+
return ctx.get('project')
|
|
37
|
+
}
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Use `defineContextDecorator` (no Http prefix) only when the contributor must run across HTTP, WebSocket, queue, and cron transports — `Ctx` defaults to the smaller `ExecutionContext` surface (`get` / `set` / `requestId` only, no `req`).
|
|
41
|
+
|
|
42
|
+
**Five precedence levels** (high → low):
|
|
43
|
+
**method > class > module > adapter > global**
|
|
44
|
+
|
|
45
|
+
Same-key collisions WITHIN a precedence level throw `DuplicateContributorError`. Across levels, the higher precedence silently overrides — a feature, not a bug, but debug it by giving resolvers distinguishable return values.
|
|
46
|
+
|
|
47
|
+
**Boot-time validation**:
|
|
48
|
+
- Cycles in `dependsOn` → `ContributorCycleError`.
|
|
49
|
+
- `dependsOn` referring to an unknown key → `MissingContributorError`.
|
|
50
|
+
- Both errors fail boot, not first request.
|
|
51
|
+
|
|
52
|
+
**Critical rules — all stem from the same shared-via-ALS instance model**:
|
|
53
|
+
- Every per-request stage (middleware → contributors → handler) gets its OWN `RequestContext` instance, but they all read/write the SAME `AsyncLocalStorage`-backed bag.
|
|
54
|
+
- **`resolve` and `onError` must RETURN the value** — the runner writes it via `ctx.set(key, value)`. Direct property assignment (`ctx.tenant = …`) sticks to one instance only and the handler instance never sees it.
|
|
55
|
+
- `ctx.set('tenant', x)` then `ctx.get('tenant')` works across instances. `ctx.req.headers[...]` works (the underlying node request is shared). Note it is a node `IncomingMessage` on Fastify and a web-backed request on h3, not an `express.Request`.
|
|
56
|
+
- Services with no `ctx` reference: `getRequestValue('tenant')` returns `MetaValue<'tenant'> | undefined` (typed via the augmented `ContextMeta`). For `requestId` use `getRequestStore()`.
|
|
57
|
+
- **No `setRequestValue` — writes flow through `ctx.set` or a contributor's return value.** Avoids "spooky action at a distance" where any service can pollute the per-request bag.
|
|
58
|
+
|
|
59
|
+
**Error matrix**:
|
|
60
|
+
- `optional: true` — `resolve` throws → key left unset; downstream sees `ctx.get(key) === undefined`.
|
|
61
|
+
- `optional: false` (default) + `onError` — return a fallback value to write; return `undefined` to skip; throw to forward to the request error handler.
|
|
62
|
+
- `optional: false` + no `onError` — throw propagates straight to the request error handler.
|
|
63
|
+
|
|
64
|
+
**Don't use this for**: response short-circuit, stream mutation, or pre-route-matching work — keep `@Middleware()` for those.
|
|
65
|
+
|
|
66
|
+
**Red flags**:
|
|
67
|
+
- `ctx.get('key')!` — the non-null assertion compiles even when the producing decorator isn't on the route. Use `ctx.require('key')`.
|
|
68
|
+
- `contributors: [LoadX]` at a module / adapter / bootstrap site — those take registrations: `LoadX.registration` or `LoadX.with({ ... }).registration`.
|
|
69
|
+
- A `paramDefaults` value that every call site overrides (`action: 'settings:read'`) — drop it and let the compiler require the field at each site.
|
|
70
|
+
- `defineContextDecorator<'k', Deps, Params>(spec)` positional form for a parameterised contributor — use `.withParams<Params>()(spec)` or `deps` inference is lost.
|
|
71
|
+
- `ctx.tenant = x` instead of returning the value from `resolve` — sticks to one instance only.
|
|
72
|
+
- Plugin / adapter authors using bare keys (`'state'`) instead of namespaced (`'@my-plugin/state'`) — collides with adopter keys.
|
|
73
|
+
- `getRequestValue<string>('traceId')` — generic is the **key** type, not value type.
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: kickjs-deny-list
|
|
3
|
+
description: Patterns to refuse outright when the user asks for them — they break v4 invariants.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
**Module / adapter / plugin shape**:
|
|
7
|
+
- `class implements AppAdapter` → use `defineAdapter()`.
|
|
8
|
+
- `class implements KickPlugin` / function returning `KickPlugin` → use `definePlugin()`.
|
|
9
|
+
- `class implements AppModule` for new code → use `defineModule()`.
|
|
10
|
+
- `bootstrap({ adapters: [MyAdapter] })` (factory) → `MyAdapter()` (instance, with parens).
|
|
11
|
+
- `@Controller('/path')` with a path argument → `@Controller()`, with the prefix in `routes().path`.
|
|
12
|
+
- Module file named `<name>.ts` (no `.module` suffix) → rename to `<name>.module.ts`. Vite HMR's glob doesn't pick up the unsuffixed form.
|
|
13
|
+
|
|
14
|
+
**DI**:
|
|
15
|
+
- `new Container()` or `Container.getInstance().reset()` in tests → use `Container.reset()` in `beforeEach` (or `Container.create()` for fully isolated graphs).
|
|
16
|
+
- DI tokens with `:` separator (`'app:db:url'`) or in PascalCase → use slash-delimited lower-case (`'app/db/url'`). First-party uses reserved `'kick/'` prefix.
|
|
17
|
+
- `Symbol.for(...)` for DI tokens — globally interned, **collides across files**. Use `createToken<T>('name')`.
|
|
18
|
+
- Raw string tokens (`@Inject('config')`) — silent collisions; widens to `unknown`. Use `createToken<T>`.
|
|
19
|
+
- Injecting a `Scope.REQUEST` service into a `SINGLETON` — container throws at resolve time.
|
|
20
|
+
|
|
21
|
+
**Bootstrap / entry file**:
|
|
22
|
+
- `bootstrap({ ... })` without `export const app = ...` → always export. HMR degrades to full restart and `createTestApp` loses the handle.
|
|
23
|
+
- `bootstrap({ register: ... })` — that option doesn't exist. Use an inline plugin in `plugins`.
|
|
24
|
+
|
|
25
|
+
**Middleware**:
|
|
26
|
+
- Using `(ctx, next)` for global middleware in `bootstrap({ middlewares })` — global middleware uses raw Express `(req, res, next)`. Wrong signature throws "Cannot read properties of undefined".
|
|
27
|
+
- Using `(req, res, next)` for an `@Middleware()` decorator — those use `(ctx, next)`.
|
|
28
|
+
- `@Middleware()` whose only output is `ctx.set('x', v)` — should be a context decorator (typed, ordered, testable).
|
|
29
|
+
|
|
30
|
+
**Context contributors**:
|
|
31
|
+
- `ctx.tenant = x` from a contributor — only sticks to one `RequestContext` instance. **Return the value** so the runner writes it via `ctx.set(key, value)`.
|
|
32
|
+
- Omitting the `declare module '@forinda/kickjs'` block — without it `ctx.get('tenant')` is `unknown`.
|
|
33
|
+
- `getRequestValue<string>('traceId')` — generic is the **key** type, not value type.
|
|
34
|
+
|
|
35
|
+
**Env / config**:
|
|
36
|
+
- `@Value('NEW_KEY')` without the key in the Zod schema — silent fallback to raw `process.env`, no coercion.
|
|
37
|
+
- `resetEnvCache()` outside tests — drops the registered schema.
|
|
38
|
+
|
|
39
|
+
**List endpoints**:
|
|
40
|
+
- Reading `req.query.status` directly — bypasses the allow-list. Use `ctx.qs({ filterable })`.
|
|
41
|
+
- Returning a bare array from a list endpoint — breaks the `PaginatedResponse<T>` contract. Use `ctx.paginate()`.
|
|
42
|
+
|
|
43
|
+
**Assets**:
|
|
44
|
+
- Hand-rolled `__dirname` arithmetic for template paths — use `assets.<ns>.<key>()` and add the namespace to `kick.config.ts assetMap`.
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: kickjs-deploy
|
|
3
|
+
description: Use when deploying this app — a Node host or Docker, Netlify, Vercel or Cloudflare Workers — or when an API route returns the SPA shell, the platform build fails, or the function is missing from a deploy.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Deploy files are added on demand: `kick g deploy docker` writes a
|
|
7
|
+
`Dockerfile` and `.dockerignore`; `kick g deploy netlify vercel` writes
|
|
8
|
+
`netlify.toml` / `vercel.json`, `src/serverless.ts` and the
|
|
9
|
+
`build:netlify` / `build:vercel` scripts.
|
|
10
|
+
|
|
11
|
+
**A Node host or a container** runs the long-running server. Without Docker:
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
{{pm}} run build && NODE_ENV=production node dist/index.js
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Start it with `node`, not `kick start`: the CLI is a dev dependency, gone
|
|
18
|
+
after a production install. The image installs from the lockfile, so commit it.
|
|
19
|
+
|
|
20
|
+
**Netlify and Vercel** run the app as a Node function; the CLI builds both:
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
{{pm}} run build:netlify # → .netlify/v1/functions/api.mjs
|
|
24
|
+
{{pm}} run build:vercel # → .vercel/output (Build Output API v3)
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Both bundle `src/serverless.ts`:
|
|
28
|
+
`createHandler(() => import('./index'))` serves the app `src/index.ts`
|
|
29
|
+
describes — its `bootstrap()` call builds the app without listening — so
|
|
30
|
+
there is one set of options. Add middleware and adapters to `src/index.ts`
|
|
31
|
+
as usual.
|
|
32
|
+
|
|
33
|
+
Settings are detected from the layout: a workspace member beside a `web`
|
|
34
|
+
package publishes `web/dist` and routes `/api/*`; an Inertia app publishes
|
|
35
|
+
`dist/client`, packages the asset manifest and SSR bundle with the function,
|
|
36
|
+
and lets it take every other path; a standalone API takes every path.
|
|
37
|
+
Override in `kick.config.ts`:
|
|
38
|
+
|
|
39
|
+
```ts
|
|
40
|
+
export default defineConfig({
|
|
41
|
+
deploy: { apiPath: '/api', staticDir: '../web/dist', include: ['data/geo.json'] },
|
|
42
|
+
})
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
`include` lists files the app reads at runtime; they are packaged with the
|
|
46
|
+
function. Memory does not survive between function instances: keep sessions in
|
|
47
|
+
`session({ store: 'cookie' })` or a shared store, and data in a database.
|
|
48
|
+
|
|
49
|
+
**Cloudflare Workers** is a different entry, not a third flag on this one.
|
|
50
|
+
Workers have no `node:http`, so `createHandler` cannot run there; use the
|
|
51
|
+
web entry over h3 v2:
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
// src/worker.ts
|
|
55
|
+
import 'reflect-metadata'
|
|
56
|
+
import { createFetchHandler } from '@forinda/kickjs/web'
|
|
57
|
+
import * as h3 from 'h3' // v2 — passed in, edge bundlers have no createRequire
|
|
58
|
+
import { modules } from './modules'
|
|
59
|
+
|
|
60
|
+
export default createFetchHandler((env) => ({ h3, modules, env }))
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Two things make or break that deploy:
|
|
64
|
+
|
|
65
|
+
1. **Pre-bundle it yourself.** Point `wrangler.jsonc`'s `main` at a bundle
|
|
66
|
+
built with SWC (the same Vite + `unplugin-swc` setup as the other
|
|
67
|
+
targets), never at `src/worker.ts`. Wrangler's own esbuild compiles
|
|
68
|
+
decorators as ES decorators and emits no decorator metadata, so DI fails
|
|
69
|
+
at startup with a `getOwnMetadata` TypeError before any request lands.
|
|
70
|
+
2. **`compatibility_flags = ["nodejs_compat"]`** — request-scoped DI and
|
|
71
|
+
`ctx.set` / `ctx.get` ride on `AsyncLocalStorage`.
|
|
72
|
+
3. **Do not `import './config'` here.** It is required in `src/index.ts` and
|
|
73
|
+
`src/serverless.ts`, and wrong in a Worker twice over: the config module
|
|
74
|
+
reaches for `node:fs` / `createRequire`, which kills the Worker at
|
|
75
|
+
startup, and `loadEnvFromSchema` parses `process.env`, which Workers do
|
|
76
|
+
not have. The `env` binding threaded through `createFetchHandler` is what
|
|
77
|
+
feeds `ConfigService.get()` and `@Value()` instead — so values arrive as
|
|
78
|
+
the raw strings the platform holds, without the schema's coercion or
|
|
79
|
+
defaults. Coerce where you read them.
|
|
80
|
+
|
|
81
|
+
Not available on Workers: views, SPA/static serving, `@Asset`, adapters and
|
|
82
|
+
plugins. Serve static files from Workers Assets or a separate deploy.
|
|
83
|
+
|
|
84
|
+
**Red flags**:
|
|
85
|
+
- An `/api/*` route returning `index.html` on Netlify — the function is not
|
|
86
|
+
routed. Check the deploy summary says a function was deployed, keep
|
|
87
|
+
`preferStatic` out of a fullstack function's config, and leave Netlify's
|
|
88
|
+
**Package directory** unset so it reads the function at the repo root.
|
|
89
|
+
- Validation errors or flash messages that vanish on Netlify / Vercel — the
|
|
90
|
+
session lives in one instance's memory. Use `session({ store: 'cookie' })`.
|
|
91
|
+
- Committing `.netlify/` or `.vercel/` — both are build output.
|
|
92
|
+
- A frontend that builds somewhere other than `web/dist` and only one of
|
|
93
|
+
`deploy.staticDir`, `SpaAdapter({ clientDir })` and netlify.toml's
|
|
94
|
+
`publish` updated. All three name that directory.
|
|
95
|
+
- Pointing a platform at `src/index.ts` — it calls `bootstrap()`, which
|
|
96
|
+
listens on a port and registers signal handlers inside the function. The
|
|
97
|
+
platform entry is `src/serverless.ts`.
|
|
98
|
+
- Expecting `kick build` alone to produce a deployable function; it builds
|
|
99
|
+
the server. Run the target command after it.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: kickjs-docs-lookup
|
|
3
|
+
description: Use FIRST when unsure about any KickJS API, option, or behaviour — before guessing from memory or inferring from surrounding code.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
These skills are deliberately short — they cover the traps, not the whole API
|
|
7
|
+
surface. When the answer is not in one of them, read the docs rather than
|
|
8
|
+
inferring it from nearby code: a wrong guess about a framework API compiles
|
|
9
|
+
fine and fails at runtime.
|
|
10
|
+
|
|
11
|
+
**Where to look**
|
|
12
|
+
|
|
13
|
+
| Question | Page |
|
|
14
|
+
| --- | --- |
|
|
15
|
+
| Anything — start here | https://kickjs.app/ |
|
|
16
|
+
| Controllers, routing, `ctx` helpers | https://kickjs.app/guide/controllers |
|
|
17
|
+
| DI, tokens, scopes | https://kickjs.app/guide/dependency-injection |
|
|
18
|
+
| Modules and mounting | https://kickjs.app/guide/modules |
|
|
19
|
+
| Adapters, plugins, lifecycle hooks | https://kickjs.app/guide/adapters |
|
|
20
|
+
| Context Contributors | https://kickjs.app/guide/context-decorators |
|
|
21
|
+
| Env, `ConfigService`, `@Value` | https://kickjs.app/guide/configuration |
|
|
22
|
+
| Middleware and guards | https://kickjs.app/guide/middleware |
|
|
23
|
+
| Testing (`createTestApp`) | https://kickjs.app/guide/testing |
|
|
24
|
+
| Typegen and generated types | https://kickjs.app/guide/typegen |
|
|
25
|
+
| HMR and the dev server | https://kickjs.app/guide/hmr |
|
|
26
|
+
| `.kick` views, forms, components | https://kickjs.app/guide/views |
|
|
27
|
+
|
|
28
|
+
**Local, and usually faster**
|
|
29
|
+
|
|
30
|
+
- `kick explain "<error message>"` — matches known failures and gives the fix.
|
|
31
|
+
Pipe a failing run in: `{{test}} 2>&1 | {{kick}} explain`.
|
|
32
|
+
- `kick doctor` — checks this project's wiring.
|
|
33
|
+
- `kick inspect` — the live route / adapter table.
|
|
34
|
+
- `.kickjs/types/` — generated types are ground truth for what exists.
|
|
35
|
+
- `node_modules/@forinda/kickjs/dist/*.d.mts` — the real signature when a doc
|
|
36
|
+
page and the code disagree.
|
|
37
|
+
|
|
38
|
+
**Rule**: if you would be guessing, look it up. If a doc page contradicts the
|
|
39
|
+
installed `.d.mts`, trust the `.d.mts` and say so — the docs may be behind the
|
|
40
|
+
version this project has.
|