sequant 2.7.0 → 2.8.0

package/dist/marketplace/external_plugins/sequant/skills/upstream/SKILL.md

@@ -0,0 +1,419 @@
+---
+name: upstream
+description: "Monitor Claude Code releases, assess compatibility with sequant, and create issues for breaking changes and deprecations. Opportunities are noted in assessment reports for human triage."
+license: MIT
+metadata:
+  author: sequant
+  version: "1.0"
+allowed-tools:
+  - Read
+  - Write
+  - Glob
+  - Grep
+  - Bash(gh *)
+  - Bash(git *)
+  - Bash(jq *)
+  - Bash(base64 *)
+  - Bash(npx tsx *)
+---
+
+<!-- sequant:local-override -->
+> **Local overrides (read this first).** Before following any instruction below, check whether `.claude/.local/skills/upstream/overrides.md` exists. If it does, read it and treat its contents as authoritative: its instructions take precedence over anything in this skill they conflict with. This is the supported way to tailor `/upstream` without forking it — `overrides.md` lives under `.claude/.local/`, which `sequant update` and `sync` never overwrite.
+
+# Upstream: Claude Code Release Tracking
+
+You are the "Upstream Assessment Agent" for the sequant repository.
+
+## Purpose
+
+When invoked as `/upstream`, your job is to:
+
+1. Fetch Claude Code release information from the public GitHub repo
+2. Analyze changes against sequant's current capabilities baseline
+3. Detect relevant changes using keyword matching and regex patterns
+4. Skip out-of-scope changes (configured in baseline.json `outOfScope`)
+5. Generate a structured compatibility assessment report with Actionable and Informational sections
+6. Auto-create GitHub issues for breaking changes, deprecations, new tools, and hook changes
+7. List opportunities in the assessment report for human triage (no individual issues created)
+
+## Invocation
+
+```bash
+# Analyze latest release
+/upstream
+
+# Analyze specific version
+/upstream v2.1.29
+
+# Analyze all releases since version
+/upstream --since v2.1.25
+
+# Dry-run mode (no issues created)
+/upstream --dry-run
+
+# Help
+/upstream --help
+```
+
+## Assessment Process
+
+### 1. Parse Arguments
+
+Parse the command arguments to determine:
+
+- **Target version**: Specific version (e.g., `v2.1.29`) or `latest`
+- **Since version**: If `--since` flag provided, assess all versions since that release
+- **Dry-run mode**: If `--dry-run` flag, generate report but skip issue creation
+- **Help**: If `--help` flag, show usage instructions
+
+### 2. Fetch Release Data
+
+Fetch release information from the public Claude Code repository:
+
+```bash
+# Get latest release
+gh release view --repo anthropics/claude-code --json tagName,name,body,publishedAt
+
+# Get specific version
+gh release view v2.1.29 --repo anthropics/claude-code --json tagName,name,body,publishedAt
+
+# List releases for --since support
+gh release list --repo anthropics/claude-code --limit 50 --json tagName,publishedAt
+```
+
+### 3. Load Baseline
+
+Load the sequant capabilities baseline from `.sequant/upstream/baseline.json`:
+
+```json
+{
+  "lastAssessedVersion": "v2.1.25",
+  "tools": {
+    "core": ["Task", "Bash", "Read", "Write", "Edit", "Glob", "Grep"],
+    "optional": ["WebFetch", "WebSearch", "NotebookEdit"]
+  },
+  "hooks": {
+    "used": ["PreToolUse"],
+    "files": ["src/hooks/pre-tool-hook.ts"]
+  },
+  "mcpServers": {
+    "required": [],
+    "optional": ["chrome-devtools", "context7", "sequential-thinking"]
+  },
+  "keywords": [
+    "Task", "Bash", "hook", "PreToolUse", "PostToolUse",
+    "MCP", "permission", "allow", "deny", "tool",
+    "background", "parallel", "agent", "subagent",
+    "settings", "config", "plugin"
+  ],
+  "dependencyMap": {
+    "permission": ["src/hooks/pre-tool-hook.ts", ".claude/settings.json"],
+    "hook": ["src/hooks/pre-tool-hook.ts"],
+    "Task": [".claude/skills/**/*.md", "src/lib/workflow/*.ts"],
+    "MCP": ["docs/mcp-integrations.md", ".claude/settings.json"]
+  },
+  "outOfScope": [
+    "PDF/document processing - users work with code and GitHub issues",
+    "Slack/OAuth integrations - workflow is GitHub-centric",
+    "Notebook editing - not a data science tool",
+    "IDE-specific features (VSCode, JetBrains) - sequant is CLI/terminal focused",
+    "Windows-specific fixes - sequant targets macOS/Linux"
+  ]
+}
+```
+
+### 4. Analyze Changes
+
+For each release, analyze the changelog/release body:
+
+**Step 1: Extract Changes**
+
+Parse the release body to extract individual change items. Common formats:
+- Bullet points: `- Added new feature X`
+- "What's changed" sections
+- BREAKING CHANGE markers
+
+**Step 2: Relevance Detection**
+
+For each change, check if it's relevant to sequant:
+
+```typescript
+// Keyword matching
+const isRelevant = baseline.keywords.some(kw =>
+  change.toLowerCase().includes(kw.toLowerCase())
+);
+
+// Pattern matching
+const patterns = {
+  newTool: /added.*tool|new.*tool|introducing/i,
+  deprecation: /deprecat|remov|no longer support/i,
+  breaking: /breaking|incompatible|must update/i,
+  hook: /hook|PreToolUse|PostToolUse/i,
+  permission: /permission|allow|deny|ask/i,
+};
+```
+
+**Step 3: Categorize**
+
+Categorize each relevant change:
+
+| Category | Detection Pattern | Issue Labels |
+|----------|------------------|--------------|
+| `breaking` | Breaking, incompatible, must update | `upstream`, `bug`, `priority:high` |
+| `deprecation` | Deprecated, removed, no longer supported | `upstream`, `bug` |
+| `new-tool` | Added tool, new tool, introducing | `upstream`, `enhancement` |
+| `hook-change` | Hook, PreToolUse, PostToolUse | `upstream`, `enhancement` |
+| `opportunity` | Keywords match but not above categories | (no issue — noted in assessment for human triage) |
+| `no-action` | Doesn't match patterns or keywords | (no issue) |
+
+**Step 4: Impact Mapping**
+
+For relevant changes, map to affected sequant files using `dependencyMap`:
+
+```typescript
+const impactFiles = baseline.dependencyMap[matchedKeyword] || [];
+```
+
+### 5. Check for Duplicates
+
+Before creating issues, check for existing upstream issues:
+
+```bash
+# Search for similar issues
+gh issue list --label upstream --search "<finding-title>" --json number,title
+```
+
+If a similar issue exists:
+- Add a comment linking to the new assessment
+- Skip creating a duplicate
+
+### 6. Generate Outputs
+
+**Output 1: Assessment Report (GitHub Issue)**
+
+Create a summary issue with the full assessment:
+
+```markdown
+## Upstream: Claude Code <version> Assessment
+
+**Release:** [<version>](https://github.com/anthropics/claude-code/releases/tag/<version>)
+**Released:** <date>
+**Assessed:** <today>
+
+### Summary
+
+| Category | Count | Action Required |
+|----------|-------|-----------------|
+| Breaking Changes | N | [status] |
+| New Tools | N | [status] |
+| Deprecations | N | [status] |
+| Opportunities | N | [status] |
+
+### Actionable
+
+*Breaking changes, deprecations, and other items that affect sequant.*
+
+[list of breaking, deprecation, new-tool, hook-change findings]
+
+### Informational
+
+*Opportunities noted for human triage. No individual issues auto-created.*
+
+[list of opportunity findings]
+
+### No Action Required
+
+[list of irrelevant changes]
+
+---
+
+*Generated by /upstream skill*
+```
+
+**Output 2: Individual Issues (Actionable Findings)**
+
+For each actionable finding (breaking, deprecation, new-tool, hook-change), create an issue.
+**Note:** Opportunities do NOT get individual issues — they are listed in the assessment report's Informational section for human triage.
+
+```markdown
+## feat: Leverage <feature> from Claude Code <version>
+
+**Upstream:** Claude Code <version>
+**Category:** <category>
+**Assessment:** #<assessment-issue>
+
+### Context
+
+<description from release notes>
+
+### Opportunity
+
+<how sequant could use this>
+
+### Proposed Implementation
+
+[To be determined during /spec phase]
+
+### Acceptance Criteria
+
+- [ ] AC-1: [To be defined]
+
+---
+
+*Auto-created by /upstream assessment #<N>*
+```
+
+Labels: `upstream`, `needs-triage`, `enhancement`
+
+**Output 3: Local Report**
+
+Save to `.sequant/upstream/<version>.md`:
+
+```markdown
+# Claude Code <version> Assessment
+
+Assessed: <date>
+Previous: <last-assessed-version>
+
+## Summary
+
+[same as GitHub issue]
+
+## Raw Findings
+
+[detailed analysis data]
+```
+
+**Output 4: Update Baseline**
+
+Update `.sequant/upstream/baseline.json`:
+- Set `lastAssessedVersion` to the assessed version
+
+### 7. Multi-Version Batching
+
+When `--since <version>` is used:
+
+1. List all releases after the specified version
+2. Assess each version individually
+3. Create a batched summary issue linking all individual assessments
+4. Update baseline to latest assessed version
+
+## Dry-Run Mode
+
+When `--dry-run` is specified:
+
+1. Perform full analysis
+2. Generate local report
+3. Output what issues WOULD be created (titles, labels)
+4. Skip actual GitHub issue creation
+5. Skip baseline update
+
+## Error Handling
+
+- **No releases found**: Exit with clear message
+- **Baseline missing**: Create default baseline, warn user
+- **GitHub API errors**: Retry with backoff, then fail gracefully
+- **Already assessed**: Skip with message (idempotent)
+
+## Output Verification
+
+**Before completing, verify:**
+
+- [ ] Release data successfully fetched
+- [ ] Baseline loaded (or created with defaults)
+- [ ] Each change categorized
+- [ ] Duplicates checked before issue creation
+- [ ] Assessment report created (or dry-run output shown)
+- [ ] Individual issues created for actionable findings (not opportunities)
+- [ ] Local report saved
+- [ ] Baseline updated with new version
+
+## Examples
+
+### Example 1: Assess Latest Release
+
+```
+/upstream
+
+Fetching latest Claude Code release...
+Release: v2.1.29 (2025-01-31)
+
+Loading baseline from .sequant/upstream/baseline.json...
+Last assessed: v2.1.27
+
+Analyzing 12 changes from release notes...
+- 3 relevant changes detected
+- 9 no-action changes
+
+Findings:
+1. [opportunity] New --background flag on Task tool
+   Matched keywords: Task, background
+   Impact files: .claude/skills/**/*.md
+
+2. [hook-change] Permissions now respect content-level ask
+   Matched keywords: permission
+   Impact files: src/hooks/pre-tool-hook.ts
+
+3. [deprecation] oldHookName deprecated
+   Matched pattern: deprecat
+   Impact files: src/hooks/pre-tool-hook.ts
+
+Creating assessment issue...
+Created: #250 - Upstream: Claude Code v2.1.29 Assessment
+
+Creating individual issues...
+Created: #251 - feat: Leverage new --background flag from Claude Code v2.1.29
+Created: #252 - chore: Update to new hook name (deprecation from v2.1.29)
+
+Saving local report to .sequant/upstream/v2.1.29.md...
+Updating baseline lastAssessedVersion to v2.1.29...
+
+Done! Assessment complete.
+```
+
+### Example 2: Dry Run
+
+```
+/upstream --dry-run
+
+[DRY RUN MODE - No issues will be created]
+
+Fetching latest Claude Code release...
+Release: v2.1.29 (2025-01-31)
+
+...analysis...
+
+Would create issues:
+1. Assessment: Upstream: Claude Code v2.1.29 Assessment
+2. Finding: feat: Leverage new --background flag from Claude Code v2.1.29
+3. Finding: chore: Update to new hook name (deprecation from v2.1.29)
+
+Local report saved: .sequant/upstream/v2.1.29.md
+Baseline NOT updated (dry-run mode)
+```
+
+### Example 3: Already Assessed
+
+```
+/upstream
+
+Fetching latest Claude Code release...
+Release: v2.1.29 (2025-01-31)
+
+Already assessed: .sequant/upstream/v2.1.29.md exists
+Use --force to re-assess.
+
+No action taken.
+```
+
+## Notes
+
+- This is an internal tool for sequant maintainers
+- All created issues get `needs-triage` label for human review
+- The skill is read-only for Claude Code repo (no PRs or edits)
+- Baseline file should be committed to version control
+- Local reports in `.sequant/upstream/` should be committed
+
+---
+
+*This skill monitors the upstream Claude Code project to help sequant stay current with new features and breaking changes.*

