sauron-cli 1.3.0 → 1.4.0

package/OpenSpec-main/schemas/spec-driven/schema.yaml

@@ -1,153 +0,0 @@
-name: spec-driven
-version: 1
-description: Default OpenSpec workflow - proposal → specs → design → tasks
-artifacts:
-  - id: proposal
-    generates: proposal.md
-    description: Initial proposal document outlining the change
-    template: proposal.md
-    instruction: |
-      Create the proposal document that establishes WHY this change is needed.
-
-      Sections:
-      - **Why**: 1-2 sentences on the problem or opportunity. What problem does this solve? Why now?
-      - **What Changes**: Bullet list of changes. Be specific about new capabilities, modifications, or removals. Mark breaking changes with **BREAKING**.
-      - **Capabilities**: Identify which specs will be created or modified:
-        - **New Capabilities**: List capabilities being introduced. Each becomes a new `specs/<name>/spec.md`. Use kebab-case names (e.g., `user-auth`, `data-export`).
-        - **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Check `openspec/specs/` for existing spec names. Leave empty if no requirement changes.
-      - **Impact**: Affected code, APIs, dependencies, or systems.
-
-      IMPORTANT: The Capabilities section is critical. It creates the contract between
-      proposal and specs phases. Research existing specs before filling this in.
-      Each capability listed here will need a corresponding spec file.
-
-      Keep it concise (1-2 pages). Focus on the "why" not the "how" -
-      implementation details belong in design.md.
-
-      This is the foundation - specs, design, and tasks all build on this.
-    requires: []
-
-  - id: specs
-    generates: "specs/**/*.md"
-    description: Detailed specifications for the change
-    template: spec.md
-    instruction: |
-      Create specification files that define WHAT the system should do.
-
-      Create one spec file per capability listed in the proposal's Capabilities section.
-      - New capabilities: use the exact kebab-case name from the proposal (specs/<capability>/spec.md).
-      - Modified capabilities: use the existing spec folder name from openspec/specs/<capability>/ when creating the delta spec at specs/<capability>/spec.md.
-
-      Delta operations (use ## headers):
-      - **ADDED Requirements**: New capabilities
-      - **MODIFIED Requirements**: Changed behavior - MUST include full updated content
-      - **REMOVED Requirements**: Deprecated features - MUST include **Reason** and **Migration**
-      - **RENAMED Requirements**: Name changes only - use FROM:/TO: format
-
-      Format requirements:
-      - Each requirement: `### Requirement: <name>` followed by description
-      - Use SHALL/MUST for normative requirements (avoid should/may)
-      - Each scenario: `#### Scenario: <name>` with WHEN/THEN format
-      - **CRITICAL**: Scenarios MUST use exactly 4 hashtags (`####`). Using 3 hashtags or bullets will fail silently.
-      - Every requirement MUST have at least one scenario.
-
-      MODIFIED requirements workflow:
-      1. Locate the existing requirement in openspec/specs/<capability>/spec.md
-      2. Copy the ENTIRE requirement block (from `### Requirement:` through all scenarios)
-      3. Paste under `## MODIFIED Requirements` and edit to reflect new behavior
-      4. Ensure header text matches exactly (whitespace-insensitive)
-
-      Common pitfall: Using MODIFIED with partial content loses detail at archive time.
-      If adding new concerns without changing existing behavior, use ADDED instead.
-
-      Example:
-      ```
-      ## ADDED Requirements
-
-      ### Requirement: User can export data
-      The system SHALL allow users to export their data in CSV format.
-
-      #### Scenario: Successful export
-      - **WHEN** user clicks "Export" button
-      - **THEN** system downloads a CSV file with all user data
-
-      ## REMOVED Requirements
-
-      ### Requirement: Legacy export
-      **Reason**: Replaced by new export system
-      **Migration**: Use new export endpoint at /api/v2/export
-      ```
-
-      Specs should be testable - each scenario is a potential test case.
-    requires:
-      - proposal
-
-  - id: design
-    generates: design.md
-    description: Technical design document with implementation details
-    template: design.md
-    instruction: |
-      Create the design document that explains HOW to implement the change.
-
-      When to include design.md (create only if any apply):
-      - Cross-cutting change (multiple services/modules) or new architectural pattern
-      - New external dependency or significant data model changes
-      - Security, performance, or migration complexity
-      - Ambiguity that benefits from technical decisions before coding
-
-      Sections:
-      - **Context**: Background, current state, constraints, stakeholders
-      - **Goals / Non-Goals**: What this design achieves and explicitly excludes
-      - **Decisions**: Key technical choices with rationale (why X over Y?). Include alternatives considered for each decision.
-      - **Risks / Trade-offs**: Known limitations, things that could go wrong. Format: [Risk] → Mitigation
-      - **Migration Plan**: Steps to deploy, rollback strategy (if applicable)
-      - **Open Questions**: Outstanding decisions or unknowns to resolve
-
-      Focus on architecture and approach, not line-by-line implementation.
-      Reference the proposal for motivation and specs for requirements.
-
-      Good design docs explain the "why" behind technical decisions.
-    requires:
-      - proposal
-
-  - id: tasks
-    generates: tasks.md
-    description: Implementation checklist with trackable tasks
-    template: tasks.md
-    instruction: |
-      Create the task list that breaks down the implementation work.
-
-      **IMPORTANT: Follow the template below exactly.** The apply phase parses
-      checkbox format to track progress. Tasks not using `- [ ]` won't be tracked.
-
-      Guidelines:
-      - Group related tasks under ## numbered headings
-      - Each task MUST be a checkbox: `- [ ] X.Y Task description`
-      - Tasks should be small enough to complete in one session
-      - Order tasks by dependency (what must be done first?)
-
-      Example:
-      ```
-      ## 1. Setup
-
-      - [ ] 1.1 Create new module structure
-      - [ ] 1.2 Add dependencies to package.json
-
-      ## 2. Core Implementation
-
-      - [ ] 2.1 Implement data export function
-      - [ ] 2.2 Add CSV formatting utilities
-      ```
-
-      Reference specs for what needs to be built, design for how to build it.
-      Each task should be verifiable - you know when it's done.
-    requires:
-      - specs
-      - design
-
-apply:
-  requires: [tasks]
-  tracks: tasks.md
-  instruction: |
-    Read context files, work through pending tasks, mark complete as you go.
-    Pause if you hit blockers or need clarification.

package/OpenSpec-main/schemas/spec-driven/templates/design.md

@@ -1,19 +0,0 @@
-## Context
-
-<!-- Background and current state -->
-
-## Goals / Non-Goals
-
-**Goals:**
-<!-- What this design aims to achieve -->
-
-**Non-Goals:**
-<!-- What is explicitly out of scope -->
-
-## Decisions
-
-<!-- Key design decisions and rationale -->
-
-## Risks / Trade-offs
-
-<!-- Known risks and trade-offs -->

package/OpenSpec-main/schemas/spec-driven/templates/proposal.md

@@ -1,23 +0,0 @@
-## Why
-
-<!-- Explain the motivation for this change. What problem does this solve? Why now? -->
-
-## What Changes
-
-<!-- Describe what will change. Be specific about new capabilities, modifications, or removals. -->
-
-## Capabilities
-
-### New Capabilities
-<!-- Capabilities being introduced. Replace <name> with kebab-case identifier (e.g., user-auth, data-export, api-rate-limiting). Each creates specs/<name>/spec.md -->
-- `<name>`: <brief description of what this capability covers>
-
-### Modified Capabilities
-<!-- Existing capabilities whose REQUIREMENTS are changing (not just implementation).
-     Only list here if spec-level behavior changes. Each needs a delta spec file.
-     Use existing spec names from openspec/specs/. Leave empty if no requirement changes. -->
-- `<existing-name>`: <what requirement is changing>
-
-## Impact
-
-<!-- Affected code, APIs, dependencies, systems -->

package/OpenSpec-main/schemas/spec-driven/templates/spec.md

@@ -1,8 +0,0 @@
-## ADDED Requirements
-
-### Requirement: <!-- requirement name -->
-<!-- requirement text -->
-
-#### Scenario: <!-- scenario name -->
-- **WHEN** <!-- condition -->
-- **THEN** <!-- expected outcome -->

package/OpenSpec-main/schemas/spec-driven/templates/tasks.md

@@ -1,9 +0,0 @@
-## 1. <!-- Task Group Name -->
-
-- [ ] 1.1 <!-- Task description -->
-- [ ] 1.2 <!-- Task description -->
-
-## 2. <!-- Task Group Name -->
-
-- [ ] 2.1 <!-- Task description -->
-- [ ] 2.2 <!-- Task description -->

package/OpenSpec-main/schemas/workspace-planning/schema.yaml

@@ -1,72 +0,0 @@
-name: workspace-planning
-version: 1
-description: Workspace planning workflow for cross-area changes
-artifacts:
-  - id: proposal
-    generates: proposal.md
-    description: Shared workspace proposal with the product goal, scope, affected areas, and impact
-    template: proposal.md
-    instruction: |
-      Create the workspace-level proposal that captures the shared product goal once.
-
-      Sections:
-      - **Why**: Explain the product goal or problem in 1-2 concise paragraphs.
-      - **What Changes**: List the cross-area behavior, workflow, or capability changes.
-      - **Affected Areas**: Name known affected areas using registered workspace link names where applicable. If scope is still being explored, say what remains unresolved.
-      - **Capabilities**: Identify workspace-scoped capabilities that need specs. Area-specific requirements should later live under `specs/<area-or-repo>/<capability>/spec.md`.
-      - **Impact**: Summarize user-facing impact, planning impact, and likely implementation homes without creating repo-local artifacts.
-
-      Keep linked repos and folders as exploration context until an explicit implementation workflow selects an affected area.
-    requires: []
-
-  - id: specs
-    generates: "specs/**/*.md"
-    description: Workspace-scoped specs organized by affected area and capability
-    template: spec.md
-    instruction: |
-      Create workspace-scoped specification files that define WHAT should change.
-
-      Use `specs/<area-or-repo>/<capability>/spec.md` for area-specific requirements. The first path segment should be a registered workspace link name when a registered area owns the requirement. If the area is unresolved, use an exploratory area name and make the unresolved question explicit in the requirement or scenario.
-
-      These specs are planning artifacts under the workspace change root. Do not create repo-local spec files in linked repos during workspace planning.
-
-      Delta operations (use ## headers):
-      - **ADDED Requirements**: New workspace-scoped behavior.
-      - **MODIFIED Requirements**: Changed behavior; include the full updated requirement.
-      - **REMOVED Requirements**: Deprecated behavior with Reason and Migration.
-      - **RENAMED Requirements**: Name changes only; use FROM:/TO: format.
-
-      Each requirement must use SHALL/MUST language and include at least one `#### Scenario:` block.
-    requires:
-      - proposal
-
-  - id: design
-    generates: design.md
-    description: Cross-area technical design and coordination decisions
-    template: design.md
-    instruction: |
-      Create the cross-area design document for workspace planning.
-
-      Focus on decisions that affect multiple areas, handoffs between areas, shared constraints, sequencing risks, and how the workspace plan should stay the source of truth. Avoid line-by-line implementation details and do not instruct agents to edit linked repos until an explicit implementation workflow provides an allowed edit root.
-    requires:
-      - proposal
-
-  - id: tasks
-    generates: tasks.md
-    description: Coordination checklist for workspace planning and later affected-area implementation
-    template: tasks.md
-    instruction: |
-      Create the workspace coordination task list.
-
-      Group tasks by phase or affected area as useful. Each actionable item must be a checkbox using `- [ ]`. When implementation tasks are area-specific, name the affected area and keep the task at planning granularity until a later implementation workflow selects an allowed edit root.
-    requires:
-      - specs
-      - design
-
-apply:
-  requires: [tasks]
-  tracks: tasks.md
-  instruction: |
-    Read the workspace planning context from status and instructions output before applying.
-    Select an affected area and confirm an allowed edit root before making implementation edits.
-    Until an explicit implementation context is available, treat linked repos and folders as read-only exploration context.

package/OpenSpec-main/schemas/workspace-planning/templates/design.md

@@ -1,33 +0,0 @@
-## Context
-
-Summarize the workspace planning context, relevant linked areas, and constraints.
-
-## Goals / Non-Goals
-
-**Goals:**
--
-
-**Non-Goals:**
-- Creating repo-local implementation artifacts before an affected area is selected.
-
-## Decisions
-
-### Decision: <title>
-
-<decision and rationale>
-
-Alternative considered: <alternative and why it was not chosen>
-
-## Risks / Trade-offs
-
-- <risk> -> <mitigation>
-
-## Coordination Notes
-
-- Affected areas:
-- Open handoffs:
-- Implementation entry criteria:
-
-## Open Questions
-
--

package/OpenSpec-main/schemas/workspace-planning/templates/proposal.md

@@ -1,28 +0,0 @@
-## Why
-
-Describe the shared product goal, problem, or opportunity that makes this workspace-level change worth planning.
-
-## What Changes
-
--
-
-## Affected Areas
-
-- Known:
-- Unresolved:
-
-## Capabilities
-
-### New Capabilities
-
--
-
-### Modified Capabilities
-
--
-
-## Impact
-
-- Workspace planning:
-- Linked repos or folders:
-- User-facing behavior:

package/OpenSpec-main/schemas/workspace-planning/templates/spec.md

@@ -1,9 +0,0 @@
-## ADDED Requirements
-
-### Requirement: <workspace requirement name>
-The workspace plan SHALL describe the required behavior and affected area without creating repo-local artifacts during planning.
-
-#### Scenario: <scenario name>
-- **GIVEN** <context>
-- **WHEN** <action>
-- **THEN** <observable result>

package/OpenSpec-main/schemas/workspace-planning/templates/tasks.md

@@ -1,15 +0,0 @@
-## 1. Workspace Planning
-
-- [ ] 1.1 Confirm the shared product goal and unresolved scope questions.
-- [ ] 1.2 Identify affected areas using registered workspace link names where applicable.
-- [ ] 1.3 Review workspace-scoped specs and design before selecting implementation areas.
-
-## 2. Affected Area Implementation
-
-- [ ] 2.1 Select an affected area and confirm its allowed edit root before implementation.
-- [ ] 2.2 Create or update repo-local implementation artifacts only after the area is selected.
-
-## 3. Verification
-
-- [ ] 3.1 Verify workspace planning artifacts remain the source of truth.
-- [ ] 3.2 Record manual acceptance evidence and follow-up fixes.

package/OpenSpec-main/scripts/README.md

@@ -1,37 +0,0 @@
-# OpenSpec Scripts
-
-Utility scripts for OpenSpec maintenance and development.
-
-## update-flake.sh
-
-Updates `flake.nix` pnpm dependency hash automatically.
-
-**When to use**: After updating dependencies (`pnpm install`, `pnpm update`).
-
-**Usage**:
-```bash
-./scripts/update-flake.sh
-```
-
-**What it does**:
-1. Reads version from `package.json` (dynamically used by `flake.nix`)
-2. Automatically determines the correct pnpm dependency hash
-3. Updates the hash in `flake.nix`
-4. Verifies the build succeeds
-
-**Example workflow**:
-```bash
-# After dependency updates
-pnpm install
-./scripts/update-flake.sh
-git add flake.nix
-git commit -m "chore: update flake.nix dependency hash"
-```
-
-## postinstall.js
-
-Post-installation script that runs after package installation.
-
-## pack-version-check.mjs
-
-Validates package version consistency before publishing.

package/OpenSpec-main/scripts/pack-version-check.mjs

@@ -1,111 +0,0 @@
-#!/usr/bin/env node
-// Guard: Ensure the packed tarball's CLI `--version` matches package.json.
-//
-// Notes:
-// - We intentionally use `npm pack` (not pnpm) because `npm pack --json` is
-//   consistently supported and returns the tarball metadata we need. The
-//   project uses pnpm for install/publish, but this guard only needs to pack
-//   locally and verify the installed CLI output.
-// - `npm pack` triggers the package's `prepare` script (build), and
-//   `changeset publish` triggers `prepublishOnly` (also builds here). This
-//   means an explicit build is not strictly necessary for the guard.
-
-import { execFileSync } from 'child_process';
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs';
-import { tmpdir } from 'os';
-import path from 'path';
-
-function log(msg) {
-  if (process.env.CI) return; // keep CI logs quiet by default
-  console.log(msg);
-}
-
-function run(cmd, args, opts = {}) {
-  return execFileSync(cmd, args, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'], ...opts });
-}
-
-function npmPack() {
-  try {
-    const jsonOut = run('npm', ['pack', '--json', '--silent']);
-    const arr = JSON.parse(jsonOut);
-    if (Array.isArray(arr) && arr.length > 0) {
-      const last = arr[arr.length - 1];
-      const file = (last && typeof last === 'object' && last.filename) || (typeof last === 'string' ? last : null);
-      if (file) return String(file).trim();
-    }
-    // Unexpected JSON shape or empty array; fallback to plain output
-    const out = run('npm', ['pack', '--silent']).trim();
-    const lines = out.split(/\r?\n/);
-    return lines[lines.length - 1].trim();
-  } catch (e) {
-    // Fallback for environments not supporting --json
-    const out = run('npm', ['pack', '--silent']).trim();
-    const lines = out.split(/\r?\n/);
-    return lines[lines.length - 1].trim();
-  }
-}
-
-function main() {
-  const pkg = JSON.parse(readFileSync(path.join(process.cwd(), 'package.json'), 'utf-8'));
-  const expected = pkg.version;
-
-  let work;
-  let tgzPath;
-
-  try {
-    log(`Packing @fission-ai/openspec@${expected}...`);
-    const filename = npmPack();
-    tgzPath = path.resolve(filename);
-    log(`Created: ${tgzPath}`);
-
-    work = mkdtempSync(path.join(tmpdir(), 'openspec-pack-check-'));
-    log(`Temp dir: ${work}`);
-
-    // Make a tiny project
-    writeFileSync(
-      path.join(work, 'package.json'),
-      JSON.stringify({ name: 'pack-check', private: true }, null, 2)
-    );
-
-    // Try to avoid noisy output and speed up
-    const env = {
-      ...process.env,
-      npm_config_loglevel: 'silent',
-      npm_config_audit: 'false',
-      npm_config_fund: 'false',
-      npm_config_progress: 'false',
-    };
-
-    // Install the tarball
-    run('npm', ['install', tgzPath, '--silent', '--no-audit', '--no-fund'], { cwd: work, env });
-
-    // Run the installed CLI via Node to avoid bin resolution/platform issues
-    const binRel = path.join('node_modules', '@fission-ai', 'openspec', 'bin', 'openspec.js');
-    const actual = run(process.execPath, [binRel, '--version'], { cwd: work }).trim();
-
-    if (actual !== expected) {
-      throw new Error(
-        `Packed CLI version mismatch: expected ${expected}, got ${actual}. ` +
-          'Ensure the dist is built and the CLI reads version from package.json.'
-      );
-    }
-
-    log('Version check passed.');
-  } finally {
-    // Always attempt cleanup
-    if (work) {
-      try { rmSync(work, { recursive: true, force: true }); } catch {}
-    }
-    if (tgzPath) {
-      try { rmSync(tgzPath, { force: true }); } catch {}
-    }
-  }
-}
-
-try {
-  main();
-  console.log('✅ pack-version-check: OK');
-} catch (err) {
-  console.error(`❌ pack-version-check: ${err.message}`);
-  process.exit(1);
-}

package/OpenSpec-main/scripts/postinstall.js

@@ -1,83 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Postinstall script that hints about shell completions
- *
- * Completion installation is opt-in: the user must run
- * `openspec completion install` explicitly. This script only
- * prints a one-line tip after npm install.
- *
- * The tip is suppressed when:
- * - CI=true environment variable is set
- * - OPENSPEC_NO_COMPLETIONS=1 environment variable is set
- * - dist/ directory doesn't exist (dev setup scenario)
- *
- * The script never fails npm install - all errors are caught and handled gracefully.
- */
-
-import { promises as fs } from 'fs';
-import path from 'path';
-import { fileURLToPath } from 'url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-/**
- * Check if we should skip installation
- */
-function shouldSkipInstallation() {
-  // Skip in CI environments
-  if (process.env.CI === 'true' || process.env.CI === '1') {
-    return { skip: true, reason: 'CI environment detected' };
-  }
-
-  // Skip if user opted out
-  if (process.env.OPENSPEC_NO_COMPLETIONS === '1') {
-    return { skip: true, reason: 'OPENSPEC_NO_COMPLETIONS=1 set' };
-  }
-
-  return { skip: false };
-}
-
-/**
- * Check if dist/ directory exists
- */
-async function distExists() {
-  const distPath = path.join(__dirname, '..', 'dist');
-  try {
-    const stat = await fs.stat(distPath);
-    return stat.isDirectory();
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Main function
- */
-async function main() {
-  try {
-    // Check if we should skip
-    const skipCheck = shouldSkipInstallation();
-    if (skipCheck.skip) {
-      // Silent skip - no output
-      return;
-    }
-
-    // Check if dist/ exists (skip silently if not - expected during dev setup)
-    if (!(await distExists())) {
-      return;
-    }
-
-    // Completions are opt-in — just print a hint
-    console.log(`\nTip: Run 'openspec completion install' for shell completions`);
-  } catch (error) {
-    // Fail gracefully - never break npm install
-  }
-}
-
-// Run main and handle any unhandled errors
-main().catch(() => {
-  // Silent failure - never break npm install
-  process.exit(0);
-});

package/OpenSpec-main/scripts/test-postinstall.sh

@@ -1,57 +0,0 @@
-#!/bin/bash
-
-# Test script for postinstall.js
-# Tests different scenarios: normal install, CI, opt-out
-
-set -e
-
-echo "======================================"
-echo "Testing OpenSpec Postinstall Script"
-echo "======================================"
-echo ""
-
-# Save original environment
-ORIGINAL_CI="${CI:-}"
-ORIGINAL_OPENSPEC_NO_COMPLETIONS="${OPENSPEC_NO_COMPLETIONS:-}"
-
-# Test 1: Normal install
-echo "Test 1: Normal install (should print tip about completions)"
-echo "--------------------------------------"
-unset CI
-unset OPENSPEC_NO_COMPLETIONS
-node scripts/postinstall.js
-echo ""
-
-# Test 2: CI environment (should skip silently)
-echo "Test 2: CI=true (should skip silently)"
-echo "--------------------------------------"
-export CI=true
-node scripts/postinstall.js
-echo "[No output expected - skipped due to CI]"
-echo ""
-
-# Test 3: Opt-out flag (should skip silently)
-echo "Test 3: OPENSPEC_NO_COMPLETIONS=1 (should skip silently)"
-echo "--------------------------------------"
-unset CI
-export OPENSPEC_NO_COMPLETIONS=1
-node scripts/postinstall.js
-echo "[No output expected - skipped due to opt-out]"
-echo ""
-
-# Restore original environment
-if [ -n "$ORIGINAL_CI" ]; then
-  export CI="$ORIGINAL_CI"
-else
-  unset CI
-fi
-
-if [ -n "$ORIGINAL_OPENSPEC_NO_COMPLETIONS" ]; then
-  export OPENSPEC_NO_COMPLETIONS="$ORIGINAL_OPENSPEC_NO_COMPLETIONS"
-else
-  unset OPENSPEC_NO_COMPLETIONS
-fi
-
-echo "======================================"
-echo "All tests completed successfully!"
-echo "======================================"