diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..3d79970 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,5 @@ +# Keep LF in the repo and in every checkout, so tests and hooks behave the same on Windows. +* text=auto eol=lf +*.png binary +*.ico binary +*.jpg binary diff --git a/docs/KIRO_USAGE.md b/docs/KIRO_USAGE.md index 67282e8..bee6685 100644 --- a/docs/KIRO_USAGE.md +++ b/docs/KIRO_USAGE.md @@ -24,6 +24,8 @@ The Devpost "How did you use Kiro?" write-up. Each answer points at files in thi **Spec versus vibe in the second half.** In Kiro Web the requests were conversational ("make the demo pets private to each browser", "a revived pet should not jump straight to demon"), but every one of them was turned into a spec change before code, see the table under Kiro Web below. Conversation decided *what*; the spec pinned down the edge cases. +**In my words: approvals in the IDE.** Running the spec tasks meant approving one command at a time, which kept interrupting my work. What fixed it: switching the chat to **Approve for me** (commands then showed "Approved for you"), and **Always allow** with a narrow pattern for repeated commands. One thing stayed blocked on purpose: when the agent tried to edit `.kiro/settings/mcp.json`, Kiro refused it with the built-in `kiro-scope` rule (`deny fs_write .kiro/settings/`), so an agent cannot change its own MCP or permission settings. The agent did not try to work around it through the shell; I edit that file myself when needed. + ## Kiro Web: the second half of the build The first half (engine, UI, hooks, MCP server) was built in the **Kiro IDE**: I wrote the PRD and BRD and Kiro ran the spec tasks (commits by `Zee7X`). Everything after it was built in **Kiro Web** agent sessions: the commits authored by `Kiro Agent` and pull requests #1 to #23. This section was written from that session's own record and every claim points at a PR, a spec line or a test. @@ -64,7 +66,9 @@ How the connections worked in Web: GitHub through Kiro Web's own GitHub connecti **Design note.** Kiro v1 hooks have no manual trigger, so the on-demand "summon" entry point is a manual steering file (`.kiro/steering/summon-healer.md`, run as `/summon-healer`), not a hook. -**Not exercised in the IDE.** The hooks were written during the IDE stage, but I did not run them against the live pet inside the IDE, so how they behave there (timing, `{{filePath}}`) is not confirmed. The script and the route are tested as described above. +**In my words: run in the Kiro IDE (19 November 2026).** With `npm run dev` on port 3000, the agent added `console.log('test')` to `src/lib/heal.ts` and saved it. The hook fired, the server logged `POST /api/local-poop 200`, and the pet showed poop 1 and Sanity 90 at once, with the event `console.log in src/lib/heal.ts` tagged KIRO. When the line was removed and saved again, the hook logged `clean after src/lib/heal.ts`: poop back to 0, Sanity 100. The file path arrived correctly; I did not check whether it came through `{{filePath}}`, stdin or an environment variable. + +![The pet on localhost after the hook fired: poop on the LCD, Sanity 90, and the KIRO event "console.log in src/lib/heal.ts" in the event log](media/kiro-hook-poop.png) ## Steering strategy @@ -88,7 +92,13 @@ The "never fabricate" rule exists because an early version of the heal feature i **What was verified outside the IDE.** `initialize` and `tools/list` return the seven tools (checked by `power.test.ts` on every test run), `get_pet_status` rendered the ASCII LCD, and `add_badge` was run over stdio against a copy of a real README: it joined the badge row, changed nothing on a second run and refused a path outside the workspace. `diagnose_pet` and the GitHub calls behind it are covered by `src/lib/__tests__/heal.test.ts` with a mocked `fetch`; they were not run against live GitHub (the unauthenticated quota was exhausted during development). -**Not exercised in the IDE.** I had not set up MCP in the IDE, so the `gitgotchi` server was not connected in Kiro's MCP panel and `/summon-healer` was not run there. The same diagnosis was used on the website (HEAL), including on a private repo, and `/api/auto-heal` was checked on production against a public repo whose latest CI run had failed: it named the failed job and step and returned the error lines of the log. +**In my words: run in the Kiro IDE (19 November 2026).** The `gitgotchi` server connected from `.kiro/settings/mcp.json`. `get_pet_status` and `diagnose_pet` ran without an approval prompt, because they are the two tools in `autoApprove`. In the `/summon-healer` flow, `diagnose_pet` found one problem, `[poop] console.log in src/lib/heal.ts`; no spec change was needed; the agent removed the line, the hook cleaned the poop, and the next `diagnose_pet` answered "No findings". `npm test` then passed 321 of 322; the one failure is described below. + +What went wrong first: my port 3000 was taken by another dev server, so the first `get_pet_status` failed with `Cannot read properties of undefined (reading 'stage')`. The MCP server now says plainly when something other than GitGotchi answers on `GITGOTCHI_URL`. The failing test was `power.test.ts`: with `core.autocrlf=true` on Windows the checkout had CRLF line endings and the frontmatter regex expected `\n`. The test now normalises line endings, and `.gitattributes` keeps LF in every checkout. + +![Kiro IDE: the gitgotchi MCP tool get_pet_status in chat, with the ASCII pet](media/kiro-mcp-get-pet-status.png) + +Also checked outside the IDE: `/api/auto-heal` on production against a public repo whose latest CI run had failed named the failed job and step and returned the error lines of the log. ## Property-based testing @@ -113,7 +123,7 @@ These are referenced from `.kiro/specs/pet-engine/requirements.md` so each requi Checked outside the IDE: `power.test.ts` validates both manifests against the schema fields and starts the bundle over stdio, which lists the same seven tools as `mcp-server/index.mjs`. -**Not imported in the IDE.** I did not import `power-gitgotchi/` through the Powers panel, so activation by keyword is not confirmed. +**Not imported in the IDE.** I did not import `power-gitgotchi/` through the Powers panel, so activation by keyword is not confirmed. The same server ran from the workspace config, as described under MCP. ## What I would tell another builder diff --git a/docs/media/kiro-mcp-get-pet-status.png b/docs/media/kiro-mcp-get-pet-status.png new file mode 100644 index 0000000..4251fd0 Binary files /dev/null and b/docs/media/kiro-mcp-get-pet-status.png differ diff --git a/mcp-server/index.mjs b/mcp-server/index.mjs index abc781a..0c4e501 100644 --- a/mcp-server/index.mjs +++ b/mcp-server/index.mjs @@ -102,7 +102,13 @@ async function call(path, init = {}) { } catch { throw new Error(`GitGotchi app not reachable at ${BASE}. Start it with "npm run dev" or set GITGOTCHI_URL.`); } - const body = await res.json().catch(() => ({})); + const body = await res.json().catch(() => null); + // Something else on that port (another dev server) answers with HTML or foreign JSON: say so plainly + // instead of failing later on a missing field. + const isGitGotchi = body && typeof body === 'object' && ('pet' in body || 'diagnosis' in body || 'error' in body); + if (!isGitGotchi) { + throw new Error(`Something other than GitGotchi answered at ${BASE} (HTTP ${res.status}). Is another app using that port? Start GitGotchi with "npm run dev" or set GITGOTCHI_URL.`); + } if (!res.ok && !body.pet) throw new Error(`HTTP ${res.status}: ${body.error || 'request failed'}`); return body; } diff --git a/power-gitgotchi/server/gitgotchi-mcp.mjs b/power-gitgotchi/server/gitgotchi-mcp.mjs index d9335f8..23743fe 100644 --- a/power-gitgotchi/server/gitgotchi-mcp.mjs +++ b/power-gitgotchi/server/gitgotchi-mcp.mjs @@ -151,7 +151,7 @@ if(!Array.isArray(r))throw Error(`ajv implementation error`);let a=n.name(`valid `);if(i.toLowerCase().includes(`/api/badge/${n.toLowerCase()}`))return{text:e,changed:!1,where:`already present`};let a=i.split(` `),o=Math.min(a.length,60),s=-1;for(let e=0;e=0){let e=s;for(;e+1/^\s*#\s+\S/.test(e));return c>=0?(a.splice(c+1,0,``,t),{text:a.join(r),changed:!0,where:`below the title on line ${c+1}`}):{text:`${t}${r}${r}${e}`,changed:!0,where:`at the top`}}const Ag=(process.env.GITGOTCHI_URL||`http://localhost:3000`).replace(/\/$/,``),jg={EGG:[` .------. `,` / . . \\ `,` | . . | `,` | .. | `,` | . . | `,` \\ . . / `," `------' ",` `],BABY_GHOST:[` .------. `,` / \\ `,` | o o | `,` | __ | `,` | | `,` | /\\/\\/\\ | `,` \\/ \\/ `,` `],CODE_DEMON:[` /\\ /\\ `,` / \\.----./ \\ `,` | > < | `,` | ww | `,` | \\vv/ | `,` /|______|\\ `,` / |_| |_| \\ `,` `],NECROMANCER:[` .--. o `,` / \\ | `,` | x x | | `,` | .. |-+ `,` /\\____/\\| `,` / | | \\ `,` /___|__|___\\ `,` `],ZOMBIE_CORPSE:[` .------. `,` / ____ \\ `,` | x x | `,` | ____ | `,` | |_||_| | `,` \\ / `," ___`-..-'___ ",` `]},Mg=e=>`[${`#`.repeat(Math.round(e/10)).padEnd(10,`.`)}] ${String(Math.round(e)).padStart(3)}`;function Ng(e){let{pet:t,events:n=[],source:r}=e,i=(jg[t.stage]||jg.BABY_GHOST).map(e=>`| ${e} |`),a=`+${`-`.repeat(18)}+`,o=n.slice(0,3).map(e=>` - ${e.label}${e.simulated?` (simulated)`:``}`).join(` `);return[t.repoName,a,...i,a,`STAGE ${t.stage} MOOD ${t.mood}`,`HP ${Mg(t.hp)}${t.recentCi&&t.recentCi.length===0?` (unmeasured: no CI runs)`:``}`,`FOOD ${Mg(t.fullness)}`,`SANITY ${Mg(t.sanity)}`,`POOP ${t.poopCount} COMMITS ${t.commitsTotal} REVIVALS ${t.resurrections}`,`"${t.statusMessage}" (data: ${r})`,...o?[`Recent:`,o]:[]].join(` -`)}const Pg=(e,t=!1)=>({content:[{type:`text`,text:e}],...t?{isError:!0}:{}}),Fg=process.env.GITGOTCHI_HOOK_TOKEN||``;async function Ig(e,t={}){let n,r={...t.headers||{},...Fg?{Authorization:`Bearer ${Fg}`}:{}};try{n=await fetch(`${Ag}${e}`,{...t,headers:r,signal:AbortSignal.timeout(15e3)})}catch{throw Error(`GitGotchi app not reachable at ${Ag}. Start it with "npm run dev" or set GITGOTCHI_URL.`)}let i=await n.json().catch(()=>({}));if(!n.ok&&!i.pet)throw Error(`HTTP ${n.status}: ${i.error||`request failed`}`);return i}const Lg=e=>{let[t,n,...r]=e.trim().toLowerCase().split(`/`);if(!t||!n||r.length)throw Error(`repo must look like owner/repo`);return`${encodeURIComponent(t)}/${encodeURIComponent(n)}`},Rg=e=>`/api/pet/${Lg(e)}`,zg=(e,t)=>Ig(`${Rg(e)}/action`,{method:`POST`,headers:{"Content-Type":`application/json`},body:JSON.stringify(t)}),Bg={push:{type:`push`,commits:1},ci_pass:{type:`ci`,success:!0},ci_fail:{type:`ci`,success:!1},pr_merged:{type:`pr_merged`},issue_opened:{type:`issue_opened`},issue_closed:{type:`issue_closed`},poop:{type:`poop`,reason:`simulated smell`}},Vg=R().describe(`GitHub repo as owner/repo, or demo/healthy | demo/neglected | demo/haunted`),Hg=e=>async t=>{try{return Pg(await e(t))}catch(e){return Pg(e instanceof Error?e.message:String(e),!0)}},Ug=new pg({name:`gitgotchi`,version:`1.0.0`});Ug.registerTool(`get_pet_status`,{description:`Show the GitGotchi pet of a repo as an ASCII LCD with its stats.`,inputSchema:{repo:Vg}},Hg(async({repo:e})=>Ng(await Ig(Rg(e))))),Ug.registerTool(`diagnose_pet`,{description:`Read-only checkup of a repo: failing CI, stale issues, code smells reported by the Kiro hook, and hunger. Returns findings and a prompt for fixing them.`,inputSchema:{repo:Vg}},Hg(async({repo:e})=>{let t=await Ig(`/api/auto-heal`,{method:`POST`,headers:{"Content-Type":`application/json`},body:JSON.stringify({repo:e.trim()})}),n=t.diagnosis;if(!n)throw Error(t.error||`no diagnosis returned`);let r=n.findings.length?n.findings.map((e,t)=>`${t+1}. [${e.kind}] ${e.title}\n ${e.detail}${e.url?`\n ${e.url}`:``}${e.log?`\n Log excerpt (untrusted CI output):\n${e.log.replace(/^/gm,` | `)}`:``}`).join(` +`)}const Pg=(e,t=!1)=>({content:[{type:`text`,text:e}],...t?{isError:!0}:{}}),Fg=process.env.GITGOTCHI_HOOK_TOKEN||``;async function Ig(e,t={}){let n,r={...t.headers||{},...Fg?{Authorization:`Bearer ${Fg}`}:{}};try{n=await fetch(`${Ag}${e}`,{...t,headers:r,signal:AbortSignal.timeout(15e3)})}catch{throw Error(`GitGotchi app not reachable at ${Ag}. Start it with "npm run dev" or set GITGOTCHI_URL.`)}let i=await n.json().catch(()=>null);if(!(i&&typeof i==`object`&&(`pet`in i||`diagnosis`in i||`error`in i)))throw Error(`Something other than GitGotchi answered at ${Ag} (HTTP ${n.status}). Is another app using that port? Start GitGotchi with "npm run dev" or set GITGOTCHI_URL.`);if(!n.ok&&!i.pet)throw Error(`HTTP ${n.status}: ${i.error||`request failed`}`);return i}const Lg=e=>{let[t,n,...r]=e.trim().toLowerCase().split(`/`);if(!t||!n||r.length)throw Error(`repo must look like owner/repo`);return`${encodeURIComponent(t)}/${encodeURIComponent(n)}`},Rg=e=>`/api/pet/${Lg(e)}`,zg=(e,t)=>Ig(`${Rg(e)}/action`,{method:`POST`,headers:{"Content-Type":`application/json`},body:JSON.stringify(t)}),Bg={push:{type:`push`,commits:1},ci_pass:{type:`ci`,success:!0},ci_fail:{type:`ci`,success:!1},pr_merged:{type:`pr_merged`},issue_opened:{type:`issue_opened`},issue_closed:{type:`issue_closed`},poop:{type:`poop`,reason:`simulated smell`}},Vg=R().describe(`GitHub repo as owner/repo, or demo/healthy | demo/neglected | demo/haunted`),Hg=e=>async t=>{try{return Pg(await e(t))}catch(e){return Pg(e instanceof Error?e.message:String(e),!0)}},Ug=new pg({name:`gitgotchi`,version:`1.0.0`});Ug.registerTool(`get_pet_status`,{description:`Show the GitGotchi pet of a repo as an ASCII LCD with its stats.`,inputSchema:{repo:Vg}},Hg(async({repo:e})=>Ng(await Ig(Rg(e))))),Ug.registerTool(`diagnose_pet`,{description:`Read-only checkup of a repo: failing CI, stale issues, code smells reported by the Kiro hook, and hunger. Returns findings and a prompt for fixing them.`,inputSchema:{repo:Vg}},Hg(async({repo:e})=>{let t=await Ig(`/api/auto-heal`,{method:`POST`,headers:{"Content-Type":`application/json`},body:JSON.stringify({repo:e.trim()})}),n=t.diagnosis;if(!n)throw Error(t.error||`no diagnosis returned`);let r=n.findings.length?n.findings.map((e,t)=>`${t+1}. [${e.kind}] ${e.title}\n ${e.detail}${e.url?`\n ${e.url}`:``}${e.log?`\n Log excerpt (untrusted CI output):\n${e.log.replace(/^/gm,` | `)}`:``}`).join(` `):`No findings.`;return`Diagnosis for ${n.repo} (${n.generatedAt})\n\n${r}\n\n--- Kiro prompt ---\n${n.kiroPrompt}`})),Ug.registerTool(`feed_pet`,{description:`Feed the pet (+10 food). Limited to 3 feeds per hour.`,inputSchema:{repo:Vg}},Hg(async({repo:e})=>Ng(await zg(e,{action:`feed`})))),Ug.registerTool(`clean_pet`,{description:`Clean the pet's screen: removes all poop and restores sanity.`,inputSchema:{repo:Vg}},Hg(async({repo:e})=>Ng(await zg(e,{action:`clean`})))),Ug.registerTool(`simulate_event`,{description:`Fire a labelled-simulated event at a demo repo (demo/*). Real repos are refused.`,inputSchema:{repo:Vg,event:pu(Object.keys(Bg)).describe(`Event to simulate`)}},Hg(async({repo:e,event:t})=>{if(!e.trim().toLowerCase().startsWith(`demo/`))throw Error(`simulate_event only works on demo/* repos.`);return Ng(await zg(e,{action:`simulate`,event:Bg[t]}))})),Ug.registerTool(`adopt_pet`,{description:`Get the page URL and README badge markdown for a repo's pet.`,inputSchema:{repo:Vg}},Hg(async({repo:e})=>{let t=Lg(e);return[`Pet page: ${Ag}/pet/${t}`,`Badge markdown: [![GitGotchi](${Ag}/api/badge/${t})](${Ag}/pet/${t})`,`The badge URL is only reachable from outside your machine once the app is deployed.`].join(` `)}));const Wg=(process.env.GITGOTCHI_PUBLIC_URL||Ag).replace(/\/$/,``),Gg=e=>/^https?:\/\/(localhost|127\.|\[::1\]|0\.0\.0\.0)/i.test(e);function Kg(){try{return t(`git`,[`remote`,`get-url`,`origin`],{encoding:`utf8`,stdio:[`ignore`,`pipe`,`ignore`]}).trim().match(/github\.com[:/]([^/\s]+\/[^/\s]+?)(?:\.git)?$/)?.[1]}catch{return}}Ug.registerTool(`add_badge`,{description:`Write the GitGotchi badge into this workspace's README (it joins the existing badge row, or goes below the title). Only edits a file inside the current workspace and never commits; review the change and commit it yourself.`,inputSchema:{repo:R().optional().describe(`owner/repo; default: the git origin of this workspace`),size:pu([`small`,`full`]).optional().describe(`small (220x40, fits a badge row) or full (360x120). Default small`),readme:R().optional().describe(`README path relative to the workspace. Default README.md`),badge_key:R().optional().describe(`Private repos only: the key from KEEPER TOOLS, MAKE BADGE LINK`)}},Hg(async({repo:e,size:t,readme:c,badge_key:l})=>{if(Gg(Wg))throw Error(`GITGOTCHI_URL points at this machine, so GitHub could not show the badge. Set GITGOTCHI_PUBLIC_URL (or GITGOTCHI_URL) to your deployment, e.g. https://gitgochi.lumelo.my.id.`);let u=(e||Kg()||``).trim();if(!u)throw Error(`No repo given and no GitHub origin remote found. Pass repo as owner/repo.`);let d=Lg(u).toLowerCase();if(d.startsWith(`demo/`))throw Error(`Demo pets have no README badge of their own.`);let f=await fetch(`${Wg}/api/pet/${d}`,{headers:Fg?{Authorization:`Bearer ${Fg}`}:{},signal:AbortSignal.timeout(15e3)}).catch(()=>null);if(f&&f.status===404&&!l)throw Error(`GitGotchi does not know ${d}. Check the name; for a private repo pass badge_key from KEEPER TOOLS.`);let p=process.cwd(),m=s(p,c||`README.md`),h=o(p,m);if(!h||h.startsWith(`..`)||a(h))throw Error(`readme must be a path inside this workspace.`);let g=Dg(Wg,d,{size:t||`small`,badgeKey:l}),_=n(m),v=kg(_?r(m,`utf8`):`# ${u.split(`/`)[1]}\n`,g,d);return v.changed?(i(m,v.text),[`${_?`Updated`:`Created`} ${h}: badge added ${v.where}.`,g,`Pet page: ${Wg}/pet/${d}`,`Not committed. Review the diff, then commit and push; the push also feeds the pet.`].join(` `)):`${h} already has the GitGotchi badge for ${d}. Nothing changed.`})),await Ug.connect(new Eg);export{}; \ No newline at end of file diff --git a/src/lib/__tests__/power.test.ts b/src/lib/__tests__/power.test.ts index 2e84bb0..a58307f 100644 --- a/src/lib/__tests__/power.test.ts +++ b/src/lib/__tests__/power.test.ts @@ -55,7 +55,8 @@ describe('Kiro Power (power-gitgotchi/)', () => { }); it('SKILL.md has summon-healer frontmatter and the four steps', () => { - const md = readFileSync(`${POWER}skills/summon-healer/SKILL.md`, 'utf8'); + // Windows checkouts with core.autocrlf=true have CRLF line endings. + const md = readFileSync(`${POWER}skills/summon-healer/SKILL.md`, 'utf8').replace(/\r\n/g, '\n'); expect(md).toMatch(/^---\nname: summon-healer\ndescription: .+\n---\n/); for (const step of ['diagnose_pet', '.kiro/specs/', 'npm test', 'actually ran']) expect(md).toContain(step); });