gmc-openspec 1.0.0 → 1.4.1

package/dist/core/context-store/registry.js

@@ -0,0 +1,229 @@
+import * as fs from 'node:fs/promises';
+import { getContextStoreMetadataPath, getContextStoreMetadataDir, listContextStoreRegistryEntries, readContextStoreRegistryState, readOptionalContextStoreMetadataState, resolveGitContextStoreBackendConfig, updateContextStoreRegistryState, validateContextStoreId, writeContextStoreMetadataState, } from './foundation.js';
+import { ContextStoreError } from './errors.js';
+import { FileSystemUtils } from '../../utils/file-system.js';
+export function getStoreRootForBackend(backend) {
+    switch (backend.type) {
+        case 'git':
+            return backend.local_path;
+    }
+}
+function normalizePathForComparison(targetPath) {
+    try {
+        return FileSystemUtils.canonicalizeExistingPath(targetPath);
+    }
+    catch {
+        return targetPath;
+    }
+}
+export function assertNoRegisteredStoreConflict(registry, id, backend) {
+    const nextPath = normalizePathForComparison(getStoreRootForBackend(backend));
+    for (const entry of listContextStoreRegistryEntries(registry ?? { version: 1, stores: {} })) {
+        const entryPath = normalizePathForComparison(getStoreRootForBackend(entry.backend));
+        if (entry.id === id && entryPath === nextPath) {
+            continue;
+        }
+        if (entry.id === id) {
+            throw new ContextStoreError(`Context store '${id}' is already registered at ${getStoreRootForBackend(entry.backend)}.`, 'context_store_id_conflict', {
+                target: 'context_store.id',
+                fix: 'Use the existing registration or choose a different context store id.',
+            });
+        }
+        if (entryPath === nextPath) {
+            throw new ContextStoreError(`Context store path is already registered as '${entry.id}'.`, 'context_store_path_conflict', {
+                target: 'context_store.root',
+                fix: `Use the existing '${entry.id}' registration or choose a different path.`,
+            });
+        }
+    }
+}
+function withRegisteredStore(registry, id, backend) {
+    assertNoRegisteredStoreConflict(registry, id, backend);
+    const stores = {
+        ...(registry?.stores ?? {}),
+        [id]: {
+            backend,
+        },
+    };
+    return {
+        version: 1,
+        stores: Object.fromEntries(Object.entries(stores).sort(([leftId], [rightId]) => leftId.localeCompare(rightId))),
+    };
+}
+function getRegisteredStoreOrThrow(registry, id) {
+    const entry = registry?.stores[id];
+    if (!entry) {
+        throw new ContextStoreError(`Unknown context store '${id}'`, 'context_store_not_found', {
+            target: 'context_store.id',
+            fix: 'Run openspec context-store list to see registered stores.',
+        });
+    }
+    return {
+        id,
+        backend: entry.backend,
+    };
+}
+function contextStoreBackendsMatch(actual, expected) {
+    return (actual.type === expected.type &&
+        normalizePathForComparison(actual.local_path) ===
+            normalizePathForComparison(expected.local_path) &&
+        actual.remote === expected.remote &&
+        actual.branch === expected.branch);
+}
+function assertExpectedRegisteredBackend(id, actual, expected) {
+    if (!expected || contextStoreBackendsMatch(actual, expected))
+        return;
+    throw new ContextStoreError(`Context store '${id}' changed before cleanup completed.`, 'context_store_registry_changed', {
+        target: 'context_store.registry',
+        fix: 'Retry the cleanup command after reviewing the current context-store registration.',
+    });
+}
+function withoutRegisteredStore(registry, id, expectedBackend) {
+    const removed = getRegisteredStoreOrThrow(registry, id);
+    assertExpectedRegisteredBackend(id, removed.backend, expectedBackend);
+    const stores = { ...(registry?.stores ?? {}) };
+    delete stores[id];
+    return {
+        removed,
+        next: {
+            version: 1,
+            stores: Object.fromEntries(Object.entries(stores).sort(([leftId], [rightId]) => leftId.localeCompare(rightId))),
+        },
+    };
+}
+async function ensureStoreMetadata(storeRoot, id, options) {
+    const metadata = await readOptionalContextStoreMetadataState(storeRoot);
+    if (!metadata) {
+        if (!options.writeIfMissing) {
+            throw new ContextStoreError(`Registered context store '${id}' is missing metadata at ${getContextStoreMetadataPath(storeRoot)}`, 'context_store_metadata_missing', {
+                target: 'context_store.metadata',
+                fix: `Create ${getContextStoreMetadataPath(storeRoot)} or rerun context-store register.`,
+            });
+        }
+        await writeContextStoreMetadataState(storeRoot, {
+            version: 1,
+            id,
+        });
+        return true;
+    }
+    if (metadata.id !== id) {
+        throw new ContextStoreError(`Context store metadata id '${metadata.id}' does not match registered id '${id}'`, 'context_store_metadata_id_mismatch', {
+            target: 'context_store.metadata',
+            fix: 'Repair the local registry or store metadata so the ids match.',
+        });
+    }
+    return false;
+}
+export async function commitContextStoreRegistration(input) {
+    const id = validateContextStoreId(input.id);
+    const backend = input.backend;
+    const storeRoot = getStoreRootForBackend(backend);
+    let metadataCreated = false;
+    try {
+        metadataCreated = await ensureStoreMetadata(storeRoot, id, {
+            writeIfMissing: input.writeMetadataIfMissing,
+        });
+        await updateContextStoreRegistryState((registry) => withRegisteredStore(registry, id, backend), { globalDataDir: input.globalDataDir });
+    }
+    catch (error) {
+        if (metadataCreated) {
+            await fs.rm(getContextStoreMetadataPath(storeRoot), { force: true });
+            await fs.rmdir(getContextStoreMetadataDir(storeRoot)).catch(() => undefined);
+        }
+        throw error;
+    }
+    return {
+        id,
+        storeRoot,
+        backend,
+        metadataCreated,
+    };
+}
+export async function registerContextStore(input) {
+    const id = validateContextStoreId(input.id);
+    const backend = await resolveGitContextStoreBackendConfig({
+        localPath: input.localPath,
+        ...(input.remote !== undefined ? { remote: input.remote } : {}),
+        ...(input.branch !== undefined ? { branch: input.branch } : {}),
+    }, input.cwd);
+    const storeRoot = getStoreRootForBackend(backend);
+    const committed = await commitContextStoreRegistration({
+        id,
+        backend,
+        writeMetadataIfMissing: true,
+        ...(input.globalDataDir ? { globalDataDir: input.globalDataDir } : {}),
+    });
+    return {
+        id: committed.id,
+        storeRoot: committed.storeRoot,
+        backend: committed.backend,
+    };
+}
+export async function listRegisteredContextStores(options = {}) {
+    const registry = await readContextStoreRegistryState(options);
+    if (!registry) {
+        return [];
+    }
+    return listContextStoreRegistryEntries(registry).map((entry) => ({
+        ...entry,
+        storeRoot: getStoreRootForBackend(entry.backend),
+    }));
+}
+export async function getRegisteredContextStore(input) {
+    const id = validateContextStoreId(input.id);
+    const registry = await readContextStoreRegistryState({
+        globalDataDir: input.globalDataDir,
+    });
+    const entry = getRegisteredStoreOrThrow(registry, id);
+    assertExpectedRegisteredBackend(id, entry.backend, input.expectedBackend);
+    return {
+        ...entry,
+        storeRoot: getStoreRootForBackend(entry.backend),
+    };
+}
+export async function unregisterContextStoreRegistration(input) {
+    const id = validateContextStoreId(input.id);
+    let removed;
+    await updateContextStoreRegistryState(async (registry) => {
+        const result = withoutRegisteredStore(registry, id, input.expectedBackend);
+        const removedEntry = {
+            ...result.removed,
+            storeRoot: getStoreRootForBackend(result.removed.backend),
+        };
+        await input.beforeCommit?.(removedEntry);
+        removed = result.removed;
+        return result.next;
+    }, { globalDataDir: input.globalDataDir });
+    if (!removed) {
+        throw new ContextStoreError(`Unknown context store '${id}'`, 'context_store_not_found', {
+            target: 'context_store.id',
+            fix: 'Run openspec context-store list to see registered stores.',
+        });
+    }
+    return {
+        ...removed,
+        storeRoot: getStoreRootForBackend(removed.backend),
+    };
+}
+export async function resolveRegisteredContextStore(input) {
+    const id = validateContextStoreId(input.id);
+    const registry = await readContextStoreRegistryState({
+        globalDataDir: input.globalDataDir,
+    });
+    if (!registry) {
+        throw new ContextStoreError('No context store registry found', 'no_context_store_registry', {
+            target: 'context_store.id',
+            fix: 'Register a context store before using --store, or pass --store-path <path>.',
+        });
+    }
+    const entry = getRegisteredStoreOrThrow(registry, id);
+    const backend = entry.backend;
+    const storeRoot = getStoreRootForBackend(backend);
+    await ensureStoreMetadata(storeRoot, id, { writeIfMissing: false });
+    return {
+        id,
+        storeRoot,
+        backend,
+    };
+}
+//# sourceMappingURL=registry.js.map

