@gempack/squad-mcp 0.3.1 → 0.5.0

package/dist/util/override-allowlist.js

@@ -0,0 +1,191 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { SquadError } from '../errors.js';
+import { rejectIfMalformed, realpathOrSelf } from './path-internal.js';
+let allowlistCache = null;
+/**
+ * Test-only: clears the memoized allowlist so env-var changes take effect.
+ * Production code should never call this.
+ */
+export function __resetOverrideAllowlistCache() {
+    allowlistCache = null;
+}
+function isUnsafeOverrideEnabled() {
+    return process.env.SQUAD_AGENTS_ALLOW_UNSAFE === '1';
+}
+function isUncOrDeviceNamespace(absolute) {
+    if (process.platform !== 'win32')
+        return false;
+    if (absolute.startsWith('\\\\?\\'))
+        return true;
+    if (absolute.startsWith('\\\\.\\'))
+        return true;
+    if (absolute.startsWith('\\\\'))
+        return true;
+    return false;
+}
+async function buildAllowlist() {
+    if (allowlistCache !== null)
+        return allowlistCache;
+    const roots = [];
+    const seen = new Set();
+    const candidates = [
+        { source: 'home', raw: os.homedir() },
+        { source: 'cwd', raw: process.cwd() },
+    ];
+    if (process.platform === 'win32') {
+        candidates.push({ source: 'appdata', raw: process.env.APPDATA });
+        candidates.push({ source: 'localappdata', raw: process.env.LOCALAPPDATA });
+    }
+    else {
+        candidates.push({ source: 'xdg_config_home', raw: process.env.XDG_CONFIG_HOME });
+    }
+    for (const c of candidates) {
+        if (!c.raw)
+            continue;
+        if (!path.isAbsolute(c.raw))
+            continue;
+        try {
+            rejectIfMalformed(c.raw);
+        }
+        catch {
+            // hostile env var (e.g. APPDATA injected with NUL) — silently skip from allowlist
+            continue;
+        }
+        if (isUncOrDeviceNamespace(c.raw))
+            continue;
+        const lexical = path.normalize(c.raw);
+        const real = await realpathOrSelf(lexical);
+        if (seen.has(real))
+            continue;
+        seen.add(real);
+        roots.push({ source: c.source, lexical, real });
+    }
+    allowlistCache = roots;
+    return roots;
+}
+function isInsideRoot(candidate, root) {
+    if (candidate === root)
+        return true;
+    const rel = path.relative(root, candidate);
+    if (rel === '' || rel === '.')
+        return true;
+    if (path.isAbsolute(rel))
+        return false;
+    if (rel === '..')
+        return false;
+    if (rel.startsWith('..' + path.sep))
+        return false;
+    return true;
+}
+function findAllowlistMatch(candidateLexical, candidateReal, roots) {
+    // Lexical AND realpath both must be inside the same allowlist entry.
+    // (Either alone is a known bypass: a symlinked-out lexical-allowed path,
+    // or a realpath-allowed path that lexically points elsewhere.)
+    for (const r of roots) {
+        if (isInsideRoot(candidateLexical, r.lexical) && isInsideRoot(candidateReal, r.real)) {
+            return r;
+        }
+    }
+    return null;
+}
+/**
+ * Validate an override directory.
+ *
+ * Returns the resolved (realpath) directory on success. Throws `OVERRIDE_REJECTED`
+ * for policy violations (UNC, malformed, not absolute, outside allowlist, symlink
+ * escape) UNLESS `SQUAD_AGENTS_ALLOW_UNSAFE=1` is set, in which case the violation
+ * is bypassed (still rejects malformed inputs hard — those are not policy choices).
+ */
+export async function validateOverrideDir(rawDir) {
+    // Hard rejections — never bypassed by the escape hatch.
+    try {
+        rejectIfMalformed(rawDir);
+    }
+    catch (err) {
+        return { ok: false, reason: 'malformed', rejectedPath: rawDir };
+    }
+    if (!path.isAbsolute(rawDir)) {
+        return { ok: false, reason: 'not_absolute', rejectedPath: rawDir };
+    }
+    if (isUncOrDeviceNamespace(rawDir)) {
+        return { ok: false, reason: 'unc_or_device_namespace', rejectedPath: rawDir };
+    }
+    const lexical = path.normalize(rawDir);
+    const real = await realpathOrSelf(lexical);
+    const unsafe = isUnsafeOverrideEnabled();
+    const roots = await buildAllowlist();
+    const match = findAllowlistMatch(lexical, real, roots);
+    if (match) {
+        return { ok: true, resolvedPath: real, allowlistMatch: match.source, unsafeOverride: false };
+    }
+    // Distinguish lexical-only escape (likely symlink) from outright outside-allowlist.
+    // If lexical matches some root but realpath does not, the user did `ln -s /tmp/x ~/.squad`.
+    let lexicalMatchExists = false;
+    for (const r of roots) {
+        if (isInsideRoot(lexical, r.lexical)) {
+            lexicalMatchExists = true;
+            break;
+        }
+    }
+    const reason = lexicalMatchExists ? 'symlink_escape' : 'outside_allowlist';
+    if (unsafe) {
+        return { ok: true, resolvedPath: real, allowlistMatch: 'unsafe_override', unsafeOverride: true };
+    }
+    return { ok: false, reason, rejectedPath: rawDir };
+}
+/**
+ * Convert a `ValidationFail` into a structured `OVERRIDE_REJECTED` error.
+ * Caller decides whether to throw or downgrade to a warn-and-fallback.
+ */
+export function rejectionToError(fail, allowlistSize) {
+    return new SquadError('OVERRIDE_REJECTED', `override directory rejected: ${fail.reason}`, {
+        reason: fail.reason,
+        path: fail.rejectedPath,
+        allowlist_size: allowlistSize,
+    });
+}
+export async function getAllowlistSize() {
+    const roots = await buildAllowlist();
+    return roots.length;
+}
+/**
+ * Validate that a candidate file path inside a previously-validated override
+ * directory does not escape (after symlink resolution).
+ *
+ * Returns the file's realpath on success, or `null` if the file does not exist
+ * or escapes the directory. Per-file escape is NOT a policy-level error — the
+ * caller falls back to embedded for that file only and continues.
+ */
+export async function validateOverrideFile(validatedDirReal, fileName) {
+    try {
+        rejectIfMalformed(fileName);
+    }
+    catch {
+        return null;
+    }
+    // Lexical: file name must not contain traversal segments.
+    const normalized = path.normalize(fileName);
+    if (path.isAbsolute(normalized))
+        return null;
+    if (normalized === '..' || normalized.startsWith('..' + path.sep) || normalized.includes(path.sep + '..' + path.sep)) {
+        return null;
+    }
+    const candidate = path.resolve(validatedDirReal, normalized);
+    // Lexical containment.
+    if (!isInsideRoot(candidate, validatedDirReal))
+        return null;
+    // Existence check before realpath.
+    try {
+        await fs.access(candidate);
+    }
+    catch {
+        return null;
+    }
+    const real = await realpathOrSelf(candidate);
+    if (!isInsideRoot(real, validatedDirReal))
+        return null;
+    return real;
+}
+//# sourceMappingURL=override-allowlist.js.map

