smashspace 0.1.1 → 0.1.3

package/README.md

@@ -28,9 +28,31 @@ The token is delivered to a local loopback port and saved to
 `~/.config/smash/credentials.json`. The same credential is used by the MCP
 server below. (Headless? use `smash login --token <PAT>`.)
 
+## Onboard a project for agents: `smash init`
+
+Run once per repo to scaffold everything agents (Claude Code / Codex) need to
+operate SmashSpace as the task backbone — no manual copying:
+
+```bash
+smash init --board-id b_xxxxxxxx
+```
+
+It writes (and is safe to re-run — existing config is kept unless `--force`):
+
+- `.claude/skills/smash/SKILL.md` + `.codex/skills/smash/SKILL.md` — the
+  SmashSpace Operator playbook (CLI/MCP usage + Inbox→Todo→Doing→Review→Done
+  workflow + safety rules). Always refreshed to the installed CLI version.
+- `.smashspace.json` — pins the instance + board.
+- `.mcp.json` — wires the `smashspace` MCP server (merged, other servers kept).
+
+Flags: `--skills-only` (just the operator skill), `--no-mcp`, `--force`,
+`--board-id <id>`. Then `smash login` once on the machine and the agents are
+ready.
+
 ## Project config: `.smashspace.json`
 
-Drop this at your repo root so `smash` knows which board to operate on:
+`smash init` writes this for you; drop it at your repo root manually if you
+prefer, so `smash` knows which board to operate on:
 
 ```json
 {
@@ -45,6 +67,7 @@ Drop this at your repo root so `smash` knows which board to operate on:
 ## Everyday commands
 
 ```bash
+smash status                     # what context is this directory in? (see below)
 smash read                       # show the board (lists + cards)
 smash scan --list "やること"      # actionable cards as JSON (for agents)
 smash create "Fix signup bug"    # add a card (to the first list, or --list)
@@ -56,6 +79,28 @@ smash --help                     # full command list (board/list/card/…)
 Pick a board with `-b <label>` (defaults to `main`), or bypass config with
 `--board-id <id>`.
 
+## Multiple repos on one machine
+
+`smash` is **directory-aware**: it walks up from your current directory to the
+nearest `.smashspace.json`, so each repo operates on its own instance and board
+automatically — no global switch to flip.
+
+```bash
+smash status        # config file, instance, board, and signed-in account for CWD
+```
+
+```text
+config    .smashspace.json
+base_url  https://smashspace.app  (.smashspace.json)
+board     main → b_xxxxxxxx
+account   <userId>  ✓ token ok (23 boards)  [file]
+```
+
+Run it whenever you're unsure which repo/board a command will hit. Add
+`--no-check` to skip the network round-trip, or `--json` for scripts. The login
+token itself is stored once per instance in `~/.config/smash/credentials.json`
+and shared across repos that point at the same `base_url`.
+
 > `smash space …` is an alias of `smash board …`, and the HTTP API mirrors
 > `/api/boards` at `/api/spaces`. In `.smashspace.json`, `space_id` / `spaces`
 > also work as aliases for `board_id` / `boards`.

package/dist/smash.mjs

