sequant 1.11.0 → 1.13.0

package/dist/src/lib/stack-config.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Stack configuration persistence
+ *
+ * Manages user's stack configuration in .sequant/stack.json
+ */
+/**
+ * Stack entry with optional path for subdirectory stacks
+ */
+export interface StackEntry {
+    name: string;
+    path?: string;
+}
+/**
+ * Persisted stack configuration
+ */
+export interface StackConfigFile {
+    /** Primary stack (determines dev URL and main commands) */
+    primary: StackEntry;
+    /** Additional stacks to include in constitution notes */
+    additional?: StackEntry[];
+    /** When this configuration was last updated */
+    lastUpdated?: string;
+}
+/**
+ * Load stack configuration from .sequant/stack.json
+ *
+ * @returns Stack configuration or null if not found
+ */
+export declare function loadStackConfig(): Promise<StackConfigFile | null>;
+/**
+ * Save stack configuration to .sequant/stack.json
+ *
+ * @param config - Stack configuration to save
+ */
+export declare function saveStackConfig(config: StackConfigFile): Promise<void>;
+/**
+ * Check if stack configuration exists
+ */
+export declare function hasStackConfig(): Promise<boolean>;
+/**
+ * Get the primary stack name from configuration
+ *
+ * @returns Primary stack name or null if not configured
+ */
+export declare function getPrimaryStack(): Promise<string | null>;
+/**
+ * Get all configured stacks (primary + additional)
+ *
+ * @returns Array of all stack names
+ */
+export declare function getAllConfiguredStacks(): Promise<string[]>;

package/dist/src/lib/stack-config.js