package/dist/util/override-allowlist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"override-allowlist.js","sourceRoot":"","sources":["../../src/util/override-allowlist.ts"],"names":[],"mappings":"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"}

package/dist/util/path-internal.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Internal helpers shared between path-safety.ts and override-allowlist.ts.
+ * Exported only for intra-`util/` reuse; do not import from outside src/util/.
+ */
+export declare function rejectIfMalformed(file: string): void;
+export declare function realpathOrSelf(p: string): Promise<string>;

package/dist/util/path-internal.js

@@ -0,0 +1,27 @@
+import { promises as fs } from 'node:fs';
+import { SquadError } from '../errors.js';
+/**
+ * Internal helpers shared between path-safety.ts and override-allowlist.ts.
+ * Exported only for intra-`util/` reuse; do not import from outside src/util/.
+ */
+export function rejectIfMalformed(file) {
+    if (file.includes('\0')) {
+        throw new SquadError('PATH_INVALID', 'file path contains NUL byte', { file });
+    }
+    if (file.startsWith('~')) {
+        throw new SquadError('PATH_INVALID', 'file path starts with ~ (tilde expansion not supported)', { file });
+    }
+    const adsIndex = file.indexOf(':', 2);
+    if (adsIndex !== -1) {
+        throw new SquadError('PATH_INVALID', 'file path contains ADS marker (:) after drive letter', { file });
+    }
+}
+export async function realpathOrSelf(p) {
+    try {
+        return await fs.realpath(p);
+    }
+    catch {
+        return p;
+    }
+}
+//# sourceMappingURL=path-internal.js.map

package/dist/util/path-internal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-internal.js","sourceRoot":"","sources":["../../src/util/path-internal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C;;;GAGG;AAEH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,UAAU,CAAC,cAAc,EAAE,6BAA6B,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IAChF,CAAC;IACD,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,UAAU,CAAC,cAAc,EAAE,yDAAyD,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5G,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IACtC,IAAI,QAAQ,KAAK,CAAC,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,UAAU,CAAC,cAAc,EAAE,sDAAsD,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IACzG,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,CAAS;IAC5C,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,CAAC;IACX,CAAC;AACH,CAAC"}

