@fission-ai/openspec 1.4.0 → 1.5.0

package/dist/core/completions/shared-flags.js

@@ -24,5 +24,10 @@ export const COMMON_FLAGS = {
         takesValue: true,
         values: ['change', 'spec'],
     },
+    store: {
+        name: 'store',
+        description: "Store id to use as the OpenSpec root (a store is a standalone OpenSpec repo you've registered)",
+        takesValue: true,
+    },
 };
 //# sourceMappingURL=shared-flags.js.map

package/dist/core/config-schema.d.ts

@@ -58,13 +58,14 @@ export declare function deleteNestedValue(obj: Record<string, unknown>, path: st
  * Coerce a string value to its appropriate type.
  * - "true" / "false" -> boolean
  * - Numeric strings -> number
+ * - JSON arrays/objects -> parsed containers
  * - Everything else -> string
  *
  * @param value - The string value to coerce
  * @param forceString - If true, always return the value as a string
  * @returns The coerced value
  */
-export declare function coerceValue(value: string, forceString?: boolean): string | number | boolean;
+export declare function coerceValue(value: string, forceString?: boolean): string | number | boolean | unknown[] | Record<string, unknown>;
 /**
  * Format a value for YAML-like display.
  *

package/dist/core/config-schema.js

@@ -125,6 +125,7 @@ export function deleteNestedValue(obj, path) {
  * Coerce a string value to its appropriate type.
  * - "true" / "false" -> boolean
  * - Numeric strings -> number
+ * - JSON arrays/objects -> parsed containers
  * - Everything else -> string
  *
  * @param value - The string value to coerce
@@ -147,8 +148,33 @@ export function coerceValue(value, forceString = false) {
     if (!isNaN(num) && isFinite(num) && value.trim() !== '') {
         return num;
     }
+    const jsonContainer = parseJsonContainer(value);
+    if (jsonContainer !== undefined) {
+        return jsonContainer;
+    }
     return value;
 }
+function parseJsonContainer(value) {
+    const trimmed = value.trim();
+    const looksLikeContainer = (trimmed.startsWith('[') && trimmed.endsWith(']')) ||
+        (trimmed.startsWith('{') && trimmed.endsWith('}'));
+    if (!looksLikeContainer) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (Array.isArray(parsed)) {
+            return parsed;
+        }
+        if (parsed !== null && typeof parsed === 'object') {
+            return parsed;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
 /**
  * Format a value for YAML-like display.
  *

package/dist/core/file-state.d.ts

@@ -0,0 +1,36 @@
+import * as nodeFs from 'node:fs';
+import { StoreError } from './store/errors.js';
+/**
+ * Shared machine-local state-file mechanics (extracted from the store
+ * registry in slice 7.1, its second consumer). Callers own the
+ * diagnostic data (code, target, wording); the factory owns the
+ * shared mechanics - the fix strings describe the lock's own
+ * behavior (stale-steal, creation), so their templates live here.
+ */
+export type FileLockErrorKind = 'create-failed' | 'timeout';
+export interface FileLockErrorInfo {
+    lockPath: string;
+    /** The original errno error for 'create-failed'. */
+    cause?: unknown;
+}
+export interface FileLockOptions {
+    lockPath: string;
+    errorFor: (kind: FileLockErrorKind, info: FileLockErrorInfo) => Error;
+}
+export interface LockErrorData {
+    /** Noun phrase for the create-failed message, e.g. "the registry lock file". */
+    createSubject: string;
+    /** The full timeout message, e.g. "Store registry is busy." */
+    busyMessage: string;
+    code: string;
+    target: string;
+}
+/** One template for lock diagnostics; callers supply the data. */
+export declare function makeLockErrorFactory(data: LockErrorData): (kind: FileLockErrorKind, info: FileLockErrorInfo) => StoreError;
+export declare function isNodeErrorCode(error: unknown, code: string): boolean;
+export declare function pathIsFile(filePath: string): Promise<boolean>;
+export declare function pathIsDirectory(dirPath: string): Promise<boolean>;
+export declare function writeFileAtomically(filePath: string, content: string): Promise<void>;
+export declare function acquireFileLock(options: FileLockOptions): Promise<nodeFs.promises.FileHandle>;
+export declare function releaseFileLock(lock: nodeFs.promises.FileHandle, lockPath: string): Promise<void>;
+//# sourceMappingURL=file-state.d.ts.map

package/dist/core/file-state.js

@@ -0,0 +1,112 @@
+import * as nodeFs from 'node:fs';
+import * as path from 'node:path';
+import { FileSystemUtils } from '../utils/file-system.js';
+import { StoreError } from './store/errors.js';
+const fs = nodeFs.promises;
+/** One template for lock diagnostics; callers supply the data. */
+export function makeLockErrorFactory(data) {
+    return (kind, info) => {
+        if (kind === 'create-failed') {
+            // A permission or filesystem problem, not contention - say so.
+            return new StoreError(`Cannot create ${data.createSubject} ${info.lockPath} (${info.cause?.code ?? info.cause}).`, data.code, {
+                target: data.target,
+                fix: `Check permissions on ${path.dirname(info.lockPath)}.`,
+            });
+        }
+        return new StoreError(data.busyMessage, data.code, {
+            target: data.target,
+            fix: `Retry shortly; if this persists, delete the stale lock file ${info.lockPath}.`,
+        });
+    };
+}
+const STALE_LOCK_THRESHOLD_MS = 30_000;
+const LOCK_DEADLINE_MS = 5000;
+const LOCK_POLL_MS = 25;
+export function isNodeErrorCode(error, code) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === code);
+}
+export async function pathIsFile(filePath) {
+    try {
+        return (await fs.stat(filePath)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+// Deliberately not FileSystemUtils.directoryExists: that variant
+// debug-logs non-ENOENT failures, which is noise inside prompt
+// validators, and pathIsFile has no FileSystemUtils equivalent - the
+// silent symmetric pair lives here.
+export async function pathIsDirectory(dirPath) {
+    try {
+        return (await fs.stat(dirPath)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function sleep(milliseconds) {
+    await new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+export async function writeFileAtomically(filePath, content) {
+    const dirPath = path.dirname(filePath);
+    await FileSystemUtils.createDirectory(dirPath);
+    const tempPath = path.join(dirPath, `.${path.basename(filePath)}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`);
+    try {
+        await fs.writeFile(tempPath, content, 'utf-8');
+        await fs.rename(tempPath, filePath);
+    }
+    catch (error) {
+        await fs.rm(tempPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+export async function acquireFileLock(options) {
+    const { lockPath, errorFor } = options;
+    const lockDir = path.dirname(lockPath);
+    await FileSystemUtils.createDirectory(lockDir);
+    if (!(await FileSystemUtils.canWriteFile(lockDir))) {
+        throw errorFor('create-failed', { lockPath, cause: 'EACCES' });
+    }
+    const deadline = Date.now() + LOCK_DEADLINE_MS;
+    while (true) {
+        try {
+            return await fs.open(lockPath, 'wx');
+        }
+        catch (error) {
+            if (!isNodeErrorCode(error, 'EEXIST')) {
+                // A permission or filesystem problem, not contention - say so.
+                throw errorFor('create-failed', { lockPath, cause: error });
+            }
+            // A crashed process leaves the lock behind forever; state-file
+            // writes are sub-second, so an old lock is an orphan - steal it.
+            let staleStolen = false;
+            try {
+                const lockStat = await fs.stat(lockPath);
+                if (Date.now() - lockStat.mtimeMs > STALE_LOCK_THRESHOLD_MS) {
+                    await fs.rm(lockPath, { force: true });
+                    staleStolen = true;
+                }
+            }
+            catch {
+                // The holder released between open and stat - retry, but stay
+                // bounded: a persistently failing stat (EPERM, delete-pending)
+                // must hit the deadline instead of spinning forever.
+            }
+            if (!staleStolen) {
+                if (Date.now() >= deadline) {
+                    throw errorFor('timeout', { lockPath });
+                }
+                await sleep(LOCK_POLL_MS);
+            }
+        }
+    }
+}
+export async function releaseFileLock(lock, lockPath) {
+    await lock.close().catch(() => undefined);
+    await fs.rm(lockPath, { force: true }).catch(() => undefined);
+}
+//# sourceMappingURL=file-state.js.map

package/dist/core/global-config.d.ts

@@ -8,6 +8,8 @@ export interface GlobalConfig {
     profile?: Profile;
     delivery?: Delivery;
     workflows?: string[];
+    /** Workset opener rows (slice 7.1); hand-edited, validated on use. */
+    openers?: unknown;
 }
 /**
  * Gets the global configuration directory path following XDG Base Directory Specification.

package/dist/core/id.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The one kebab id grammar. Store ids, change ids, and legacy initiative ids
+ * all share it.
+ */
+export declare const KEBAB_ID_REGEX: RegExp;
+export declare function isKebabId(value: string): boolean;
+/** Human rendering of the grammar, shared so the wording never forks. */
+export declare const KEBAB_ID_DESCRIPTION = "must be kebab-case with lowercase letters, numbers, and single hyphen separators";
+/** The fix-line twin of KEBAB_ID_DESCRIPTION, shared for the same reason. */
+export declare const KEBAB_ID_FIX = "Use kebab-case with lowercase letters, numbers, and single hyphen separators.";
+/**
+ * The folder-safe-name grammar (store ids layer the kebab grammar on
+ * top of it; workset member labels use it alone). Returns a problem
+ * description, or null when valid.
+ */
+export declare function folderStyleNameProblem(value: string, label: string): string | null;
+//# sourceMappingURL=id.d.ts.map

package/dist/core/id.js

@@ -0,0 +1,30 @@
+/**
+ * The one kebab id grammar. Store ids, change ids, and legacy initiative ids
+ * all share it.
+ */
+export const KEBAB_ID_REGEX = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+export function isKebabId(value) {
+    return KEBAB_ID_REGEX.test(value);
+}
+/** Human rendering of the grammar, shared so the wording never forks. */
+export const KEBAB_ID_DESCRIPTION = 'must be kebab-case with lowercase letters, numbers, and single hyphen separators';
+/** The fix-line twin of KEBAB_ID_DESCRIPTION, shared for the same reason. */
+export const KEBAB_ID_FIX = 'Use kebab-case with lowercase letters, numbers, and single hyphen separators.';
+/**
+ * The folder-safe-name grammar (store ids layer the kebab grammar on
+ * top of it; workset member labels use it alone). Returns a problem
+ * description, or null when valid.
+ */
+export function folderStyleNameProblem(value, label) {
+    if (value.length === 0) {
+        return `${label} must not be empty`;
+    }
+    if (value === '.' || value === '..') {
+        return `${label} must not be '${value}'`;
+    }
+    if (/[\\/]/u.test(value)) {
+        return `${label} must not contain path separators`;
+    }
+    return null;
+}
+//# sourceMappingURL=id.js.map

package/dist/core/index.d.ts

@@ -1,6 +1,6 @@
 export { GLOBAL_CONFIG_DIR_NAME, GLOBAL_CONFIG_FILE_NAME, GLOBAL_DATA_DIR_NAME, type GlobalDataDirOptions, type GlobalConfig, getGlobalConfigDir, getGlobalConfigPath, getGlobalConfig, saveGlobalConfig, getGlobalDataDir } from './global-config.js';
-export * from './workspace/index.js';
-export * from './context-store/index.js';
-export * from './collections/index.js';
+export * from './references.js';
+export * from './store/index.js';
 export * from './planning-home.js';
+export * from './openspec-root.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.js

@@ -1,7 +1,7 @@
 // Core OpenSpec logic will be implemented here
 export { GLOBAL_CONFIG_DIR_NAME, GLOBAL_CONFIG_FILE_NAME, GLOBAL_DATA_DIR_NAME, getGlobalConfigDir, getGlobalConfigPath, getGlobalConfig, saveGlobalConfig, getGlobalDataDir } from './global-config.js';
-export * from './workspace/index.js';
-export * from './context-store/index.js';
-export * from './collections/index.js';
+export * from './references.js';
+export * from './store/index.js';
 export * from './planning-home.js';
+export * from './openspec-root.js';
 //# sourceMappingURL=index.js.map

package/dist/core/init.js

@@ -10,6 +10,8 @@ import ora from 'ora';
 import * as fs from 'fs';
 import { createRequire } from 'module';
 import { FileSystemUtils } from '../utils/file-system.js';
+import { classifyOpenSpecDir, storePointerProblem } from './project-config.js';
+import { findRepoPlanningRootSync } from './planning-home.js';
 import { transformToHyphenCommands } from '../utils/command-references.js';
 import { AI_TOOLS, OPENSPEC_DIR_NAME, } from './config.js';
 import { PALETTE } from './styles/palette.js';
@@ -65,6 +67,28 @@ export class InitCommand {
         const openspecPath = path.join(projectPath, openspecDir);
         // Validation happens silently in the background
         const extendMode = await this.validate(projectPath, openspecPath);
+        // Pointer guard (slice 3.2): a config-only openspec/ with a store:
+        // declaration is externalized planning, not a root to extend — and a
+        // subdirectory of such a repo must not silently grow a nested root.
+        // Refuse before legacy cleanup, migration, or prompts touch anything.
+        // In extend mode the walk finds projectPath itself; otherwise it
+        // finds the nearest ancestor root (so pointer-repo subdirectories
+        // refuse exactly where a normal command would resolve the pointer).
+        const guardRoot = findRepoPlanningRootSync(projectPath);
+        if (guardRoot) {
+            const { hasPlanningShape, pointer } = classifyOpenSpecDir(guardRoot);
+            if (!hasPlanningShape) {
+                if (pointer.malformed) {
+                    throw new Error(`The store declaration in ${pointer.filePath} is invalid (` +
+                        storePointerProblem(pointer.malformed) +
+                        `). Fix or remove the store: line before running openspec init.`);
+                }
+                if (pointer.value !== undefined) {
+                    throw new Error(`This repo's planning is externalized to store '${pointer.value}' (${pointer.filePath}). ` +
+                        `Remove the store: line first to convert this repo to a local OpenSpec root.`);
+                }
+            }
+        }
         // Check for legacy artifacts and handle cleanup
         await this.handleLegacyCleanup(projectPath, extendMode);
         // Detect available tools in the project (task 7.1)
@@ -440,10 +464,6 @@ export class InitCommand {
         if (configYamlExists || configYmlExists) {
             return 'exists';
         }
-        // In non-interactive mode without --force, skip config creation
-        if (!this.canPromptInteractively() && !this.force) {
-            return 'skipped';
-        }
         try {
             const yamlContent = serializeConfig({ schema: DEFAULT_SCHEMA });
             await FileSystemUtils.writeFile(configPath, yamlContent);

package/dist/core/list.d.ts

@@ -1,6 +1,8 @@
+import type { RootOutput } from './root-selection.js';
 interface ListOptions {
     sort?: 'recent' | 'name';
     json?: boolean;
+    root?: RootOutput;
 }
 export declare class ListCommand {
     execute(targetPath?: string, mode?: 'changes' | 'specs', options?: ListOptions): Promise<void>;

package/dist/core/list.js

@@ -61,7 +61,7 @@ function formatRelativeTime(date) {
 }
 export class ListCommand {
     async execute(targetPath = '.', mode = 'changes', options = {}) {
-        const { sort = 'recent', json = false } = options;
+        const { sort = 'recent', json = false, root } = options;
         if (mode === 'changes') {
             const changesDir = path.join(targetPath, 'openspec', 'changes');
             // Check if changes directory exists
@@ -78,7 +78,7 @@ export class ListCommand {
                 .map(entry => entry.name);
             if (changeDirs.length === 0) {
                 if (json) {
-                    console.log(JSON.stringify({ changes: [] }));
+                    console.log(JSON.stringify({ changes: [], ...(root ? { root } : {}) }, null, 2));
                 }
                 else {
                     console.log('No active changes found.');
@@ -114,7 +114,7 @@ export class ListCommand {
                     lastModified: c.lastModified.toISOString(),
                     status: c.totalTasks === 0 ? 'no-tasks' : c.completedTasks === c.totalTasks ? 'complete' : 'in-progress'
                 }));
-                console.log(JSON.stringify({ changes: jsonOutput }, null, 2));
+                console.log(JSON.stringify({ changes: jsonOutput, ...(root ? { root } : {}) }, null, 2));
                 return;
             }
             // Display results
@@ -135,13 +135,23 @@ export class ListCommand {
             await fs.access(specsDir);
         }
         catch {
-            console.log('No specs found.');
+            if (json) {
+                console.log(JSON.stringify({ specs: [], ...(root ? { root } : {}) }, null, 2));
+            }
+            else {
+                console.log('No specs found.');
+            }
             return;
         }
         const entries = await fs.readdir(specsDir, { withFileTypes: true });
         const specDirs = entries.filter(e => e.isDirectory()).map(e => e.name);
         if (specDirs.length === 0) {
-            console.log('No specs found.');
+            if (json) {
+                console.log(JSON.stringify({ specs: [], ...(root ? { root } : {}) }, null, 2));
+            }
+            else {
+                console.log('No specs found.');
+            }
             return;
         }
         const specs = [];
@@ -159,6 +169,10 @@ export class ListCommand {
             }
         }
         specs.sort((a, b) => a.id.localeCompare(b.id));
+        if (json) {
+            console.log(JSON.stringify({ specs, ...(root ? { root } : {}) }, null, 2));
+            return;
+        }
         console.log('Specs:');
         const padding = '  ';
         const nameWidth = Math.max(...specs.map(s => s.id.length));

package/dist/core/openers.d.ts

@@ -0,0 +1,77 @@
+import type { WorksetMember } from './worksets.js';
+/**
+ * The workset opener table (slice 7.1). Supporting a new tool is
+ * configuration, not code: every tool is an instance of one of exactly
+ * two launch styles - 'workspace-file' (invoke with the generated
+ * .code-workspace) or 'attach-dirs' (pre-args plus one attach flag per
+ * member; no positional, ever - agent sessions open clean). Users add
+ * tools or adjust parameters under the global config file's `openers`
+ * key (the git difftool/mergetool pattern).
+ */
+export type OpenerStyle = 'workspace-file' | 'attach-dirs';
+export interface OpenerDefinition {
+    id: string;
+    label: string;
+    style: OpenerStyle;
+    command: string;
+    /** Pre-args before any attach flags or the workspace-file path. */
+    args: string[];
+    /** attach-dirs only; one flag + path pair per member. */
+    attachFlag: string;
+}
+/**
+ * Temporary kill-switch (2026-06): worksets open only in IDE-style
+ * ('workspace-file') tools while the CLI-agent ('attach-dirs') open flow
+ * is reworked. The agents (Claude Code, codex) launch in a single primary
+ * cwd rather than a true combined multi-root view, which makes "where does
+ * my change land?" ambiguous. Default off; set
+ * OPENSPEC_ENABLE_CLI_AGENT_OPENERS=1 to restore them (internal rollback seam).
+ */
+export declare function isCliAgentOpenersEnabled(): boolean;
+/** Whether a tool can be opened right now (CLI-agent styles are gated). */
+export declare function isOpenerEnabled(opener: OpenerDefinition): boolean;
+export declare const BUILTIN_OPENERS: readonly OpenerDefinition[];
+export declare function mergeOpenerTable(rawOpeners: unknown, configPath: string): OpenerDefinition[];
+export interface OpenerScanOptions {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    /** Stat seam for tests (win32 candidate paths on posix hosts). */
+    isExecutableFile?: (candidatePath: string) => boolean;
+}
+/**
+ * PATH availability scan (ported from the deleted workspace openers
+ * at f858c19^, sharpened for injectability: the path module is keyed
+ * by the injected platform, and a command already carrying a known
+ * executable extension matches as-is).
+ */
+export declare function isOpenerCommandAvailable(command: string, options?: OpenerScanOptions): boolean;
+export interface OpenerChoice {
+    opener: OpenerDefinition;
+    available: boolean;
+    /** `(<command> not found on PATH)` when unavailable. */
+    note: string | null;
+}
+/** Table order preserved, available tools first (stable sort). */
+export declare function listOpenerChoices(table: OpenerDefinition[], options?: OpenerScanOptions): OpenerChoice[];
+export declare function findOpener(table: OpenerDefinition[], id: string): OpenerDefinition | null;
+export interface LaunchCommand {
+    executable: string;
+    args: string[];
+    /** The surviving primary member's path. */
+    cwd: string;
+    label: string;
+    style: OpenerStyle;
+}
+/**
+ * Pure argv builder. workspace-file: pre-args + the generated file's
+ * absolute path (which also defuses the cursor shim's `agent`
+ * first-arg hijack). attach-dirs: pre-args + one attach flag + path
+ * pair per surviving member, the primary included (the locked "one
+ * attach flag per member"); never a trailing positional - both agent
+ * CLIs would read one as a starter prompt, which 7.1 locks out.
+ */
+export declare function buildLaunchCommand(opener: OpenerDefinition, input: {
+    members: WorksetMember[];
+    codeWorkspacePath: string;
+}): LaunchCommand;
+//# sourceMappingURL=openers.d.ts.map