@@ -3392,9 +3392,10 @@ var {
 import { spawn } from "node:child_process";
 import { createServer } from "node:http";
 import { randomBytes } from "node:crypto";
-import { readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
+import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
 import { platform as platform2 } from "node:os";
 import { createInterface } from "node:readline/promises";
+import { relative, join as join3, dirname as dirname3 } from "node:path";
 import { stdin, stdout } from "node:process";
 
 // ../../shared/board-registry.ts
@@ -3571,6 +3572,219 @@ function resolveBoardEntry(config, label) {
   return entry;
 }
 
+// ../../cli/templates.ts
+var SMASH_SKILL_MD = `---
+name: smash
+description: Operate SmashSpace task boards from the terminal and MCP. Use when the user asks for /smash list, /smash inbox, /smash todo-dig, /smash todo-dev, /smash review, task-board triage, card development, card review, or moving SmashSpace cards between Inbox/Todo/Doing/Review/Done.
+---
+
+# SmashSpace Operator
+
+Use this skill to run repeatable workflows against a SmashSpace task board.
+
+SmashSpace is a Cloudflare-native Kanban where people work in the UI and AI
+agents work through the CLI, MCP, and HTTP API on the **same** data.
+Product: <https://smashspace.app>.
+
+## How to reach the board
+
+Operate through the **\`smashspace-mcp\` MCP tools** when available; otherwise fall
+back to the **\`smash\` CLI**. Do **not** hit the HTTP API with \`curl\` or a raw
+browser \u2014 the CLI and MCP are the supported surfaces and they resolve auth and
+the target board for you.
+
+- CLI install: \`npm i -g smashspace\` (then \`smash --help\`)
+- MCP server: \`smashspace-mcp\` (exposes \`smash_*\` tools, same token as the CLI)
+- Sign in once per machine: \`smash login\` (browser approval; token saved to
+  \`~/.config/smash/credentials.json\` and reused by MCP)
+
+### Which board am I on?
+
+\`smash\` is **directory-aware**: it walks up from the current directory to the
+nearest \`.smashspace.json\`. **Always confirm context before acting:**
+
+\`\`\`bash
+smash status          # config file, instance, board, signed-in account
+\`\`\`
+
+Pick a board with \`-b <label>\` (defaults to \`main\`), or bypass config with
+\`--board-id <id>\`. Canonical lists on a task board: \`Inbox\`, \`Todo\`, \`Doing\`,
+\`Review\`, \`Done\`.
+
+## Safety Rules
+
+- Never move a card to \`Done\` without verification.
+- This workflow uses \`Done\` \u2014 there is no separate "Complete" state.
+- Before development, inspect the **full** card: title, description, checklist,
+  labels, comments, images/attachments, artifacts, external refs, assignees,
+  custom data, and \`agent_meta\`.
+- Before changing a card, leave a comment that explains the plan.
+- Preserve user changes in the repo. Do not revert unrelated dirty files.
+- Scope remote writes to the resolved board (\`smash status\` to confirm).
+- If an operation can affect production data beyond the task board, ask first.
+
+## Command vocabulary
+
+MCP-first; the CLI equivalents are shown so the workflow is reproducible.
+
+\`\`\`bash
+smash status                     # resolved config / instance / board / account
+smash read                       # show the board (lists + cards)
+smash scan --list "Todo"         # actionable cards as JSON (best for agents)
+smash create "Fix signup bug"    # add a card to the resolved board (--list to target)
+smash move <cardId> "Review"     # move a card to a list by name
+smash archive <cardId>           # archive (soft-delete) a card
+
+smash card show <cardId>                       # full card detail before acting
+smash card update <cardId> --title/--desc ...  # edit fields
+smash comment add <cardId> "plan / progress"   # leave a comment
+smash checklist add <cardId> "step"            # checklist items
+smash agent-meta set <cardId> --data '{...}'   # structured agent state (see below)
+smash artifact create <cardId> --kind markdown --name "Report" --content-md-file ./r.md
+\`\`\`
+
+Use \`smash <group> --help\` for the full surface (\`board\`/\`list\`/\`card\`/
+\`comment\`/\`checklist\`/\`label\`/\`artifact\`/\`attachment\`/\`agent-meta\`/
+\`external-refs\`/\`assignees\`).
+
+## List matching
+
+Use exact canonical names when present. For Todo-like selection, match
+case-insensitively and semantically: \`Todo\`, \`To Do\`, \`\u3084\u308B\u3053\u3068\`, \`\u3084\u308B\`,
+\`\u30BF\u30B9\u30AF\`, \`Backlog\`, \`Next\`, \`Ready\`, \`Planned\`. Exclude \`Doing\`, \`Review\`,
+\`Done\`, and archive-like lists unless the user explicitly asks.
+
+## \`agent_meta\` convention
+
+Keep the card's agent state current while you work:
+
+\`\`\`json
+{
+  "primary_agent": "claude-code",   // or "codex"
+  "status": "working",              // working | waiting_review | done
+  "turn": "agent",                  // agent | human
+  "current_step": "concise phase",
+  "progress": 0.4                   // realistic partial value
+}
+\`\`\`
+
+Set \`status: "done"\` only after verification passes.
+
+## Command: /smash list
+
+Show the current board state before choosing work. Do **not** mutate.
+
+1. Read the resolved board (\`smash read\`, or \`smash scan\` for JSON).
+2. Report board title, board ID, each list (name, ID, card count), and active
+   card titles, kept compact.
+
+Infer options from wording: \`brief\` (names + counts), \`full\` (all cards incl.
+Done), \`todo\` / \`review\` / \`inbox\` (that list only), \`ids\` (include IDs).
+
+## Command: /smash inbox
+
+Research the board and create actionable improvement cards in \`Inbox\`.
+
+1. Read the current board to avoid duplicates.
+2. Generate concrete ideas from multiple perspectives (entrepreneur, UI/UX,
+   engineer, AI specialist).
+3. For each, create one \`Inbox\` card with a specific title, a detailed
+   description (user value, expected behavior, acceptance criteria), and an
+   optional checklist. Add a short comment naming the perspective and rationale.
+
+Quality bar: titles must be concrete and implementable; no vague cards like
+"Improve UI"; avoid duplicating existing cards.
+
+## Command: /smash todo-dig
+
+Deeply analyze Todo-like cards and prepare them for implementation.
+
+1. Find Todo-like lists (see list matching).
+2. Inspect all card data (\`smash card show <cardId>\`).
+3. Comment the implementation approach, likely files/modules, risks, unknowns,
+   and validation plan.
+4. Update \`agent_meta\` (\`status: working\`, \`turn: agent\`, \`progress: ~0.2\`).
+5. Create/update a checklist with implementation and verification steps.
+6. Do not move cards unless asked.
+
+Run cards in parallel only when implementation areas do not overlap.
+
+## Command: /smash todo-dev
+
+Implement Todo-like cards end to end.
+
+1. Find Todo-like lists; inspect the full card.
+2. Comment the implementation approach **before editing code**.
+3. Move the card to \`Doing\` (\`smash move <cardId> "Doing"\`).
+4. Update \`agent_meta\` (\`status: working\`, \`progress\` starting near \`0.1\`).
+5. Implement the change in the repo.
+6. Run appropriate checks: \`npm run build\`; unit/API/contract tests when
+   relevant; a dev-browser/UI check for UI changes.
+7. Update checklist items as completed.
+8. Add a completion comment with changed files and verification results.
+9. Move to \`Review\` \u2014 **not** \`Done\` \u2014 unless /smash review has already verified.
+
+Use subagents only for independent work with disjoint file ownership.
+
+## Command: /smash review
+
+Verify \`Review\` cards and move verified work to \`Done\`.
+
+1. Inspect the card; understand what must be verified.
+2. Choose verification: UI change \u2192 run the app/dev-browser; logic/API change \u2192
+   unit/integration/API tests; broad change \u2192 \`npm run build\` + targeted tests.
+3. Inspect screenshots or test output.
+4. On pass: comment the verification command/result, move \`Review\` \u2192 \`Done\`, set
+   \`agent_meta.status: done\`.
+5. On fail: keep in \`Review\` or move back to \`Doing\`, comment the failure and the
+   next action.
+
+## Fallbacks
+
+- Prefer \`smashspace-mcp\` MCP tools. If unavailable, use the \`smash\` CLI.
+- If the CLI is not installed: \`npm i -g smashspace\`, then \`smash login\`.
+- If a board returns "Sign-in required": run \`smash login\`, or set \`SMASH_TOKEN\`
+  for a headless/CI agent.
+
+## Required Final Report
+
+At the end of any /smash workflow, report:
+
+- board and list(s) touched
+- cards created, moved, or updated
+- comments / checklists / custom data / \`agent_meta\` changes
+- verification commands and results
+- any cards left blocked or unverified
+`;
+var OPENAI_AGENT_YAML = `interface:
+  display_name: "SmashSpace Operator"
+  short_description: "Run SmashSpace task-board workflows."
+  default_prompt: "Use $smash to run /smash review on the resolved board."
+`;
+function smashspaceJson(baseUrl, boardId) {
+  return `${JSON.stringify(
+    {
+      base_url: baseUrl,
+      default: "main",
+      spaces: {
+        main: { space_id: boardId, comment: "Team task board" }
+      }
+    },
+    null,
+    2
+  )}
+`;
+}
+function mcpServerEntry(baseUrl, boardId) {
+  return {
+    command: "smashspace-mcp",
+    env: {
+      SMASH_BASE_URL: baseUrl,
+      SMASH_SPACES: `${baseUrl.replace(/\/+$/, "")}/space/${boardId}`
+    }
+  };
+}
+
 // ../../cli/index.ts
 var DEFAULT_BASE_URL = process.env.SMASH_BASE_URL ?? "https://smashspace.app";
 var program2 = new Command();
@@ -4389,6 +4603,168 @@ program2.command("whoami").description("Show the user identified by the saved/en
     [`\u2713 ${me.userId} (${me.boardCount} boards) on ${baseUrl}`]
   );
 });