package/dist/util/path-safety.js.map

@@ -1 +1 @@
-{"version":3,"file":"path-safety.js","sourceRoot":"","sources":["../../src/util/path-safety.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"path-safety.js","sourceRoot":"","sources":["../../src/util/path-safety.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gempack/squad-mcp",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "MCP server for the squad-dev workflow: classification, risk scoring, agent selection, advisory orchestration",
   "type": "module",
   "license": "Apache-2.0",
@@ -47,6 +47,7 @@
     "skills",
     ".claude-plugin",
     "README.md",
+    "INSTALL.md",
     "LICENSE",
     "NOTICE",
     "CHANGELOG.md"

package/skills/brainstorm/SKILL.md

@@ -0,0 +1,284 @@
+---
+name: brainstorm
+description: Collaborative brainstorm and research skill. Takes a problem, decision, or implementation topic; runs deep web research in parallel; spawns specialist agents for multi-domain perspectives; synthesizes findings into an options matrix with pros/cons/risks/sources and a recommendation. Output is a decision aid, NOT code. Use this BEFORE /squad to decide what to build; use /squad after to implement. Trigger when the user types /brainstorm or asks to "brainstorm", "research approaches", "explore options", "help me think through", "what does the industry use", or "best practices for".
+---
+
+# Skill: Brainstorm
+
+## Objective
+Help the user think through a problem, decision, or implementation idea by running parallel web research (market patterns, best practices, pitfalls, examples) and gathering specialist agent perspectives, then synthesizing the findings into a structured options matrix with a recommendation. This skill is exploratory — it does not write code, run tests, or modify the repo.
+
+Position in the workflow:
+- **`/brainstorm`** → decide what to build (this skill)
+- **`/squad`** → implement what was decided
+- **`/squad-review`** → review what was implemented
+
+## Skill Name
+`/brainstorm`
+
+## Inviolable Rules
+
+1. **No code implementation.** This skill produces a brainstorm report. It must not edit files, run scripts, run tests, or modify any persistent state.
+2. **No `git commit`, `git push`, or any state-mutating git command.** Read-only git is fine (`git log`, `git status`, `git diff` for context).
+3. **Cite sources.** Every market claim, best practice, statistic, or "industry uses X" assertion must link to the URL it came from. Unsourced claims are not allowed.
+4. **Multiple options.** Always present at least two alternatives with explicit pros/cons. Never single-answer. The user is brainstorming, not asking for a verdict.
+5. **Honest gaps.** When research is incomplete or a decision needs more input, surface it explicitly under "Open questions" — do not paper over.
+6. **No AI attribution in any artifact produced.** Consistent with the global commit-authorship rule: if the brainstorm output ever gets pasted into a commit, doc, or message, it must not carry `Co-Authored-By: Claude / Anthropic / AI / Generated with [...]` lines.
+
+## Inputs
+
+The skill takes one required argument (the topic) and optional flags:
+
+| Param | Default | Description |
+|-------|---------|-------------|
+| `<topic>` | required | Free-form text describing the problem, decision, or idea to brainstorm |
+| `--depth <level>` | `medium` | `quick` (3 web queries, 1 agent), `medium` (6 queries, 2-3 agents), `deep` (10+ queries, 4 agents + tech-lead) |
+| `--no-web` | off | Skip web research entirely. Agents-only mode. Use when offline or when the topic is purely internal-codebase. |
+| `--focus <domain>` | auto | Force a domain bias: `frontend`, `backend`, `infra`, `data`, `security`, `business`, `mobile`. Auto-detection scans the topic text for keywords. |
+| `--sources <N>` | 5 | Cap on web sources cited per section. Avoids dump of every result. |
+
+## Step 1: Topic Understanding
+
+Read the user's prompt and extract:
+- **Problem/decision**: what is being decided? Phrase it as a question.
+- **Constraints**: tech stack, team size, scale, budget, timeline (if mentioned or inferable from `git log` / `package.json` / `README`).
+- **Existing context**: scan the current repo for related code, prior decisions in `CHANGELOG.md` or ADRs (`docs/adr/`, `architecture/`).
+- **Domain(s)**: classify into one or more of `frontend / backend / infra / data / security / business / mobile`.
+- **What "done" looks like**: what would satisfy the user — a single recommendation, multiple paths to consider, a comparison table, a risk inventory?
+
+If the topic is ambiguous, ask **one** clarifying question before proceeding. Do not ask a list of questions; pick the most load-bearing one.
+
+## Step 2: Research Plan
+
+Build a research plan with:
+
+### Web queries (skip if `--no-web`)
+
+Construct 3-10 targeted queries (count from `--depth`). Use the **current year** in queries that benefit from recency:
+
+- `{topic} best practices {year}`
+- `{topic} {dominant_stack} examples`
+- `{topic} alternatives comparison`
+- `{topic} common pitfalls`
+- `{topic} performance` / `security` / `scalability` / `cost`
+- `{topic} case study {year}` (for industry examples)
+- `{topic} open source` (if implementation references would help)
+- `{topic} vs {known_alternative}` (if a comparison is implicit)
+
+Avoid:
+- Generic queries like "{topic}" alone (returns marketing pages).
+- Queries that the user can find better via their internal docs (e.g., proprietary product internals).
+
+### Agents
+
+Pick agents based on detected domains. For `--depth quick`: pick the single most relevant. For `medium`: 2-3. For `deep`: 4 + tech-lead. Mapping:
+
+| Domain | Primary agent |
+|--------|---------------|
+| frontend | senior-developer (UX/perf perspective) |
+| backend | senior-developer + senior-architect |
+| infra | senior-architect + senior-dev-security |
+| data | senior-dba + senior-architect |
+| security | senior-dev-security + senior-architect |
+| business | product-owner |
+| testing | senior-qa |
+| code quality | senior-dev-reviewer |
+
+`tech-lead` is included only at `--depth deep` (or whenever 3+ agents participate, to consolidate).
+
+## Step 3: Parallel Research and Agent Spawn
+
+Run web queries and agent invocations **in parallel** in a single message:
+- One `WebSearch` tool call per query.
+- One `Agent` tool call per specialist.
+
+Per-agent prompt template:
+
+```
+You are participating in a brainstorm — pre-implementation thinking.
+
+## Topic
+{topic restated}
+
+## What we know so far
+{problem framing, constraints, existing context}
+
+## Your perspective
+As {agent role}, contribute:
+1. The 1-3 approaches you would consider, with one-line pros/cons each.
+2. Domain-specific risks the user should weigh.
+3. Open questions that need answers before deciding.
+4. (Optional) One concrete example from your experience or prior projects.
+
+Format: at most 400 words. Bullet points fine. Do NOT produce a full review template.
+Do NOT recommend code changes — this is exploration, not implementation.
+If you do not have enough context to contribute meaningfully, say so explicitly.
+```
+
+## Step 4: Findings Synthesis
+
+Aggregate web findings and agent perspectives into:
+
+### Market research section
+Group findings by category. **Cite every claim.** Example:
+
+```
+### What the industry does
+- Stripe and Block use a "saga" pattern for cross-service refund flows — [Stripe Engineering blog](url), [Square's saga implementation](url).
+- 7 of the top 10 fintech APIs (per State of API 2026) implement idempotency keys via request headers — [State of API 2026](url).
+
+### Best practices
+- Always include a `request_id` in idempotency keys to disambiguate retries — [GitHub's idempotency guide](url).
+
+### Pitfalls / anti-patterns
+- Don't use the database PK as an idempotency key — collisions across retries break replays — [Postgres weekly issue 543](url).
+```
+
+### Options matrix
+
+Build a table of **3-5 alternatives**. Columns:
+
+| # | Approach | How it works | Pros | Cons | Risk | Best when |
+|---|----------|--------------|------|------|------|-----------|
+
+Each row is one viable path. "Approach" is short (3-6 words). "How it works" is one sentence. Pros/cons are bullet-style condensed.
+
+### Agent perspectives
+
+One collapsible section per agent that participated:
+
+```
+<details>
+<summary>senior-architect</summary>
+{their perspective bullet-pointed}
+</details>
+```
+
+## Step 5: Tech-Lead Recommendation
+
+If `--depth deep` (or 3+ agents participated), spawn the `tech-lead` agent with:
+
+```
+You are consolidating a brainstorm. Pick one option and justify.
+
+## Topic
+{topic}
+
+## Options matrix
+{the matrix from step 4}
+
+## Web findings summary
+{condensed market research, with sources}
+
+## Specialist perspectives
+{condensed bullets from each agent}
+
+## Your task
+1. Pick ONE option from the matrix as the recommendation.
+2. Explain in 3-5 sentences why this option, with the trade-offs you accepted.
+3. List the top 2-3 open questions that must be answered before implementation begins.
+4. Suggest the immediate next step (e.g., spike, prototype, more research, /squad implement).
+
+Format: at most 400 words. No long template. No scorecard.
+```
+
+For `quick` and `medium` depth, the synthesizing skill itself produces the recommendation directly (no separate tech-lead spawn).
+
+## Step 6: Delivery
+
+Output in this format:
+
+```
+# Brainstorm: {short topic}
+
+## Topic
+{problem framing in 1-2 sentences}
+
+## Context I gathered
+- {key fact 1 from repo / git / user prompt}
+- {key fact 2}
+
+## Market research
+
+### What the industry does
+- {finding} — [source title](url)
+- {finding} — [source title](url)
+
+### Best practices
+- {practice} — [source](url)
+
+### Pitfalls / anti-patterns
+- {pitfall} — [source](url)
+
+## Options matrix
+
+| # | Approach | How it works | Pros | Cons | Risk | Best when |
+|---|----------|--------------|------|------|------|-----------|
+| A | ... | ... | ... | ... | Low | small scale, low traffic |
+| B | ... | ... | ... | ... | Med | growth phase |
+| C | ... | ... | ... | ... | High | enterprise / regulated |
+
+## Agent perspectives
+
+<details><summary>senior-architect</summary>{view}</details>
+<details><summary>senior-developer</summary>{view}</details>
+
+## Recommendation
+**Option {letter}** — {one-paragraph justification including the trade-offs accepted}.
+
+## Open questions
+- {gap 1 — needs decision or more research}
+- {gap 2}
+- {gap 3}
+
+## Next steps
+- `/squad implement {selected option}` to execute
+- `/brainstorm --focus {domain} {sub-topic}` to deep-dive on a specific concern
+- Spike / prototype: {1-2 line description if appropriate}
+- Continue research on: {gap}
+
+Sources used:
+- [Title 1](url)
+- [Title 2](url)
+- ...
+```
+
+If `--no-web` was passed, omit "Market research" section and replace with a one-line note: `Web research disabled — agents-only brainstorm.`
+
+If the user passed `--depth quick`, output is condensed: skip "Agent perspectives" details, drop the matrix to 2-3 options, and replace the recommendation paragraph with one sentence.
+
+## Edge Cases
+
+- **Topic is too vague** ("help me think about scaling") → ask one clarifying question first; do not run research blindly.
+- **Topic is purely internal** (only repo-specific, no public reference) → suggest `--no-web` and note that web research is unlikely to add value.
+- **Topic touches a regulated domain** (PCI, HIPAA, GDPR, SOX) → flag the regulatory angle in the Open questions section even if the user did not mention it. Do not produce legal/compliance advice — point at the right specialists/docs.
+- **Web search returns thin results** → state honestly: "Web research surfaced limited material; the recommendation leans on agent perspectives and codebase context." Do not invent citations.
+- **Agent reports "not enough context"** → record it and proceed; do not retry with more context just to force an opinion.
+- **The user wants implementation, not brainstorm** → redirect: "This sounds like a `/squad` task. `/brainstorm` is for pre-implementation exploration."
+
+## Boundaries
+
+- This skill never edits files.
+- This skill never runs state-mutating git commands.
+- This skill never claims authority for legal/regulatory/compliance verdicts — it points at sources and specialists.
+- This skill never invents URLs or sources. If unsure, omit the citation and note the gap.
+- This skill produces text only.
+
+## Considerations
+
+### Cost vs depth
+- `quick`: ~3 web queries + 1 agent. Roughly 5-10K tokens. Useful for quick reality-checks.
+- `medium` (default): ~6 queries + 2-3 agents. ~20-40K tokens. Useful for genuine option exploration.
+- `deep`: ~10+ queries + 4 agents + tech-lead. ~60-100K tokens. Useful for high-stakes decisions where multiple stakeholders need to align.
+
+### When to use vs alternatives
+- Use `/brainstorm` when: deciding *what* to build, comparing approaches, scanning industry, exploring a problem space.
+- Use `/squad` when: you've decided and want to implement.
+- Use `/squad-review` when: implementation is done and you want a multi-perspective review.
+- Use `WebSearch` directly when: you need one specific answer, not a brainstorm framing.
+
+### Sources reliability
+Prefer (in this order): official docs, recognized engineering blogs (e.g., Stripe, AWS, Cloudflare, Google Cloud, Microsoft, Netflix Tech Blog), academic / standards bodies, recognized newsletters (Pragmatic Engineer, Increment), GitHub READMEs of widely-adopted libraries, conference talks. Avoid: SEO listicles, vendor-marketing pieces masquerading as articles, AI-generated content farms.
+
+### Output format consistency
+Always close with a "Next steps" block and a flat list of all sources used. The Next steps block is the bridge from brainstorm to action — never omit it.