package/dist/core/index.d.ts

@@ -1,5 +1,7 @@
 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 './jira/index.js';
+export * from './context-store/index.js';
+export * from './collections/index.js';
 export * from './planning-home.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.js

@@ -2,5 +2,7 @@
 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 './jira/index.js';
+export * from './context-store/index.js';
+export * from './collections/index.js';
 export * from './planning-home.js';
 //# sourceMappingURL=index.js.map

package/dist/core/planning-home.js

@@ -1,6 +1,6 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { getWorkspaceChangesDir, getWorkspaceSharedStatePath, parseWorkspaceSharedState, } from './workspace/index.js';
+import { getWorkspaceChangesDir, readWorkspaceViewStateSync, workspaceStateFileExistsSync, } from './workspace/index.js';
 import { FileSystemUtils } from '../utils/file-system.js';
 const REPO_DEFAULT_SCHEMA = 'spec-driven';
 const WORKSPACE_DEFAULT_SCHEMA = 'workspace-planning';
@@ -12,14 +12,6 @@ function pathExistsAsDirectory(candidatePath) {
         return false;
     }
 }
-function pathExistsAsFile(candidatePath) {
-    try {
-        return fs.statSync(candidatePath).isFile();
-    }
-    catch {
-        return false;
-    }
-}
 function getSearchStartDirectory(startPath) {
     const resolved = path.resolve(startPath);
     try {
@@ -45,7 +37,7 @@ function findNearestAncestor(startPath, predicate) {
     }
 }
 export function findWorkspacePlanningRootSync(startPath = process.cwd()) {
-    return findNearestAncestor(startPath, (dirPath) => pathExistsAsFile(getWorkspaceSharedStatePath(dirPath)));
+    return findNearestAncestor(startPath, workspaceStateFileExistsSync);
 }
 export function findRepoPlanningRootSync(startPath = process.cwd()) {
     return findNearestAncestor(startPath, (dirPath) => pathExistsAsDirectory(path.join(dirPath, 'openspec')));
@@ -66,24 +58,16 @@ function relativePlanningPath(fromPath, toPath) {
     }
     return path.posix.relative(fromPath.replace(/\\/g, '/'), toPath.replace(/\\/g, '/'));
 }
-function readWorkspaceSharedStateSync(workspaceRoot) {
-    try {
-        return parseWorkspaceSharedState(fs.readFileSync(getWorkspaceSharedStatePath(workspaceRoot), 'utf-8'));
-    }
-    catch {
-        return null;
-    }
-}
 function workspacePlanningHome(workspaceRoot) {
-    const sharedState = readWorkspaceSharedStateSync(workspaceRoot);
+    const viewState = readWorkspaceViewStateSync(workspaceRoot);
     return {
         kind: 'workspace',
         root: workspaceRoot,
         changesDir: getWorkspaceChangesDir(workspaceRoot),
         defaultSchema: WORKSPACE_DEFAULT_SCHEMA,
         workspace: {
-            name: sharedState?.name ?? path.basename(workspaceRoot),
-            links: Object.keys(sharedState?.links ?? {}).sort((a, b) => a.localeCompare(b)),
+            name: viewState?.name ?? path.basename(workspaceRoot),
+            links: Object.keys(viewState?.links ?? {}).sort((a, b) => a.localeCompare(b)),
         },
     };
 }

package/dist/core/validation/validator.d.ts

@@ -27,6 +27,17 @@ export declare class Validator {
     isValid(report: ValidationReport): boolean;
     private extractRequirementText;
     private containsShallOrMust;
+    /**
+     * Build an error 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
+     * ("must contain SHALL or MUST") is confusing because the keyword is visibly
+     * present in the spec. Per the OpenSpec conventions the keyword has to live
+     * 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.
+     */
+    private buildMissingShallOrMustMessage;
     private countScenarios;
     private formatSectionList;
 }

package/dist/core/validation/validator.js

@@ -150,7 +150,7 @@ export class Validator {
                         issues.push({ level: 'ERROR', path: entryPath, message: `ADDED "${block.name}" is missing requirement text` });
                     }
                     else if (!this.containsShallOrMust(requirementText)) {
-                        issues.push({ level: 'ERROR', path: entryPath, message: `ADDED "${block.name}" must contain SHALL or MUST` });
+                        issues.push({ level: 'ERROR', path: entryPath, message: this.buildMissingShallOrMustMessage('ADDED', block.name) });
                     }
                     const scenarioCount = this.countScenarios(block.raw);
                     if (scenarioCount < 1) {
@@ -172,7 +172,7 @@ export class Validator {
                         issues.push({ level: 'ERROR', path: entryPath, message: `MODIFIED "${block.name}" is missing requirement text` });
                     }
                     else if (!this.containsShallOrMust(requirementText)) {
-                        issues.push({ level: 'ERROR', path: entryPath, message: `MODIFIED "${block.name}" must contain SHALL or MUST` });
+                        issues.push({ level: 'ERROR', path: entryPath, message: this.buildMissingShallOrMustMessage('MODIFIED', block.name) });
                     }
                     const scenarioCount = this.countScenarios(block.raw);
                     if (scenarioCount < 1) {
@@ -401,6 +401,23 @@ export class Validator {
     containsShallOrMust(text) {
         return /\b(SHALL|MUST)\b/.test(text);
     }
+    /**
+     * Build an error 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
+     * ("must contain SHALL or MUST") is confusing because the keyword is visibly
+     * present in the spec. Per the OpenSpec conventions the keyword has to live
+     * 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`;
+        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;
+    }
     countScenarios(blockRaw) {
         const matches = blockRaw.match(/^####\s+/gm);
         return matches ? matches.length : 0;

package/dist/core/workspace/foundation.d.ts

@@ -1,13 +1,10 @@
+import { type ContextStoreBinding, type ContextStoreSelector } from '../context-store/index.js';
 export declare const WORKSPACE_METADATA_DIR_NAME = ".openspec-workspace";
-export declare const WORKSPACE_SHARED_STATE_FILE_NAME = "workspace.yaml";
-export declare const WORKSPACE_LOCAL_STATE_FILE_NAME = "local.yaml";
+export declare const WORKSPACE_VIEW_STATE_FILE_NAME = "workspace.yaml";
 export declare const WORKSPACE_CHANGES_DIR_NAME = "changes";
-export declare const MANAGED_WORKSPACES_DIR_NAME = "workspaces";
-export declare const WORKSPACE_REGISTRY_FILE_NAME = "registry.yaml";
-export declare const WORKSPACE_LOCAL_STATE_IGNORE_PATTERN = ".openspec-workspace/local.yaml";
 export declare const WORKSPACE_CODE_WORKSPACE_EXTENSION = ".code-workspace";
-export declare const WORKSPACE_SUPPORTED_OPENER_VALUES: readonly ["codex", "claude", "github-copilot", "editor"];
-export declare const WORKSPACE_AGENT_OPENER_IDS: readonly ["codex", "claude", "github-copilot"];
+export declare const WORKSPACE_SUPPORTED_OPENER_VALUES: readonly ["codex-cli", "claude", "github-copilot", "editor"];
+export declare const WORKSPACE_AGENT_OPENER_IDS: readonly ["codex-cli", "claude", "github-copilot"];
 export declare const WORKSPACE_EDITOR_OPENER_IDS: readonly ["vscode"];
 export type WorkspaceSupportedOpenerValue = typeof WORKSPACE_SUPPORTED_OPENER_VALUES[number];
 export type WorkspaceAgentOpenerId = typeof WORKSPACE_AGENT_OPENER_IDS[number];
@@ -19,16 +16,20 @@ export type WorkspacePreferredOpener = {
     kind: 'editor';
     id: WorkspaceEditorOpenerId;
 };
-export interface WorkspaceSharedState {
-    version: 1;
-    name: string;
-    links: Record<string, WorkspaceLinkState>;
+export interface WorkspaceContextState {
+    kind: 'initiative';
+    store: ContextStoreBinding;
+    initiative: {
+        id: string;
+    };
 }
-export type WorkspaceLinkState = Record<string, unknown>;
-export interface WorkspaceLocalState {
+export interface WorkspaceViewState {
     version: 1;
-    paths: Record<string, string>;
+    name: string;
+    context: WorkspaceContextState | null;
+    links: Record<string, string | null>;
     preferred_opener?: WorkspacePreferredOpener;
+    tools?: string[];
     workspace_skills?: WorkspaceSkillState;
 }
 export interface WorkspaceSkillState {
@@ -38,50 +39,29 @@ export interface WorkspaceSkillState {
     last_applied_workflow_ids?: string[];
     last_applied_at?: string;
 }
-export interface WorkspaceRegistryState {
-    version: 1;
-    workspaces: Record<string, string>;
-}
-export interface WorkspaceRegistryEntry {
-    name: string;
-    workspaceRoot: string;
-}
-export interface WorkspacePathOptions {
-    globalDataDir?: string;
-}
 export declare function getWorkspaceMetadataDir(workspaceRoot: string): string;
-export declare function getWorkspaceSharedStatePath(workspaceRoot: string): string;
-export declare function getWorkspaceLocalStatePath(workspaceRoot: string): string;
+export declare function getWorkspaceViewStatePath(workspaceRoot: string): string;
 export declare function getWorkspaceChangesDir(workspaceRoot: string): string;
-export declare function getManagedWorkspacesDir(options?: WorkspacePathOptions): string;
-export declare function getManagedWorkspaceRoot(workspaceName: string, options?: WorkspacePathOptions): string;
-export declare function getWorkspaceRegistryPath(options?: WorkspacePathOptions): string;
 export declare function getWorkspaceCodeWorkspaceFileName(workspaceName: string): string;
 export declare function getWorkspaceCodeWorkspacePath(workspaceRoot: string, workspaceName: string): string;
-export declare function getWorkspacePortableIgnorePatterns(workspaceName?: string): string[];
+/**
+ * @deprecated Managed workspaces no longer create portable ignore rules.
+ * This compatibility shim remains for callers that still ask which ignore
+ * patterns OpenSpec owns for workspace-local generated files.
+ */
+export declare function getWorkspacePortableIgnorePatterns(_workspaceName?: string): string[];
 export declare function validateWorkspaceName(name: string): string;
 export declare function validateWorkspaceLinkName(name: string): string;
 export declare function isValidWorkspaceName(name: string): boolean;
 export declare function isValidWorkspaceLinkName(name: string): boolean;
-export declare function isWorkspaceRoot(candidateRoot: string): Promise<boolean>;
-export declare function findWorkspaceRoot(startPath?: string): Promise<string | null>;
 export declare function isWorkspaceAgentOpenerId(value: string): value is WorkspaceAgentOpenerId;
 export declare function isWorkspaceSupportedOpenerValue(value: string): value is WorkspaceSupportedOpenerValue;
 export declare function parseWorkspacePreferredOpenerValue(value: string): WorkspacePreferredOpener;
 export declare function validateWorkspacePreferredOpener(opener: WorkspacePreferredOpener): WorkspacePreferredOpener;
-export declare function parseWorkspaceSharedState(content: string): WorkspaceSharedState;
-export declare function parseWorkspaceLocalState(content: string): WorkspaceLocalState;
-export declare function parseWorkspaceRegistryState(content: string): WorkspaceRegistryState;
-export declare function serializeWorkspaceSharedState(state: WorkspaceSharedState): string;
-export declare function serializeWorkspaceLocalState(state: WorkspaceLocalState): string;
-export declare function serializeWorkspaceRegistryState(state: WorkspaceRegistryState): string;
-export declare function listWorkspaceRegistryEntries(registry: WorkspaceRegistryState): WorkspaceRegistryEntry[];
-export declare function readWorkspaceSharedState(workspaceRoot: string): Promise<WorkspaceSharedState>;
-export declare function readWorkspaceLocalState(workspaceRoot: string): Promise<WorkspaceLocalState>;
-export declare function readOptionalWorkspaceLocalState(workspaceRoot: string): Promise<WorkspaceLocalState | null>;
-export declare function writeWorkspaceSharedState(workspaceRoot: string, state: WorkspaceSharedState): Promise<void>;
-export declare function writeWorkspaceLocalState(workspaceRoot: string, state: WorkspaceLocalState): Promise<void>;
-export declare function readWorkspaceRegistryState(options?: WorkspacePathOptions): Promise<WorkspaceRegistryState | null>;
-export declare function writeWorkspaceRegistryState(state: WorkspaceRegistryState, options?: WorkspacePathOptions): Promise<void>;
-export declare function workspaceChangesDirExists(workspaceRoot: string): Promise<boolean>;
+export declare function createWorkspaceInitiativeContext(store: ContextStoreBinding, initiativeId: string): WorkspaceContextState;
+export declare function getWorkspaceContextStoreId(context: WorkspaceContextState): string;
+export declare function getWorkspaceContextStoreSelector(context: WorkspaceContextState): ContextStoreSelector;
+export declare function getWorkspaceContextInitiativeId(context: WorkspaceContextState): string;
+export declare function parseWorkspaceViewState(content: string): WorkspaceViewState;
+export declare function serializeWorkspaceViewState(state: WorkspaceViewState): string;
 //# sourceMappingURL=foundation.d.ts.map