sequant 2.6.2 → 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/commands/sync.d.ts

@@ -7,6 +7,7 @@
 interface SyncOptions {
     force?: boolean;
     quiet?: boolean;
+    dryRun?: boolean;
 }
 /**
  * Get the version of skills currently installed

package/dist/src/commands/sync.js

@@ -181,7 +181,7 @@ async function updateSkillsVersion() {
     await writeFile(SKILLS_VERSION_PATH, getPackageVersion());
 }
 export async function syncCommand(options = {}) {
-    const { force = false, quiet = false } = options;
+    const { force = false, quiet = false, dryRun = false } = options;
     if (!quiet) {
         console.log(chalk.blue("\nSyncing templates...\n"));
         console.log(chalk.yellow("Note: For seamless auto-updates, install sequant as a Claude Code plugin:\n" +
@@ -231,6 +231,61 @@ export async function syncCommand(options = {}) {
         process.exitCode = 1;
         return;
     }
+    // Preview path: report exactly what the apply would write, then stop without
+    // mutating (#722). This branch is only reached when `force` is set or the
+    // version marker mismatches — i.e. the path that runs `copyTemplates(force:
+    // true)` and rewrites the whole tree. (A matching-version, non-force dry-run
+    // already returned at the report-only short-circuit above, which never
+    // mutates.) `copyTemplates` does NOT protect in-place customizations the way
+    // `update` does — the force copy overwrites them — so the preview counts
+    // `local-override` files alongside `new`/`modified`. Reporting only
+    // new+modified would under-report the write-set, the exact divergence #722
+    // is about.
+    if (dryRun) {
+        const changes = await computeTemplateChanges(manifest.stack, tokens);
+        const newFiles = changes.filter((c) => c.status === "new");
+        const modifiedFiles = changes.filter((c) => c.status === "modified");
+        const localOverrides = changes.filter((c) => c.status === "local-override");
+        const toWrite = [...newFiles, ...modifiedFiles, ...localOverrides];
+        if (!quiet) {
+            console.log(chalk.bold("Summary (dry-run):"));
+            console.log(chalk.green(`  New files: ${newFiles.length}`));
+            console.log(chalk.yellow(`  Modified: ${modifiedFiles.length}`));
+            console.log(chalk.blue(`  Local overrides (overwritten by sync): ${localOverrides.length}`));
+            if (modifiedFiles.length > 0) {
+                console.log(chalk.bold("\nModified files:"));
+                for (const file of modifiedFiles) {
+                    console.log(chalk.yellow(`  ${file.path}`));
+                }
+            }
+            if (newFiles.length > 0) {
+                console.log(chalk.bold("\nNew files:"));
+                for (const file of newFiles) {
+                    console.log(chalk.green(`  ${file.path}`));
+                }
+            }
+            if (localOverrides.length > 0) {
+                console.log(chalk.bold("\nLocal overrides (will be overwritten by sync):"));
+                for (const file of localOverrides) {
+                    console.log(chalk.blue(`  ${file.path}`));
+                }
+            }
+            if (toWrite.length === 0) {
+                console.log(chalk.green("\n✔ Skills are already up to date!"));
+            }
+            else {
+                console.log(chalk.gray("\n(dry-run mode - no changes made)"));
+            }
+        }
+        // Non-zero exit when work is pending so the documented preview surface can
+        // gate CI/automation (the #709 intent): a dry-run reporting nothing must
+        // mean nothing to do. The matching-version short-circuit signals drift the
+        // same way.
+        if (toWrite.length > 0) {
+            process.exitCode = 1;
+        }
+        return;
+    }
     // Copy templates with force to overwrite existing files
     const copyOptions = {
         force: true, // Always overwrite when syncing

package/dist/src/commands/update.js

@@ -167,6 +167,13 @@ export async function updateCommand(options) {
     }
     if (options.dryRun) {
         console.log(chalk.gray("\n(dry-run mode - no changes made)"));
+        // Non-zero exit when work is pending so a CI/automation job can gate on the
+        // preview, matching `sync --dry-run` (#724 / #709 intent): a dry-run that
+        // reports nothing must mean nothing to do. The no-op case short-circuits at
+        // the "Everything is up to date!" return above, so it correctly stays 0.
+        if (applySet.length > 0) {
+            process.exitCode = 1;
+        }
         return;
     }
     // Confirm update. --yes and --force both auto-confirm; otherwise we need a

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.