@hackspot/cli 0.1.1

package/README.md

@@ -0,0 +1,87 @@
+# hackspot
+
+Turn a [hackspot.dev](https://hackspot.dev) idea into a project and hand it to your
+AI coding agent. The website already generated the build playbook (pitch, why it
+wins, scoped MVP, demo script) — this CLI fetches it by id, scaffolds the files an
+agent reads, and launches that agent on the build.
+
+It is **not** an LLM of its own: it drives your existing tooling (Claude Code,
+Codex, opencode, or any command you pass).
+
+Published as [`@hackspot/cli`](https://www.npmjs.com/package/@hackspot/cli); once
+installed the command on your `PATH` is `hackspot`. Install instructions:
+<https://docs.hackspot.dev/docs/install>.
+
+## 1. `login` — connect this machine
+
+A device-code flow: the CLI shows a 6-digit code, you enter it on the website while
+signed in, and the CLI is handed a token saved to `~/.hackspot/config.json`.
+
+```bash
+npx @hackspot/cli login
+# → shows a 6-digit code + opens https://hackspot.dev/app/cli
+#   enter the code there; the CLI saves your token
+```
+
+Flags: `--dev` (target `http://localhost:3000`), `--base-url <url>`, `--no-open`.
+
+## 2. `list` — see the ideas you can build
+
+Lists your saved ideas (newest first) with the id each `build` takes:
+
+```bash
+npx @hackspot/cli list
+#   42  🚀 Pitch Coach  (fit 87)
+#       Real-time feedback on your demo delivery
+#   …
+npx @hackspot/cli list --json   # raw list, for scripting
+```
+
+Flags: `--json`, `--dev` / `--base-url <url>`.
+
+## 3. `build` — scaffold an idea + launch your agent
+
+Grab an idea's id from `hackspot list` (or its URL on the site, `/app/ideas/<id>`).
+
+```bash
+npx @hackspot/cli build 42            # scaffolds ./<idea-slug>/ and launches your agent
+npx @hackspot/cli build 42 ./my-app   # choose the directory
+```
+
+It writes three files into the target directory:
+
+| File            | Purpose                                                        |
+| --------------- | ------------------------------------------------------------- |
+| `AGENTS.md`     | The playbook as the cross-tool context file agents auto-read. |
+| `PROMPT.md`     | The bootstrap instruction (paste into any agent).             |
+| `hackspot.json` | The structured idea (id, pitch, MVP, demo, event brief).      |
+
+Then it picks an agent and launches it in that directory, inheriting your terminal:
+
+- `--agent claude` → `claude "<bootstrap prompt>"`
+- `--agent codex` → `codex "<bootstrap prompt>"`
+- `--agent opencode` → `opencode run "<bootstrap prompt>"`
+- `--agent "<command>"` → any command; include `{prompt}` to substitute the bootstrap
+  prompt, otherwise it's appended as the final argument.
+
+With no `--agent`, it auto-detects the first installed of `claude` → `codex` →
+`opencode`.
+
+Other flags: `--no-launch` (scaffold only, print the command), `--force` (allow a
+non-empty directory), `--dev` / `--base-url <url>`.
+
+## `whoami` / `logout`
+
+```bash
+npx @hackspot/cli whoami    # show the linked account (validates the token)
+npx @hackspot/cli logout    # clear the local token
+```
+
+## Env
+
+| Variable             | Notes                                                       |
+| -------------------- | ----------------------------------------------------------- |
+| `HACKSPOT_TOKEN`     | Overrides the saved token (CI / ephemeral shells).          |
+| `HACKSPOT_BASE_URL`  | Default base URL; overridden by `--base-url` / `--dev`.     |
+
+Tokens last 90 days and are revocable from the website.

package/dist/index.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+import{spawnSync as P}from"node:child_process";import{existsSync as c,mkdirSync as p,readdirSync as g,writeFileSync as C}from"node:fs";import{join as W}from"node:path";import{parseArgs as d}from"node:util";import{chmodSync as S,mkdirSync as U,readFileSync as h,writeFileSync as y}from"node:fs";import{homedir as b}from"node:os";import{dirname as f,join as m}from"node:path";var v="https://hackspot.dev",u="http://localhost:3000";function x(){return m(b(),".hackspot","config.json")}function j(){try{return JSON.parse(h(x(),"utf8"))}catch{return{}}}function G(z){let J=x();U(f(J),{recursive:!0,mode:448});let Q={...j(),...z};y(J,`${JSON.stringify(Q,null,2)}
+`,{mode:384});try{S(J,384)}catch{}}function N(){return process.env.HACKSPOT_TOKEN||j().token||void 0}function q(z){return(z["base-url"]??(z.dev?u:void 0)??process.env.HACKSPOT_BASE_URL??j().baseUrl??v).replace(/\/+$/,"")}var l=`hackspot build — scaffold an idea and hand it to your AI agent
+
+Usage:
+  hackspot build <idea-id> [dir] [options]
+
+Options:
+  --agent <name|cmd>  claude | codex | opencode, or a custom command. A custom
+                      command may contain {prompt} (substituted) — otherwise the
+                      bootstrap prompt is appended as a final argument.
+  --no-launch         Scaffold files only; print the command instead of running it
+  --force             Allow scaffolding into a non-empty directory
+  --base-url <url>    App base URL (default: production, https://hackspot.dev)
+  --dev               Target local dev (http://localhost:3000)
+  -h, --help          Show this help`,B={claude:{cmd:"claude",args:(z)=>[z]},codex:{cmd:"codex",args:(z)=>[z]},opencode:{cmd:"opencode",args:(z)=>["run",z]}};function t(z){return z.title.toLowerCase().replace(/[^a-z0-9]+/g,"-").replace(/^-+|-+$/g,"")||`idea-${z.id}`}function o(z){let J=process.platform==="win32"?"where":"which";return P(J,[z],{stdio:"ignore",shell:!0}).status===0}function n(z,J){if(z){let Q=B[z];if(Q)return{argv:[Q.cmd,...Q.args(J)],label:z};let X=z.split(/\s+/);return{argv:z.includes("{prompt}")?X.map(($)=>$.replace("{prompt}",J)):[...X,J],label:z}}for(let[Q,X]of Object.entries(B))if(o(X.cmd))return{argv:[X.cmd,...X.args(J)],label:Q};return null}function T(z){return/[\s"]/.test(z)?`"${z.replace(/"/g,"\\\"")}"`:z}async function I(z){let{values:J,positionals:Q}=d({args:z,allowPositionals:!0,options:{agent:{type:"string"},"no-launch":{type:"boolean"},force:{type:"boolean"},"base-url":{type:"string"},dev:{type:"boolean"},help:{type:"boolean",short:"h"}}});if(J.help){console.log(l);return}let X=Q[0];if(!X)throw Error("Usage: hackspot build <idea-id> [dir]");let Z=N();if(!Z)throw Error("Not logged in. Run `hackspot login` first.");let $=q(J),M=await fetch(`${$}/api/cli/ideas/${encodeURIComponent(X)}`,{headers:{authorization:`Bearer ${Z}`}});if(M.status===401)throw Error("Token invalid or expired. Run `hackspot login` again.");if(M.status===404)throw Error(`Idea ${X} not found (or not yours).`);if(!M.ok){let H=`Couldn't fetch idea ${X} (${M.status})`;try{let _=await M.json();if(_.error)H+=`: ${_.error}`}catch{}throw Error(H)}let K=await M.json(),Y=Q[1]??W(process.cwd(),t(K.json));if(p(Y,{recursive:!0}),!J.force&&c(Y)&&g(Y).length>0)throw Error(`${Y} is not empty. Pass --force to scaffold into it anyway.`);C(W(Y,"AGENTS.md"),K.agentsMarkdown),C(W(Y,"PROMPT.md"),`${K.bootstrapPrompt}
+`),C(W(Y,"hackspot.json"),`${JSON.stringify(K.json,null,2)}
+`);let D=K.json.emoji?`${K.json.emoji} ${K.json.title}`:K.json.title;console.log(`
+  Scaffolded "${D}" into ${Y}`),console.log(`    AGENTS.md  PROMPT.md  hackspot.json
+`);let V=n(J.agent,K.bootstrapPrompt);if(J["no-launch"]||!V){if(!V&&!J["no-launch"])console.log(`  No agent found (looked for claude, codex, opencode). Install one, or run
+`+`  your agent in that directory — it'll read AGENTS.md. PROMPT.md has the prompt.
+`);else if(V)console.log(`  To start your agent, run:
+`),console.log(`    cd ${T(Y)} && ${V.argv.map(T).join(" ")}
+`);return}console.log(`  Launching ${V.label} in ${Y} …
+`);let[k,...F]=V.argv,O=P(k,F,{cwd:Y,stdio:"inherit",shell:!0});if(O.error)throw Error(`Failed to launch ${V.label}: ${O.error.message}`);if(typeof O.status==="number"&&O.status!==0)process.exitCode=O.status}import{parseArgs as i}from"node:util";var s=`hackspot list — list the ideas you can build
+
+Usage:
+  hackspot list [options]
+
+Options:
+  --json              Print the raw idea list as JSON
+  --base-url <url>    App base URL (default: production, https://hackspot.dev)
+  --dev               Target local dev (http://localhost:3000)
+  -h, --help          Show this help`;async function A(z){let{values:J}=i({args:z,options:{json:{type:"boolean"},"base-url":{type:"string"},dev:{type:"boolean"},help:{type:"boolean",short:"h"}}});if(J.help){console.log(s);return}let Q=N();if(!Q)throw Error("Not logged in. Run `hackspot login` first.");let X=q(J),Z=await fetch(`${X}/api/cli/ideas`,{headers:{authorization:`Bearer ${Q}`}});if(Z.status===401)throw Error("Token invalid or expired. Run `hackspot login` again.");if(!Z.ok){let K=`Couldn't list ideas (${Z.status})`;try{let Y=await Z.json();if(Y.error)K+=`: ${Y.error}`}catch{}throw Error(K)}let{ideas:$}=await Z.json();if(J.json){console.log(JSON.stringify($,null,2));return}if($.length===0){console.log(`
+  No saved ideas yet. Generate and save some at https://hackspot.dev, then
+  run \`hackspot list\` again.
+`);return}let M=Math.max(...$.map((K)=>String(K.id).length));console.log(`
+  ${$.length} idea${$.length===1?"":"s"}:
+`);for(let K of $){let Y=String(K.id).padStart(M),D=K.emoji?`${K.emoji} ${K.title}`:K.title;if(console.log(`  ${Y}  ${D}  (fit ${K.score})`),K.tagline)console.log(`  ${" ".repeat(M)}  ${K.tagline}`)}console.log("\n  Build one with `hackspot build <id>`.\n")}import{spawn as a}from"node:child_process";import{parseArgs as r}from"node:util";var e=`hackspot login — connect this machine to your hackspot.dev account
+
+Options:
+  --base-url <url>    App base URL (default: production, https://hackspot.dev)
+  --dev               Target local dev (http://localhost:3000)
+  --no-open           Don't try to open the browser automatically
+  -h, --help          Show this help`;function zz(z){return new Promise((J)=>setTimeout(J,z))}function Jz(z){let J=process.platform==="win32"?"start":process.platform==="darwin"?"open":"xdg-open";try{a(J,[z],{stdio:"ignore",shell:!0,detached:!0}).unref()}catch{}}async function E(z){let{values:J}=r({args:z,options:{"base-url":{type:"string"},dev:{type:"boolean"},"no-open":{type:"boolean"},help:{type:"boolean",short:"h"}}});if(J.help){console.log(e);return}let Q=q(J),X=await fetch(`${Q}/api/cli/auth/start`,{method:"POST"});if(!X.ok)throw Error(`Couldn't start login (${X.status}). Is ${Q} reachable?`);let{code:Z,deviceSecret:$,verifyUrl:M,expiresInSec:K}=await X.json();if(console.log(`
+  Your code:  ${Z}
+`),console.log(`  Open ${M} and enter it to connect.`),console.log(`  (Expires in ${Math.round(K/60)} minutes.)
+`),!J["no-open"])Jz(M);let Y=Date.now()+K*1000;process.stderr.write("  Waiting for approval");while(Date.now()<Y){await zz(3000),process.stderr.write(".");let D=await fetch(`${Q}/api/cli/auth/poll`,{method:"POST",headers:{"content-type":"application/json"},body:JSON.stringify({deviceSecret:$})});if(D.status===410)throw process.stderr.write(`
+`),Error("This code expired before it was approved. Run `hackspot login` again.");if(!D.ok)continue;let V=await D.json();if(V.status==="approved"&&V.token){G({token:V.token,baseUrl:Q}),process.stderr.write(`
+`),console.log("  Connected. You can now run `hackspot build <idea-id>`.\n");return}}throw process.stderr.write(`
+`),Error("Timed out waiting for approval. Run `hackspot login` again.")}import{parseArgs as Kz}from"node:util";function L(){G({token:void 0}),console.log("Logged out (local token cleared).")}var Qz=`hackspot whoami — show the account this machine is linked to
+
+Options:
+  --base-url <url>    App base URL (default: production, https://hackspot.dev)
+  --dev               Target local dev (http://localhost:3000)
+  -h, --help          Show this help`;async function R(z){let{values:J}=Kz({args:z,options:{"base-url":{type:"string"},dev:{type:"boolean"},help:{type:"boolean",short:"h"}}});if(J.help){console.log(Qz);return}let Q=N();if(!Q){console.log("Not logged in. Run `hackspot login`."),process.exitCode=1;return}let X=q(J),Z=await fetch(`${X}/api/cli/me`,{headers:{authorization:`Bearer ${Q}`}});if(!Z.ok){console.log("Logged in, but the token is no longer valid. Run `hackspot login` again."),process.exitCode=1;return}let{userId:$}=await Z.json();console.log(`Logged in as ${$} on ${X}.`)}var w=`hackspot — scaffold a hackspot.dev idea for your AI coding agent
+
+Usage:
+  hackspot login                     Connect this machine to your account
+  hackspot list                      List the ideas you can build
+  hackspot build <idea-id> [dir]     Scaffold an idea and launch your agent
+  hackspot whoami                    Show the linked account
+  hackspot logout                    Clear the local token
+
+Run 'hackspot <command> --help' for command-specific options.`;async function Xz(){let[z,...J]=process.argv.slice(2);switch(z){case"login":await E(J);return;case"list":await A(J);return;case"build":await I(J);return;case"whoami":await R(J);return;case"logout":L();return;case"-h":case"--help":case void 0:console.log(w);return;default:console.error(`Unknown command: ${z}
+`),console.error(w),process.exitCode=1}}Xz().catch((z)=>{console.error(z instanceof Error?z.message:String(z)),process.exitCode=1});

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@hackspot/cli",
+  "version": "0.1.1",
+  "type": "module",
+  "description": "Scaffold a hackspot.dev idea into a project and hand it to your AI coding agent.",
+  "keywords": ["hackspot", "hackathon", "cli", "ai", "scaffold", "claude", "codex"],
+  "homepage": "https://docs.hackspot.dev/docs/install",
+  "license": "MIT",
+  "bin": {
+    "hackspot": "./dist/index.js"
+  },
+  "files": ["dist", "README.md"],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "login": "bun run src/index.ts login",
+    "login:dev": "bun run src/index.ts login --dev",
+    "cli:build": "bun run src/index.ts build",
+    "bundle": "bun build src/index.ts --target=node --outfile dist/index.js --minify",
+    "prepublishOnly": "bun run bundle"
+  }
+}