@@ -0,0 +1,77 @@
+/**
+ * Stack configuration persistence
+ *
+ * Manages user's stack configuration in .sequant/stack.json
+ */
+import { fileExists, readFile, writeFile, ensureDir } from "./fs.js";
+import { dirname } from "path";
+const STACK_CONFIG_PATH = ".sequant/stack.json";
+/**
+ * Load stack configuration from .sequant/stack.json
+ *
+ * @returns Stack configuration or null if not found
+ */
+export async function loadStackConfig() {
+    try {
+        if (!(await fileExists(STACK_CONFIG_PATH))) {
+            return null;
+        }
+        const content = await readFile(STACK_CONFIG_PATH);
+        const config = JSON.parse(content);
+        // Validate required fields
+        if (!config.primary || !config.primary.name) {
+            return null;
+        }
+        return config;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Save stack configuration to .sequant/stack.json
+ *
+ * @param config - Stack configuration to save
+ */
+export async function saveStackConfig(config) {
+    const configWithTimestamp = {
+        ...config,
+        lastUpdated: new Date().toISOString(),
+    };
+    await ensureDir(dirname(STACK_CONFIG_PATH));
+    await writeFile(STACK_CONFIG_PATH, JSON.stringify(configWithTimestamp, null, 2) + "\n");
+}
+/**
+ * Check if stack configuration exists
+ */
+export async function hasStackConfig() {
+    return fileExists(STACK_CONFIG_PATH);
+}
+/**
+ * Get the primary stack name from configuration
+ *
+ * @returns Primary stack name or null if not configured
+ */
+export async function getPrimaryStack() {
+    const config = await loadStackConfig();
+    return config?.primary?.name ?? null;
+}
+/**
+ * Get all configured stacks (primary + additional)
+ *
+ * @returns Array of all stack names
+ */
+export async function getAllConfiguredStacks() {
+    const config = await loadStackConfig();
+    if (!config)
+        return [];
+    const stacks = [config.primary.name];
+    if (config.additional) {
+        for (const entry of config.additional) {
+            if (!stacks.includes(entry.name)) {
+                stacks.push(entry.name);
+            }
+        }
+    }
+    return stacks;
+}

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

@@ -1,6 +1,30 @@
 /**
  * Stack detection and configuration
  */
+/**
+ * Detected stack with location information
+ */
+export interface DetectedStack {
+    /** Stack name (e.g., "nextjs", "python") */
+    stack: string;
+    /** Path relative to project root (empty string for root) */
+    path: string;
+}
+/**
+ * Stack configuration for persistence in .sequant/stack.json
+ */
+export interface StackConfig_Persisted {
+    /** Primary stack for the project (determines dev URL, commands) */
+    primary: {
+        name: string;
+        path?: string;
+    };
+    /** Additional stacks to include in constitution notes */
+    additional?: Array<{
+        name: string;
+        path?: string;
+    }>;
+}
 /**
  * Supported package managers
  */
@@ -46,4 +70,46 @@ export interface StackConfig {
 }
 export declare const STACKS: Record<string, StackConfig>;
 export declare function detectStack(): Promise<string | null>;
+/**
+ * Detect stack in a specific directory
+ * Similar to detectStack but operates on a given path
+ *
+ * @param basePath - Directory path to check (relative to cwd)
+ * @returns Stack name or null if not detected
+ */
+export declare function detectStackInDirectory(basePath: string): Promise<string | null>;
+/**
+ * Detect all stacks in the repository
+ *
+ * Traverses root and immediate subdirectories (1 level deep) to find
+ * all stacks present in a monorepo or multi-stack project.
+ *
+ * @returns Array of detected stacks with their paths
+ */
+export declare function detectAllStacks(): Promise<DetectedStack[]>;
 export declare function getStackConfig(stack: string): StackConfig;
+/**
+ * Stack-specific notes for constitution templates
+ *
+ * These notes are injected into the constitution during setup to provide
+ * context-aware guidance for AI-assisted development.
+ */
+export declare const STACK_NOTES: Record<string, string>;
+/**
+ * Get stack-specific notes for constitution template
+ *
+ * @param stack - The stack name (e.g., "nextjs", "python", "rust")
+ * @returns The stack-specific notes markdown content
+ */
+export declare function getStackNotes(stack: string): string;
+/**
+ * Get combined stack notes for multiple stacks
+ *
+ * Combines notes from a primary stack and optional additional stacks
+ * into a single markdown section for multi-stack projects.
+ *
+ * @param primary - Primary stack name (determines primary tooling)
+ * @param additional - Additional stacks to include notes for
+ * @returns Combined stack notes markdown content
+ */
+export declare function getMultiStackNotes(primary: string, additional?: string[]): string;

package/dist/src/lib/stacks.js

@@ -1,7 +1,25 @@
 /**
  * Stack detection and configuration
  */
+import { readdir } from "fs/promises";
 import { fileExists, readFile } from "./fs.js";
+/**
+ * Directories to skip during multi-stack detection
+ */
+const SKIP_DIRECTORIES = [
+    "node_modules",
+    ".git",
+    "vendor",
+    "dist",
+    "build",
+    ".next",
+    ".nuxt",
+    ".output",
+    "__pycache__",
+    "target",
+    ".claude",
+    ".sequant",
+];
 /**
  * Package manager configurations
  */
@@ -307,6 +325,320 @@ export async function detectStack() {
     }
     return null;
 }
+/**
+ * Detect stack in a specific directory
+ * Similar to detectStack but operates on a given path
+ *
+ * @param basePath - Directory path to check (relative to cwd)
+ * @returns Stack name or null if not detected
+ */
+export async function detectStackInDirectory(basePath) {
+    const pathPrefix = basePath ? `${basePath}/` : "";
+    // Check for Next.js config files
+    for (const file of STACKS.nextjs.detection.files || []) {
+        if (await fileExists(`${pathPrefix}${file}`)) {
+            return "nextjs";
+        }
+    }
+    // Check for Astro config files
+    for (const file of STACKS.astro.detection.files || []) {
+        if (await fileExists(`${pathPrefix}${file}`)) {
+            return "astro";
+        }
+    }
+    // Check for SvelteKit config files
+    for (const file of STACKS.sveltekit.detection.files || []) {
+        if (await fileExists(`${pathPrefix}${file}`)) {
+            return "sveltekit";
+        }
+    }
+    // Check for Remix config files
+    for (const file of STACKS.remix.detection.files || []) {
+        if (await fileExists(`${pathPrefix}${file}`)) {
+            return "remix";
+        }
+    }
+    // Check for Nuxt config files
+    for (const file of STACKS.nuxt.detection.files || []) {
+        if (await fileExists(`${pathPrefix}${file}`)) {
+            return "nuxt";
+        }
+    }
+    // Check package.json for JS framework dependencies
+    const packageJsonPath = `${pathPrefix}package.json`;
+    if (await fileExists(packageJsonPath)) {
+        try {
+            const pkg = JSON.parse(await readFile(packageJsonPath));
+            const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+            if (deps.next)
+                return "nextjs";
+            if (deps.astro)
+                return "astro";
+            if (deps["@sveltejs/kit"])
+                return "sveltekit";
+            if (deps["@remix-run/react"])
+                return "remix";
+            if (deps.nuxt)
+                return "nuxt";
+        }
+        catch {
+            // Ignore parse errors
+        }
+    }
+    // Check for Rust
+    if (await fileExists(`${pathPrefix}Cargo.toml`)) {
+        return "rust";
+    }
+    // Check for Go
+    if (await fileExists(`${pathPrefix}go.mod`)) {
+        return "go";
+    }
+    // Check for Python
+    for (const file of STACKS.python.detection.files || []) {
+        if (await fileExists(`${pathPrefix}${file}`)) {
+            return "python";
+        }
+    }
+    return null;
+}
+/**
+ * Detect all stacks in the repository
+ *
+ * Traverses root and immediate subdirectories (1 level deep) to find
+ * all stacks present in a monorepo or multi-stack project.
+ *
+ * @returns Array of detected stacks with their paths
+ */
+export async function detectAllStacks() {
+    const results = [];
+    // Check root directory
+    const rootStack = await detectStackInDirectory("");
+    if (rootStack) {
+        results.push({ stack: rootStack, path: "" });
+    }
+    // Check immediate subdirectories (1 level deep)
+    try {
+        const entries = await readdir(".", { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (SKIP_DIRECTORIES.includes(entry.name))
+                continue;
+            if (entry.name.startsWith("."))
+                continue; // Skip hidden directories
+            const subdirStack = await detectStackInDirectory(entry.name);
+            if (subdirStack) {
+                // Skip if same stack as root (likely a false positive)
+                // e.g., both root and /packages/web detect "nextjs"
+                // We want distinct stacks, not duplicates
+                const isDuplicate = results.some((r) => r.stack === subdirStack && r.path === "");
+                // Only skip if root has the same stack AND this is a common mono-repo pattern
+                // (like packages/, apps/, etc.)
+                if (!isDuplicate ||
+                    entry.name === "frontend" ||
+                    entry.name === "backend") {
+                    results.push({ stack: subdirStack, path: entry.name });
+                }
+            }
+        }
+    }
+    catch {
+        // Directory read failed, return what we have
+    }
+    return results;
+}
 export function getStackConfig(stack) {
     return STACKS[stack] || STACKS.generic;
 }
+/**
+ * Stack-specific notes for constitution templates
+ *
+ * These notes are injected into the constitution during setup to provide
+ * context-aware guidance for AI-assisted development.
+ */
+export const STACK_NOTES = {
+    nextjs: `### Next.js
+
+**Testing:**
+- Use Jest or Vitest with React Testing Library
+- Place tests in \`__tests__/\` directories or as \`.test.ts(x)\` files
+- Use \`next/jest\` preset for proper Next.js configuration
+- Mock \`next/router\` and \`next/navigation\` in component tests
+
+**Linting:**
+- ESLint with \`eslint-config-next\` (included by default)
+- Run \`npm run lint\` or \`next lint\`
+- TypeScript strict mode recommended
+
+**Build:**
+- Output to \`.next/\` directory
+- Use \`next build\` for production builds
+- Static exports via \`output: 'export'\` in next.config.js`,
+    astro: `### Astro
+
+**Testing:**
+- Astro projects may not have test scripts configured by default
+- Consider adding Vitest: \`npm install -D vitest\`
+- Use \`@astrojs/test-utils\` for component testing
+
+**Linting:**
+- Consider ESLint with \`eslint-plugin-astro\`
+- Install: \`npm install -D eslint eslint-plugin-astro\`
+
+**Build:**
+- Output to \`dist/\` by default
+- Use \`astro build\` for production
+- SSR mode available via adapters`,
+    sveltekit: `### SvelteKit
+
+**Testing:**
+- Use Vitest with \`@testing-library/svelte\`
+- Playwright for E2E testing (often pre-configured)
+- Place unit tests in \`src/\` alongside components
+
+**Linting:**
+- ESLint with \`eslint-plugin-svelte\`
+- Prettier with \`prettier-plugin-svelte\`
+- Run \`npm run lint\` and \`npm run check\`
+
+**Build:**
+- Output depends on adapter (node, static, vercel, etc.)
+- Use \`svelte-kit build\` for production
+- Type-check with \`svelte-kit sync && svelte-check\``,
+    remix: `### Remix
+
+**Testing:**
+- Use Vitest or Jest with React Testing Library
+- Cypress or Playwright for E2E testing
+- Test loaders and actions separately from components
+
+**Linting:**
+- ESLint with React and TypeScript plugins
+- Remix doesn't include ESLint config by default
+
+**Build:**
+- Output to \`build/\` directory
+- Use \`remix build\` for production
+- Server and client bundles are separate`,
+    nuxt: `### Nuxt
+
+**Testing:**
+- Use Vitest with \`@nuxt/test-utils\`
+- \`@vue/test-utils\` for component testing
+- Playwright for E2E testing
+
+**Linting:**
+- ESLint with \`@nuxt/eslint-config\`
+- Run \`npm run lint\` or \`nuxi lint\`
+
+**Build:**
+- Output to \`.output/\` directory
+- Use \`nuxi build\` for production
+- \`nuxi generate\` for static site generation`,
+    rust: `### Rust
+
+**Testing:**
+- Unit tests: \`#[cfg(test)]\` modules in source files
+- Integration tests: \`tests/\` directory
+- Run \`cargo test\` for all tests
+- Use \`#[should_panic]\` for panic tests
+
+**Linting:**
+- \`cargo clippy\` for lints (install: \`rustup component add clippy\`)
+- \`cargo fmt\` for formatting
+- Consider \`cargo deny\` for dependency auditing
+
+**Build:**
+- Debug: \`cargo build\`
+- Release: \`cargo build --release\`
+- Output to \`target/debug/\` or \`target/release/\``,
+    python: `### Python
+
+**Testing:**
+- pytest is the standard test runner
+- Place tests in \`tests/\` directory
+- Use \`pytest-cov\` for coverage reports
+- Fixtures in \`conftest.py\`
+
+**Linting:**
+- Ruff for fast linting and formatting: \`ruff check .\` and \`ruff format .\`
+- Alternative: Black + isort + flake8
+- mypy for type checking
+
+**Build:**
+- Use virtual environments (venv, poetry, pdm)
+- \`python -m build\` for package builds
+- \`pip install -e .\` for development installs`,
+    go: `### Go
+
+**Testing:**
+- Tests in \`*_test.go\` files alongside source
+- Run \`go test ./...\` for all packages
+- Use \`-v\` for verbose output, \`-race\` for race detection
+- Table-driven tests are idiomatic
+
+**Linting:**
+- \`golangci-lint run\` for comprehensive linting
+- \`go vet\` for basic checks
+- \`gofmt\` or \`goimports\` for formatting
+
+**Build:**
+- \`go build ./...\` to compile
+- \`go install\` to build and install
+- Cross-compile with GOOS/GOARCH environment variables`,
+    generic: `### General Guidelines
+
+**Testing:**
+- Check for test scripts in package.json or equivalent
+- Common patterns: \`npm test\`, \`pytest\`, \`go test\`, \`cargo test\`
+
+**Linting:**
+- Check for lint scripts or configuration files
+- Common: ESLint, Prettier, Ruff, golangci-lint, clippy
+
+**Build:**
+- Check for build scripts and output directories
+- Document build commands in README`,
+};
+/**
+ * Get stack-specific notes for constitution template
+ *
+ * @param stack - The stack name (e.g., "nextjs", "python", "rust")
+ * @returns The stack-specific notes markdown content
+ */
+export function getStackNotes(stack) {
+    return STACK_NOTES[stack] || STACK_NOTES.generic;
+}
+/**
+ * Get combined stack notes for multiple stacks
+ *
+ * Combines notes from a primary stack and optional additional stacks
+ * into a single markdown section for multi-stack projects.
+ *
+ * @param primary - Primary stack name (determines primary tooling)
+ * @param additional - Additional stacks to include notes for
+ * @returns Combined stack notes markdown content
+ */
+export function getMultiStackNotes(primary, additional = []) {
+    const sections = [];
+    // Add primary stack notes (with "Primary" marker)
+    const primaryNotes = STACK_NOTES[primary] || STACK_NOTES.generic;
+    if (additional.length > 0) {
+        // Replace the first line heading to include "(Primary)"
+        const modifiedPrimary = primaryNotes.replace(/^### (.+)$/m, "### $1 (Primary)");
+        sections.push(modifiedPrimary);
+    }
+    else {
+        sections.push(primaryNotes);
+    }
+    // Add additional stack notes
+    for (const stack of additional) {
+        if (stack === primary)
+            continue; // Skip if same as primary
+        const notes = STACK_NOTES[stack];
+        if (notes && notes !== STACK_NOTES.generic) {
+            sections.push(notes);
+        }
+    }
+    return sections.join("\n\n---\n\n");
+}

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

@@ -32,6 +32,8 @@ export interface CopyTemplatesOptions {
     noSymlinks?: boolean;
     /** Force replacement of existing files/symlinks */
     force?: boolean;
+    /** Additional stacks to include in constitution notes (for multi-stack projects) */
+    additionalStacks?: string[];
 }
 /**
  * Create symlinks for files in a directory, with fallback to copy

package/dist/src/lib/templates.js

@@ -2,11 +2,12 @@
  * Template management - copy and process templates
  */
 import { readdir, chmod } from "fs/promises";
-import { join, dirname, basename, relative, isAbsolute } from "path";
+import { join, dirname, relative, isAbsolute } from "path";
 import { fileURLToPath } from "url";
 import { readFile, writeFile, ensureDir, fileExists, isSymlink, createSymlink, removeFileOrSymlink, } from "./fs.js";
-import { getStackConfig } from "./stacks.js";
+import { getStackConfig, getStackNotes, getMultiStackNotes } from "./stacks.js";
 import { isNativeWindows } from "./system.js";
+import { getProjectName } from "./project-name.js";
 // Get the package templates directory
 function getTemplatesDir() {
     const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -157,11 +158,19 @@ export async function symlinkDir(srcDir, destDir, options = {}) {
 export async function copyTemplates(stack, tokens, options = {}) {
     const templatesDir = getTemplatesDir();
     const stackConfig = getStackConfig(stack);
+    // Detect project name from available sources (package.json, Cargo.toml, etc.)
+    const projectName = await getProjectName();
+    // Get stack-specific notes for constitution template
+    // Use multi-stack notes if additional stacks are provided
+    const stackNotes = options.additionalStacks && options.additionalStacks.length > 0
+        ? getMultiStackNotes(stack, options.additionalStacks)
+        : getStackNotes(stack);
     const variables = {
         ...stackConfig.variables,
         ...tokens,
-        PROJECT_NAME: basename(process.cwd()) || "project",
+        PROJECT_NAME: projectName,
         STACK: stack,
+        STACK_NOTES: stackNotes,
     };
     async function copyDir(srcDir, destDir) {
         try {

package/dist/src/lib/upstream/assessment.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Main assessment module for upstream analysis
+ * Coordinates release fetching, analysis, and output generation
+ */
+import type { AssessmentOptions, Baseline, BatchedAssessment, ReleaseData, UpstreamAssessment } from "./types.js";
+/**
+ * Validate a version string to prevent command injection
+ * @throws Error if version format is invalid
+ */
+export declare function validateVersion(version: string): void;
+/**
+ * Check if gh CLI is available and authenticated
+ * @returns Object with availability status and error message if not available
+ */
+export declare function checkGhCliAvailable(): Promise<{
+    available: boolean;
+    authenticated: boolean;
+    error?: string;
+}>;
+/**
+ * Fetch release data from Claude Code repository
+ */
+export declare function fetchRelease(version?: string): Promise<ReleaseData | null>;
+/**
+ * List releases from Claude Code repository
+ */
+export declare function listReleases(limit?: number): Promise<Array<{
+    tagName: string;
+    publishedAt: string;
+}>>;
+/**
+ * Get releases since a specific version
+ */
+export declare function getReleasesSince(sinceVersion: string): Promise<string[]>;
+/**
+ * Load baseline from file
+ */
+export declare function loadBaseline(path?: string): Promise<Baseline>;
+/**
+ * Save baseline to file
+ */
+export declare function saveBaseline(baseline: Baseline, path?: string): Promise<void>;
+/**
+ * Update baseline with new assessed version
+ */
+export declare function updateBaseline(version: string, path?: string): Promise<void>;
+/**
+ * Check if a version has already been assessed
+ */
+export declare function isAlreadyAssessed(version: string): Promise<boolean>;
+/**
+ * Save local report
+ */
+export declare function saveLocalReport(assessment: UpstreamAssessment): Promise<string>;
+/**
+ * Run a single version assessment
+ */
+export declare function assessVersion(version: string, options?: AssessmentOptions): Promise<UpstreamAssessment | null>;
+/**
+ * Run assessment for latest release
+ */
+export declare function assessLatest(options?: AssessmentOptions): Promise<UpstreamAssessment | null>;
+/**
+ * Run batched assessment for multiple versions
+ */
+export declare function assessSince(sinceVersion: string, options?: AssessmentOptions): Promise<BatchedAssessment | null>;
+/**
+ * Main entry point for upstream assessment
+ */
+export declare function runUpstream(options?: AssessmentOptions): Promise<UpstreamAssessment | BatchedAssessment | null>;