mulmoterminal 6.6.0 → 6.8.0

package/README.md

@@ -303,7 +303,8 @@ with `tmux` installed the agent sessions survive and come back under **Settings
 survived a restart**; without it they end with the server.
 
 **First-run setup (optional).** `npx mulmoterminal@latest init` checks your environment (Node ≥ 22.12
-and every CLI in the table above), seeds the launcher's **directory
+and every CLI in the table above), says how to update when Node is behind the latest LTS of its line
+or Claude Code is behind its `stable` release, seeds the launcher's **directory
 presets** from the projects in your Claude Code history, and writes `~/.mulmoterminal/config.json`.
 It's **idempotent** — re-run it any time to refresh the presets; it overwrites the managed parts
 and keeps your other settings. When `claude` is installed it can hand off to the
@@ -704,7 +705,7 @@ the `claude` / `codex` sessions themselves.
 | `CLIENT_PORT` | `6856`         | Vite dev-server port (dev only: the URL you open with `yarn dev`). |
 | `CLAUDE_BIN` | `claude`       | The Claude Code binary to spawn. On Windows a bare name is resolved on `PATH` before it reaches the PTY layer (which matches file names exactly): to the `.exe` when there is one, otherwise to the `.cmd` shim an npm-global install leaves, run through `cmd.exe`. |
 | `CLAUDE_CWD` | current dir    | Working directory each `claude` PTY runs in; determines which project's sessions are listed. Via `npx mulmoterminal@latest` it defaults to the directory you ran the command from (override with `--cwd <dir>`, relative allowed); when the server is run directly it falls back to `~/mulmoclaude`. A value read from `.env` must be an absolute path (`~` is not expanded). Running in one of your own project directories does **not** litter it — see the note under the table. |
-| `CLAUDE_PERMISSION_MODE` | `auto` | Permission mode passed to each `claude` spawn. |
+| `CLAUDE_PERMISSION_MODE` | `auto` | Permission mode passed to each `claude` spawn. A Claude Code whose `--help` does not list the mode is not started: the cell says so, and for `auto` says to update Claude Code. |
 | `MT_TITLE_SOURCE` | `transcript` | Where the cell header's AI title comes from. `transcript` reads the title Claude Code writes into its own transcript — no extra process. `headless` restores the old behaviour of summarizing the recent turns with `claude -p`, which costs a model call but follows a session whose topic drifts (Claude's own title is written once and never revised). |
 | `MT_TITLE_MODEL` | `haiku` | Model used for the cell header's AI title. Only read when `MT_TITLE_SOURCE=headless`. Accepts a `--model` alias or a full model id. |
 | `CODEX_BIN`  | `codex`        | The Codex CLI binary to spawn. |
