@codewalla_india/openspec 1.3.1 → 1.3.3

package/dist/core/validation/validator.js

@@ -4,9 +4,15 @@ import { SpecSchema, ChangeSchema } from '../schemas/index.js';
 import { MarkdownParser } from '../parsers/markdown-parser.js';
 import { ChangeParser } from '../parsers/change-parser.js';
 import { MIN_PURPOSE_LENGTH, MAX_REQUIREMENT_TEXT_LENGTH, VALIDATION_MESSAGES } from './constants.js';
-import { parseDeltaSpec, normalizeRequirementName } from '../parsers/requirement-blocks.js';
+import { parseDeltaSpec, foldRequirementName, normalizeRequirementName, extractRequirementsSection, findMissingCurrentScenarios, } from '../parsers/requirement-blocks.js';
+import { extractRequirementBody as extractRequirementBodyShared, containsShallOrMust as containsShallOrMustShared, countScenarios as countScenariosShared, } from '../parsers/requirement-text.js';
 import { findMainSpecStructureIssues } from '../parsers/spec-structure.js';
 import { FileSystemUtils } from '../../utils/file-system.js';
+import { discoverSpecFiles, hasAnyFileUnder } from '../../utils/spec-discovery.js';
+import { METADATA_FILENAME, readSkipSpecsMarker, resolveSchemaForChange, } from '../../utils/change-metadata.js';
+import { resolveTaskFilesForChange } from '../../utils/task-progress.js';
+import { findTaskNumberingIssues } from './task-numbering.js';
+import { getPackageSchemasDir, getSchemaDir } from '../artifact-graph/index.js';
 export class Validator {
     strictMode;
     constructor(strictMode = false) {
@@ -66,8 +72,20 @@ export class Validator {
             const parser = new ChangeParser(content, changeDir);
             const change = await parser.parseChangeWithDeltas(changeName);
             const result = ChangeSchema.safeParse(change);
+            const marker = readSkipSpecsMarker(changeDir);
+            if (marker.invalidReason) {
+                issues.push({ level: 'ERROR', path: METADATA_FILENAME, message: this.formatInvalidMarkerMessage(marker.invalidReason) });
+            }
             if (!result.success) {
-                issues.push(...this.convertZodErrors(result.error));
+                let zodIssues = this.convertZodErrors(result.error);
+                // Only the no-deltas error is marker-aware here: the marker+files
+                // conflict is validateChangeDeltaSpecs's job, and every caller of
+                // this proposal-level pass (archive's non-blocking warnings) pairs
+                // it with that gate.
+                if (marker.declared) {
+                    zodIssues = zodIssues.filter(issue => !issue.message.startsWith(VALIDATION_MESSAGES.CHANGE_NO_DELTAS));
+                }
+                issues.push(...zodIssues);
             }
             issues.push(...this.applyChangeRules(change, content));
         }
@@ -86,24 +104,47 @@ export class Validator {
      * Validate delta-formatted spec files under a change directory.
      * Enforces:
      * - At least one delta across all files
-     * - ADDED/MODIFIED: each requirement has SHALL/MUST and at least one scenario
+     * - ADDED/MODIFIED: each requirement has at least one scenario; missing
+     *   English SHALL/MUST keywords are guidance unless strict mode is enabled
      * - REMOVED: names only; no scenario/description required
      * - RENAMED: pairs well-formed
      * - No duplicates within sections; no cross-section conflicts per spec
+     *
+     * When `options.mainSpecsDir` is given, MODIFIED blocks are also checked
+     * against the current main specs for the scenario loss archive refuses to
+     * apply (#1477). When `options.projectRoot` is given, the schema's tracked
+     * task files are checked for ambiguous numbering (#1520). Omitting either
+     * option keeps existing library and archive callers behaving as before.
      */
-    async validateChangeDeltaSpecs(changeDir) {
+    async validateChangeDeltaSpecs(changeDir, options = {}) {
         const issues = [];
         const specsDir = path.join(changeDir, 'specs');
         let totalDeltas = 0;
+        let hasRootLevelSpec = false;
         const missingHeaderSpecs = [];
         const emptySectionSpecs = [];
         try {
-            const entries = await fs.readdir(specsDir, { withFileTypes: true });
-            for (const entry of entries) {
-                if (!entry.isDirectory())
-                    continue;
-                const specName = entry.name;
-                const specFile = path.join(specsDir, specName, 'spec.md');
+            // Discover delta specs through the same helper the change parser, show,
+            // apply, and archive use, so validate never accepts a layout the merge
+            // path silently skips (#1385). It finds spec.md at any depth, covering
+            // both specs/<capability>/spec.md and the nested multi-area
+            // specs/<area>/<capability>/spec.md layout (#1182b).
+            const discoveredSpecs = await discoverSpecFiles(specsDir);
+            // A spec.md directly at the specs/ root has no capability folder, so the
+            // merge path drops it: without this error the change validates clean and
+            // archives while its requirements never reach openspec/specs/ (#1385).
+            // Only a regular file counts — a *directory* named spec.md is a capability
+            // folder like any other, and discoverSpecFiles reads it normally.
+            const rootSpecStat = await fs.stat(path.join(specsDir, 'spec.md')).catch(() => null);
+            hasRootLevelSpec = rootSpecStat?.isFile() === true;
+            if (hasRootLevelSpec) {
+                issues.push({
+                    level: 'ERROR',
+                    path: 'spec.md',
+                    message: 'Delta spec found at specs/spec.md. Delta specs must live under a capability path (e.g. specs/<capability-path>/spec.md) — a file at the specs/ root is ignored when the change is applied or archived.',
+                });
+            }
+            for (const { id: specId, specFile } of discoveredSpecs) {
                 let content;
                 try {
                     content = await fs.readFile(specFile, 'utf-8');
@@ -112,7 +153,24 @@ export class Validator {
                     continue;
                 }
                 const plan = parseDeltaSpec(content);
-                const entryPath = `${specName}/spec.md`;
+                const entryPath = FileSystemUtils.toPosixPath(path.relative(specsDir, specFile));
+                // Surface (as INFO, never a failure) the non-canonical level-3 headers
+                // the delta reader skipped while parsing ADDED/MODIFIED sections —
+                // without this note a stray divider like "### Documentation
+                // Requirements" would pass validate <change> while failing
+                // archive/validate <spec>. The list comes from the parse itself, so it
+                // reflects exactly what the reader skipped.
+                for (const stray of plan.skippedHeaders) {
+                    const nameless = /^requirement:?$/i.test(stray.header);
+                    issues.push({
+                        level: 'INFO',
+                        path: entryPath,
+                        line: stray.line,
+                        message: nameless
+                            ? `Header "### ${stray.header}" in ${stray.section} is missing a requirement name and is ignored by validation. Add a name, e.g. "### Requirement: <name>".`
+                            : `Header "### ${stray.header}" in ${stray.section} is not a "### Requirement:" header and is ignored by validation. Use "### Requirement: ${stray.header}" if it should be validated as a requirement.`,
+                    });
+                }
                 const sectionNames = [];
                 if (plan.sectionPresence.added)
                     sectionNames.push('## ADDED Requirements');
@@ -147,10 +205,20 @@ export class Validator {
                     }
                     const requirementText = this.extractRequirementText(block.raw);
                     if (!requirementText) {
-                        issues.push({ level: 'ERROR', path: entryPath, message: `ADDED "${block.name}" is missing requirement text` });
+                        issues.push({
+                            level: 'ERROR',
+                            path: entryPath,
+                            message: this.containsShallOrMust(block.name)
+                                ? this.buildMissingShallOrMustMessage(`ADDED "${block.name}"`, block.name)
+                                : `ADDED "${block.name}" is missing requirement text`,
+                        });
                     }
                     else if (!this.containsShallOrMust(requirementText)) {
-                        issues.push({ level: 'ERROR', path: entryPath, message: this.buildMissingShallOrMustMessage('ADDED', block.name) });
+                        issues.push({
+                            level: 'WARNING',
+                            path: entryPath,
+                            message: this.buildMissingShallOrMustMessage(`ADDED "${block.name}"`, block.name, true),
+                        });
                     }
                     const scenarioCount = this.countScenarios(block.raw);
                     if (scenarioCount < 1) {
@@ -169,16 +237,33 @@ export class Validator {
                     }
                     const requirementText = this.extractRequirementText(block.raw);
                     if (!requirementText) {
-                        issues.push({ level: 'ERROR', path: entryPath, message: `MODIFIED "${block.name}" is missing requirement text` });
+                        issues.push({
+                            level: 'ERROR',
+                            path: entryPath,
+                            message: this.containsShallOrMust(block.name)
+                                ? this.buildMissingShallOrMustMessage(`MODIFIED "${block.name}"`, block.name)
+                                : `MODIFIED "${block.name}" is missing requirement text`,
+                        });
                     }
                     else if (!this.containsShallOrMust(requirementText)) {
-                        issues.push({ level: 'ERROR', path: entryPath, message: this.buildMissingShallOrMustMessage('MODIFIED', block.name) });
+                        issues.push({
+                            level: 'WARNING',
+                            path: entryPath,
+                            message: this.buildMissingShallOrMustMessage(`MODIFIED "${block.name}"`, block.name, true),
+                        });
                     }
                     const scenarioCount = this.countScenarios(block.raw);
                     if (scenarioCount < 1) {
                         issues.push({ level: 'ERROR', path: entryPath, message: `MODIFIED "${block.name}" must include at least one scenario` });
                     }
                 }
+                // Run archive's scenario-loss check here too, so the change fails at
+                // authoring time instead of days later at archive time (#1477).
+                if (options.mainSpecsDir && plan.modified.length > 0) {
+                    const mainSpecFile = path.join(options.mainSpecsDir, ...specId.split('/'), 'spec.md');
+                    FileSystemUtils.assertPathWithin(path.dirname(mainSpecFile), mainSpecFile);
+                    issues.push(...(await this.findScenarioLossIssues(plan.modified, plan.renamed, mainSpecFile, entryPath, path.dirname(mainSpecFile))));
+                }
                 // Validate REMOVED (names only)
                 for (const name of plan.removed) {
                     const key = normalizeRequirementName(name);
@@ -231,11 +316,30 @@ export class Validator {
                     if (addedNames.has(toKey)) {
                         issues.push({ level: 'ERROR', path: entryPath, message: `RENAMED TO collides with ADDED for "${to}"` });
                     }
+                    // Folded comparison: a case/whitespace variant of the FROM header
+                    // in REMOVED is the same contradiction, not a different name.
+                    const removedFoldMatch = [...removedNames].find((r) => foldRequirementName(r) === foldRequirementName(fromKey));
+                    if (removedFoldMatch !== undefined) {
+                        issues.push({
+                            level: 'ERROR',
+                            path: entryPath,
+                            message: `Requirement present in both RENAMED and REMOVED: "${from}"` +
+                                (removedFoldMatch === fromKey ? '' : ` (REMOVED spells it "${removedFoldMatch}")`),
+                        });
+                    }
                 }
             }
         }
-        catch {
-            // If no specs dir, treat as no deltas
+        catch (error) {
+            // A missing specs dir (or a stray `specs` file) means no deltas;
+            // anything else (EACCES, EIO) must stay loud — discoverSpecFiles
+            // documents that silently dropping an unreadable capability recreates
+            // the data-loss class it prevents, and archive lets the same error
+            // propagate.
+            const code = error?.code;
+            if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+                throw error;
+            }
         }
         for (const { path: specPath, sections } of emptySectionSpecs) {
             issues.push({
@@ -251,11 +355,185 @@ export class Validator {
                 message: 'No delta sections found. Add headers such as "## ADDED Requirements" or move non-delta notes outside specs/.',
             });
         }
-        if (totalDeltas === 0) {
-            issues.push({ level: 'ERROR', path: 'file', message: this.enrichTopLevelError('change', VALIDATION_MESSAGES.CHANGE_NO_DELTAS) });
+        const marker = readSkipSpecsMarker(changeDir);
+        if (marker.invalidReason) {
+            issues.push({ level: 'ERROR', path: METADATA_FILENAME, message: this.formatInvalidMarkerMessage(marker.invalidReason) });
+        }
+        // ANY file under specs/ contradicts the marker - not just parsed deltas.
+        // Headerless or stray files would be silently dropped at archive time (and
+        // some still satisfy the artifact graph's specs/**  glob) while the change
+        // claims to have nothing, so they must surface as an explicit conflict.
+        // Probed only when the marker is declared, and unreadable specs/ (a stray
+        // `specs` file, permission errors) fails closed as a conflict: the marker
+        // claims nothing is there, and validate must not crash where the
+        // historical path degraded to "no deltas".
+        const skipSpecs = marker.declared;
+        let specsDirHasFiles = false;
+        if (skipSpecs) {
+            try {
+                specsDirHasFiles = await hasAnyFileUnder(specsDir);
+            }
+            catch {
+                specsDirHasFiles = true;
+            }
+        }
+        if (skipSpecs && specsDirHasFiles) {
+            issues.push({ level: 'ERROR', path: 'file', message: VALIDATION_MESSAGES.CHANGE_SKIP_SPECS_CONFLICT });
+        }
+        // The root-level error already names the file and the fix; adding "No
+        // deltas found" on top would contradict it, since the deltas are sitting in
+        // the file just reported.
+        if (totalDeltas === 0 && !hasRootLevelSpec) {
+            if (skipSpecs && !specsDirHasFiles) {
+                issues.push({ level: 'INFO', path: 'file', message: VALIDATION_MESSAGES.CHANGE_SKIP_SPECS_ACCEPTED });
+            }
+            else if (!skipSpecs) {
+                issues.push({ level: 'ERROR', path: 'file', message: this.enrichTopLevelError('change', VALIDATION_MESSAGES.CHANGE_NO_DELTAS) });
+            }
+        }
+        if (options.projectRoot) {
+            issues.push(...await this.collectTaskNumberingIssues(changeDir, options.projectRoot));
         }
         return this.createReport(issues);
     }
+    async collectTaskNumberingIssues(changeDir, projectRoot) {
+        try {
+            const schemaName = resolveSchemaForChange(changeDir, undefined, projectRoot).replace(/\.ya?ml$/, '');
+            const schemaDir = getSchemaDir(schemaName, projectRoot);
+            const builtInSchemaDir = path.join(getPackageSchemasDir(), 'spec-driven');
+            if (schemaName !== 'spec-driven' ||
+                schemaDir === null ||
+                FileSystemUtils.canonicalizeExistingPath(schemaDir) !==
+                    FileSystemUtils.canonicalizeExistingPath(builtInSchemaDir)) {
+                return [];
+            }
+        }
+        catch {
+            return [];
+        }
+        let taskFiles;
+        try {
+            taskFiles = resolveTaskFilesForChange(changeDir, projectRoot);
+        }
+        catch {
+            return [];
+        }
+        if (taskFiles.length === 0) {
+            taskFiles = [path.join(changeDir, 'tasks.md')];
+        }
+        const documents = [];
+        for (const taskFile of taskFiles) {
+            let content;
+            try {
+                content = await fs.readFile(taskFile, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            documents.push({
+                path: FileSystemUtils.toPosixPath(path.relative(changeDir, taskFile)),
+                content,
+            });
+        }
+        documents.sort((left, right) => left.path.localeCompare(right.path));
+        return findTaskNumberingIssues(documents).map((issue) => ({
+            level: 'WARNING',
+            path: issue.path,
+            line: issue.line,
+            message: issue.message,
+        }));
+    }
+    /**
+     * Report MODIFIED requirements whose block omits a scenario the main spec
+     * still carries. Uses the same comparison archive applies, so validate can
+     * only report what archive would refuse.
+     *
+     * Silent when the main spec or the requirement header is absent: applying a
+     * MODIFIED against a base that is not there yet is a different failure (a
+     * sister change still in flight is the legitimate case), and archive is the
+     * gate for it. A spec that exists but cannot be read is not absent, though —
+     * archive aborts on it, so reporting it beats calling the change valid.
+     */
+    async findScenarioLossIssues(modified, renamed, mainSpecFile, entryPath, mainSpecRoot) {
+        let mainContent;
+        FileSystemUtils.assertPathWithin(mainSpecRoot, mainSpecFile);
+        try {
+            mainContent = await fs.readFile(mainSpecFile, 'utf-8');
+        }
+        catch (error) {
+            const code = error?.code;
+            // Reported only for the codes that mean the file itself is unusable, and
+            // will be just as unusable when archive reads it. Everything else -
+            // ENOENT/ENOTDIR ("no main spec"), and transient resource errors like
+            // EMFILE that say nothing about the file - stays silent rather than
+            // failing a change that is fine. `validate --all` reads six changes at
+            // once, so a resource error must never become a verdict.
+            const UNUSABLE = new Set(['EACCES', 'EPERM', 'EISDIR', 'ELOOP', 'ENAMETOOLONG']);
+            if (!code || !UNUSABLE.has(code))
+                return [];
+            return [
+                {
+                    level: 'ERROR',
+                    path: entryPath,
+                    message: `Could not read ${FileSystemUtils.toPosixPath(mainSpecFile)} to check the MODIFIED requirements against it ` +
+                        `(${code}). Archive reads the same file, so fix the file before archiving.`,
+                },
+            ];
+        }
+        const currentBlocks = new Map();
+        for (const block of extractRequirementsSection(mainContent).bodyBlocks) {
+            currentBlocks.set(normalizeRequirementName(block.name), block);
+        }
+        // Archive applies RENAMED before MODIFIED, so a MODIFIED naming the new
+        // header is compared against the renamed block's scenarios. Fall back to
+        // the old header, or a rename-plus-modify pair would skip the check.
+        const renamedFrom = new Map(renamed.map(({ from, to }) => [normalizeRequirementName(to), normalizeRequirementName(from)]));
+        // Walked, not looked up once: renames chain (A→B then B→C leaves C holding
+        // A's block), and the visited set stops a cycle from looping forever. Every
+        // name in a rename cycle is also a rename FROM, so the skip above already
+        // keeps the walk out of one; the guard stays because the cost of being
+        // wrong about that is a hung CLI, not a wrong message.
+        const currentBlockFor = (name) => {
+            const visited = new Set();
+            let key = name;
+            while (key !== undefined && !visited.has(key)) {
+                const block = currentBlocks.get(key);
+                if (block)
+                    return block;
+                visited.add(key);
+                key = renamedFrom.get(key);
+            }
+            return undefined;
+        };
+        // A MODIFIED naming a header the same delta renames away is already
+        // reported ("MODIFIED references old name from RENAMED"), and the block it
+        // would land on is not the one it names — so any scenario named here would
+        // send the author after the wrong requirement.
+        const renamedAway = new Set(renamed.map(({ from }) => normalizeRequirementName(from)));
+        const issues = [];
+        for (const block of modified) {
+            const key = normalizeRequirementName(block.name);
+            if (renamedAway.has(key))
+                continue;
+            const current = currentBlockFor(key);
+            if (!current)
+                continue;
+            const missing = findMissingCurrentScenarios(current, block);
+            if (missing.length === 0)
+                continue;
+            issues.push({
+                level: 'ERROR',
+                path: entryPath,
+                message: `MODIFIED "${block.name}" omits scenario(s) the current spec still has: ` +
+                    `${missing.map(name => `"${name}"`).join(', ')}. ` +
+                    'Copy them into the MODIFIED block (a MODIFIED requirement replaces the whole block, so archive refuses to drop them).',
+            });
+        }
+        return issues;
+    }
+    formatInvalidMarkerMessage(invalidReason) {
+        return `${VALIDATION_MESSAGES.CHANGE_SKIP_SPECS_INVALID_METADATA} (${invalidReason})`;
+    }
     convertZodErrors(error) {
         return error.issues.map(err => {
             let message = err.message;
@@ -302,6 +580,29 @@ export class Validator {
                 });
             }
         });
+        // SHALL/MUST body-keyword guidance for main specs (#1156, #243). The main-spec
+        // parser collapses the requirement header into `text`, so we recover the
+        // header+body pairs here (the same source the delta path trusts) and reuse
+        // the delta detection. A non-empty body that omits the English keyword gets
+        // guidance, while a missing body remains an error. Emitted exactly once per
+        // requirement (the Zod refine that used to emit a generic error is removed).
+        extractRequirementsSection(content).bodyBlocks.forEach((block, index) => {
+            const requirementText = this.extractRequirementText(block.raw);
+            if (!requirementText) {
+                issues.push({
+                    level: 'ERROR',
+                    path: `requirements[${index}]`,
+                    message: this.buildMissingShallOrMustMessage(`Requirement "${block.name}"`, block.name),
+                });
+            }
+            else if (!this.containsShallOrMust(requirementText)) {
+                issues.push({
+                    level: 'WARNING',
+                    path: `requirements[${index}]`,
+                    message: this.buildMissingShallOrMustMessage(`Requirement "${block.name}"`, block.name, true),
+                });
+            }
+        });
         return issues;
     }
     applyChangeRules(change, content) {
@@ -376,33 +677,19 @@ export class Validator {
         return report.valid;
     }
     extractRequirementText(blockRaw) {
-        const lines = blockRaw.split('\n');
-        // Skip header line (index 0)
-        let i = 1;
-        // Find the first substantial text line, skipping metadata and blank lines
-        for (; i < lines.length; i++) {
-            const line = lines[i];
-            // Stop at scenario headers
-            if (/^####\s+/.test(line))
-                break;
-            const trimmed = line.trim();
-            // Skip blank lines
-            if (trimmed.length === 0)
-                continue;
-            // Skip metadata lines (lines starting with ** like **ID**, **Priority**, etc.)
-            if (/^\*\*[^*]+\*\*:/.test(trimmed))
-                continue;
-            // Found first non-metadata, non-blank line - this is the requirement text
-            return trimmed;
-        }
-        // No requirement text found
-        return undefined;
+        // Delegate to the shared, fence-/metadata-/multi-line-aware body reader.
+        // Validation intentionally does not use the parser/display header-title
+        // fallback for canonical `### Requirement:` blocks: #1280 requires a
+        // SHALL/MUST that appears only in the header to receive the body-keyword
+        // hint. Line 0 is the `### Requirement: ...` header.
+        const [, ...bodyLines] = blockRaw.split('\n');
+        return extractRequirementBodyShared(bodyLines) || undefined;
     }
     containsShallOrMust(text) {
-        return /\b(SHALL|MUST)\b/.test(text);
+        return containsShallOrMustShared(text);
     }
     /**
-     * Build an error message for a requirement block whose body lacks SHALL/MUST.
+     * Build a message for a requirement block whose body lacks SHALL/MUST.
      *
      * When the SHALL/MUST keyword already appears in the requirement header (e.g.
      * `### Requirement: The system SHALL ...`) the original generic error
@@ -411,16 +698,18 @@ export class Validator {
      * on the requirement body line (the line right after the header), so we point
      * the author at that exact fix when the keyword is found in the header only.
      */
-    buildMissingShallOrMustMessage(action, blockName) {
-        const base = `${action} "${blockName}" must contain SHALL or MUST`;
+    buildMissingShallOrMustMessage(prefix, blockName, guidanceOnly = false) {
+        const base = `${prefix} ${guidanceOnly ? 'should' : 'must'} contain SHALL or MUST`;
+        const suffix = guidanceOnly ? ' (RFC 2119 best practice for English specs)' : '';
         if (this.containsShallOrMust(blockName)) {
-            return `${base} in the requirement body, not only in the header. Move the SHALL/MUST statement to the line immediately after the "### Requirement: ..." header.`;
+            return `${base} in the requirement body, not only in the header. Move the SHALL/MUST statement to the line immediately after the "### Requirement: ..." header.${suffix}`;
         }
-        return base;
+        return `${base}${suffix}`;
     }
     countScenarios(blockRaw) {
-        const matches = blockRaw.match(/^####\s+/gm);
-        return matches ? matches.length : 0;
+        // Fence-aware count via the shared reader: a `#### Scenario:` inside a fenced
+        // example is not a real scenario. Drop the header line (index 0).
+        return countScenariosShared(blockRaw.split('\n').slice(1));
     }
     formatSectionList(sections) {
         if (sections.length === 0)

package/dist/core/version-check.d.ts

@@ -0,0 +1,152 @@
+/**
+ * The registry to ask: only the environment variable npm exports (under
+ * `npm run`, or an explicit export). Deliberately not a `registry=` line from
+ * any .npmrc — letting file contents choose the destination of an outbound
+ * request is a flow worth avoiding for a convenience this small, and a project
+ * file would travel with a cloned repository. Anyone on a private mirror can
+ * export `npm_config_registry`, or turn the check off entirely.
+ */
+export declare function registryUrl(): string;
+/**
+ * Compares two semver-ish versions. Returns 1 when a > b, -1 when a < b, 0
+ * otherwise. Prereleases sort below their release (1.7.0-beta.1 < 1.7.0).
+ */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * Returns the published version when the installed CLI is behind it, otherwise
+ * null. Never throws and never blocks for longer than the request timeout.
+ */
+export declare function getAvailableCliUpdate(): Promise<string | null>;
+/**
+ * Directory the running CLI was loaded from, or null when it cannot be
+ * resolved. Shown in the upgrade hint so anyone who upgraded but still runs an
+ * old binary — a stale pnpm/volta/npx shim, or two installs on PATH — can see
+ * which copy is actually answering.
+ */
+export declare function getInstallDir(): string | null;
+/**
+ * True when the running CLI resolves from a `node_modules` belonging to the
+ * project being updated or any ancestor of it — the hoisted-root layout npm and
+ * pnpm workspaces produce. Anchored on the target path rather than the working
+ * directory, since `openspec update <path>` and running from a sub-package are
+ * both normal. Never throws: process.cwd() fails when the directory has been
+ * deleted, and a wrong upgrade hint must not take down a successful update.
+ */
+export declare function isProjectLocalInstall(installDir: string | null, projectPath?: string): boolean;
+/**
+ * True for the throwaway caches npx/pnpm dlx/bunx unpack into. Telling those
+ * users to install globally would create the second copy on PATH they were
+ * deliberately avoiding.
+ */
+export declare function isEphemeralRunnerInstall(installDir: string | null): boolean;
+/**
+ * Directories npm installs global packages into. Derived from the running node
+ * rather than by shelling out to `npm prefix -g`, which would cost more than
+ * the version check itself. Only a hint: `process.execPath` is realpath'd, so
+ * on Homebrew it lands in the Cellar rather than the brew prefix — which is
+ * why the install's own layout is the primary signal below.
+ */
+export declare function npmGlobalRoots(): string[];
+/**
+ * The prefix of an npm global install, read from the install's own shape:
+ * `<prefix>/lib/node_modules/<pkg>` on POSIX, `<prefix>/node_modules/<pkg>` on
+ * Windows. Self-describing, so it holds for Homebrew, nvm, Debian and anywhere
+ * else npm's prefix is not derivable from the node binary. Null when the
+ * layout does not match.
+ */
+export declare function npmPrefixFromInstallDir(installDir: string | null): string | null;
+/**
+ * True only when npm itself owns this copy. Everything else — a pnpm, bun,
+ * yarn or volta global — would be made worse by `npm install -g`, which adds a
+ * second copy that may not even be the one on PATH.
+ */
+export declare function isNpmGlobalInstall(installDir: string | null, roots?: string[]): boolean;
+/**
+ * True when the CLI is running from a clone rather than an install. Upgrade
+ * advice is meaningless there: the version is whatever the branch says.
+ */
+export declare function isSourceCheckout(installDir: string | null): boolean;
+export type PackageManager = 'npm' | 'pnpm' | 'bun' | 'yarn' | 'volta';
+/**
+ * The package manager that owns this copy, so the printed command is one the
+ * user's setup will actually honor.
+ */
+export declare function detectPackageManager(installDir: string | null): PackageManager;
+/**
+ * Builds the hint, with the upgrade command chosen for how this copy of the CLI
+ * was installed. Pure so every branch is assertable.
+ */
+export declare function buildCliUpdateLines(latestVersion: string, installDir: string | null, projectPath: string, options?: {
+    withCommand?: boolean;
+}): string[];
+/**
+ * The upgrade command for however this copy was installed, plus the reminder
+ * that instruction files come from the CLI and so need a second pass.
+ */
+export declare function buildUpgradeCommandLines(installDir: string | null, projectPath: string): string[];
+/**
+ * Whether we can run the upgrade for the user instead of only printing it.
+ *
+ * Only an npm-owned global install qualifies, because `npm install -g` is the
+ * only command we run: a pnpm/bun/yarn/volta global would get a second copy
+ * that may not be the one on PATH, a project dependency belongs to that
+ * project's package manager, an npx/dlx cache has nothing to upgrade, and a
+ * source checkout is not an install at all.
+ */
+export declare function canSelfUpgrade(installDir: string | null, projectPath: string): boolean;
+/**
+ * Whether to offer the upgrade rather than just print the command. Kept here,
+ * as a pure function of the environment, because the interesting mistakes live
+ * in this decision: offering where `npm install -g` cannot help, or asking a
+ * question no one can answer.
+ */
+export declare function shouldOfferUpgrade(params: {
+    installDir: string | null;
+    projectPath: string;
+    interactive: boolean;
+    stdoutIsTty: boolean;
+}): boolean;
+/**
+ * The `openspec` npm installs alongside its global package, so the upgrade can
+ * be handed to the copy npm just wrote rather than to whatever PATH resolves.
+ * Null when it cannot be found, in which case PATH is the only option left.
+ */
+export declare function upgradedBinPath(roots?: string[], installDir?: string | null): string | null;
+/**
+ * Asks a CLI binary its version. Used to confirm an upgrade actually landed:
+ * `npm install -g` exits 0 even when it installed nothing, so its exit code
+ * alone cannot justify telling the user they are on a new version.
+ */
+export declare function readCliVersion(binPath: string): Promise<string | null>;
+export type UpgradeOutcome = 'upgraded' | 'declined' | 'failed' | 'cancelled' | 'not-on-path';
+/**
+ * Offers to run the upgrade and reports what actually happened. The version is
+ * read back from the installed binary rather than assumed, so "upgraded" is a
+ * fact and a PATH that still answers with the old copy is caught here instead
+ * of silently doing nothing.
+ */
+export declare function offerCliUpgrade(latestVersion: string): Promise<UpgradeOutcome>;
+/**
+ * Runs `openspec update` again with the CLI that was just installed — this
+ * process is still the old code, so it cannot write the new workflows itself.
+ * Resolves the exit code to pass along; when no `openspec` is on PATH the
+ * upgrade still landed but nothing was regenerated, so it says so and
+ * resolves 0 rather than reporting a failure the upgrade did not have.
+ */
+export declare function rerunUpdateWithUpgradedCli(projectPath: string, options?: {
+    force?: boolean;
+    binPath?: string;
+}): Promise<number>;
+/**
+ * Prints the upgrade hint. Instruction files are generated by the installed
+ * CLI, so "up to date" only ever means "matches this CLI" — without this note
+ * a stale install looks like a successful update.
+ */
+export declare function displayCliUpdateNote(latestVersion: string, projectPath?: string, options?: {
+    withCommand?: boolean;
+}): void;
+/**
+ * Prints just the manual command, for when the offer was declined or failed.
+ */
+export declare function displayUpgradeCommand(projectPath?: string): void;
+//# sourceMappingURL=version-check.d.ts.map