chamba 0.0.1 → 0.1.0

package/skill/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: chamba
+description: Open a browser workspace paired to this terminal session so the human can see rendered markdown, paste screenshots the agent can read, and point at UI - one shared conversation between the terminal agent and the browser. Use when the user says /chamba, asks to "open chamba", wants to share or receive images, or wants a visual workspace alongside the terminal.
+when_to_use: The user typed /chamba, asked to open the chamba workspace, wants to paste or be shown an image/screenshot, or wants a browser surface paired with this terminal session.
+---
+
+# chamba
+
+chamba pairs this terminal session with a browser workspace over one shared
+conversation. The terminal stays home base; the browser is where the human reads
+rendered markdown, pastes screenshots you can open, and points at UI. A pasted
+image arrives as a real file path you can `Read`; anything you send back with a
+file renders inline in their browser.
+
+Every command is `npx chamba@latest <command>`. Conversation content prints on
+stdout (what you read and act on); status and hints go to stderr, so a command's
+stdout is just the messages. Using `@latest` resolves the newest published
+version rather than a stale one npx may have cached.
+
+## Opening a session
+
+```
+npx chamba@latest open --title "what this is about"
+```
+
+Optionally `--kind spec` for spec work (extra Draft/Mock/Diagram surfaces). This
+prints a URL on stdout - give that URL to the human and ask them to open it. The
+server starts automatically if it is not already running.
+
+## The loop
+
+After opening (or `attach`), wait for the human:
+
+```
+npx chamba@latest poll
+```
+
+`poll` blocks until there is something to read, then prints it and returns. Run it
+again to keep waiting - it is safe to re-run (a batch re-delivers if you were
+interrupted before acting). React to what each line says:
+
+- A message from the human (`you: ...`): do the work, then answer with `reply`.
+- An attachment line (`  [file] name -> /abs/path`): that path is a real file on
+  disk. `Read` it (screenshots, mockups, logs) and act on what you see.
+- An annotation batch (`you [N annotations]:`): the human pointed at elements in
+  the app tab. Each numbered item carries the comment, the `selector`, the `page`
+  and `viewport`, a `[shot]` screenshot path to `Read`, and - when the app is
+  React/Next - the `component:` name and its source `file:line`. Use the source
+  and selector to find the code, `Read` the shot to see the problem, fix each item,
+  then `reply`. (React 19 shows the component name but may omit `file:line` unless
+  the app opted into bippy's source tier; fall back to the selector then.)
+- `· You moved to another session (<id>)`: the human switched sessions. Hand off
+  with `npx chamba@latest attach <id>`, then keep polling that one.
+- `· Session ended`: the human handed back to the terminal. Stop polling and
+  resume terminal work.
+
+## Replying
+
+```
+npx chamba@latest reply on it - here is the diff you asked about
+```
+
+Send a file back (renders in their browser); text is optional alongside it:
+
+```
+npx chamba@latest reply here's the chart --image /abs/path/to/chart.png
+```
+
+Use `--file a,b` / `--image a,b` (comma-separated) for several files.
+
+## Handing back
+
+```
+npx chamba@latest end
+```
+
+Ends the session from the terminal (the browser goes read-only). The human can
+also hand back from the browser, which you will see as `· Session ended` on your
+next poll.
+
+## Spec sessions
+
+A spec session is chamba's deepest use: a structured interview that produces a
+spec package - a canonical markdown draft, mockups, diagrams, and a decision log -
+in the same shared thread and the same annotation system.
+Open one with `--kind spec`:
+
+```
+npx chamba@latest open --kind spec --title "checkout redesign spec"
+```
+
+This unlocks three surface tabs beside "Your app" - Draft, Mock, Diagram - each
+annotatable exactly like the app tab.
+You drive the session from the terminal with four commands (`ask`, `decision`,
+`artifact`, `export`); the human answers, points, and annotates from the browser.
+
+### Intake: infer the kind of work, then confirm it
+
+A spec session opens with a free-form dump - text, pasted images, files.
+Read all of it, infer which of four kinds of spec work this is, and confirm your
+read with the human before diving in (they can override).
+Record the confirmed kind with `decision` so it is on the log.
+
+The four kinds are behaviorally distinct - they change what you do, not just a label:
+
+- **co-spec** - no spec exists yet; you build one from scratch.
+  Start wide (goals, users, constraints, what success means), then converge; most
+  of the work is net-new question cards and a draft that grows from nothing.
+- **review** - a spec or feature already exists and the human wants it pressure-tested.
+  Read it first against the codebase, then lead with the gaps, contradictions, and
+  unstated assumptions you find rather than with open-ended questions.
+- **refine** - a draft exists and is roughly right; the work is sharpening.
+  Hunt vague terms, underspecified edges, and missing error/empty/loading states,
+  then propose precise wording and confirm it.
+- **feedback** - the human has a running thing and reactions to it.
+  Lean on the Your app tab and annotations: turn each pointed-at problem into a
+  decision and a draft revision.
+
+### The interview doctrine
+
+- Hunt ambiguity relentlessly; every vague term ("fast", "simple", "secure") is a
+  question waiting to be asked.
+- Assume the highest standard: when you offer options, mark the one you would
+  choose as `recommended` and say why in its description.
+- Give development cost low weight - prefer quality, simplicity, robustness,
+  scalability, and long-term maintainability; surface the trade-off and let the
+  human decide.
+- Cross-reference every claim against the actual code as `path:line`; do not assert
+  what the codebase does from memory.
+- Never let anything unresolved silently vanish: if you cannot get an answer,
+  record it as an `assumed` decision so it surfaces as an open question.
+- The human can stop anytime; the card always carries a stop affordance, so honor it.
+
+### Asking - question cards
+
+Post a structured question with `ask`.
+Options are structured (a label, a description, an optional `recommended` flag), so
+the card is passed as JSON - inline via `--json` or as a file path positional:
+
+```
+npx chamba@latest ask --json '{
+  "question": "How should an expired checkout session behave?",
+  "options": [
+    {"label": "Silent refresh", "description": "Mint a new session, keep the cart, no interruption.", "recommended": true},
+    {"label": "Prompt to resume", "description": "Show a resume dialog before restoring the cart."},
+    {"label": "Hard reset", "description": "Discard the cart and start over."}
+  ]
+}'
+```
+
+Offer as many options as the question genuinely has (up to six); do not pad to a
+number, and do not collapse real choices to fit.
+You never add a "let me type my own" option or a "leave a note" option: the card
+always shows a free-text custom-answer field and always lets the human annotate
+their choice, with voice on both.
+The answer returns as a normal message on your next `poll` - there is no separate
+answer command - and `ask` fills in the card id for you.
+
+### Recording decisions
+
+Every material choice goes on the decision log, marked `confirmed` (the human chose
+it) or `assumed` (you chose it provisionally on their behalf):
+
+```
+npx chamba@latest decision --status confirmed --summary "Expired sessions refresh silently, cart preserved"
+npx chamba@latest decision --status assumed --summary "Guest checkout is in scope" --detail "Unconfirmed; revisit before finalizing"
+```
+
+`assumed` entries are the ones that surface as open questions on export, so record
+them honestly rather than guessing silently.
+
+### Building artifacts - draft, mock, diagram
+
+Publish a draft, mock, or diagram from a file with `artifact`; the matching surface
+tab renders it, annotatable like the app:
+
+```
+npx chamba@latest artifact --kind draft   --name spec     --file /abs/spec.md
+npx chamba@latest artifact --kind mock     --name checkout --file /abs/checkout.html
+npx chamba@latest artifact --kind diagram --name flow     --file /abs/flow.mmd
+```
+
+- `draft` is markdown (rendered), `mock` is HTML (served sandboxed with the
+  annotation layer injected), `diagram` is mermaid.
+- Build the draft live: re-post the same `--kind draft --name <name>` as you write,
+  and its tab reloads to the new revision each time - this is how the spec builds in
+  front of the human.
+- Keep one draft name (e.g. `spec`) as the canonical draft; it becomes `spec.md` on
+  export, and any other draft names land in `assets/`.
+- Mocks and diagrams are annotated through the same select -> comment -> card flow as
+  the app tab; a batch of mock annotations arrives on `poll` just like app ones.
+
+### Exporting the package
+
+Nothing leaves `.chamba/` automatically.
+When the spec is ready to be official, copy the self-contained package to a
+destination the human names (usually under `docs/`):
+
+```
+npx chamba@latest export docs/checkout-spec
+```
+
+This writes `spec.md` (the canonical draft), `assets/` (mocks and diagrams), and
+`decisions.md` (the log, grouped confirmed vs. assumed/open).
+
+## Notes
+
+- All commands talk to a local server that shares this container; you never need a
+  host or port beyond the defaults.
+- Presence is automatic: while you are parked in `poll`, the browser shows the
+  agent as here.
+- Past sessions stay readable: `npx chamba@latest attach <id>` reloads any session's
+  recent history.

package/web/assets/abnfDiagram-VRR7QNED-aw1_rWFY.js

@@ -0,0 +1 @@
+import{g as p,r as u,d as a}from"./chunk-MOJQB5TN-BRzAoPL7.js";import{p as f}from"./chunk-JWPE2WC7-CMWXKnkF.js";import{_ as n,l as o}from"./mermaid.core-CyLpSBwh.js";import{M as c,b as d}from"./cynefin-VYW2F7L2-CtWqChj_.js";import"./index-CBBSnvKL.js";var v=d().RailroadAbnf.parser.LangiumParser,i=n(e=>{const r=e.alternatives.map(g);return r.length===1?r[0]:{type:"choice",alternatives:r}},"transformAlternation"),g=n(e=>{const r=e.elements.map(y);return r.length===1?r[0]:{type:"sequence",elements:r}},"transformConcatenation"),b=n(e=>{if(e.includes("*")){const[t,s]=e.split("*"),l=t?parseInt(t,10):0,m=s?parseInt(s,10):1/0;return{min:l,max:m}}const r=parseInt(e,10);return{min:r,max:r}},"parseRepeat"),y=n(e=>{const r=A(e.primary);if(!e.repeat)return r;const{min:t,max:s}=b(e.repeat);return t===0&&s===1?{type:"optional",element:r}:{type:"repetition",element:r,min:t,max:s}},"transformElement"),A=n(e=>{switch(e.$type){case"AbnfStringLiteral":return{type:"terminal",value:e.value};case"AbnfNumVal":return{type:"terminal",value:e.value};case"AbnfRuleName":return{type:"nonterminal",name:e.name};case"AbnfGroup":return i(e.element);case"AbnfOptionalGroup":return{type:"optional",element:i(e.element)};default:throw new Error(`Unsupported ABNF primary node: ${e.$type}`)}},"transformPrimary"),P=n(e=>({name:e.name,definition:i(e.definition)}),"transformRule"),h=n(e=>{f(e,a),e.title&&a.setTitle(e.title),e.rules.map(r=>a.addRule(P(r)))},"populateDb"),R={parse:n(e=>{a.clear(),o.debug("[ABNF Parser] Starting Langium parse");const r=v.parse(e);if(r.lexerErrors.length>0||r.parserErrors.length>0)throw new c(r);const t=r.value;o.debug("[ABNF Parser] Parsed rules:",t.rules.length),h(t),o.debug("[ABNF Parser] Parse complete")},"parse"),parser:{yy:a}},B={parser:R,db:a,renderer:u,styles:p};export{B as diagram};

package/web/assets/arc-BMhSK0Sy.js

@@ -0,0 +1 @@
+import{Y as ln,$ as an,a0 as F,a1 as q,a2 as j,a3 as un,a4 as y,a5 as tn,a6 as J,a7 as _,a8 as rn,a9 as o,aa as on,ab as sn,ac as fn}from"./mermaid.core-CyLpSBwh.js";function cn(l){return l.innerRadius}function yn(l){return l.outerRadius}function gn(l){return l.startAngle}function dn(l){return l.endAngle}function mn(l){return l&&l.padAngle}function pn(l,h,I,D,v,A,z,a){var O=I-l,i=D-h,n=z-v,d=a-A,u=d*O-n*i;if(!(u*u<y))return u=(n*(h-A)-d*(l-v))/u,[l+u*O,h+u*i]}function U(l,h,I,D,v,A,z){var a=l-I,O=h-D,i=(z?A:-A)/J(a*a+O*O),n=i*O,d=-i*a,u=l+n,s=h+d,f=I+n,c=D+d,B=(u+f)/2,t=(s+c)/2,m=f-u,g=c-s,R=m*m+g*g,T=v-A,P=u*c-f*s,S=(g<0?-1:1)*J(on(0,T*T*R-P*P)),Y=(P*g-m*S)/R,$=(-P*m-g*S)/R,w=(P*g+m*S)/R,p=(-P*m+g*S)/R,x=Y-B,e=$-t,r=w-B,C=p-t;return x*x+e*e>r*r+C*C&&(Y=w,$=p),{cx:Y,cy:$,x01:-n,y01:-d,x11:Y*(v/T-1),y11:$*(v/T-1)}}function hn(){var l=cn,h=yn,I=j(0),D=null,v=gn,A=dn,z=mn,a=null,O=ln(i);function i(){var n,d,u=+l.apply(this,arguments),s=+h.apply(this,arguments),f=v.apply(this,arguments)-un,c=A.apply(this,arguments)-un,B=rn(c-f),t=c>f;if(a||(a=n=O()),s<u&&(d=s,s=u,u=d),!(s>y))a.moveTo(0,0);else if(B>tn-y)a.moveTo(s*F(f),s*q(f)),a.arc(0,0,s,f,c,!t),u>y&&(a.moveTo(u*F(c),u*q(c)),a.arc(0,0,u,c,f,t));else{var m=f,g=c,R=f,T=c,P=B,S=B,Y=z.apply(this,arguments)/2,$=Y>y&&(D?+D.apply(this,arguments):J(u*u+s*s)),w=_(rn(s-u)/2,+I.apply(this,arguments)),p=w,x=w,e,r;if($>y){var C=sn($/u*q(Y)),K=sn($/s*q(Y));(P-=C*2)>y?(C*=t?1:-1,R+=C,T-=C):(P=0,R=T=(f+c)/2),(S-=K*2)>y?(K*=t?1:-1,m+=K,g-=K):(S=0,m=g=(f+c)/2)}var G=s*F(m),H=s*q(m),L=u*F(T),M=u*q(T);if(w>y){var N=s*F(g),Q=s*q(g),V=u*F(R),W=u*q(R),E;if(B<an)if(E=pn(G,H,V,W,N,Q,L,M)){var X=G-E[0],Z=H-E[1],b=N-E[0],k=Q-E[1],nn=1/q(fn((X*b+Z*k)/(J(X*X+Z*Z)*J(b*b+k*k)))/2),en=J(E[0]*E[0]+E[1]*E[1]);p=_(w,(u-en)/(nn-1)),x=_(w,(s-en)/(nn+1))}else p=x=0}S>y?x>y?(e=U(V,W,G,H,s,x,t),r=U(N,Q,L,M,s,x,t),a.moveTo(e.cx+e.x01,e.cy+e.y01),x<w?a.arc(e.cx,e.cy,x,o(e.y01,e.x01),o(r.y01,r.x01),!t):(a.arc(e.cx,e.cy,x,o(e.y01,e.x01),o(e.y11,e.x11),!t),a.arc(0,0,s,o(e.cy+e.y11,e.cx+e.x11),o(r.cy+r.y11,r.cx+r.x11),!t),a.arc(r.cx,r.cy,x,o(r.y11,r.x11),o(r.y01,r.x01),!t))):(a.moveTo(G,H),a.arc(0,0,s,m,g,!t)):a.moveTo(G,H),!(u>y)||!(P>y)?a.lineTo(L,M):p>y?(e=U(L,M,N,Q,u,-p,t),r=U(G,H,V,W,u,-p,t),a.lineTo(e.cx+e.x01,e.cy+e.y01),p<w?a.arc(e.cx,e.cy,p,o(e.y01,e.x01),o(r.y01,r.x01),!t):(a.arc(e.cx,e.cy,p,o(e.y01,e.x01),o(e.y11,e.x11),!t),a.arc(0,0,u,o(e.cy+e.y11,e.cx+e.x11),o(r.cy+r.y11,r.cx+r.x11),t),a.arc(r.cx,r.cy,p,o(r.y11,r.x11),o(r.y01,r.x01),!t))):a.arc(0,0,u,T,R,t)}if(a.closePath(),n)return a=null,n+""||null}return i.centroid=function(){var n=(+l.apply(this,arguments)+ +h.apply(this,arguments))/2,d=(+v.apply(this,arguments)+ +A.apply(this,arguments))/2-an/2;return[F(d)*n,q(d)*n]},i.innerRadius=function(n){return arguments.length?(l=typeof n=="function"?n:j(+n),i):l},i.outerRadius=function(n){return arguments.length?(h=typeof n=="function"?n:j(+n),i):h},i.cornerRadius=function(n){return arguments.length?(I=typeof n=="function"?n:j(+n),i):I},i.padRadius=function(n){return arguments.length?(D=n==null?null:typeof n=="function"?n:j(+n),i):D},i.startAngle=function(n){return arguments.length?(v=typeof n=="function"?n:j(+n),i):v},i.endAngle=function(n){return arguments.length?(A=typeof n=="function"?n:j(+n),i):A},i.padAngle=function(n){return arguments.length?(z=typeof n=="function"?n:j(+n),i):z},i.context=function(n){return arguments.length?(a=n??null,i):a},i}export{hn as d};