@forinda/kickjs-cli 8.14.8 → 8.16.0
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-DhiaLsBj.mjs +591 -0
- package/dist/agent-docs-DhiaLsBj.mjs.map +1 -0
- package/dist/agent-docs-lNvu1K1x.mjs +590 -0
- package/dist/{build-cXg5ZlrG.mjs → build-BNHMWtNY.mjs} +2 -2
- package/dist/{build-Ch7Mu-zN.mjs → build-vY0bmwuH.mjs} +3 -3
- package/dist/{build-Ch7Mu-zN.mjs.map → build-vY0bmwuH.mjs.map} +1 -1
- package/dist/{builtins-Cj-H0MpD.mjs → builtins-CRRb7Lq1.mjs} +2 -2
- package/dist/{builtins-1iFKUPC8.mjs → builtins-tE4nrAZ_.mjs} +59 -59
- package/dist/cli.mjs +2 -2
- package/dist/{config-DJ3Yuos3.mjs → config-mXO3F69m.mjs} +2 -2
- package/dist/{config-LzGMuzP3.mjs → config-zWl1-NCq.mjs} +3 -3
- package/dist/{config-LzGMuzP3.mjs.map → config-zWl1-NCq.mjs.map} +1 -1
- package/dist/{doctor-hrYL914U.mjs → doctor-z92r35fo.mjs} +9 -9
- package/dist/{doctor-hrYL914U.mjs.map → doctor-z92r35fo.mjs.map} +1 -1
- package/dist/{fullstack-BDk2Min0.mjs → fullstack-BqevN8LJ.mjs} +13 -13
- package/dist/{fullstack-BDk2Min0.mjs.map → fullstack-BqevN8LJ.mjs.map} +1 -1
- package/dist/{fullstack-DOx3kvFi.mjs → fullstack-eMi-9BtZ.mjs} +9 -9
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +2 -2
- package/dist/{plugin-h1RvCxk1.mjs → plugin-BbbHEAzr.mjs} +2 -2
- package/dist/{plugin-DmerIwIH.mjs → plugin-CH4X4T0O.mjs} +2 -2
- package/dist/project-Bp6SIRyt.mjs +132 -0
- package/dist/project-D96UoR0P.mjs +133 -0
- package/dist/project-D96UoR0P.mjs.map +1 -0
- package/dist/{project-root-DBTLa3ee.mjs → project-root-Bw3CEPC7.mjs} +3 -3
- package/dist/{project-root-DBTLa3ee.mjs.map → project-root-Bw3CEPC7.mjs.map} +1 -1
- package/dist/{project-root-DQwgpeEX.mjs → project-root-DN0YbQE5.mjs} +2 -2
- package/dist/{rolldown-runtime-UeWuLvbj.mjs → rolldown-runtime-CYy3EyO3.mjs} +1 -1
- package/dist/{run-plugins-CajtgfCU.mjs → run-plugins-f7i7TlPV.mjs} +67 -67
- package/dist/run-plugins-f7i7TlPV.mjs.map +1 -0
- package/dist/{typegen-BsYWuduu.mjs → typegen-Bq4Fis9G.mjs} +5 -5
- package/dist/{typegen-BsYWuduu.mjs.map → typegen-Bq4Fis9G.mjs.map} +1 -1
- package/dist/{typegen-DmSQleE5.mjs → typegen-_x_Q5O0b.mjs} +4 -4
- package/dist/{types-CX1RqHCf.mjs → types-BLZecxnS.mjs} +1 -1
- package/package.json +3 -3
- 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-BLpdFCWy.mjs +0 -932
- package/dist/agent-docs-c9x_je96.mjs +0 -933
- package/dist/agent-docs-c9x_je96.mjs.map +0 -1
- package/dist/package-manager-DMNCUv5Z.mjs +0 -12
- package/dist/package-manager-DMNCUv5Z.mjs.map +0 -1
- package/dist/package-manager-W-gJGan_.mjs +0 -11
- package/dist/project-BhLkKHOD.mjs +0 -135
- package/dist/project-CXcAR-tR.mjs +0 -136
- package/dist/project-CXcAR-tR.mjs.map +0 -1
- package/dist/run-plugins-CajtgfCU.mjs.map +0 -1
|
@@ -0,0 +1,590 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @forinda/kickjs-cli v8.16.0
|
|
3
|
+
*
|
|
4
|
+
* Copyright (c) Felix Orinda
|
|
5
|
+
*
|
|
6
|
+
* This source code is licensed under the MIT license found in the
|
|
7
|
+
* LICENSE file in the root directory of this source tree.
|
|
8
|
+
*
|
|
9
|
+
* @license MIT
|
|
10
|
+
*/
|
|
11
|
+
import{t as e}from"./rolldown-runtime-CYy3EyO3.mjs";import{f as t,o as n,r,t as i}from"./config-mXO3F69m.mjs";import{createRequire as a}from"node:module";import{existsSync as o,readFileSync as s,readdirSync as c,statSync as l}from"node:fs";import{basename as u,dirname as d,extname as f,join as p,relative as m,resolve as h,sep as g}from"node:path";import{fileURLToPath as ee}from"node:url";import{access as te,mkdir as ne,readFile as _,writeFile as v}from"node:fs/promises";import*as y from"@clack/prompts";import b from"picocolors";let x=!1;function re(e){x=e}const ie=/* @__PURE__ */ new Set([`.ts`,`.tsx`,`.js`,`.jsx`,`.mjs`,`.cjs`,`.json`,`.md`]);async function S(e,t){x||(await ne(d(e),{recursive:!0}),await v(e,t,`utf-8`),ie.has(f(e))&&await oe(e,t).catch(()=>{}))}let C;async function ae(e){if(C!==void 0)return C;try{C=await import(a(p(e,`package.json`)).resolve(`oxfmt`))}catch{C=await import(`oxfmt`).catch(()=>null)}return C}async function oe(e,t){let n=await ae(process.cwd());if(!n)return;let r=await se(e);if(r===null)return;let i=await n.format(e,t,r);i.code!==t&&await v(e,i.code,`utf-8`)}const w=/* @__PURE__ */ new Map;async function se(e){let t=d(e),n=t;if(w.has(n))return w.get(n);for(;;){let e=p(t,`.oxfmtrc.json`);if(o(e))try{let t=await _(e,`utf-8`),r=JSON.parse(t);return delete r.$schema,delete r.ignorePatterns,w.set(n,r),r}catch{return w.set(n,null),null}let r=d(t);if(r===t)return w.set(n,null),null;t=r}}async function ce(e){try{return await te(e),!0}catch{return!1}}const T=d(ee(import.meta.url)),E=[p(T,`..`,`templates`),p(T,`..`,`..`,`templates`)].find(e=>o(p(e,`base`)));function le(e){return e.split(`/`).map(e=>e.startsWith(`_dot_`)?`.${e.slice(5)}`:e).join(`/`)}function ue(e,t={}){let n=t.templatesDir??E,r=/* @__PURE__ */ new Map,i=[],a=[],u={},d=[],f={};for(let t of e){let e=p(n,t);if(!o(e))throw Error(`Unknown scaffold layer "${t}" (${e})`);let m=p(e,`feature.json`);if(o(m)){let e=JSON.parse(s(m,`utf-8`));i.push(...e.dependencies??[]),a.push(...e.devDependencies??[]),Object.assign(u,e.builds),d.push(...e.integrations??[]),Object.assign(f,e.scripts)}let h=p(e,`files`);if(o(h))for(let e of c(h,{recursive:!0,encoding:`utf-8`}).toSorted()){let t=p(h,e);if(!l(t).isFile())continue;let n=s(t,`utf-8`),i=le(e.split(g).join(`/`));if(i.endsWith(`.append`)){let e=i.slice(0,-7);r.set(e,(r.get(e)??``)+n)}else r.set(i,n)}}d.push(...t.extra??[]);let m=t.vars??{},h=e=>e.replace(/\{\{(\w+)\}\}/g,(e,t)=>m[t]??e);for(let[e,t]of r)t.includes(`// @kick:`)&&r.set(e,de(t,d,h));return{files:r,dependencies:[...new Set(i)],devDependencies:[...new Set(a)].filter(e=>!i.includes(e)),builds:u,integrations:d,scripts:f}}function D(e,t){let n=e=>e.replace(/\{\{(\w+)\}\}/g,(e,n)=>n in t?t[n]:e);return new Map([...e].map(([e,t])=>[e,n(t)]))}const O=/^([ \t]*)\/\/ @kick:([\w-]+)[ \t]*$/;function de(e,t,n=e=>e){let r=e.split(`
|
|
12
|
+
`),i=new Set(r.map(e=>O.exec(e)?.[2]).filter(Boolean)),a=t.filter(e=>!e.slot||i.has(e.slot)),o=[],s=-1;for(let e=0;e<r.length;e++){let t=O.exec(r[e]);if(!t){o.push(r[e]);continue}let[,i,c]=t;if(c===`imports`){s=o.length;continue}let l=a.filter(e=>e.slot===c&&e.code).map(e=>fe(`${n(e.code)},`,i));l.length>0?o.push(...l):o.at(-1)?.trimEnd().endsWith(`[`)&&r[e+1]?.trim().startsWith(`]`)&&(o.pop(),e++)}if(s>=0){let e=e=>RegExp(`(?<![\\w$])${e.replace(/\$/g,`\\$`)}(?![\\w$])`),t=o.join(`
|
|
13
|
+
`),n=/^import\b[^;]*?\bfrom\s*['"][^'"]+['"]/gm,r=(t.match(n)??[]).join(`
|
|
14
|
+
`),i=t.replace(n,``).replace(/^[ \t]*\/\/.*$/gm,``),c=t=>e(t).test(i)&&!e(t).test(r),l=a.flatMap(e=>{if(!e.import)return[];let{names:t,default:n,from:r}=e.import,i={from:r,names:t?.filter(c),default:n&&c(n)?n:void 0};return i.names?.length||i.default?[i]:[]});o.splice(s,0,...pe(l))}return o.join(`
|
|
15
|
+
`)}function fe(e,t){return e.split(`
|
|
16
|
+
`).map(e=>e&&t+e).join(`
|
|
17
|
+
`)}function pe(e){let t=/* @__PURE__ */ new Map;for(let n of e){let e=t.get(n.from)??{names:[]};e.default??=n.default;for(let t of n.names??[])e.names.includes(t)||e.names.push(t);t.set(n.from,e)}return[...t].map(([e,{names:t,default:n}])=>{let r=`import ${[n,t.length?`{ ${t.join(`, `)} }`:void 0].filter(Boolean).join(`, `)} from '${e}'`;return r.length<=100||t.length===0?r:`import ${n?`${n}, `:``}{\n${t.map(e=>` ${e},`).join(`
|
|
18
|
+
`)}\n} from '${e}'`})}const me={GET:b.green,POST:b.cyan,PUT:b.yellow,PATCH:b.magenta,DELETE:b.red};function he(e){return(me[e]??b.dim)(e.padEnd(7))}function k(e){let t=`[${e}]`.padEnd(10);switch(e){case`CRITICAL`:return b.red(t);case`WARNING`:return b.yellow(t);case`INFO`:return b.blue(b.dim(t));default:return t}}b.green(`✓`),b.red(`✖`),b.yellow(`⚠`),b.blue(`ℹ`);function A(e){y.intro(b.bgCyan(b.black(` ${e} `)))}function j(e){y.outro(e)}function M(e){y.isCancel(e)&&(y.cancel(`Operation cancelled.`),process.exit(0))}async function N(e){let t=await y.text(e);return M(t),t}async function P(e){let t=await y.select(e);return M(t),t}async function F(e){let t=await y.multiselect(e);return M(t),t}async function I(e){let t=await y.confirm(e);return M(t),t}function L(){return y.spinner()}const R=y.log,ge=[[`pnpm-lock.yaml`,`pnpm`],[`yarn.lock`,`yarn`],[`bun.lock`,`bun`],[`bun.lockb`,`bun`],[`package-lock.json`,`npm`]];function z(e){for(let t=e;;t=d(t)){let e=ge.find(([e])=>o(h(t,e)));if(e)return e[1];if(d(t)===t)return null}}function B(e){let t=e;for(;t;){let e=h(t,`package.json`);if(o(e))try{let t=JSON.parse(s(e,`utf-8`)).packageManager;if(typeof t==`string`){let e=t.split(`@`)[0];if(i.includes(e))return e}}catch{}let n=d(t);if(n===t)return null;t=n}return null}async function V(e,t=process.cwd()){if(e&&i.includes(e))return{pm:e,source:`flag`};let r=await n(t);if(r?.packageManager&&i.includes(r.packageManager))return{pm:r.packageManager,source:`config`};let a=B(t);if(a)return{pm:a,source:`package.json`};let o=z(t);if(o)return{pm:o,source:`lockfile`};let s=process.env.npm_config_user_agent?.split(`/`)[0];return s&&i.includes(s)?{pm:s,source:`user-agent`}:{pm:`npm`,source:`default`}}async function H(e,t=process.cwd()){let{pm:n}=await V(e,t);return n}function _e(e=process.cwd()){return B(e)??z(e)??`npm`}function U(e,n){return{pm:e,kick:r(e,`kick`),test:t(e,`test`),moduleEntry:n===`class`?`UserModule`:`UserModule()`}}function W(e,t,n=E){let r=[];for(let i of e){let e=p(n,i,`skills`);if(o(e))for(let n of c(e).filter(e=>e.endsWith(`.txt`)).toSorted()){let a=s(p(e,n),`utf8`),o=/^---\nname: (.*)\ndescription: (.*)\n---\n\n([\s\S]*)$/.exec(a);if(!o)throw Error(`${i}/skills/${n}: expected a name / description frontmatter`);let c=D(/* @__PURE__ */ new Map([[`body`,o[3].replace(/\n$/,``)]]),{...t});r.push({slug:n.slice(0,-4),name:o[1],description:o[2],body:c.get(`body`)})}}return r}function ve(e,t=E){let n=[e];!o(p(e,`kick.config.ts`))&&o(p(e,`server/kick.config.ts`))&&n.push(p(e,`server`));let r=/* @__PURE__ */ new Set;for(let e of n){let t;try{t=JSON.parse(s(p(e,`package.json`),`utf8`))}catch{continue}for(let e of Object.keys({...t.dependencies,...t.devDependencies}))r.add(e)}return r.size?c(t).filter(e=>e.startsWith(`feature-`)).toSorted().filter(e=>{let n=p(t,e,`feature.json`);if(!o(n))return!1;let i=JSON.parse(s(n,`utf8`)).dependencies;return!!i?.length&&i.every(e=>r.has(e))}):[]}function G(e,n){let r=e;return n===`fullstack`&&r!==`pnpm`?`${t(r,`dev:server`)} + ${t(r,`dev:web`)}`:t(r,`dev`)}function ye(e,n,i){return`# CLAUDE.md — ${e}
|
|
19
|
+
|
|
20
|
+
**Read \`./.agents/AGENTS.md\` first.** It is the canonical, multi-agent
|
|
21
|
+
reference for this project (Claude, Copilot, Codex, Gemini, etc.) —
|
|
22
|
+
project conventions, structure, decorator patterns, env wiring, CLI
|
|
23
|
+
generators, every gotcha.
|
|
24
|
+
|
|
25
|
+
**Skills, when you want them:** \`kick g agents --only skills\` writes
|
|
26
|
+
\`./.agents/skills/\` — one task-oriented skill per subdirectory
|
|
27
|
+
(\`add-module/\`, \`write-controller-test/\`, \`bootstrap-export/\`,
|
|
28
|
+
\`deny-list/\`, …), each a \`SKILL.md\` with YAML frontmatter (\`name\`,
|
|
29
|
+
\`description\`) and the recipe body. The structure follows the Claude
|
|
30
|
+
Code skills convention — agents that auto-load skills from
|
|
31
|
+
\`.agents/skills/\` pick each up by its frontmatter. \`kick g agents\`
|
|
32
|
+
alone also adds \`GEMINI.md\` and \`COPILOT.md\`.
|
|
33
|
+
|
|
34
|
+
This file is a thin Claude-specific layer on top of those two; when
|
|
35
|
+
they disagree on anything substantive, treat \`.agents/AGENTS.md\` as
|
|
36
|
+
authoritative and flag the discrepancy.
|
|
37
|
+
|
|
38
|
+
## Why \`.agents/\` + this thin pointer
|
|
39
|
+
|
|
40
|
+
\`.agents/AGENTS.md\` is what every agent reads (Codex, Cursor, Gemini,
|
|
41
|
+
Copilot, Aider, …) — one canonical source so the prose doesn't drift
|
|
42
|
+
across copies. \`CLAUDE.md\` is what Claude Code automatically loads as
|
|
43
|
+
project context on each conversation, so it stays at the project root.
|
|
44
|
+
Keeping CLAUDE.md slim and pointing at \`.agents/\` avoids two
|
|
45
|
+
out-of-sync copies of the same content. Per-agent files
|
|
46
|
+
(\`.agents/GEMINI.md\`, \`.agents/COPILOT.md\`) live alongside
|
|
47
|
+
\`AGENTS.md\` for tool-specific notes that don't belong in the shared
|
|
48
|
+
prose.
|
|
49
|
+
|
|
50
|
+
## Claude-specific notes
|
|
51
|
+
|
|
52
|
+
- **Slash commands** — \`/help\` for Claude Code commands; \`/init\`
|
|
53
|
+
to refresh project memory if AGENTS.md changes substantially.
|
|
54
|
+
- **Feedback** — file issues at <https://github.com/anthropics/claude-code/issues>.
|
|
55
|
+
- **Persistent memory** — Claude maintains user/feedback/project/
|
|
56
|
+
reference memories under \`.claude/memory/\`. If you ask for
|
|
57
|
+
something that contradicts a remembered preference, Claude flags
|
|
58
|
+
it before acting; corrections update memory automatically.
|
|
59
|
+
- **Long-running tasks** — \`/loop\` and \`/schedule\` for recurring
|
|
60
|
+
or background work. Useful for "wait for the deploy then open a
|
|
61
|
+
cleanup PR" or "every Monday triage the issue board" patterns.
|
|
62
|
+
|
|
63
|
+
## Quick reference (full version in .agents/AGENTS.md)
|
|
64
|
+
|
|
65
|
+
\`\`\`bash
|
|
66
|
+
${i} install
|
|
67
|
+
${G(i,n)} # Dev server with HMR + typegen
|
|
68
|
+
${t(i,`build`)} && ${t(i,`start`)} # Production
|
|
69
|
+
${t(i,`test`)} # Vitest
|
|
70
|
+
${n===`fullstack`?t(i,`typecheck`):`${r(i,`kick`)} typecheck`} # tsc/tsgo, whichever the project has
|
|
71
|
+
${n===`fullstack`?t(i,`format`):`${r(i,`kick`)} format`} # oxfmt
|
|
72
|
+
\`\`\`
|
|
73
|
+
|
|
74
|
+
\`kick\` is this project's dev dependency, not a global command: every \`kick …\`
|
|
75
|
+
in these docs runs as \`${r(i,`kick`)} …\` in a shell.
|
|
76
|
+
|
|
77
|
+
## v4 framework reminders
|
|
78
|
+
|
|
79
|
+
When generating or modifying code in this project, stay aligned with the v4 conventions documented in \`.agents/AGENTS.md\`:
|
|
80
|
+
|
|
81
|
+
- **Adapters**: \`defineAdapter()\` factory — never \`class implements AppAdapter\`.
|
|
82
|
+
- **Plugins**: \`definePlugin()\` factory — never plain function returning \`KickPlugin\`.
|
|
83
|
+
- **DI tokens**: \`<scope>/<area>/<key>[:<instance>]\` — a lowercase scope, then slash-separated segments (e.g. \`'app/users/repository'\`, \`'app/Users/repository'\`, \`'mycorp/cache/redis'\`). First-party uses the reserved \`'kick/'\` prefix; this project owns its own scope.
|
|
84
|
+
- **Decorators**: \`@Controller()\` (no path arg — mount prefix comes from \`routes().path\`).
|
|
85
|
+
- **HTTP runtime**: this app may run on Express, Fastify, or h3 — check \`kick.config.ts\` \`runtime\` (or \`bootstrap({ runtime })\`) before writing engine-specific code. Prefer engine-neutral \`ctx\` APIs (\`ctx.json\`/\`ctx.body\`/\`ctx.params\`/\`ctx.sse\`); don't assume \`ctx.req\` is an Express request. Uploads (\`@FileUpload\` → \`ctx.file\`/\`ctx.files\`) work on all three (\`kick add upload\` installs the driver). Full rules in \`.agents/AGENTS.md\` → "HTTP runtime".
|
|
86
|
+
- **Module entry file** MUST be named \`<name>.module.ts\` and live under \`src/modules/<name>/\`. The Vite plugin auto-discovers \`*.module.[tj]sx?\` for graceful HMR — a misnamed \`projects.ts\` silently degrades every save into a full restart.
|
|
87
|
+
- **Env**: schema lives in \`src/config/index.ts\`; \`import './config'\` MUST be the first import in \`src/index.ts\` (side-effect registers the schema before any \`@Value\` resolves).
|
|
88
|
+
- **Assets**: drop new template files into \`src/templates/<namespace>/\`; the dev watcher auto-rebuilds the \`KickAssets\` augmentation + \`assets.x.y()\` re-walks on next call. No restart, no manual build.
|
|
89
|
+
- **Context Contributors** (\`defineContextDecorator\`) over \`@Middleware()\` for ctx-population work.
|
|
90
|
+
- **Repos under tests**: \`Container.create()\` for isolation — never \`new Container()\` or \`getInstance().reset()\`.
|
|
91
|
+
- **Bootstrap export**: \`src/index.ts\` must end with \`export const app = await bootstrap({ ... })\`. The Vite plugin and \`createTestApp\` import the named \`app\`; without the export, HMR silently degrades to full restarts.
|
|
92
|
+
- **Thin entry file**: aggregate \`modules\`, \`middlewares\`, \`plugins\`, \`adapters\` in their own folders (\`src/modules/index.ts\`, \`src/middleware/index.ts\`, …) and pass them by name to \`bootstrap()\` — never inline the lists in \`src/index.ts\`.
|
|
93
|
+
- **Refresh these files**: \`kick g agents -f\` regenerates \`CLAUDE.md\` at the project root and \`.agents/AGENTS.md\` + \`.agents/GEMINI.md\` + \`.agents/COPILOT.md\` + every \`.agents/skills/<name>/SKILL.md\` from the latest CLI templates. Hand-edited content is overwritten — keep customisation in \`.agents/AGENTS.local.md\` or per-skill \`SKILL.local.md\` files alongside.
|
|
94
|
+
|
|
95
|
+
For everything else (controllers, services, modules, RequestContext API, generators, CLI commands, package additions, env wiring, troubleshooting) → \`.agents/AGENTS.md\`.
|
|
96
|
+
`}function be(e,n,i){return`# AGENTS.md — AI Agent Guide for ${e}
|
|
97
|
+
|
|
98
|
+
This guide is the **canonical, multi-agent reference** for this KickJS
|
|
99
|
+
application — Claude, Copilot, Codex, Gemini, etc. all read it first.
|
|
100
|
+
Per-agent files (\`CLAUDE.md\`, \`GEMINI.md\`, etc.) are thin layers that
|
|
101
|
+
add tool-specific affordances on top.
|
|
102
|
+
|
|
103
|
+
## Before You Start
|
|
104
|
+
|
|
105
|
+
1. Run \`${i} install\` to install dependencies
|
|
106
|
+
2. Run \`${G(i,n)}\` to verify the app starts
|
|
107
|
+
|
|
108
|
+
\`kick\` is this project's dev dependency, not a global command: every \`kick …\`
|
|
109
|
+
below runs as \`${r(i,`kick`)} …\` in a shell.${n===`fullstack`?`
|
|
110
|
+
|
|
111
|
+
## Fullstack workspace layout
|
|
112
|
+
|
|
113
|
+
This is a WORKSPACE root — the KickJS API lives in \`server/\`, the typed web
|
|
114
|
+
app in \`web/\`. Run both with \`${G(i,n)}\`. From this root,
|
|
115
|
+
\`${t(i,`test`)}\`, \`${t(i,`typecheck`)}\` and \`${t(i,`format`)}\` reach into
|
|
116
|
+
\`server/\` (and \`web/\` for typecheck).
|
|
117
|
+
|
|
118
|
+
The type loop (do not break it):
|
|
119
|
+
1. \`server/\` handlers RETURN their payloads → \`kick typegen\` emits
|
|
120
|
+
\`server/.kickjs/types/kick__client.d.ts\`: the ambient \`KickClientApi\`
|
|
121
|
+
namespace, every response resolved to a plain shape. \`kick dev\` writes it
|
|
122
|
+
at startup but NOT on save — run \`kick typegen\` in \`server/\` after changing a route or a
|
|
123
|
+
response (the root \`build\` script runs it too).
|
|
124
|
+
2. \`web/tsconfig.json\` lists that file in \`compilerOptions.types\`.
|
|
125
|
+
3. \`web/src/api.ts\` = \`createClient<KickClientApi.Api>({ baseUrl })\`
|
|
126
|
+
— every call site is typed from the server's handlers. \`baseUrl\` is the
|
|
127
|
+
relative \`/api/v1\` (Vite proxies it in dev) unless \`VITE_API_URL\` points at
|
|
128
|
+
an API on another origin.
|
|
129
|
+
|
|
130
|
+
Rules: kick commands (\`kick g\`, \`kick typegen\`, \`kick dev\`, \`kick typecheck\`)
|
|
131
|
+
run in \`server/\` — the root has no \`kick.config.ts\`; never import server runtime code into \`web/\` (the d.ts bridge is
|
|
132
|
+
type-only); prefer return-value handlers so responses stay inferable.`:``}
|
|
133
|
+
3. Read the [KickJS documentation](https://kickjs.app/) for framework details
|
|
134
|
+
|
|
135
|
+
## HTTP runtime — DON'T assume Express-only
|
|
136
|
+
|
|
137
|
+
KickJS is **engine-pluggable**. It runs on **Express (default), Fastify, or h3** —
|
|
138
|
+
chosen with one line: \`bootstrap({ runtime: fastifyRuntime() })\`. Before writing
|
|
139
|
+
any engine-specific code, **check which engine this project uses**:
|
|
140
|
+
|
|
141
|
+
- \`kick.config.ts\` → the \`runtime\` field (\`'express'\` | \`'fastify'\` | \`'h3'\`), and/or
|
|
142
|
+
- \`src/index.ts\` → the \`runtime:\` passed to \`bootstrap()\`, and/or
|
|
143
|
+
- \`package.json\` → \`fastify\` / \`h3\` in deps.
|
|
144
|
+
|
|
145
|
+
Rules that keep generated code correct on **every** engine:
|
|
146
|
+
|
|
147
|
+
- **Prefer return-value handlers.** \`return payload\` sends 200 json on every
|
|
148
|
+
engine and lets \`kick typegen\` infer the response type into
|
|
149
|
+
\`KickRoutes.Api\` (consumed by the \`@forinda/kickjs-client\` typed client);
|
|
150
|
+
\`reply(status, body)\` for non-200, \`reply.noContent()\` for 204. A declared
|
|
151
|
+
\`{ response: schema }\` on the route feeds BOTH the OpenAPI success response
|
|
152
|
+
and the typegen response type. \`ctx.json(...)\` stays fully supported but
|
|
153
|
+
infers \`unknown\`.
|
|
154
|
+
- **Lifecycle hooks:** \`@PostConstruct()\` after instantiation; \`@PreDestroy()\`
|
|
155
|
+
when a REQUEST-scoped service's request closes (release transactions/handles).
|
|
156
|
+
- **Write to \`ctx\`, not the raw request/response.** \`ctx.json()\`, \`ctx.body\`,
|
|
157
|
+
\`ctx.params\`, \`ctx.query\`, \`ctx.set/get\`, \`ctx.sse()\` are engine-neutral and
|
|
158
|
+
work identically everywhere. \`ctx.req\` / \`ctx.res\` are the engine-native
|
|
159
|
+
objects — their **type follows the active runtime** (Express by default; the
|
|
160
|
+
\`kick/runtime\` typegen retypes them to Fastify / h3 when \`runtime\` is set).
|
|
161
|
+
Don't assume \`ctx.req\` is an \`express.Request\` in portable code.
|
|
162
|
+
- **Global middleware** in \`bootstrap({ middlewares })\` is connect-style
|
|
163
|
+
\`(req, res, next)\` — it runs on all engines (Fastify via \`@fastify/middie\`,
|
|
164
|
+
h3 via \`fromNodeHandler\`). But on Fastify / h3 the engine parses the body
|
|
165
|
+
natively, so the default \`express.json()\` is **auto-skipped** (\`nativeBodyParsing\`).
|
|
166
|
+
Don't add \`express.json()\` manually on those engines.
|
|
167
|
+
- **File uploads** work on all three: \`@FileUpload({ mode, fieldName, ... })\` →
|
|
168
|
+
\`ctx.file\` / \`ctx.files\` (same Multer-shaped object everywhere). Backends:
|
|
169
|
+
Express \`multer\`, Fastify \`@fastify/multipart\`, h3 native. Run
|
|
170
|
+
\`kick add upload\` to install the runtime-correct driver. The \`@FileUpload\`
|
|
171
|
+
decorator is **memory-only** (portable); disk / custom-storage (\`storage\` /
|
|
172
|
+
\`dest\`) is Express-only via the \`upload.single/array()\` middleware.
|
|
173
|
+
- **Engine subpaths**: \`import { fastifyRuntime } from '@forinda/kickjs/fastify'\`
|
|
174
|
+
or \`h3Runtime\` from \`'@forinda/kickjs/h3'\`. Express is the zero-config default
|
|
175
|
+
(no import, nothing to install).
|
|
176
|
+
- **Not supported on Fastify / h3**: \`ctx.render()\` (no view engine). Calling it
|
|
177
|
+
throws a clear error rather than failing silently.
|
|
178
|
+
- Run \`kick doctor\` to verify the runtime's engine peers + upload driver are installed.
|
|
179
|
+
|
|
180
|
+
## v4 Conventions (don't skip)
|
|
181
|
+
|
|
182
|
+
KickJS v4 made a handful of structural changes from v3. Internalise these
|
|
183
|
+
before generating or modifying code — they are the source of most agent
|
|
184
|
+
mistakes:
|
|
185
|
+
|
|
186
|
+
- **Adapters** — \`defineAdapter()\` factory. Never write \`class Foo implements AppAdapter\`.
|
|
187
|
+
|
|
188
|
+
\`\`\`ts
|
|
189
|
+
export const MyAdapter = defineAdapter<MyOptions>({
|
|
190
|
+
name: 'MyAdapter',
|
|
191
|
+
defaults: { ... },
|
|
192
|
+
build: (config) => ({
|
|
193
|
+
beforeMount({ app }) { /* ... */ },
|
|
194
|
+
afterStart({ server }) { /* ... */ },
|
|
195
|
+
}),
|
|
196
|
+
})
|
|
197
|
+
\`\`\`
|
|
198
|
+
|
|
199
|
+
- **Plugins** — \`definePlugin()\` factory. Same shape, never plain function returning \`KickPlugin\`.
|
|
200
|
+
|
|
201
|
+
- **DI tokens** — \`<scope>/<area>/<key>[:<instance>]\`. The scope is
|
|
202
|
+
lowercase; the segments after it are identifiers (\`kick typegen\` warns
|
|
203
|
+
on names that don't fit — a bare \`'UserRepository'\`, a dotted
|
|
204
|
+
\`'app.db'\`):
|
|
205
|
+
|
|
206
|
+
\`\`\`ts
|
|
207
|
+
const USERS_REPO = createToken<UsersRepo>('app/Users/repository')
|
|
208
|
+
const DB = createToken<Database>('app/Db/connection')
|
|
209
|
+
\`\`\`
|
|
210
|
+
|
|
211
|
+
The \`kick/\` prefix is reserved for first-party packages; this project
|
|
212
|
+
owns its own scope (\`app/\`, your domain name, etc.).
|
|
213
|
+
|
|
214
|
+
- **\`@Controller()\`** takes **no arguments**. Set the route prefix with the
|
|
215
|
+
module's \`routes().path\`.
|
|
216
|
+
|
|
217
|
+
- **Env** — the schema lives in \`src/config/index.ts\`. \`src/index.ts\` imports
|
|
218
|
+
it once, as its **first** import (\`import './config'\`, before \`bootstrap()\`);
|
|
219
|
+
tests that read config import it too (\`import '@/config'\`). Nothing else
|
|
220
|
+
imports from \`src/config\`: read values with \`getEnv('KEY')\`, an injected
|
|
221
|
+
\`ConfigService\` (\`config.get('KEY')\`), or \`@Value('KEY')\` typed as
|
|
222
|
+
\`Env<'KEY'>\` — never \`process.env\`. Add a key to the schema before reading it.
|
|
223
|
+
A concern with several keys (a database, a mail provider) gets a typed section
|
|
224
|
+
instead: \`defineSettings('DB', schema)\` in the module's own
|
|
225
|
+
\`<name>.settings.ts\` — not in \`src/config\` — declared by the module that
|
|
226
|
+
needs it (\`settings: () => [DbSettings]\`) and read through
|
|
227
|
+
\`@Inject(DbSettings)\` or \`DbSettings.get()\`. Its variables are \`DB_*\`.
|
|
228
|
+
|
|
229
|
+
- **Module entry files MUST be named \`<name>.module.ts\`** — see the Vite
|
|
230
|
+
HMR contract at the top of "Module Pattern" below. The CLI enforces this;
|
|
231
|
+
hand-rolled files must too.
|
|
232
|
+
|
|
233
|
+
- **Assets** — drop new template files into \`src/templates/<namespace>/\`
|
|
234
|
+
(or wherever \`kick.config.ts\` points). The dev watcher auto-rebuilds the
|
|
235
|
+
\`KickAssets\` augmentation; \`assets.x.y()\` re-walks on next call. No restart,
|
|
236
|
+
no manual build step.
|
|
237
|
+
|
|
238
|
+
- **Context over \`@Middleware()\`** — when a middleware's only job is to
|
|
239
|
+
populate \`ctx.set('key', value)\`, use \`defineHttpContextDecorator()\`
|
|
240
|
+
(HTTP) or \`defineContextDecorator()\` (transport-agnostic) instead.
|
|
241
|
+
Typed via \`ContextMeta\`, ordered via \`dependsOn\`, validated at boot.
|
|
242
|
+
Reserve \`@Middleware()\` for response short-circuit / stream mutation /
|
|
243
|
+
pre-route-matching work.
|
|
244
|
+
|
|
245
|
+
Two ground rules around the data flow — both stem from the fact that
|
|
246
|
+
every per-request stage gets its OWN \`RequestContext\` instance, all
|
|
247
|
+
reading/writing the SAME \`AsyncLocalStorage\`-backed Map:
|
|
248
|
+
- **\`resolve\` and \`onError\` must RETURN the value.** The runner
|
|
249
|
+
writes it via \`ctx.set(reg.key, value)\` on your behalf. Direct
|
|
250
|
+
property assignment (\`ctx.tenant = …\`) sticks to the contributor
|
|
251
|
+
instance only — the handler instance never sees it.
|
|
252
|
+
- **Read across instances via \`ctx.set\` / \`ctx.get\`** (or
|
|
253
|
+
\`getRequestValue(key)\` from a service that has no \`ctx\` reference
|
|
254
|
+
— typed via \`MetaValue<K>\`). \`ctx.req\` works because the underlying
|
|
255
|
+
Express request is shared; bespoke property assignments don't.
|
|
256
|
+
|
|
257
|
+
- **Test isolation** — default to \`Container.create()\` for fresh DI state.
|
|
258
|
+
Never \`new Container()\` and never \`getInstance().reset()\` — both leak
|
|
259
|
+
registrations between tests.
|
|
260
|
+
|
|
261
|
+
\`\`\`ts
|
|
262
|
+
const container = Container.create()
|
|
263
|
+
// ... register test-scoped providers, run, discard
|
|
264
|
+
\`\`\`
|
|
265
|
+
|
|
266
|
+
- **Bootstrap export** — \`src/index.ts\` MUST end with
|
|
267
|
+
\`export const app = await bootstrap({ ... })\`. The Vite plugin imports
|
|
268
|
+
the named \`app\` symbol to drive HMR module swaps; testing helpers
|
|
269
|
+
(\`createTestApp\`) and the OpenAPI introspector also rely on it. Drop
|
|
270
|
+
the \`export\` and \`kick dev\` will silently fall back to a full restart
|
|
271
|
+
on every save while \`createTestApp\` complains about a missing handle.
|
|
272
|
+
|
|
273
|
+
- **Keep \`src/index.ts\` thin** — collect plugins, modules, middleware, and
|
|
274
|
+
adapters in dedicated folders and re-export aggregated arrays. Do **not**
|
|
275
|
+
inline registration in the entry file:
|
|
276
|
+
|
|
277
|
+
\`\`\`ts
|
|
278
|
+
// src/modules/index.ts — fluent chain (default for \`modules.style: 'define'\`)
|
|
279
|
+
export const modules = defineModules().mount(HelloModule()).mount(UsersModule())
|
|
280
|
+
// OR with \`modules.style: 'class'\`:
|
|
281
|
+
// export const modules: AppModuleEntry[] = [HelloModule, UsersModule]
|
|
282
|
+
|
|
283
|
+
// src/middleware/index.ts
|
|
284
|
+
export const middleware = [helmet(), cors(), requestId(), ...]
|
|
285
|
+
|
|
286
|
+
// src/plugins/index.ts
|
|
287
|
+
export const plugins = [MetricsPlugin(), AuditPlugin()]
|
|
288
|
+
|
|
289
|
+
// src/adapters/index.ts
|
|
290
|
+
export const adapters = [SwaggerAdapter({ ... }), DevToolsAdapter()]
|
|
291
|
+
\`\`\`
|
|
292
|
+
|
|
293
|
+
\`\`\`ts
|
|
294
|
+
// src/index.ts — stays small; one import per category
|
|
295
|
+
import 'reflect-metadata'
|
|
296
|
+
import './config'
|
|
297
|
+
import { bootstrap } from '@forinda/kickjs'
|
|
298
|
+
import { modules } from './modules'
|
|
299
|
+
import { middleware } from './middleware'
|
|
300
|
+
import { plugins } from './plugins'
|
|
301
|
+
import { adapters } from './adapters'
|
|
302
|
+
|
|
303
|
+
export const app = await bootstrap({ modules, middlewares, plugins, adapters })
|
|
304
|
+
\`\`\`
|
|
305
|
+
|
|
306
|
+
This keeps the entry file diff-friendly, scales to dozens of modules
|
|
307
|
+
without git churn, and lets each domain own its own registration list.
|
|
308
|
+
The generators (\`kick g module\`, \`kick g middleware\`, \`kick g plugin\`,
|
|
309
|
+
\`kick g adapter\`) follow this layout — manual additions should too.
|
|
310
|
+
|
|
311
|
+
Everything else (controllers, services, modules, RequestContext API, generators,
|
|
312
|
+
package additions, env access patterns, troubleshooting) is detailed below.
|
|
313
|
+
|
|
314
|
+
## Where to Find Things
|
|
315
|
+
|
|
316
|
+
### Application Structure
|
|
317
|
+
|
|
318
|
+
| What | Where |
|
|
319
|
+
|------|-------|
|
|
320
|
+
| Entry point | \`src/index.ts\` |
|
|
321
|
+
| Module registry | \`src/modules/index.ts\` |
|
|
322
|
+
| Feature modules | \`src/modules/<module-name>/\` |
|
|
323
|
+
| **Module entry file** | \`src/modules/<name>/<name>.module.ts\` (filename suffix is required — see Vite HMR contract below) |
|
|
324
|
+
| Env values | \`.env\` |
|
|
325
|
+
| Env schema (Zod) | \`src/config/index.ts\` |
|
|
326
|
+
| TypeScript config | \`tsconfig.json\` |
|
|
327
|
+
| Vite config (HMR) | \`vite.config.ts\` |
|
|
328
|
+
| Vitest config | \`vitest.config.ts\` |
|
|
329
|
+
| Formatter config | \`.oxfmtrc.json\` (oxfmt) |
|
|
330
|
+
| CLI config | \`kick.config.ts\` |
|
|
331
|
+
|
|
332
|
+
### Module Pattern (${n.toUpperCase()})
|
|
333
|
+
|
|
334
|
+
> **Vite HMR auto-discovery contract:** module files **must** be named \`<name>.module.ts\` (or \`.tsx\`/\`.js\`/\`.jsx\`) and live under \`src/modules/\`. The Vite plugin scans for \`*.module.[tj]sx?\` to drive graceful HMR rebuilds; renaming a file to \`projects.ts\` (no \`.module\`) silently breaks HMR — saves trigger a full restart instead of a swap. The CLI generator (\`kick g module <name>\`) follows the convention; manual files must too.
|
|
335
|
+
|
|
336
|
+
Each module in \`src/modules/<name>/\` typically contains:
|
|
337
|
+
|
|
338
|
+
${n===`rest`?`\`\`\`
|
|
339
|
+
<name>/
|
|
340
|
+
├── <name>.controller.ts # HTTP routes (@Controller)
|
|
341
|
+
├── <name>.service.ts # Business logic (@Service)
|
|
342
|
+
├── <name>.repository.ts # Data access — factory + contract + token
|
|
343
|
+
├── dtos/ # Request/response schemas (Zod)
|
|
344
|
+
└── <name>.module.ts # Module definition (defineModule factory)
|
|
345
|
+
\`\`\`
|
|
346
|
+
`:"```\nsrc/\n├── index.ts # Add routes here\n└── ... # Custom structure\n```\n"}
|
|
347
|
+
|
|
348
|
+
## Checklist: Adding a Feature
|
|
349
|
+
|
|
350
|
+
Follow the **\`kickjs-add-module\`** skill — it has the ordered steps, the
|
|
351
|
+
canonical \`defineModule\` shape, and the \`import.meta.glob\` requirement that
|
|
352
|
+
silently breaks DI when omitted.
|
|
353
|
+
|
|
354
|
+
## Common Tasks
|
|
355
|
+
|
|
356
|
+
Each of these has a skill with the steps and the traps:
|
|
357
|
+
|
|
358
|
+
| Task | Skill |
|
|
359
|
+
| --- | --- |
|
|
360
|
+
| Add a feature module | \`kickjs-add-module\` |
|
|
361
|
+
| Add an adapter | \`kickjs-add-adapter\` |
|
|
362
|
+
| Add a plugin | \`kickjs-add-plugin\` |
|
|
363
|
+
| Add a context contributor | \`kickjs-context-contributor\` |
|
|
364
|
+
| Write a controller test | \`kickjs-write-controller-test\` |
|
|
365
|
+
| List endpoint with filters / pagination | \`kickjs-query-parsing-list-endpoint\` |
|
|
366
|
+
| Serve bundled assets | \`kickjs-use-asset-manager\` |
|
|
367
|
+
| Flag a route (public, exempt, unmetered) | \`kickjs-route-flags\` |
|
|
368
|
+
| Add a kick CLI command or generator | \`kickjs-cli-plugin\` |
|
|
369
|
+
| Deploy to Netlify / Vercel / Cloudflare | \`kickjs-deploy\` |
|
|
370
|
+
| Server-rendered pages with \`.kick\` views | \`kickjs-views\` |
|
|
371
|
+
| HTML forms: errors, flash, browser checks, CSRF | \`kickjs-views-forms\` |
|
|
372
|
+
| Anything else | \`kickjs-docs-lookup\` |
|
|
373
|
+
|
|
374
|
+
## Testing Guidelines
|
|
375
|
+
|
|
376
|
+
See the **\`kickjs-write-controller-test\`** skill for the canonical test — it
|
|
377
|
+
carries the call shape, the DI reset, and the env side-effect import, each of
|
|
378
|
+
which has its own failure mode.
|
|
379
|
+
|
|
380
|
+
Run with \`${i} run test\` (\`test:watch\` for watch mode).
|
|
381
|
+
|
|
382
|
+
## Environment Variables
|
|
383
|
+
|
|
384
|
+
The schema lives in \`src/config/index.ts\` and registers itself with kickjs **at
|
|
385
|
+
module load**; \`src/index.ts\` imports it (\`import './config'\`) before
|
|
386
|
+
\`bootstrap()\` so the cache is populated before DI resolves anything. Add a key
|
|
387
|
+
to the schema, put its value in \`.env\`, and it is typed everywhere.
|
|
388
|
+
|
|
389
|
+
Read it with \`@Value('KEY')\` for construction-time values, or inject
|
|
390
|
+
\`ConfigService\` for dynamic access.
|
|
391
|
+
|
|
392
|
+
When a key reads as \`undefined\`, use the **\`kickjs-env-wiring-check\`** skill or
|
|
393
|
+
run \`kick explain "ConfigService.get('KEY') returned undefined"\`. The cause
|
|
394
|
+
differs between app code and tests and the two look identical, which is what
|
|
395
|
+
makes it slow to spot.
|
|
396
|
+
|
|
397
|
+
## Standalone Utilities (No DI Required)
|
|
398
|
+
|
|
399
|
+
These work anywhere — scripts, plain files, outside \`@Service\`/\`@Controller\`:
|
|
400
|
+
|
|
401
|
+
| Utility | Import | Example |
|
|
402
|
+
|---------|--------|---------|
|
|
403
|
+
| \`Logger.for(name)\` | \`@forinda/kickjs\` | \`const log = Logger.for('MyScript')\` |
|
|
404
|
+
| \`createLogger(name)\` | \`@forinda/kickjs\` | \`const log = createLogger('Worker')\` |
|
|
405
|
+
| \`createToken<T>(name)\` | \`@forinda/kickjs\` | \`const TOKEN = createToken<string>('app/Db/url')\` |
|
|
406
|
+
| \`ref(value)\` | \`@forinda/kickjs\` | \`const count = ref(0)\` |
|
|
407
|
+
| \`computed(fn)\` | \`@forinda/kickjs\` | \`const doubled = computed(() => count.value * 2)\` |
|
|
408
|
+
| \`watch(source, cb)\` | \`@forinda/kickjs\` | \`watch(() => count.value, (v) => log(v))\` |
|
|
409
|
+
| \`reactive(obj)\` | \`@forinda/kickjs\` | \`const state = reactive({ count: 0 })\` |
|
|
410
|
+
| \`HttpException\` | \`@forinda/kickjs\` | \`throw new HttpException(404, 'Not found')\` |
|
|
411
|
+
| \`HttpStatus\` | \`@forinda/kickjs\` | \`HttpStatus.NOT_FOUND // 404\` |
|
|
412
|
+
|
|
413
|
+
## Key Decorators
|
|
414
|
+
|
|
415
|
+
### HTTP Routes
|
|
416
|
+
| Decorator | Purpose |
|
|
417
|
+
|-----------|---------|
|
|
418
|
+
| \`@Controller()\` | Define route prefix |
|
|
419
|
+
| \`@Get('/'), @Post('/')\` | HTTP method handlers |
|
|
420
|
+
| \`@Middleware(fn)\` | Attach middleware |
|
|
421
|
+
| \`@Public()\` | Skip auth (requires auth adapter) |
|
|
422
|
+
| \`@Roles('admin')\` | Role-based access |
|
|
423
|
+
|
|
424
|
+
### Dependency Injection
|
|
425
|
+
| Decorator | Purpose |
|
|
426
|
+
|-----------|---------|
|
|
427
|
+
| \`defineModule({...})\` | Define feature module (factory; preferred — paired with \`defineModules()\` registry) |
|
|
428
|
+
| \`defineModules()\` | Build the modules registry as a chainable list (\`.mount(X())\`) |
|
|
429
|
+
| \`AppModule\` interface | Legacy module shape — \`class X implements AppModule\` (toggle via \`modules.style: 'class'\`) |
|
|
430
|
+
| \`@Service()\` | Register singleton service |
|
|
431
|
+
| \`@Repository()\` | Register repository |
|
|
432
|
+
| \`@Autowired()\` | Property injection |
|
|
433
|
+
| \`@Inject('token')\` | Token-based injection |
|
|
434
|
+
| \`@Value('VAR')\` | Inject env variable |
|
|
435
|
+
|
|
436
|
+
### Context Decorators
|
|
437
|
+
|
|
438
|
+
Typed, ordered way to populate \`ctx.set/get\` keys before the handler runs.
|
|
439
|
+
Use this **instead of \`@Middleware()\`** when the middleware's only output
|
|
440
|
+
is a value other code reads off \`ctx\`.
|
|
441
|
+
|
|
442
|
+
**Authoring** — pick the right factory:
|
|
443
|
+
|
|
444
|
+
| Factory | When |
|
|
445
|
+
|---------|------|
|
|
446
|
+
| \`defineHttpContextDecorator(spec)\` | HTTP only (the common case). \`Ctx\` is \`RequestContext\`, so \`ctx.req\` / \`ctx.params\` / \`ctx.query\` are typed. |
|
|
447
|
+
| \`defineContextDecorator(spec)\` | Transport-agnostic (HTTP + WS + queue + cron). \`Ctx\` is \`ExecutionContext\` — only \`get\` / \`require\` / \`set\` / \`requestId\`. |
|
|
448
|
+
| \`<either>.withParams<P>()(spec)\` | The contributor takes per-call params. **Always use the curried form for params** — the positional form forces you to spell \`K\` and \`D\` and loses \`deps\` inference. |
|
|
449
|
+
|
|
450
|
+
Spec fields: \`{ key, deps, dependsOn, optional, paramDefaults, requiredParams, onError, resolve }\`.
|
|
451
|
+
|
|
452
|
+
**Call sites — all five, precedence high → low:**
|
|
453
|
+
|
|
454
|
+
| # | Site | Form |
|
|
455
|
+
|---|------|------|
|
|
456
|
+
| 1 | Method | \`@LoadX\` / \`@LoadX({ ... })\` above a controller method |
|
|
457
|
+
| 2 | Class | \`@LoadX\` / \`@LoadX({ ... })\` above the controller class |
|
|
458
|
+
| 3 | Module | \`defineModule({ build: () => ({ contributors: () => [LoadX.registration] }) })\` — or \`AppModule.contributors?()\` in class form |
|
|
459
|
+
| 4 | Adapter | \`AppAdapter.contributors?(): ContributorRegistration[]\` |
|
|
460
|
+
| 5 | Global | \`bootstrap({ contributors: [LoadX.registration] })\` |
|
|
461
|
+
|
|
462
|
+
Sites 3–5 take **registrations**, not decorators:
|
|
463
|
+
|
|
464
|
+
- \`LoadX.registration\` — uses \`paramDefaults\` as-is.
|
|
465
|
+
- \`LoadX.with({ ...params }).registration\` — call-site params merged over \`paramDefaults\`.
|
|
466
|
+
|
|
467
|
+
Duplicate keys are resolved by precedence; the lower-precedence one is
|
|
468
|
+
dropped silently, which is how a method-level decorator overrides an
|
|
469
|
+
adapter-shipped default.
|
|
470
|
+
|
|
471
|
+
**Params:** a **required** field of \`P\` with no \`paramDefaults\` entry must be
|
|
472
|
+
supplied at every call site — \`@LoadX\` bare, \`@LoadX()\`, and \`.registration\`
|
|
473
|
+
are compile errors for such a decorator. Never invent a placeholder default
|
|
474
|
+
just to make the type check; add \`requiredParams: ['field']\` for runtime
|
|
475
|
+
enforcement at JS call sites.
|
|
476
|
+
|
|
477
|
+
**Reading values:** \`ctx.require('key')\` for values a contributor guarantees
|
|
478
|
+
(throws \`MissingContextValueError\`, returns a non-optional type);
|
|
479
|
+
\`ctx.get('key')\` for \`optional: true\` contributors and ad-hoc keys (returns
|
|
480
|
+
\`| undefined\`). Never \`ctx.get('key')!\` — it compiles even when the producing
|
|
481
|
+
decorator isn't applied to the route.
|
|
482
|
+
|
|
483
|
+
| Concept | Where it lives |
|
|
484
|
+
|---------|----------------|
|
|
485
|
+
| Type augmentation (value types) | \`declare module '@forinda/kickjs' { interface ContextMeta { ... } }\` |
|
|
486
|
+
| Type augmentation (key-only) | \`declare module '@forinda/kickjs' { interface ContextKeys { ... } }\` — valid in \`dependsOn\`, value stays \`unknown\` |
|
|
487
|
+
|
|
488
|
+
Cycles and missing \`dependsOn\` keys throw at \`app.setup()\` (boot fails
|
|
489
|
+
fast). The \`onError\` hook is async-permitted.
|
|
490
|
+
|
|
491
|
+
Full guide: <https://kickjs.app/guide/context-decorators>.
|
|
492
|
+
|
|
493
|
+
## Common Pitfalls
|
|
494
|
+
|
|
495
|
+
See the **\`kickjs-deny-list\`** skill — the maintained list of things that
|
|
496
|
+
compile, run, and are still wrong.
|
|
497
|
+
|
|
498
|
+
For a specific failure, \`kick explain "<error message>"\` beats reading either:
|
|
499
|
+
it matches the message against known causes and prints the fix.
|
|
500
|
+
|
|
501
|
+
## CLI Commands Reference
|
|
502
|
+
|
|
503
|
+
See the **\`kickjs-cli-commands-cheatsheet\`** skill for the full table, the
|
|
504
|
+
shell-safe field syntax, and the non-obvious flags. \`kick --help\` and
|
|
505
|
+
\`kick <cmd> --help\` are authoritative for the installed version.
|
|
506
|
+
|
|
507
|
+
## Learn More
|
|
508
|
+
|
|
509
|
+
Use the **\`kickjs-docs-lookup\`** skill — it maps questions to the right guide
|
|
510
|
+
page and lists the local tools (\`kick explain\`, \`kick doctor\`, \`kick inspect\`,
|
|
511
|
+
\`.kickjs/types/\`) that usually answer faster than a search.
|
|
512
|
+
|
|
513
|
+
Start at <https://kickjs.app/>.
|
|
514
|
+
|
|
515
|
+
`}function K(e,t,n,r=`define`,i=[]){let a=`<!-- Generated by \`kick g agents\` for ${e}. Edits are overwritten on the next refresh; keep customisation in a SKILL.local.md alongside. -->`;return W([`base`,...i],U(n,r)).map(e=>({slug:e.slug,content:`---
|
|
516
|
+
name: ${e.name}
|
|
517
|
+
description: ${e.description}
|
|
518
|
+
---
|
|
519
|
+
|
|
520
|
+
${a}
|
|
521
|
+
|
|
522
|
+
${e.body}
|
|
523
|
+
`}))}function xe(e,t,n){return`# GEMINI.md — ${e}
|
|
524
|
+
|
|
525
|
+
**Read \`./AGENTS.md\` first.** It is the canonical, multi-agent
|
|
526
|
+
reference for this project — every convention, structure, decorator
|
|
527
|
+
pattern, env wiring rule, generator usage. This file is a thin
|
|
528
|
+
Gemini-specific layer; when the two disagree on anything substantive,
|
|
529
|
+
treat \`AGENTS.md\` as authoritative and flag the discrepancy.
|
|
530
|
+
|
|
531
|
+
## Why this file
|
|
532
|
+
|
|
533
|
+
Gemini CLI auto-loads \`GEMINI.md\` when it lives alongside the
|
|
534
|
+
agent-context files. Keeping it in \`.agents/\` next to \`AGENTS.md\`
|
|
535
|
+
means Gemini reads the same shared prose as Codex / Cursor / Copilot
|
|
536
|
+
without us copy-pasting.
|
|
537
|
+
|
|
538
|
+
## Gemini-specific notes
|
|
539
|
+
|
|
540
|
+
- **Skills activation** — Gemini activates skills via
|
|
541
|
+
\`activate_skill\` (its native MCP-style tool); the equivalent on
|
|
542
|
+
Claude Code is the \`Skill\` tool. Cross-reference the
|
|
543
|
+
\`kickjs-skills.md\` index for the available triggers.
|
|
544
|
+
- **Tool naming** — Gemini's tool names differ from Claude Code's
|
|
545
|
+
(e.g. \`read_file\` vs \`Read\`, \`run_terminal_command\` vs
|
|
546
|
+
\`Bash\`). The shared prose in \`AGENTS.md\` describes intents, not
|
|
547
|
+
tool names; consult Gemini's docs for the concrete invocation.
|
|
548
|
+
- **File ops** — Gemini's file edits are sandboxed; large refactors
|
|
549
|
+
may need explicit confirmation. Prefer the smallest-possible-edit
|
|
550
|
+
pattern.
|
|
551
|
+
|
|
552
|
+
## Refreshing this file
|
|
553
|
+
|
|
554
|
+
\`kick g agents --only gemini -f\` regenerates this file from the
|
|
555
|
+
CLI template. Hand-edited content is overwritten — keep customisation
|
|
556
|
+
in \`.agents/GEMINI.local.md\`.
|
|
557
|
+
`}function Se(e,t,n){return`# COPILOT.md — ${e}
|
|
558
|
+
|
|
559
|
+
**Read \`./AGENTS.md\` first.** It is the canonical, multi-agent
|
|
560
|
+
reference for this project — every convention, structure, decorator
|
|
561
|
+
pattern, env wiring rule, generator usage. This file is a thin
|
|
562
|
+
Copilot-specific layer; when the two disagree on anything substantive,
|
|
563
|
+
treat \`AGENTS.md\` as authoritative and flag the discrepancy.
|
|
564
|
+
|
|
565
|
+
## Why this file
|
|
566
|
+
|
|
567
|
+
GitHub Copilot CLI auto-loads \`COPILOT.md\` when it lives alongside
|
|
568
|
+
the agent-context files. Keeping it in \`.agents/\` next to
|
|
569
|
+
\`AGENTS.md\` means Copilot reads the same shared prose as
|
|
570
|
+
Codex / Cursor / Gemini / Claude Code without copy-pasting.
|
|
571
|
+
|
|
572
|
+
## Copilot-specific notes
|
|
573
|
+
|
|
574
|
+
- **Skills** — Copilot CLI auto-discovers skills from installed
|
|
575
|
+
plugins; cross-reference \`kickjs-skills.md\` for available
|
|
576
|
+
triggers in this project.
|
|
577
|
+
- **Tool naming** — Copilot's tool names differ from Claude Code's
|
|
578
|
+
(\`edit\` vs \`Edit\`, \`shell\` vs \`Bash\`, etc.). The shared
|
|
579
|
+
prose in \`AGENTS.md\` describes intents, not tool names; consult
|
|
580
|
+
Copilot's docs for the concrete invocation.
|
|
581
|
+
- **Confirmation flows** — Copilot CLI surfaces destructive
|
|
582
|
+
operations through an explicit approval gate. Stage edits with
|
|
583
|
+
short, focused diffs so each one is easy to review at the prompt.
|
|
584
|
+
|
|
585
|
+
## Refreshing this file
|
|
586
|
+
|
|
587
|
+
\`kick g agents --only copilot -f\` regenerates this file from the
|
|
588
|
+
CLI template. Hand-edited content is overwritten — keep customisation
|
|
589
|
+
in \`.agents/COPILOT.local.md\`.
|
|
590
|
+
`}var q=/* @__PURE__ */ e({generateAgentDocs:()=>Q,writeLayerSkills:()=>$});const J=`.agents`,Ce=/* @__PURE__ */ new Set([`rest`,`minimal`,`fullstack`,`inertia`]);function Y(e,t){if(t)return t;try{let t=JSON.parse(s(p(e,`package.json`),`utf-8`));if(t.name)return t.name.replace(/^@[^/]+\//,``)}catch{}return e.split(`/`).findLast(Boolean)??`app`}async function X(e){try{return(await n(e))?.modules?.style===`class`?`class`:`define`}catch{return`define`}}async function Z(e,t){if(t)return t;try{let t=(await n(e))?.pattern;if(t&&Ce.has(t))return t}catch{}return`rest`}async function Q(e){let t=e.only??`all`,n=Y(e.outDir,e.name),r=await H(e.pm,e.outDir),i=await Z(e.outDir,e.template),a=await X(e.outDir),s=t===`agents`||t===`both`||t===`all`,c=t===`claude`||t===`both`||t===`all`,l=t===`skills`||t===`all`,u=t===`gemini`||t===`all`,d=t===`copilot`||t===`all`,f=[];if(s&&f.push({file:p(e.outDir,J,`AGENTS.md`),render:()=>be(n,i,r)}),c&&f.push({file:p(e.outDir,`CLAUDE.md`),render:()=>ye(n,i,r)}),l){let t=ve(e.outDir);for(let o of K(n,i,r,a,t))f.push({file:p(e.outDir,J,`skills`,o.slug,`SKILL.md`),render:()=>o.content})}u&&f.push({file:p(e.outDir,J,`GEMINI.md`),render:()=>xe(n,i,r)}),d&&f.push({file:p(e.outDir,J,`COPILOT.md`),render:()=>Se(n,i,r)});let m=[];for(let{file:t,render:n}of f)o(t)&&!e.force&&!await I({message:`${t.replace(e.outDir+`/`,``)} already exists. Overwrite?`,initialValue:!1})?console.log(` Skipped — existing ${t.replace(e.outDir+`/`,``)} preserved.`):(await S(t,n()),m.push(t));return m}async function $(e,t,n){let r=(u(e)===`server`?[e,d(e)]:[e]).find(e=>o(p(e,J,`skills`)));if(!t.length||!r)return[];let i=await X(e),a=new Set(W(t,U(n,i)).map(e=>e.slug)),s=K(Y(e),await Z(e),n,i,t).filter(e=>a.has(e.slug)),c=[];for(let t of s){let n=p(r,J,`skills`,t.slug,`SKILL.md`);o(n)||(await S(n,t.content),c.push(m(e,n)))}return c}export{S as C,re as S,k as _,H as a,ue as b,A as c,j as d,P as f,b as g,he as h,_e as i,R as l,N as m,Q as n,V as o,L as p,$ as r,I as s,q as t,F as u,E as v,ce as x,D as y};
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* @forinda/kickjs-cli v8.
|
|
2
|
+
* @forinda/kickjs-cli v8.16.0
|
|
3
3
|
*
|
|
4
4
|
* Copyright (c) Felix Orinda
|
|
5
5
|
*
|
|
@@ -8,5 +8,5 @@
|
|
|
8
8
|
*
|
|
9
9
|
* @license MIT
|
|
10
10
|
*/
|
|
11
|
-
import{t as e}from"./rolldown-runtime-
|
|
11
|
+
import{t as e}from"./rolldown-runtime-CYy3EyO3.mjs";import{cpSync as t,existsSync as n,mkdirSync as r,statSync as i,writeFileSync as a}from"node:fs";import{dirname as o,isAbsolute as s,join as c,relative as l,resolve as u}from"node:path";import{glob as d}from"glob";import{groupAssetKeys as f}from"@forinda/kickjs";var p=/* @__PURE__ */ e({ASSET_MANIFEST_VERSION:()=>1,buildAssets:()=>m});async function m(e,t){let{cwd:n,silent:i=!1}=t,o=t.distDir??e?.build?.outDir??`dist`,s=e?.assetMap;if(!s||Object.keys(s).length===0)return null;let d=i?()=>{}:console.log,f=u(n,o);r(f,{recursive:!0});let p=[],m={};for(let[e,t]of Object.entries(s)){let r=await h(e,t,n,f);p.push(r.entrySummary),Object.assign(m,r.manifestSlice),d(` ✓ ${e}: ${r.entrySummary.filesCopied} file(s) → ${r.entrySummary.dest}`)}let g={version:1,entries:m},_=c(f,`.kickjs-assets.json`);return a(_,JSON.stringify(g,null,2)+`
|
|
12
12
|
`,`utf-8`),d(` ✓ wrote manifest → ${l(n,_)} (${Object.keys(m).length} entries)`),{manifestPath:_,entries:p,manifest:g}}async function h(e,i,a,s){let p=u(a,i.src),m=i.dest?u(a,i.dest):c(s,e);if(v(m,a))return console.warn(` ⚠ assetMap.${e}.dest ('${i.dest}') resolves outside the project root — skipping copy`),{entrySummary:{namespace:e,src:i.src,dest:l(a,m),filesCopied:0},manifestSlice:{}};if(!n(p)||!y(p))return{entrySummary:{namespace:e,src:i.src,dest:l(a,m),filesCopied:0},manifestSlice:{}};let h=i.glob??`**/*`,b=await d(h,{cwd:p,nodir:!0,dot:!1,posix:!0});r(m,{recursive:!0});let x={},S=[...b].toSorted(),{pairs:C,collisionGroupsResolved:w}=f(e,S,{strategy:i.keys??`auto`}),T=0;for(let{rel:e,key:n}of C){let i=c(p,e),a=c(m,e);x[n]=_(s,a),!g(i,a)&&(r(o(a),{recursive:!0}),t(i,a),T++)}return w>0&&console.log(` ℹ assetMap.${e}: auto-resolved ${w} basename collision(s) by keeping extensions (set 'keys: "strip"' to opt back into legacy last-write-wins behaviour, or 'keys: "with-extension"' to keep all keys verbose).`),{entrySummary:{namespace:e,src:i.src,dest:l(a,m),filesCopied:T},manifestSlice:x}}function g(e,t){if(!n(t))return!1;try{let n=i(e),r=i(t);return r.size===n.size&&r.mtimeMs>=n.mtimeMs}catch{return!1}}function _(e,t){return l(e,t).split(/[\\/]/).filter(Boolean).join(`/`)}function v(e,t){let n=l(t,e);return n===``?!1:n.startsWith(`..`)||s(n)}function y(e){try{return i(e).isDirectory()}catch{return!1}}export{p as n,m as t};
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* @forinda/kickjs-cli v8.
|
|
2
|
+
* @forinda/kickjs-cli v8.16.0
|
|
3
3
|
*
|
|
4
4
|
* Copyright (c) Felix Orinda
|
|
5
5
|
*
|
|
@@ -8,6 +8,6 @@
|
|
|
8
8
|
*
|
|
9
9
|
* @license MIT
|
|
10
10
|
*/
|
|
11
|
-
import{t as e}from"./rolldown-runtime-
|
|
11
|
+
import{t as e}from"./rolldown-runtime-CYy3EyO3.mjs";import{dirname as t,isAbsolute as n,join as r,relative as i,resolve as a}from"node:path";import{cpSync as o,existsSync as s,mkdirSync as c,statSync as l,writeFileSync as u}from"node:fs";import{glob as d}from"glob";import{groupAssetKeys as f}from"@forinda/kickjs";var p=/* @__PURE__ */ e({ASSET_MANIFEST_VERSION:()=>1,buildAssets:()=>m});async function m(e,t){let{cwd:n,silent:o=!1}=t,s=t.distDir??e?.build?.outDir??`dist`,l=e?.assetMap;if(!l||Object.keys(l).length===0)return null;let d=o?()=>{}:console.log,f=a(n,s);c(f,{recursive:!0});let p=[],m={};for(let[e,t]of Object.entries(l)){let r=await h(e,t,n,f);p.push(r.entrySummary),Object.assign(m,r.manifestSlice),d(` ✓ ${e}: ${r.entrySummary.filesCopied} file(s) → ${r.entrySummary.dest}`)}let g={version:1,entries:m},_=r(f,`.kickjs-assets.json`);return u(_,JSON.stringify(g,null,2)+`
|
|
12
12
|
`,`utf-8`),d(` ✓ wrote manifest → ${i(n,_)} (${Object.keys(m).length} entries)`),{manifestPath:_,entries:p,manifest:g}}async function h(e,n,l,u){let p=a(l,n.src),m=n.dest?a(l,n.dest):r(u,e);if(v(m,l))return console.warn(` ⚠ assetMap.${e}.dest ('${n.dest}') resolves outside the project root — skipping copy`),{entrySummary:{namespace:e,src:n.src,dest:i(l,m),filesCopied:0},manifestSlice:{}};if(!s(p)||!y(p))return{entrySummary:{namespace:e,src:n.src,dest:i(l,m),filesCopied:0},manifestSlice:{}};let h=n.glob??`**/*`,b=await d(h,{cwd:p,nodir:!0,dot:!1,posix:!0});c(m,{recursive:!0});let x={},S=[...b].toSorted(),{pairs:C,collisionGroupsResolved:w}=f(e,S,{strategy:n.keys??`auto`}),T=0;for(let{rel:e,key:n}of C){let i=r(p,e),a=r(m,e);x[n]=_(u,a),!g(i,a)&&(c(t(a),{recursive:!0}),o(i,a),T++)}return w>0&&console.log(` ℹ assetMap.${e}: auto-resolved ${w} basename collision(s) by keeping extensions (set 'keys: "strip"' to opt back into legacy last-write-wins behaviour, or 'keys: "with-extension"' to keep all keys verbose).`),{entrySummary:{namespace:e,src:n.src,dest:i(l,m),filesCopied:T},manifestSlice:x}}function g(e,t){if(!s(t))return!1;try{let n=l(e),r=l(t);return r.size===n.size&&r.mtimeMs>=n.mtimeMs}catch{return!1}}function _(e,t){return i(e,t).split(/[\\/]/).filter(Boolean).join(`/`)}function v(e,t){let r=i(t,e);return r===``?!1:r.startsWith(`..`)||n(r)}function y(e){try{return l(e).isDirectory()}catch{return!1}}export{p as n,m as t};
|
|
13
|
-
//# sourceMappingURL=build-
|
|
13
|
+
//# sourceMappingURL=build-vY0bmwuH.mjs.map
|