@@ -766,7 +767,7 @@ The Settings modal (the gear button) persists per-user UI choices to `~/.mulmote
 
 ![The Settings modal — a sidebar of grouped sections beside the one being edited](https://raw.githubusercontent.com/receptron/mulmoterminal/main/docs/guide/images/settings-tabs.png)
 
-*Open it from the gear button in the toolbar. The **sidebar** groups the sections — Appearance, Projects, Header & launch, Input, Models & servers, Notifications, Integrations, Sessions, Help — and one is on screen at a time; on a phone the sidebar becomes a picker above the section. Settings is available in **English and Japanese**: it follows your browser's language unless you pick one under **Language** (per browser, like the theme). Only this modal is translated so far. Under the title, a **Version** row shows what is running: the version from the shipped `package.json`, plus a `commit <sha>` chip on a git checkout — there the version is only whatever was last released, so the commit is what identifies the build. When something newer exists, the row is followed by the header badge's update notice, command included. Pick a **theme**, set the **terminal font size**, **font** and **scroll speed** (and whether sending **returns to the latest output**), set a custom **attention sound**, list the repos the cross-repo **PRs & Issues** view should aggregate, add **launch commands** for grid cells, register your own **MCP servers**, and turn on the switches for what this app writes on your behalf — **issue work comments**, the **PR clone footer**, the **closing summary**, the **decision digest**, the **dev worklog** — no need to hand-edit the config file. Four settings stay with their skill because a form would be the wrong tool for them (`keymap`, `themes`, `providers`, `buttons`/`chips`); Settings shows what each is doing now and launches that skill. Note that **theme, font size, scroll speed and the return-to-latest switch are stored per browser** (they're display preferences, so a phone and a desktop keep their own); the rest live in `~/.mulmoterminal/config.json` and are shared by every client.*
+*Open it from the gear button in the toolbar. The **sidebar** groups the sections — Appearance, Projects, Header & launch, Input, Models & servers, Notifications, Integrations, Sessions, Help — and one is on screen at a time; on a phone the sidebar becomes a picker above the section. The interface is available in **English, 日本語, 简体中文, 繁體中文 and 한국어**: it follows your browser's language unless you pick one under **Language** (per browser, like the theme). Translated so far: this modal, the grid's status words, and every button's hover tip and screen-reader label; the rest of the app's words are still English. Under the title, a **Version** row shows what is running: the version from the shipped `package.json`, plus a `commit <sha>` chip on a git checkout — there the version is only whatever was last released, so the commit is what identifies the build. When something newer exists, the row is followed by the header badge's update notice, command included. Pick a **theme**, set the **terminal font size**, **font** and **scroll speed** (and whether sending **returns to the latest output**), set a custom **attention sound**, list the repos the cross-repo **PRs & Issues** view should aggregate, add **launch commands** for grid cells, register your own **MCP servers**, and turn on the switches for what this app writes on your behalf — **issue work comments**, the **PR clone footer**, the **closing summary**, the **decision digest**, the **dev worklog** — no need to hand-edit the config file. Four settings stay with their skill because a form would be the wrong tool for them (`keymap`, `themes`, `providers`, `buttons`/`chips`); Settings shows what each is doing now and launches that skill. Note that **theme, font size, scroll speed and the return-to-latest switch are stored per browser** (they're display preferences, so a phone and a desktop keep their own); the rest live in `~/.mulmoterminal/config.json` and are shared by every client.*
 
 | Field        | Meaning |
 | ------------ | ------- |
@@ -1287,6 +1288,29 @@ server says when it arrives — including any directory you expanded while waiti
 pane has not read before says so (`Loading…`) rather than claiming to be empty, and a read that
 fails shows the error rather than a tree it can no longer vouch for.
 
+**Several files open as tabs, when you ask for them.** A plain click in the tree replaces the file
+in front, as it always has — so someone who never wants a tab never sees one. **Cmd+click** (Ctrl+click
+off macOS) or the row menu's **Open in a new tab** adds a tab, and a strip of tabs appears under the
+header once there are two. Opening a file that already has a tab goes to that tab, from the tree, the
+finder, the search or a clicked terminal path alike. Switching tabs saves the one you leave, exactly as
+opening another file does, so only the front tab can hold unsaved edits; each tab keeps its own place
+(Preview or editor, caret, scroll) and the whole strip is remembered with the rest of the pane. Close a
+tab with its **×**, a middle click, or **Delete** while it has focus; ←/→, Home and End move between them.
+
+**HTML pages and images show in the pane too.** An `.html` file has a **Preview** like a Markdown
+file: the page itself, sandboxed as presentHtml pages are — its scripts run on an opaque origin with
+no fetch/XHR; images and the curated CDN list still load, and so does an image it links beside it,
+while a relative stylesheet or script does not. An `.svg` previews as the picture it draws, and a PNG, JPEG, GIF or WebP opens as the image
+rather than as "not text". A path to any of these clicked in terminal output opens in the pane when
+it is up, so a chart an agent just wrote stays in the grid. They are served only under the workspace
+or a terminal's directory, like every other file the app hands to the browser.
+
+**A link in the Preview opens in the pane.** A link to another file (`./b.md`, `../README.md`) is
+resolved against the document it is in and opens in a new tab — in Preview when it is Markdown — or
+goes to the tab that file already has. A link that climbs above the pane's folder is not opened and
+the pane says so; an external link opens in a new browser tab, and a `#heading` link scrolls the
+document.
+
 The toggle is not the only way in: while a cell is enlarged, **clicking a file path the agent
 printed** opens it here too, rather than in a new tab or full-screen — see
 [Clicking a file path](#clicking-a-file-path).
@@ -1687,7 +1711,7 @@ narrow and tall for one record you are discussing — and each position keeps it
 
 ![Zoom — one agent enlarged, the others as a filmstrip along the bottom](https://raw.githubusercontent.com/receptron/mulmoterminal/main/docs/guide/images/grid-zoom.png)
 
-- **Set a terminal aside** — the moon button in a cell's header **sinks** it: the tile, its
+- **Set a terminal aside** — the bed button (a person asleep) in a cell's header **sinks** it: the tile, its
   filmstrip thumbnail and its cockpit-roster row all fade, and the working dot stops pulsing.
   The session stays **connected and keeps its whole history** — this is what to reach for
   instead of `/clear`-ing a cell you are done with for now, which resets the conversation just

package/bin/check-versions.d.ts

@@ -0,0 +1,7 @@
+export declare const NODE_RELEASES_URL: string;
+export declare const CLAUDE_DIST_TAGS_URL: string;
+export declare function fetchNodeReleases(): Promise<unknown>;
+export declare function fetchClaudeStable(): Promise<string | null>;
+export declare function resolveCommandPath(cmd: string, env?: Record<string, string | undefined>, platform?: string): string | null;
+export declare function readClaudeVersion(binaryPath: string, timeout_ms?: number): Promise<string | null>;
+export declare function checkVersions(options: { claudeBin: string | null }): Promise<{ node: string[]; claude: string[] }>;

package/bin/check-versions.js

@@ -0,0 +1,80 @@
+// The network and process half of `init`'s version check (#2477); the decisions are in
+// bin/version-drift.js. Every probe resolves null on failure — `init` must finish offline.
+import { execFile } from "node:child_process";
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { extensionsFor, namesAPath, realProbe, searchDirectories } from "./has-command.js";
+import { nodeUpgradeGuide } from "./node-install.js";
+import { claudeDrift, claudeDriftLines, claudeUpdateCommands, nodeDrift, nodeDriftLines, parseClaudeVersion } from "./version-drift.js";
+
+export const NODE_RELEASES_URL = "https://nodejs.org/dist/index.json";
+const REGISTRY = (process.env.npm_config_registry || "https://registry.npmjs.org").replace(/\/$/, "");
+export const CLAUDE_DIST_TAGS_URL = `${REGISTRY}/-/package/@anthropic-ai/claude-code/dist-tags`;
+
+const FETCH_TIMEOUT_MS = 4000;
+// `claude --version` starts the whole CLI, which is slower than a fetch on a cold disk.
+const CLAUDE_VERSION_TIMEOUT_MS = 8000;
+
+async function fetchJson(url) {
+  try {
+    const response = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS), headers: { accept: "application/json" } });
+    return response.ok ? await response.json() : null;
+  } catch {
+    return null;
+  }
+}
+
+export const fetchNodeReleases = () => fetchJson(NODE_RELEASES_URL);
+
+export async function fetchClaudeStable() {
+  const distTags = await fetchJson(CLAUDE_DIST_TAGS_URL);
+  return typeof distTags?.stable === "string" ? distTags.stable : null;
+}
+
+/**
+ * Where `cmd` lives, symlinks followed, or null — searched with the start-up gate's own PATH rules
+ * (bin/has-command.js). Only picks the update command, never gates.
+ */
+export function resolveCommandPath(cmd, env = process.env, platform = process.platform) {
+  const join = platform === "win32" ? path.win32.join : path.posix.join;
+  const candidates = namesAPath(cmd) ? [cmd] : searchDirectories(platform, env).flatMap((dir) => extensionsFor(platform).map((ext) => join(dir, cmd + ext)));
+  const found = candidates.find((candidate) => realProbe.isFile(candidate) && (platform === "win32" || realProbe.isExecutable(candidate)));
+  if (found === undefined) return null;
+  try {
+    return realpathSync(found);
+  } catch {
+    return found;
+  }
+}
+
+// Own timer rather than execFile's `timeout`: that one only signals the child and then waits for it
+// to exit, so a `claude` that ignores SIGTERM (or a grandchild holding stdout) would hold `init`.
+export function readClaudeVersion(binaryPath, timeout_ms = CLAUDE_VERSION_TIMEOUT_MS) {
+  return new Promise((resolve) => {
+    const child = execFile(binaryPath, ["--version"], (error, stdout) => {
+      clearTimeout(timer);
+      resolve(error ? null : parseClaudeVersion(stdout));
+    });
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      resolve(null);
+    }, timeout_ms);
+  });
+}
+
+async function claudeLines(claudeBin) {
+  const binaryPath = resolveCommandPath(claudeBin);
+  const [localVersion, stable] = await Promise.all([binaryPath ? readClaudeVersion(binaryPath) : null, fetchClaudeStable()]);
+  return claudeDriftLines(claudeDrift(localVersion, stable), localVersion, claudeUpdateCommands(binaryPath));
+}
+
+async function nodeLines() {
+  const releases = await fetchNodeReleases();
+  return nodeDriftLines(nodeDrift(process.versions.node, releases), nodeUpgradeGuide(process.execPath, process.platform, process.env));
+}
+
+/** The hint lines `init` prints under its Node and Claude Code checks. */
+export async function checkVersions({ claudeBin }) {
+  const [node, claude] = await Promise.all([nodeLines(), claudeBin ? claudeLines(claudeBin) : []]);
+  return { node, claude };
+}