+program2.command("status").aliases(["context", "where"]).description(
+  "Show the context resolved from the current directory: config file, instance, board, and signed-in account"
+).option("--no-check", "Skip the live token check (offline)").action(async (opts) => {
+  const loaded = loadProjectConfig();
+  const baseUrl = resolveBaseUrl(loaded);
+  const baseSource = program2.getOptionValueSource("baseUrl") === "cli" ? "--base-url" : loaded?.config.base_url ? CONFIG_FILENAME : process.env.SMASH_BASE_URL ? "env:SMASH_BASE_URL" : "default";
+  let board = null;
+  let boardError = null;
+  if (loaded) {
+    try {
+      const entry = resolveBoardEntry(loaded.config, void 0);
+      board = { label: entry.label, boardId: entry.board_id };
+    } catch (e) {
+      boardError = e instanceof Error ? e.message : String(e);
+    }
+  }
+  const cred = await findCredential(baseUrl);
+  const token = await resolveToken(baseUrl);
+  const tokenSource = process.env.SMASH_TOKEN ? "env:SMASH_TOKEN" : cred ? "file" : null;
+  let live = null;
+  if (token && opts.check) {
+    try {
+      const ctrl = new AbortController();
+      const timer = setTimeout(() => ctrl.abort(), 5e3);
+      const res = await fetch(new URL("/api/usage/me", baseUrl), {
+        headers: { Authorization: `Bearer ${token}` },
+        signal: ctrl.signal
+      }).finally(() => clearTimeout(timer));
+      if (res.ok) {
+        const me = await res.json();
+        live = { ok: true, userId: me.userId, boardCount: me.boardCount };
+      } else {
+        live = { ok: false, error: `${res.status} ${res.statusText}` };
+      }
+    } catch (e) {
+      live = { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+  }
+  const account = (live?.ok ? live.userId : void 0) ?? cred?.userId ?? null;
+  if (getOpts().json) {
+    show({
+      cwd: process.cwd(),
+      config: loaded?.path ?? null,
+      baseUrl,
+      baseUrlSource: baseSource,
+      board,
+      boardError,
+      account,
+      tokenPresent: !!token,
+      tokenSource,
+      live,
+      boards: loaded?.config.boards.map((b) => ({
+        label: b.label,
+        boardId: b.board_id
+      })) ?? []
+    });
+    return;
+  }
+  const cfgDisplay = loaded ? relative(process.cwd(), loaded.path) || loaded.path : `(none \u2014 searched up from ${process.cwd()})`;
+  const lines = [
+    `config    ${cfgDisplay}`,
+    `base_url  ${baseUrl}  (${baseSource})`
+  ];
+  if (board)
+    lines.push(`board     ${board.label} \u2192 ${board.boardId}`);
+  else if (boardError)
+    lines.push(`board     (unresolved: ${boardError})`);
+  else
+    lines.push(`board     (no ${CONFIG_FILENAME}; pass --board-id)`);
+  if (!token) {
+    lines.push(`account   \u2717 not signed in \u2014 run 'smash login'`);
+  } else if (live) {
+    lines.push(
+      live.ok ? `account   ${live.userId}  \u2713 token ok (${live.boardCount} boards)  [${tokenSource}]` : `account   ${account ?? "?"}  \u2717 token check failed: ${live.error}  [${tokenSource}]`
+    );
+  } else {
+    lines.push(
+      `account   ${account ?? "(token set)"}  [${tokenSource}] (not checked)`
+    );
+  }
+  if (loaded && loaded.config.boards.length > 1) {
+    const active = board?.label ?? loaded.config.default ?? "main";
+    lines.push("", "boards:");
+    for (const b of loaded.config.boards) {
+      lines.push(`  ${b.label === active ? "*" : " "} ${b.label} \u2192 ${b.board_id}`);
+    }
+  }
+  show(void 0, lines);
+});
+program2.command("init").description(
+  "Scaffold this project for agents: operator skill + .smashspace.json + .mcp.json"
+).option("--board-id <id>", "Board/space id to pin in .smashspace.json / .mcp.json").option("--skills-only", "Only (re)install the operator skill files").option("--no-mcp", "Skip writing .mcp.json").option("-f, --force", "Overwrite .smashspace.json / .mcp.json if they exist").action(
+  async (opts) => {
+    const cwd = process.cwd();
+    const actions = [];
+    const abs = (rel) => join3(cwd, rel);
+    const put = async (rel, content) => {
+      const p = abs(rel);
+      await mkdir2(dirname3(p), { recursive: true });
+      await writeFile2(p, content, "utf8");
+    };
+    const exists = async (rel) => {
+      try {
+        await readFile2(abs(rel));
+        return true;
+      } catch {
+        return false;
+      }
+    };
+    await put(".claude/skills/smash/SKILL.md", SMASH_SKILL_MD);
+    await put(".codex/skills/smash/SKILL.md", SMASH_SKILL_MD);
+    await put(".codex/skills/smash/agents/openai.yaml", OPENAI_AGENT_YAML);
+    actions.push(
+      "\u2713 operator skill \u2192 .claude/skills/smash/ + .codex/skills/smash/"
+    );
+    const baseUrl = resolveBaseUrl();
+    const boardId = opts.boardId ?? "b_xxxxxxxx";
+    const placeholder = boardId === "b_xxxxxxxx";
+    if (!opts.skillsOnly) {
+      if (await exists(CONFIG_FILENAME) && !opts.force) {
+        actions.push(`\u2022 ${CONFIG_FILENAME} exists \u2014 kept (use --force)`);
+      } else {
+        await put(CONFIG_FILENAME, smashspaceJson(baseUrl, boardId));
+        actions.push(
+          `\u2713 ${CONFIG_FILENAME}${placeholder ? " (placeholder space_id \u2014 edit it)" : ` (${boardId})`}`
+        );
+      }
+      if (opts.mcp !== false) {
+        let mcp = { mcpServers: {} };
+        if (await exists(".mcp.json")) {
+          try {
+            mcp = JSON.parse(await readFile2(abs(".mcp.json"), "utf8"));
+          } catch {
+          }
+          if (!mcp.mcpServers)
+            mcp.mcpServers = {};
+        }
+        const servers = mcp.mcpServers;
+        if (servers.smashspace && !opts.force) {
+          actions.push("\u2022 .mcp.json already wires 'smashspace' \u2014 kept (use --force)");
+        } else {
+          servers.smashspace = mcpServerEntry(baseUrl, boardId);
+          await put(".mcp.json", `${JSON.stringify(mcp, null, 2)}
+`);
+          actions.push("\u2713 .mcp.json \u2014 smashspace MCP server");
+        }
+      }
+    }
+    const next = ["", "Next:", "  1. smash login              # sign in (browser approval)"];
+    if (!opts.skillsOnly && placeholder) {
+      next.push("  2. edit .smashspace.json    # set your real space_id (`smash board list` to find it)");
+    }
+    next.push(
+      "  \u2192 Claude Code / Codex pick up .claude|.codex/skills/smash automatically"
+    );
+    if (getOpts().json) {
+      show({ cwd, actions, baseUrl, boardId: placeholder ? null : boardId });
+      return;
+    }
+    show(void 0, [...actions, ...next]);
+  }
+);
 program2.command("create <title>").description(`Create a card on the resolved board (${CONFIG_FILENAME}, default "main")`).option("-b, --board <label>", "board label from config").option("--board-id <id>", "explicit board id (bypass config)").option("-l, --list <name>", "target list name (default: first list)").option("-d, --desc <text>", "card description (Markdown)").action(async (title, opts) => {
   const ctx = resolveContext(opts);
   const detail = await fetchBoard(ctx.boardId, ctx.baseUrl);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smashspace",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "SmashSpace CLI + MCP — operate SmashSpace boards from your terminal, Claude Code, Cursor, and Codex.",
   "type": "module",
   "bin": {