package/dist/src/lib/errors.d.ts

@@ -86,6 +86,91 @@ export declare class SubprocessError extends SequantError {
     readonly metadata: SubprocessErrorMetadata;
     constructor(message: string, metadata?: SubprocessErrorMetadata, cause?: Error);
 }
+/**
+ * Metadata carried by {@link RateLimitError} / {@link BillingError}.
+ *
+ * Fields mirror the structured signals the Claude Agent SDK emits via
+ * `rate_limit_event` (`SDKRateLimitInfo`). The `canUserPurchaseCredits` /
+ * `hasChargeableSavedPaymentMethod` fields arrived in SDK 0.3.181 and are
+ * optional so older streams (or absent fields) degrade gracefully.
+ */
+export interface RateLimitMetadata {
+    [key: string]: unknown;
+    /** Unix timestamp (seconds or ms) at which the limit resets. */
+    resetsAt?: number;
+    /** Which limit window was hit (five_hour, seven_day, overage, …). */
+    rateLimitType?: string;
+    /** Why overage/billing was disabled (e.g. `out_of_credits`). */
+    overageDisabledReason?: string;
+    /** SDK error code; `credits_required` indicates a billing failure. */
+    errorCode?: string;
+    /** Whether the user can self-serve purchase credits (≥0.3.181). */
+    canUserPurchaseCredits?: boolean;
+    /** Whether a chargeable payment method is on file (≥0.3.181). */
+    hasChargeableSavedPaymentMethod?: boolean;
+}
+/**
+ * Transient rate-limit error (HTTP 429-style throttle, overloaded API).
+ *
+ * Retryable: waiting and re-running can succeed once the limit window resets.
+ */
+export declare class RateLimitError extends SequantError {
+    readonly metadata: RateLimitMetadata;
+    constructor(message: string, metadata?: RateLimitMetadata, cause?: Error);
+}
+/**
+ * Billing / out-of-credits error.
+ *
+ * NOT retryable: a no-MCP retry (or any retry) cannot refill credits, so the
+ * executor must surface the real cause instead of looping. Drives the #592
+ * fallback-noise skip in phase-executor.
+ */
+export declare class BillingError extends SequantError {
+    readonly metadata: RateLimitMetadata;
+    constructor(message: string, metadata?: RateLimitMetadata, cause?: Error);
+}
+/**
+ * Structural subset of the SDK's `SDKRateLimitInfo` consumed when building a
+ * rate-limit error. Declared here (not imported from the SDK) so `errors.ts`
+ * stays SDK-free — only the driver owns the `@anthropic-ai/claude-agent-sdk`
+ * import.
+ */
+export interface RateLimitInfoLike {
+    status?: string;
+    resetsAt?: number;
+    rateLimitType?: string;
+    overageDisabledReason?: string;
+    errorCode?: string;
+    canUserPurchaseCredits?: boolean;
+    hasChargeableSavedPaymentMethod?: boolean;
+}
+/**
+ * True when the rate-limit info represents a billing/credits failure (which a
+ * retry cannot fix), rather than a transient throttle.
+ */
+export declare function isBillingFailure(info: RateLimitInfoLike): boolean;
+/**
+ * True when the rate-limit info represents an actual failure (rejection or
+ * billing), as opposed to an informational `allowed` / `allowed_warning`
+ * event. The driver uses this to avoid mis-attributing a stale warning event
+ * to an unrelated phase failure.
+ */
+export declare function isRateLimitFailureInfo(info: RateLimitInfoLike): boolean;
+/**
+ * Build a user-facing message from rate-limit info, naming the real cause:
+ * - billing/credits → "Out of credits" (enriched with purchasable vs hard
+ *   limit when the ≥0.3.181 `canUserPurchaseCredits` field is present)
+ * - transient throttle → "Rate limited — resets at HH:MM" (date-qualified as
+ *   "MM-DD HH:MM" when the reset is not today; reset time omitted entirely when
+ *   `resetsAt` is absent)
+ */
+export declare function formatRateLimitMessage(info: RateLimitInfoLike): string;
+/**
+ * Construct the appropriate typed error from structured rate-limit info.
+ * Billing/credits failures become a non-retryable {@link BillingError};
+ * transient throttles become a retryable {@link RateLimitError}.
+ */
+export declare function createRateLimitError(info: RateLimitInfoLike): RateLimitError | BillingError;
 /**
  * Map of error type names to their constructors.
  * Used for deserialization from logs.

package/dist/src/lib/errors.js

@@ -82,6 +82,115 @@ export class SubprocessError extends SequantError {
         this.name = "SubprocessError";
     }
 }
+/**
+ * Transient rate-limit error (HTTP 429-style throttle, overloaded API).
+ *
+ * Retryable: waiting and re-running can succeed once the limit window resets.
+ */
+export class RateLimitError extends SequantError {
+    constructor(message, metadata = {}, cause) {
+        super(message, { isRetryable: true, metadata, cause });
+        this.name = "RateLimitError";
+    }
+}
+/**
+ * Billing / out-of-credits error.
+ *
+ * NOT retryable: a no-MCP retry (or any retry) cannot refill credits, so the
+ * executor must surface the real cause instead of looping. Drives the #592
+ * fallback-noise skip in phase-executor.
+ */
+export class BillingError extends SequantError {
+    constructor(message, metadata = {}, cause) {
+        super(message, { isRetryable: false, metadata, cause });
+        this.name = "BillingError";
+    }
+}
+/**
+ * True when the rate-limit info represents a billing/credits failure (which a
+ * retry cannot fix), rather than a transient throttle.
+ */
+export function isBillingFailure(info) {
+    return (info.errorCode === "credits_required" ||
+        info.overageDisabledReason === "out_of_credits");
+}
+/**
+ * True when the rate-limit info represents an actual failure (rejection or
+ * billing), as opposed to an informational `allowed` / `allowed_warning`
+ * event. The driver uses this to avoid mis-attributing a stale warning event
+ * to an unrelated phase failure.
+ */
+export function isRateLimitFailureInfo(info) {
+    return info.status === "rejected" || isBillingFailure(info);
+}
+/**
+ * Format a Unix timestamp (seconds or ms) as a local time string.
+ *
+ * Bare `HH:MM` when the reset falls on the current local calendar day;
+ * date-qualified `MM-DD HH:MM` otherwise. Multi-day windows
+ * (`rateLimitType: seven_day*`) can reset days out — a bare `HH:MM` there reads
+ * as "later today" and misleads the user (#732 QA follow-up), so the date is
+ * included whenever the reset is not today.
+ */
+function formatResetTime(resetsAt) {
+    // Heuristic: values below ~1e12 are seconds, otherwise milliseconds.
+    const ms = resetsAt < 1e12 ? resetsAt * 1000 : resetsAt;
+    const d = new Date(ms);
+    const hh = String(d.getHours()).padStart(2, "0");
+    const mm = String(d.getMinutes()).padStart(2, "0");
+    const now = new Date();
+    const sameDay = d.getFullYear() === now.getFullYear() &&
+        d.getMonth() === now.getMonth() &&
+        d.getDate() === now.getDate();
+    if (sameDay) {
+        return `${hh}:${mm}`;
+    }
+    const mon = String(d.getMonth() + 1).padStart(2, "0");
+    const day = String(d.getDate()).padStart(2, "0");
+    return `${mon}-${day} ${hh}:${mm}`;
+}
+/**
+ * Build a user-facing message from rate-limit info, naming the real cause:
+ * - billing/credits → "Out of credits" (enriched with purchasable vs hard
+ *   limit when the ≥0.3.181 `canUserPurchaseCredits` field is present)
+ * - transient throttle → "Rate limited — resets at HH:MM" (date-qualified as
+ *   "MM-DD HH:MM" when the reset is not today; reset time omitted entirely when
+ *   `resetsAt` is absent)
+ */
+export function formatRateLimitMessage(info) {
+    if (isBillingFailure(info)) {
+        if (info.canUserPurchaseCredits === true) {
+            return "Out of credits — purchasable";
+        }
+        if (info.canUserPurchaseCredits === false) {
+            return "Out of credits — hard limit";
+        }
+        return "Out of credits";
+    }
+    if (info.resetsAt !== undefined) {
+        return `Rate limited — resets at ${formatResetTime(info.resetsAt)}`;
+    }
+    return "Rate limited";
+}
+/**
+ * Construct the appropriate typed error from structured rate-limit info.
+ * Billing/credits failures become a non-retryable {@link BillingError};
+ * transient throttles become a retryable {@link RateLimitError}.
+ */
+export function createRateLimitError(info) {
+    const message = formatRateLimitMessage(info);
+    const metadata = {
+        resetsAt: info.resetsAt,
+        rateLimitType: info.rateLimitType,
+        overageDisabledReason: info.overageDisabledReason,
+        errorCode: info.errorCode,
+        canUserPurchaseCredits: info.canUserPurchaseCredits,
+        hasChargeableSavedPaymentMethod: info.hasChargeableSavedPaymentMethod,
+    };
+    return isBillingFailure(info)
+        ? new BillingError(message, metadata)
+        : new RateLimitError(message, metadata);
+}
 /**
  * Map of error type names to their constructors.
  * Used for deserialization from logs.
@@ -94,4 +203,6 @@ export const ERROR_TYPE_MAP = {
     BuildError: BuildError,
     TimeoutError: TimeoutError,
     SubprocessError: SubprocessError,
+    RateLimitError: RateLimitError,
+    BillingError: BillingError,
 };

package/dist/src/lib/version-check.d.ts

@@ -114,6 +114,25 @@ export declare function fetchLatestVersion(): Promise<string | null>;
  * Returns: -1 if a < b, 0 if a == b, 1 if a > b
  */
 export declare function compareVersions(a: string, b: string): number;
+/**
+ * Pure preflight check for the running Node version against the engines floor.
+ *
+ * Returns an actionable, multi-line message when `current` is below `floor`,
+ * or `null` when it satisfies the floor (or when `floor` is missing/unparseable,
+ * in which case the guard is skipped rather than crashing the CLI).
+ *
+ * `floor` is the raw `engines.node` value (e.g. ">=22.12.0"); the leading range
+ * operator is stripped before comparison. Reuses {@link compareVersions} — no
+ * `semver` dependency.
+ */
+export declare function getNodeVersionError(current: string, floor: string | null | undefined): string | null;
+/**
+ * Side-effecting wrapper around {@link getNodeVersionError}: prints the message
+ * and exits non-zero when the running Node is below the floor. Uses only
+ * built-in globals (`process.version`, `console`, `process.exit`) so it runs —
+ * rather than crashes — on the old Node it rejects.
+ */
+export declare function assertNodeVersion(floor: string | null | undefined): void;
 /**
  * Check if the current version is outdated
  */