package/bin/has-command.d.ts

@@ -3,6 +3,10 @@ export interface CommandProbe {
   isExecutable: (candidate: string) => boolean;
 }
 
+export declare const realProbe: CommandProbe;
+export declare const namesAPath: (cmd: string) => boolean;
+export declare const extensionsFor: (platform: string) => string[];
+export declare const searchDirectories: (platform: string, env: Record<string, string | undefined>) => string[];
 export declare function hasCommand(
   cmd: string,
   options?: { platform?: NodeJS.Platform; env?: Record<string, string | undefined>; probe?: CommandProbe },

package/bin/has-command.js

@@ -37,9 +37,9 @@ import path from "node:path";
 const WINDOWS_LAUNCHABLE_EXTENSIONS = ["", ".exe", ".com", ".cmd", ".bat"];
 
 /** A name CreateProcess/execvp resolves itself rather than by searching PATH. */
-const namesAPath = (cmd) => cmd.includes("/") || cmd.includes("\\");
+export const namesAPath = (cmd) => cmd.includes("/") || cmd.includes("\\");
 
-const realProbe = {
+export const realProbe = {
   isFile: (candidate) => {
     try {
       return statSync(candidate).isFile();
@@ -60,7 +60,7 @@ const realProbe = {
 };
 
 // "" first so an explicit `foo.exe` is found as itself rather than as `foo.exe.EXE`.
-const extensionsFor = (platform) => (platform === "win32" ? WINDOWS_LAUNCHABLE_EXTENSIONS : [""]);
+export const extensionsFor = (platform) => (platform === "win32" ? WINDOWS_LAUNCHABLE_EXTENSIONS : [""]);
 
 // A Windows PATH entry may be QUOTED — `"C:\Program Files\tools"` — which the shells strip and a
 // plain join would not, leaving a path that matches nothing. Same rule as the server's
@@ -69,7 +69,7 @@ const extensionsFor = (platform) => (platform === "win32" ? WINDOWS_LAUNCHABLE_E
 // The current directory is on neither platform's list. cmd.exe searches it and POSIX shells do
 // not, but what launches an agent is node-pty on both — and the directory THIS process sits in is
 // the launch directory, never the one the PTY will run in.
-const searchDirectories = (platform, env) => {
+export const searchDirectories = (platform, env) => {
   const raw = env.PATH || env.Path || "";
   if (platform === "win32") {
     return raw

package/bin/mulmoterminal.js

@@ -223,12 +223,18 @@ function passStartupGate(args) {
 async function runInit(initArgs) {
   log("Setting up MulmoTerminal…\n");
 
+  const hasClaude = agentInstalled("claude");
+  // Imported here so a normal launch never loads the version check or reaches its network.
+  const { checkVersions } = await import("./check-versions.js");
+  const versionHints = await checkVersions({ claudeBin: hasClaude ? agentBin("claude") : null });
+
   const nodeOk = nodeMeetsMinimum(process.versions.node);
   console.log(nodeOk ? `  ✓ Node ${process.versions.node}` : `  ✗ Node ${process.versions.node} — MulmoTerminal needs ≥ ${MIN_NODE_LABEL}`);
+  versionHints.node.forEach((line) => console.log(line));
 
-  const hasClaude = agentInstalled("claude");
   if (hasClaude) {
     console.log("  ✓ Claude Code CLI");
+    versionHints.claude.forEach((line) => console.log(line));
   } else {
     console.log("  ✗ Claude Code CLI — not found");
     console.log("      → npm install -g @anthropic-ai/claude-code   (then run `claude` and log in)");

package/bin/version-drift.d.ts

@@ -0,0 +1,11 @@
+export type Drift = { kind: "current" } | { kind: "unknown" } | { kind: "behind"; latest: string; sameMajor?: boolean };
+export declare const CURRENT: Drift;
+export declare const UNKNOWN: Drift;
+export declare const CLAUDE_UPDATE_NATIVE: string;
+export declare const CLAUDE_UPDATE_NPM: string;
+export declare function nodeDrift(localVersion: string, releases: unknown): Drift;
+export declare function claudeDrift(localVersion: string | null, stableVersion: string | null): Drift;
+export declare function parseClaudeVersion(stdout: string | null | undefined): string | null;
+export declare function claudeUpdateCommands(realPath: string | null): string[];
+export declare function nodeDriftLines(drift: Drift, upgrade: import("./node-install.js").NodeUpgradeGuide): string[];
+export declare function claudeDriftLines(drift: Drift, localVersion: string | null, updateCommands: string[]): string[];

package/bin/version-drift.js

@@ -0,0 +1,88 @@
+// Whether this machine's Node and Claude Code are behind the published releases, and what `init`
+// says about it (#2477). Pure: the releases, the local versions and the binary path are handed in
+// by bin/check-versions.js, so every decision here is testable without the network.
+import { NODE_DOWNLOAD_URL } from "./node-install.js";
+import { isNewerVersion } from "./update-check.js";
+
+export const CURRENT = { kind: "current" };
+export const UNKNOWN = { kind: "unknown" };
+
+const stripV = (version) => String(version).replace(/^v/, "");
+const majorOf = (version) => Number.parseInt(stripV(version).split(".")[0], 10);
+const newestOf = (versions) => versions.reduce((newest, version) => (isNewerVersion(version, newest) ? version : newest));
+// Remote strings are printed as-is, so only a plain x.y.z is accepted — anything else would compare
+// as zeros (and read as current) or put the registry's text on the user's terminal.
+const isPlainVersion = (version) => typeof version === "string" && /^v?\d+\.\d+\.\d+$/.test(version);
+const isRelease = (entry) => typeof entry === "object" && entry !== null && isPlainVersion(entry.version);
+
+/**
+ * Node against the LTS releases in nodejs.org's index.json.
+ *
+ * The target is the newest LTS of the same major: moving someone off a working 22.x because 24.x
+ * exists is not this check's call. A major with no LTS release is compared with the newest LTS,
+ * unless it is newer than that one — a Current release is not behind anything.
+ */
+export function nodeDrift(localVersion, releases) {
+  if (!Array.isArray(releases) || Number.isNaN(majorOf(localVersion))) return UNKNOWN;
+  const ltsVersions = releases.filter((entry) => isRelease(entry) && entry.lts).map((entry) => stripV(entry.version));
+  if (ltsVersions.length === 0) return UNKNOWN;
+  const sameMajor = ltsVersions.filter((version) => majorOf(version) === majorOf(localVersion));
+  const newestLts = newestOf(ltsVersions);
+  if (sameMajor.length === 0 && majorOf(localVersion) > majorOf(newestLts)) return CURRENT;
+  const target = sameMajor.length > 0 ? newestOf(sameMajor) : newestLts;
+  return isNewerVersion(target, stripV(localVersion)) ? { kind: "behind", latest: target, sameMajor: sameMajor.length > 0 } : CURRENT;
+}
+
+/** Claude Code against the npm `stable` dist-tag. Ahead of `stable` (on `latest`) is current. */
+export function claudeDrift(localVersion, stableVersion) {
+  if (typeof localVersion !== "string" || !isPlainVersion(stableVersion)) return UNKNOWN;
+  return isNewerVersion(stableVersion, localVersion) ? { kind: "behind", latest: stableVersion } : CURRENT;
+}
+
+/** `claude --version` prints `2.1.284 (Claude Code)`; anything without a leading version is null. */
+export function parseClaudeVersion(stdout) {
+  return /^\s*(\d+\.\d+\.\d+)/.exec(String(stdout ?? ""))?.[1] ?? null;
+}
+
+export const CLAUDE_UPDATE_NATIVE = "claude update";
+export const CLAUDE_UPDATE_NPM = "npm install -g @anthropic-ai/claude-code@latest";
+
+/**
+ * How to update the Claude Code at `realPath`. Only the two layouts checked on a real machine get a
+ * single command; anything else gets both, as the server's own "too old" message does.
+ */
+export function claudeUpdateCommands(realPath) {
+  const path = String(realPath ?? "").replaceAll("\\", "/");
+  if (path.includes("/node_modules/@anthropic-ai/claude-code/")) return [CLAUDE_UPDATE_NPM];
+  if (path.includes("/.local/share/claude/")) return [CLAUDE_UPDATE_NATIVE];
+  return [CLAUDE_UPDATE_NATIVE, `${CLAUDE_UPDATE_NPM}   (if you installed it with npm)`];
+}
+
+const HINT = "      → ";
+const COMMAND = "          ";
+
+function updateLines(headline, commands, fallback, via = null) {
+  if (commands.length === 0) return [`${HINT}${headline} Update: ${fallback}`];
+  const withTool = via ? " with " + via : "";
+  return [`${HINT}${headline} To update${withTool}:`, ...commands.map((command) => `${COMMAND}${command}`)];
+}
+
+/**
+ * The lines printed under `✓ Node …`; empty when there is nothing to say. The commands are the
+ * install tool's own upgrade (`nodeUpgradeGuide`), which may land on a newer major than the one
+ * named — so the tool is named too.
+ */
+export function nodeDriftLines(drift, upgrade) {
+  if (drift.kind === "unknown") return [`${HINT}○ could not check for a newer Node (offline?)`];
+  if (drift.kind !== "behind") return [];
+  const headline = drift.sameMajor ? `Node ${drift.latest} is out (latest ${majorOf(drift.latest)}.x LTS).` : `Node ${drift.latest} is the latest LTS.`;
+  return updateLines(headline, upgrade.commands, NODE_DOWNLOAD_URL, upgrade.via);
+}
+
+/** The lines printed under `✓ Claude Code CLI`; empty when there is nothing to say. */
+export function claudeDriftLines(drift, localVersion, updateCommands) {
+  if (localVersion === null) return [`${HINT}○ could not read the Claude Code version`];
+  if (drift.kind === "unknown") return [`${HINT}○ could not check for a newer Claude Code (offline?)`];
+  if (drift.kind !== "behind") return [];
+  return updateLines(`Claude Code ${localVersion} is older than the stable release ${drift.latest}.`, updateCommands, CLAUDE_UPDATE_NATIVE);
+}

package/blueprints/ask/hearing.json

@@ -4,13 +4,16 @@
       "id": "documents",
       "label": "質問する相手の文書（このフォルダの中のファイルを 1 行に 1 つ）",
       "why": "答えはこの文書だけから出し、どこに書いてあるかを示す",
-      "kind": "text"
+      "kind": "text",
+      "lines": true,
+      "pick": "files"
     },
     {
       "id": "questions",
       "label": "質問（1 行に 1 つ）",
       "why": "質問ごとに一つ答える",
-      "kind": "text"
+      "kind": "text",
+      "lines": true
     },
     {
       "id": "keep",

package/blueprints/ask/steps.json

@@ -13,7 +13,8 @@
       "description": "残すと決めたなら、確かめた答えを FAQ.md に書き足す。",
       "skill": "skills/keep",
       "check": "node \"$BLUEPRINT_USECASE/checks/replies.mjs\" keep",
-      "gates": ["review"]
+      "gates": ["review"],
+      "reads": [".blueprint/replies.md"]
     }
   ]
 }

package/blueprints/docs/checks/chaff.sh

@@ -4,4 +4,4 @@
 if [ -n "${CHAFF_BIN:-}" ]; then
   exec sh -c "$CHAFF_BIN \"\$@\"" chaff "$@"
 fi
-exec npx -y chaffjs@0.10 "$@"
+exec npx -y chaffjs@0.11 "$@"

package/blueprints/docs/skills/workspace/SKILL.md

@@ -12,7 +12,7 @@ repository, `.git/info/exclude`) until the person has approved the models.
 1. `.blueprint/` already exists (the build created it). Everything this build records goes there.
 2. Run chaff once through the base pack's wrapper, so its first download happens now and not in the
    middle of a later step: `sh <base pack>/checks/chaff.sh rules --json > /dev/null`. The wrapper runs the
-   pinned chaff (`npx -y chaffjs@0.10`) unless `CHAFF_BIN` names another. If it fails, show the person the
+   pinned chaff (`npx -y chaffjs@0.11`) unless `CHAFF_BIN` names another. If it fails, show the person the
    error and stop — do not work around it.
 3. If the folder is a git repository, add `.blueprint/` to `.git/info/exclude`. That keeps the build's
    working files out of commits without touching `.gitignore`, which belongs to the person.

package/blueprints/firebase/checks/security-report.sh

@@ -0,0 +1,11 @@
+#!/bin/sh
+# The security review's report exists, walks every OWASP Top 10:2025 category, and leaves no HIGH or
+# MEDIUM finding open or merely accepted. A finding is one line: `- <HIGH|MEDIUM|LOW> <fixed|open|accepted>: …`.
+set -eu
+report=.blueprint/security-review.md
+[ -s "$report" ] || { echo "missing $report" >&2; exit 1; }
+for category in A01 A02 A03 A04 A05 A06 A07 A08 A09 A10; do
+  grep -q "^#.*$category" "$report" || { echo "$report has no section for $category (OWASP Top 10:2025)" >&2; exit 1; }
+done
+open=$(grep -nE '^- (HIGH|MEDIUM) (open|accepted)' "$report" || true)
+[ -z "$open" ] || { printf 'HIGH / MEDIUM findings must be fixed, but are open or accepted in %s:\n%s\n' "$report" "$open" >&2; exit 1; }

package/blueprints/firebase/checks/security.sh

@@ -0,0 +1,41 @@
+#!/bin/sh
+# The security review is proven by what ships, not by the review's word: the rules refuse what the
+# review's emulator tests say they refuse, the rules end in deny-all, Hosting sends the headers a browser
+# needs, no service account key is in the project, the dependencies have no known high-severity hole,
+# the review's own report is in place, and dev runs what the review left — so production, which ships
+# what dev ran, gets the fixes, and a header that breaks the page shows up here, on dev.
+set -eu
+here="$(dirname "$0")"
+sh "$here/security-report.sh"
+grep -qE 'allow +read, *write: *if +false' firestore.rules || { echo "firestore.rules does not end in a deny-all (allow read, write: if false)" >&2; exit 1; }
+node -e 'const fs=require("node:fs");
+  const hosting=[JSON.parse(fs.readFileSync("firebase.json","utf8")).hosting].flat().filter(Boolean);
+  if (hosting.length===0) { console.error("firebase.json has no hosting section"); process.exit(1); }
+  for (const site of hosting) {
+    const all=(site.headers??[]).filter((h)=>h.source==="**").flatMap((h)=>h.headers??[]);
+    const value=(key)=>all.find((h)=>h.key.toLowerCase()===key)?.value??"";
+    const missing=[];
+    if (!/nosniff/i.test(value("x-content-type-options"))) missing.push("X-Content-Type-Options: nosniff");
+    if (!value("content-security-policy")) missing.push("Content-Security-Policy");
+    if (!/frame-ancestors/i.test(value("content-security-policy")) && !/deny|sameorigin/i.test(value("x-frame-options"))) missing.push("frame-ancestors or X-Frame-Options");
+    if (missing.length) { console.error("firebase.json hosting headers for ** lack: "+missing.join(", ")); process.exit(1); }
+  }'
+keys=$(grep -rlE '"private_key"|-----BEGIN [A-Z ]*PRIVATE KEY-----' . --exclude-dir=node_modules --exclude-dir=.firebase --exclude-dir=dist 2>/dev/null || true)
+[ -z "$keys" ] || { printf 'a private key is in the project; move it out and revoke it:\n%s\n' "$keys" >&2; exit 1; }
+audit() {
+  # Read from the summary, not the exit code: an audit that could not reach the registry must not pass.
+  (cd "$1" && yarn audit --groups dependencies --json 2>/dev/null) | node -e 'let s="";process.stdin.on("data",(c)=>s+=c).on("end",()=>{
+    const summary = s.split("\n").filter(Boolean).map((line) => JSON.parse(line)).find((entry) => entry.type === "auditSummary");
+    if (!summary) { console.error(process.argv[1] + ": yarn audit did not report a summary (is the registry reachable?)"); process.exit(1); }
+    const { high = 0, critical = 0 } = summary.data.vulnerabilities;
+    if (high + critical > 0) { console.error(`${process.argv[1]}: yarn audit finds ${high} high and ${critical} critical vulnerabilities in dependencies`); process.exit(1); }
+  })' "$1"
+}
+audit .
+if [ -f functions/package.json ]; then
+  [ -f functions/yarn.lock ] || { echo "functions/ has no yarn.lock; install its dependencies with yarn so they can be audited" >&2; exit 1; }
+  audit functions
+fi
+sh "$here/emulator-test.sh" security
+[ .blueprint/build-id -nt .blueprint/security-review.md ] || { echo "dev was not deployed after the review; deploy it to dev again so production ships what dev runs" >&2; exit 1; }
+sh "$here/deploy-check.sh" dev

package/blueprints/firebase/checks/start-here.sh

@@ -0,0 +1,8 @@
+#!/bin/sh
+# The first page the finished build shows says where the published app is and what to try to see it works.
+set -eu
+start=.blueprint/start-here.md
+[ -s "$start" ] || { echo "missing $start" >&2; exit 1; }
+prod=$(sh "$(dirname "$0")/project-id.sh" prod)
+grep -q "https://$prod.web.app" "$start" || { echo "$start does not name the production URL (https://$prod.web.app)" >&2; exit 1; }
+grep -q '^- \[ \] ' "$start" || { echo "$start has no checklist of what to try (- [ ] …)" >&2; exit 1; }

package/blueprints/firebase/manifest.json

@@ -35,5 +35,6 @@
   "credentials": [
     "firebase login",
     "gcloud auth login"
-  ]
+  ],
+  "report": ".blueprint/start-here.md"
 }

package/blueprints/firebase/plan.json

@@ -59,12 +59,19 @@
       "check": "sh \"$BLUEPRINT_BASE/checks/protect.sh\"",
       "gates": ["billing"]
     },
+    {
+      "id": "security",
+      "title": "セキュリティ診断",
+      "description": "本番に公開する前に、OWASP Top 10:2025 に沿って作ったものを攻撃する側の目で読み、突ける穴を直してエミュレータの試験で確かめ、報告を書く。直したものは開発用に公開し直して、画面が壊れていないことまで確かめる。",
+      "skill": "skills/security",
+      "check": "sh \"$BLUEPRINT_BASE/checks/security.sh\""
+    },
     {
       "id": "deploy-production",
       "title": "本番に公開",
       "description": "開発用で確かめたものと同じビルドを本番に公開する。",
       "skill": "skills/deploy-production",
-      "check": "sh \"$BLUEPRINT_BASE/checks/deploy-check.sh\" prod",
+      "check": "sh \"$BLUEPRINT_BASE/checks/deploy-check.sh\" prod && sh \"$BLUEPRINT_BASE/checks/start-here.sh\"",
       "gates": ["deploy-production"]
     }
   ]

package/blueprints/firebase/skills/deploy-production/SKILL.md

@@ -12,8 +12,21 @@ This is the **deploy-production** gate: the user has approved it. Deploy the sam
    then `firebase deploy --project prod`. The check compares the served id with `.blueprint/build-id`, so it
    proves THIS build is live. Git is not needed for this.
 2. Tell the user the URL and that the next change should go through dev first.
+3. Write `.blueprint/start-here.md`, in the spec's language. It is what the person sees the moment the build
+   finishes, so it answers "now what?" in the order they will need it:
+   - **Open it** — the production URL (`https://<prod-project-id>.web.app`) and who can sign in, and how.
+   - **Check that it works** — one checkbox per must-have in the spec, each an action and what should happen
+     (`- [ ] 申請を 1 件出す → 承認者の一覧に出る`), using the app's real screen and button names; one for
+     someone who should be refused (another account, a signed-out visitor) being refused.
+   - **The next change** — edit, try it on dev (`https://<dev-project-id>.web.app`), then publish to production;
+     never straight to production.
+   - **Costs and safety** — the budget alert and where it goes; where the security review is
+     (`.blueprint/security-review.md`).
 
-Done when the check passes: the production site serves the id this deploy wrote to `.blueprint/build-id`.
+   Keep it short: it is a first page, not the manual.
+
+Done when the check passes: the production site serves the id this deploy wrote to `.blueprint/build-id`, and
+`.blueprint/start-here.md` names the production URL and has the checklist.
 
 ## Always
 

package/blueprints/firebase/skills/security/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: blueprint-firebase-security
+description: "Before production, review the app against OWASP Top 10:2025, fix what is exploitable, prove it on the emulators, and redeploy dev."
+---
+
+# Security review
+
+Everything is built and runs on dev. Before production, review it the way an attacker would read it, fix what
+is exploitable, and leave a report the person can read. On Firebase the attacker does not need the screen: the
+web config is public, so anyone can call Firestore and the callable functions directly with their own client.
+The rules and the functions are the whole defence.
+
+## Method
+
+1. **Context.** Read `.blueprint/spec.md` (above all "必ず詰める点" and the access table), then `firestore.rules`,
+   `functions/src/`, `firebase.json` and the web app's source. Note who may do what and where input enters.
+2. **Audit, category by category** (the list below). For each rule and each callable, ask what a signed-in
+   stranger, a signed-out visitor and a user of another role can do with a hand-written request.
+3. **Fix** every HIGH and MEDIUM finding, and prove it in `test/blueprint/security.spec.ts` against the
+   emulators: the attack is refused (`assertFails`, or the callable throwing) and the legitimate use still works.
+4. **Report** in `.blueprint/security-review.md` (format below).
+5. **Redeploy dev** the way the deploy-dev step does (new `.blueprint/build-id`, `firebase deploy --project dev`),
+   even when nothing changed, so production ships exactly what dev now runs. Do not deploy to `prod`.
+
+Severity: **HIGH** is directly exploitable (read or change someone's data, bypass sign-in or a role, run code).
+**MEDIUM** needs a specific condition but the impact is real. **LOW** is defence in depth. Report a finding only
+when you can state how it is exploited and you are at least 70% sure; a guess is not a finding. Do not report
+denial of service, rate limits, quota exhaustion, or missing validation on a field that cannot cause harm.
+
+## What to look at in this app (OWASP Top 10:2025)
+
+- **A01 Broken Access Control** — every `match` opens only what the access table says; ownership and role come
+  from `request.auth` (custom claims), never from a field the client wrote; `list` queries cannot read past what
+  `get` allows; every callable checks `context.auth` and the role itself.
+- **A02 Security Misconfiguration** — the rules end in deny-all; Hosting sends `Content-Security-Policy` (with
+  `frame-ancestors 'none'`, and `connect-src` / `script-src` listing exactly the Firebase and Google hosts the
+  app uses), `X-Content-Type-Options: nosniff` and `Referrer-Policy`; App Check enforced; no emulator setting
+  reaches the production build.
+- **A03 Software Supply Chain Failures** — `yarn audit` clean of high and critical at the root and in
+  `functions/` (install `functions/` with yarn); no dependency the app does not use.
+- **A04 Cryptographic Failures** — no service account key, private key or admin credential anywhere in the
+  project or the built site; secrets for functions in Secret Manager, not in code or `.env` that is deployed.
+- **A05 Injection** — the screen never renders stored text as HTML (`v-html` only on text the app wrote);
+  functions build no query, URL, shell command or file path from input without checking it.
+- **A06 Insecure Design** — the spec's rules (limits, states, who may change what) are in the rules or the
+  functions, not only in the screen; field lists pinned with `keys().hasOnly` and `affectedKeys().hasOnly`.
+- **A07 Authentication Failures** — only the sign-in providers the spec names are enabled; a signed-out or
+  unverified user gets nothing the spec does not allow them.
+- **A08 Software or Data Integrity Failures** — roles and privileges are set only by functions (custom claims),
+  never by a document a user can write; uploaded files are checked by Storage rules for type and size.
+- **A09 Security Logging and Alerting Failures** — privileged actions and refusals in functions are logged
+  without tokens or personal data beyond what the spec needs.
+- **A10 Mishandling of Exceptional Conditions** — callables throw `HttpsError` with a short message, never a
+  stack or an internal error text; a failed check refuses rather than lets through.
+
+## The report
+
+`.blueprint/security-review.md`, in the spec's language. One section per category, its heading naming the id
+(`## A01 …` through `## A10 …`), each with what you checked and every finding on a line of its own:
+
+```
+- HIGH fixed: <what was wrong, how it could be exploited> — <what changed, which test proves it>
+- LOW accepted: <what, and why it is acceptable for this app>
+```
+
+The state is `fixed`, `open` or `accepted`. A HIGH or MEDIUM may not be `open` or `accepted`: fix it, or ask
+through the blueprint question tool if fixing it would change what the spec asks for. A category with nothing
+to report says what was checked and "指摘なし". Write the report before step 5, so the deploy comes after it.
+
+Done when the check passes: the report covers A01–A10 with nothing HIGH or MEDIUM left open, the rules end in
+deny-all, Hosting sends the headers, no private key is in the project, both audits are clean,
+`emulator-test.sh security` passes, and dev serves a build deployed after the report and still renders.
+
+## Always
+
+- Read `.blueprint/spec.md` first. It is the agreed specification; do not widen it.
+- When you need a decision, ask it through the blueprint question tool and stop. Do not guess.
+- Never enable billing, deploy to production, delete data or handle a credential unless this step's gates say the
+  user approved exactly that.
+- Say you are done by stopping; the executor runs the check. Do not claim success yourself.

package/blueprints/from-collection/checks/spec.sh

@@ -0,0 +1,26 @@
+#!/bin/sh
+# The spec carries the whole source over: every field, view, action and ingest of every copied collection is named in it
+# by a token that says which collection it belongs to — `books.title`, `books.views.board`, `books.actions.tidy`,
+# `books.ingest` — so nothing is dropped without a person seeing it go. A bare key is not enough: two collections
+# share keys (`id`, `name`), and one of them would vouch for the other.
+set -eu
+[ -s .blueprint/source/source.json ] || { echo "missing .blueprint/source/source.json; the build was started without a collection" >&2; exit 1; }
+node -e '
+const fs = require("node:fs");
+const spec = fs.readFileSync(".blueprint/spec.md", "utf8");
+const source = JSON.parse(fs.readFileSync(".blueprint/source/source.json", "utf8"));
+const missing = source.collections.flatMap((slug) => {
+  const schema = JSON.parse(fs.readFileSync(`.blueprint/source/collections/${slug}/schema.json`, "utf8"));
+  const tokens = [
+    ...Object.keys(schema.fields ?? {}).map((key) => `${slug}.${key}`),
+    ...(schema.views ?? []).map((view) => `${slug}.views.${view.id}`),
+    ...[...(schema.actions ?? []), ...(schema.collectionActions ?? [])].map((action) => `${slug}.actions.${action.id}`),
+    ...(schema.ingest ? [`${slug}.ingest`] : []),
+  ];
+  return tokens.filter((token) => !spec.includes("`" + token + "`"));
+});
+if (missing.length > 0) {
+  console.error("the spec does not carry these over from the source (name each in backquotes, as `collection.key`):\n" + missing.join("\n"));
+  process.exit(1);
+}
+'