@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.
Files changed (73) hide show
  1. package/dist/agent-docs-DhiaLsBj.mjs +591 -0
  2. package/dist/agent-docs-DhiaLsBj.mjs.map +1 -0
  3. package/dist/agent-docs-lNvu1K1x.mjs +590 -0
  4. package/dist/{build-cXg5ZlrG.mjs → build-BNHMWtNY.mjs} +2 -2
  5. package/dist/{build-Ch7Mu-zN.mjs → build-vY0bmwuH.mjs} +3 -3
  6. package/dist/{build-Ch7Mu-zN.mjs.map → build-vY0bmwuH.mjs.map} +1 -1
  7. package/dist/{builtins-Cj-H0MpD.mjs → builtins-CRRb7Lq1.mjs} +2 -2
  8. package/dist/{builtins-1iFKUPC8.mjs → builtins-tE4nrAZ_.mjs} +59 -59
  9. package/dist/cli.mjs +2 -2
  10. package/dist/{config-DJ3Yuos3.mjs → config-mXO3F69m.mjs} +2 -2
  11. package/dist/{config-LzGMuzP3.mjs → config-zWl1-NCq.mjs} +3 -3
  12. package/dist/{config-LzGMuzP3.mjs.map → config-zWl1-NCq.mjs.map} +1 -1
  13. package/dist/{doctor-hrYL914U.mjs → doctor-z92r35fo.mjs} +9 -9
  14. package/dist/{doctor-hrYL914U.mjs.map → doctor-z92r35fo.mjs.map} +1 -1
  15. package/dist/{fullstack-BDk2Min0.mjs → fullstack-BqevN8LJ.mjs} +13 -13
  16. package/dist/{fullstack-BDk2Min0.mjs.map → fullstack-BqevN8LJ.mjs.map} +1 -1
  17. package/dist/{fullstack-DOx3kvFi.mjs → fullstack-eMi-9BtZ.mjs} +9 -9
  18. package/dist/index.d.mts.map +1 -1
  19. package/dist/index.mjs +2 -2
  20. package/dist/{plugin-h1RvCxk1.mjs → plugin-BbbHEAzr.mjs} +2 -2
  21. package/dist/{plugin-DmerIwIH.mjs → plugin-CH4X4T0O.mjs} +2 -2
  22. package/dist/project-Bp6SIRyt.mjs +132 -0
  23. package/dist/project-D96UoR0P.mjs +133 -0
  24. package/dist/project-D96UoR0P.mjs.map +1 -0
  25. package/dist/{project-root-DBTLa3ee.mjs → project-root-Bw3CEPC7.mjs} +3 -3
  26. package/dist/{project-root-DBTLa3ee.mjs.map → project-root-Bw3CEPC7.mjs.map} +1 -1
  27. package/dist/{project-root-DQwgpeEX.mjs → project-root-DN0YbQE5.mjs} +2 -2
  28. package/dist/{rolldown-runtime-UeWuLvbj.mjs → rolldown-runtime-CYy3EyO3.mjs} +1 -1
  29. package/dist/{run-plugins-CajtgfCU.mjs → run-plugins-f7i7TlPV.mjs} +67 -67
  30. package/dist/run-plugins-f7i7TlPV.mjs.map +1 -0
  31. package/dist/{typegen-BsYWuduu.mjs → typegen-Bq4Fis9G.mjs} +5 -5
  32. package/dist/{typegen-BsYWuduu.mjs.map → typegen-Bq4Fis9G.mjs.map} +1 -1
  33. package/dist/{typegen-DmSQleE5.mjs → typegen-_x_Q5O0b.mjs} +4 -4
  34. package/dist/{types-CX1RqHCf.mjs → types-BLZecxnS.mjs} +1 -1
  35. package/package.json +3 -3
  36. package/templates/base/files/_dot_vscode/extensions.json +3 -0
  37. package/templates/base/files/kick.config.ts +4 -0
  38. package/templates/base/skills/add-adapter.txt +56 -0
  39. package/templates/base/skills/add-module.txt +53 -0
  40. package/templates/base/skills/add-plugin.txt +69 -0
  41. package/templates/base/skills/bootstrap-export.txt +21 -0
  42. package/templates/base/skills/cli-commands-cheatsheet.txt +46 -0
  43. package/templates/base/skills/cli-plugin.txt +61 -0
  44. package/templates/base/skills/context-contributor.txt +73 -0
  45. package/templates/base/skills/deny-list.txt +44 -0
  46. package/templates/base/skills/deploy.txt +99 -0
  47. package/templates/base/skills/docs-lookup.txt +40 -0
  48. package/templates/base/skills/env-wiring-check.txt +44 -0
  49. package/templates/base/skills/guard-vs-middleware-vs-contributor.txt +95 -0
  50. package/templates/base/skills/query-parsing-list-endpoint.txt +48 -0
  51. package/templates/base/skills/refresh-agent-docs.txt +27 -0
  52. package/templates/base/skills/route-flags.txt +73 -0
  53. package/templates/base/skills/thin-entry-file.txt +49 -0
  54. package/templates/base/skills/use-asset-manager.txt +61 -0
  55. package/templates/base/skills/write-controller-test.txt +63 -0
  56. package/templates/feature-views/feature.json +21 -0
  57. package/templates/feature-views/files/src/adapters/views.ts +5 -0
  58. package/templates/feature-views/files/src/views/home.kick +3 -0
  59. package/templates/feature-views/files/src/views/layouts/main.kick +13 -0
  60. package/templates/feature-views/files/src/views.ts +9 -0
  61. package/templates/feature-views/skills/views-forms.txt +68 -0
  62. package/templates/feature-views/skills/views.txt +49 -0
  63. package/templates/fullstack-root/files/_dot_vscode/extensions.json +3 -0
  64. package/dist/agent-docs-BLpdFCWy.mjs +0 -932
  65. package/dist/agent-docs-c9x_je96.mjs +0 -933
  66. package/dist/agent-docs-c9x_je96.mjs.map +0 -1
  67. package/dist/package-manager-DMNCUv5Z.mjs +0 -12
  68. package/dist/package-manager-DMNCUv5Z.mjs.map +0 -1
  69. package/dist/package-manager-W-gJGan_.mjs +0 -11
  70. package/dist/project-BhLkKHOD.mjs +0 -135
  71. package/dist/project-CXcAR-tR.mjs +0 -136
  72. package/dist/project-CXcAR-tR.mjs.map +0 -1
  73. 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.14.8
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-UeWuLvbj.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)+`
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.14.8
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-UeWuLvbj.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)+`
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-Ch7Mu-zN.mjs.map
13
+ //# sourceMappingURL=build-vY0bmwuH.mjs.map