@codewalla_india/openspec 1.0.1

package/dist/core/store/foundation.js

@@ -0,0 +1,251 @@
+import * as nodeFs from 'node:fs';
+import * as path from 'node:path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { z } from 'zod';
+import { folderStyleNameProblem, isKebabId, KEBAB_ID_DESCRIPTION, KEBAB_ID_FIX, } from '../id.js';
+import { getGlobalDataDir } from '../global-config.js';
+import { FileSystemUtils } from '../../utils/file-system.js';
+import { acquireFileLock, isNodeErrorCode, makeLockErrorFactory, pathIsDirectory, pathIsFile, releaseFileLock, writeFileAtomically, } from '../file-state.js';
+import { formatZodIssues } from '../zod-issues.js';
+import { StoreError } from './errors.js';
+const fs = nodeFs.promises;
+export const STORE_METADATA_DIR_NAME = '.openspec-store';
+export const STORE_METADATA_FILE_NAME = 'store.yaml';
+export const STORES_DIR_NAME = 'stores';
+export const STORE_REGISTRY_FILE_NAME = 'registry.yaml';
+function joinStorePath(basePath, ...segments) {
+    return FileSystemUtils.joinPath(basePath, ...segments);
+}
+export function getStoresDir(options = {}) {
+    return joinStorePath(options.globalDataDir ?? getGlobalDataDir(), STORES_DIR_NAME);
+}
+export function getStoreRegistryPath(options = {}) {
+    return joinStorePath(getStoresDir(options), STORE_REGISTRY_FILE_NAME);
+}
+export function getStoreMetadataDir(storeRoot) {
+    return joinStorePath(storeRoot, STORE_METADATA_DIR_NAME);
+}
+export function getStoreMetadataPath(storeRoot) {
+    return joinStorePath(getStoreMetadataDir(storeRoot), STORE_METADATA_FILE_NAME);
+}
+export function validateStoreId(id) {
+    const folderProblem = folderStyleNameProblem(id, 'Store id');
+    if (folderProblem !== null) {
+        throw new StoreError(folderProblem, 'invalid_store_id', {
+            target: 'store.id',
+            fix: KEBAB_ID_FIX,
+        });
+    }
+    if (!isKebabId(id)) {
+        throw new StoreError(`Store id ${KEBAB_ID_DESCRIPTION}`, 'invalid_store_id', {
+            target: 'store.id',
+            fix: KEBAB_ID_FIX,
+        });
+    }
+    return id;
+}
+export function isValidStoreId(id) {
+    try {
+        validateStoreId(id);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isFileNotFoundError(error) {
+    return isNodeErrorCode(error, 'ENOENT');
+}
+function normalizeExistingPathForStorage(existingPath) {
+    return FileSystemUtils.canonicalizeExistingPath(existingPath);
+}
+function nonEmptyOptionalString() {
+    return z.string().min(1).optional();
+}
+const GitBackendConfigSchema = z.object({
+    type: z.literal('git'),
+    local_path: z.string().min(1),
+    remote: nonEmptyOptionalString(),
+    branch: nonEmptyOptionalString(),
+}).strict();
+const RegistryEntrySchema = z.object({
+    backend: GitBackendConfigSchema,
+}).strict();
+const RegistryStateSchema = z.object({
+    version: z.literal(1),
+    stores: z.record(z.string(), RegistryEntrySchema),
+    // Legacy code-checkout map data is tolerated on read and dropped on
+    // the next write.
+    repos: z.unknown().optional(),
+}).strict();
+const MetadataStateSchema = z.object({
+    version: z.literal(1),
+    id: z.string(),
+    remote: nonEmptyOptionalString(),
+}).strict();
+function storeStateDiagnostic(label) {
+    if (label.includes('metadata')) {
+        return {
+            code: 'invalid_store_metadata',
+            target: 'store.metadata',
+            fix: 'Repair .openspec-store/store.yaml.',
+        };
+    }
+    return {
+        code: 'invalid_store_registry',
+        target: 'store.registry',
+        fix: `Repair or remove ${getStoreRegistryPath({})}.`,
+    };
+}
+function invalidStoreStateError(label, message) {
+    const diagnostic = storeStateDiagnostic(label);
+    return new StoreError(`Invalid ${label}: ${message}`, diagnostic.code, {
+        target: diagnostic.target,
+        fix: diagnostic.fix,
+    });
+}
+function parseYamlObject(content, label) {
+    try {
+        return parseYaml(content);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw invalidStoreStateError(label, message);
+    }
+}
+function assertValidStoreIds(ids, label) {
+    for (const id of ids) {
+        if (!isKebabId(id)) {
+            throw invalidStoreStateError(label, `'${id}': ${KEBAB_ID_DESCRIPTION}`);
+        }
+    }
+}
+export function parseStoreRegistryState(content) {
+    const raw = parseYamlObject(content, 'store registry state');
+    const result = RegistryStateSchema.safeParse(raw);
+    if (!result.success) {
+        throw invalidStoreStateError('store registry state', formatZodIssues(result.error));
+    }
+    assertValidStoreIds(Object.keys(result.data.stores), 'store id');
+    return {
+        version: 1,
+        stores: result.data.stores,
+    };
+}
+export function parseStoreMetadataState(content) {
+    const raw = parseYamlObject(content, 'store metadata state');
+    const result = MetadataStateSchema.safeParse(raw);
+    if (!result.success) {
+        throw invalidStoreStateError('store metadata state', formatZodIssues(result.error));
+    }
+    validateStoreId(result.data.id);
+    return {
+        version: 1,
+        id: result.data.id,
+        ...(result.data.remote !== undefined ? { remote: result.data.remote } : {}),
+    };
+}
+export function serializeStoreRegistryState(state) {
+    const result = RegistryStateSchema.safeParse(state);
+    if (!result.success) {
+        throw invalidStoreStateError('store registry state', formatZodIssues(result.error));
+    }
+    assertValidStoreIds(Object.keys(result.data.stores), 'store id');
+    return stringifyYaml({
+        version: 1,
+        stores: result.data.stores,
+    });
+}
+export function serializeStoreMetadataState(state) {
+    const result = MetadataStateSchema.safeParse(state);
+    if (!result.success) {
+        throw invalidStoreStateError('store metadata state', formatZodIssues(result.error));
+    }
+    validateStoreId(result.data.id);
+    return stringifyYaml({
+        version: 1,
+        id: result.data.id,
+        ...(result.data.remote !== undefined ? { remote: result.data.remote } : {}),
+    });
+}
+export function listStoreRegistryEntries(registry) {
+    return Object.entries(registry.stores)
+        .map(([id, store]) => ({ id, backend: store.backend }))
+        .sort((a, b) => a.id.localeCompare(b.id));
+}
+export async function isStoreRoot(candidateRoot) {
+    return pathIsFile(getStoreMetadataPath(candidateRoot));
+}
+export async function readStoreRegistryState(options = {}) {
+    const registryPath = getStoreRegistryPath(options);
+    if (!(await pathIsFile(registryPath))) {
+        return null;
+    }
+    return parseStoreRegistryState(await fs.readFile(registryPath, 'utf-8'));
+}
+export async function writeStoreRegistryState(state, options = {}) {
+    await writeFileAtomically(getStoreRegistryPath(options), serializeStoreRegistryState(state));
+}
+const storeRegistryLockError = makeLockErrorFactory({
+    createSubject: 'the registry lock file',
+    busyMessage: 'Store registry is busy.',
+    code: 'store_registry_busy',
+    target: 'store.registry',
+});
+export async function updateStoreRegistryState(updater, options = {}) {
+    const registryPath = getStoreRegistryPath(options);
+    const lockPath = `${registryPath}.lock`;
+    const lock = await acquireFileLock({
+        lockPath,
+        errorFor: storeRegistryLockError,
+    });
+    try {
+        const next = await updater(await readStoreRegistryState(options));
+        await writeStoreRegistryState(next, options);
+        return next;
+    }
+    finally {
+        await releaseFileLock(lock, lockPath);
+    }
+}
+export async function readStoreMetadataState(storeRoot) {
+    return parseStoreMetadataState(await fs.readFile(getStoreMetadataPath(storeRoot), 'utf-8'));
+}
+export async function readOptionalStoreMetadataState(storeRoot) {
+    try {
+        return await readStoreMetadataState(storeRoot);
+    }
+    catch (error) {
+        if (isFileNotFoundError(error)) {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function writeStoreMetadataState(storeRoot, state) {
+    await FileSystemUtils.writeFile(getStoreMetadataPath(storeRoot), serializeStoreMetadataState(state));
+}
+export async function resolveGitStoreBackendConfig(input, cwd = process.cwd()) {
+    if (input.localPath.length === 0) {
+        throw new Error('Store local path must not be empty.');
+    }
+    const resolvedPath = path.isAbsolute(input.localPath)
+        ? path.resolve(input.localPath)
+        : path.resolve(cwd, input.localPath);
+    if (!(await pathIsDirectory(resolvedPath))) {
+        throw new Error(`Store local path does not exist: ${input.localPath}`);
+    }
+    if (input.remote !== undefined && input.remote.length === 0) {
+        throw new Error('Store backend remote must not be empty when provided.');
+    }
+    if (input.branch !== undefined && input.branch.length === 0) {
+        throw new Error('Store branch must not be empty when provided.');
+    }
+    return {
+        type: 'git',
+        local_path: normalizeExistingPathForStorage(resolvedPath),
+        ...(input.remote ? { remote: input.remote } : {}),
+        ...(input.branch ? { branch: input.branch } : {}),
+    };
+}
+//# sourceMappingURL=foundation.js.map

package/dist/core/store/git.d.ts

@@ -0,0 +1,23 @@
+export declare function isGitRepositoryAtRoot(storeRoot: string): Promise<boolean>;
+export declare function initGitRepository(storeRoot: string): Promise<boolean>;
+/**
+ * `git var` resolves identity exactly as `git commit` would (config, env vars,
+ * auto-detection), so this fails precisely when the initial commit would.
+ */
+export declare function assertGitCommitIdentity(probeCwd: string): Promise<void>;
+/**
+ * Index-preserving initial commit: the pathspec on `git commit` keeps files
+ * the user had already staged out of setup's commit and leaves them staged.
+ * Pathspecs may be files or directories.
+ */
+export declare function commitStoreFiles(storeRoot: string, id: string, pathspecs: string[]): Promise<boolean>;
+export declare function gitHasCommits(storeRoot: string): Promise<boolean | null>;
+export declare function gitHasUncommittedChanges(storeRoot: string): Promise<boolean | null>;
+export declare function gitHasRemote(storeRoot: string): Promise<boolean | null>;
+/**
+ * The configured origin URL, read from local Git config only — never a
+ * network touch. Null when there is no repository or no origin.
+ */
+export declare function gitOriginUrl(storeRoot: string): Promise<string | null>;
+export declare function gitDirectoryHasTrackedFiles(storeRoot: string, relativeDir: string): Promise<boolean | null>;
+//# sourceMappingURL=git.d.ts.map

package/dist/core/store/git.js

@@ -0,0 +1,137 @@
+import { execFile } from 'node:child_process';
+import * as nodeFs from 'node:fs';
+import * as path from 'node:path';
+import { promisify } from 'node:util';
+import { StoreError } from './errors.js';
+const fs = nodeFs.promises;
+const execFileAsync = promisify(execFile);
+/**
+ * Git mechanics for stores: repository detection, setup-time init and
+ * commit, and the read-only facts doctor reports. Nothing here clones, pulls,
+ * pushes, or syncs — setup-time `git init` plus one initial commit is the
+ * entire write surface.
+ */
+function isSpawnNotFoundError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === 'ENOENT');
+}
+export async function isGitRepositoryAtRoot(storeRoot) {
+    try {
+        const stat = await fs.stat(path.join(storeRoot, '.git'));
+        return stat.isDirectory() || stat.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export async function initGitRepository(storeRoot) {
+    if (await isGitRepositoryAtRoot(storeRoot)) {
+        return false;
+    }
+    try {
+        await execFileAsync('git', ['init'], { cwd: storeRoot });
+    }
+    catch (error) {
+        throw new StoreError(`Failed to initialize Git repository: ${error instanceof Error ? error.message : String(error)}`, 'store_git_init_failed', {
+            target: 'store.git',
+            fix: 'Install Git or rerun setup with --no-init-git.',
+        });
+    }
+    return true;
+}
+/**
+ * `git var` resolves identity exactly as `git commit` would (config, env vars,
+ * auto-detection), so this fails precisely when the initial commit would.
+ */
+export async function assertGitCommitIdentity(probeCwd) {
+    for (const identVar of ['GIT_COMMITTER_IDENT', 'GIT_AUTHOR_IDENT']) {
+        try {
+            await execFileAsync('git', ['var', identVar], { cwd: probeCwd });
+        }
+        catch (error) {
+            if (isSpawnNotFoundError(error)) {
+                throw new StoreError('Git is not available, so setup cannot create the initial store commit.', 'store_git_init_failed', {
+                    target: 'store.git',
+                    fix: 'Install Git or rerun setup with --no-init-git.',
+                });
+            }
+            throw new StoreError('No usable Git commit identity is configured, so setup cannot create the initial store commit.', 'store_git_identity_missing', {
+                target: 'store.git',
+                fix: 'Run git config --global user.name "Your Name" and git config --global user.email "you@example.com", or rerun setup with --no-init-git.',
+            });
+        }
+    }
+}
+/**
+ * Index-preserving initial commit: the pathspec on `git commit` keeps files
+ * the user had already staged out of setup's commit and leaves them staged.
+ * Pathspecs may be files or directories.
+ */
+export async function commitStoreFiles(storeRoot, id, pathspecs) {
+    if (pathspecs.length === 0) {
+        return false;
+    }
+    try {
+        await execFileAsync('git', ['add', '--', ...pathspecs], { cwd: storeRoot });
+        await execFileAsync('git', ['commit', '-m', `Initialize OpenSpec store ${id}`, '--', ...pathspecs], { cwd: storeRoot });
+    }
+    catch (error) {
+        // Best-effort unstage so a failed commit (gpg signing, hooks) does not
+        // leave setup's files in the user's index after rollback deletes them.
+        await execFileAsync('git', ['rm', '--cached', '-r', '-f', '-q', '--', ...pathspecs], {
+            cwd: storeRoot,
+        }).catch(() => undefined);
+        throw new StoreError(`Failed to create the initial store commit: ${error instanceof Error ? error.message : String(error)}`, 'store_git_commit_failed', {
+            target: 'store.git',
+            fix: 'Commit the created files manually, or rerun setup with --no-init-git.',
+        });
+    }
+    return true;
+}
+async function gitProbe(storeRoot, args) {
+    try {
+        const { stdout } = await execFileAsync('git', ['-C', storeRoot, ...args]);
+        return stdout;
+    }
+    catch {
+        return null;
+    }
+}
+export async function gitHasCommits(storeRoot) {
+    try {
+        await execFileAsync('git', ['-C', storeRoot, 'rev-parse', '--verify', '--quiet', 'HEAD']);
+        return true;
+    }
+    catch (error) {
+        if (isSpawnNotFoundError(error))
+            return null;
+        // Exit 1 = repo exists but HEAD has no commits. Anything else (exit 128:
+        // corrupt or fake .git) is unknown, not "commitless".
+        const exitCode = error.code;
+        return exitCode === 1 ? false : null;
+    }
+}
+export async function gitHasUncommittedChanges(storeRoot) {
+    const stdout = await gitProbe(storeRoot, ['status', '--porcelain']);
+    return stdout === null ? null : stdout.trim().length > 0;
+}
+export async function gitHasRemote(storeRoot) {
+    const stdout = await gitProbe(storeRoot, ['remote']);
+    return stdout === null ? null : stdout.trim().length > 0;
+}
+/**
+ * The configured origin URL, read from local Git config only — never a
+ * network touch. Null when there is no repository or no origin.
+ */
+export async function gitOriginUrl(storeRoot) {
+    const stdout = await gitProbe(storeRoot, ['remote', 'get-url', 'origin']);
+    const url = stdout?.trim();
+    return url ? url : null;
+}
+export async function gitDirectoryHasTrackedFiles(storeRoot, relativeDir) {
+    const stdout = await gitProbe(storeRoot, ['ls-files', '--', relativeDir]);
+    return stdout === null ? null : stdout.trim().length > 0;
+}
+//# sourceMappingURL=git.js.map

package/dist/core/store/index.d.ts

@@ -0,0 +1,5 @@
+export * from './foundation.js';
+export * from './errors.js';
+export * from './registry.js';
+export * from './operations.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/store/index.js

@@ -0,0 +1,5 @@
+export * from './foundation.js';
+export * from './errors.js';
+export * from './registry.js';
+export * from './operations.js';
+//# sourceMappingURL=index.js.map

package/dist/core/store/operations.d.ts

@@ -0,0 +1,114 @@
+import { type OpenSpecRootInspection } from '../openspec-root.js';
+import { type StoreGitBackendConfig, type StorePathOptions, type StoreRegistryState } from './foundation.js';
+import { type StoreDiagnostic } from './errors.js';
+type PathKind = 'missing' | 'directory' | 'file' | 'other';
+export interface StoreInfo {
+    id: string;
+    root: string;
+    metadataPath?: string;
+}
+export interface StoreMutationResult {
+    store: StoreInfo;
+    /** Clone-source knowledge for human sharing guidance; never in JSON. */
+    remotes?: {
+        canonical?: string;
+        observed?: string;
+    };
+    registryCommit: {
+        path: string;
+        registered: boolean;
+        alreadyRegistered: boolean;
+    };
+    git: {
+        isRepository: boolean;
+        initialized: boolean;
+        committed: boolean;
+    };
+    createdArtifacts: string[];
+    diagnostics: StoreDiagnostic[];
+}
+export interface StoreCleanupResult {
+    store: StoreInfo;
+    registryCommit: {
+        path: string;
+        removed: boolean;
+    };
+    files: {
+        deleted: boolean;
+        deletedPath?: string;
+        leftOnDisk?: string;
+    };
+    diagnostics: StoreDiagnostic[];
+}
+export interface StoreListResult {
+    stores: StoreInfo[];
+}
+export interface StoreDoctorResult {
+    stores: StoreInspection[];
+    diagnostics: StoreDiagnostic[];
+}
+export interface StoreInspection extends StoreInfo {
+    openspecRoot: OpenSpecRootInspection;
+    metadata: {
+        present: boolean | null;
+        valid: boolean | null;
+        id?: string;
+        /** Canonical clone source from store.yaml; null when absent. */
+        remote: string | null;
+    };
+    git: {
+        isRepository: boolean | null;
+        hasCommits: boolean | null;
+        hasUncommittedChanges: boolean | null;
+        hasRemote: boolean | null;
+        /** Observed origin URL, live-probed; null when none. */
+        originUrl: string | null;
+    };
+    diagnostics: StoreDiagnostic[];
+}
+export interface SetupStoreInput {
+    id?: string;
+    path?: string;
+    initGit?: boolean;
+    allowInsideGitRepository?: boolean;
+    /** Canonical clone source written into store.yaml (slice 3.3). */
+    remote?: string;
+}
+export interface RegisterExistingStoreInput {
+    path?: string;
+    id?: string;
+    allowCreateIdentity?: boolean;
+}
+export interface CleanupStoreInput extends StorePathOptions {
+    id: string;
+}
+export interface PreparedStoreCleanup extends StoreInfo, StorePathOptions {
+    backend: StoreGitBackendConfig;
+}
+export interface PreparedStoreSetup {
+    id: string;
+    root: string;
+    rootKind: Extract<PathKind, 'missing' | 'directory'>;
+    backend?: StoreGitBackendConfig;
+    registry: StoreRegistryState | null;
+    remote?: string;
+}
+export declare function expandUserPath(inputPath: string): string;
+/**
+ * Resolves the effective Git mode for a prepared setup: on by default for new
+ * stores, off for reruns of an already-registered store (which must stay
+ * no-ops), and always honoring an explicit --init-git/--no-init-git.
+ */
+export declare function resolveSetupGitEnabled(prepared: PreparedStoreSetup, initGit?: boolean): boolean;
+export declare function prepareStoreSetup(input: Pick<SetupStoreInput, 'id' | 'path' | 'allowInsideGitRepository' | 'remote'>): Promise<PreparedStoreSetup>;
+export declare function setupPreparedStore(prepared: PreparedStoreSetup, input?: Pick<SetupStoreInput, 'initGit'>): Promise<StoreMutationResult>;
+export declare function setupStore(input: SetupStoreInput): Promise<StoreMutationResult>;
+export declare function registerExistingStore(input: RegisterExistingStoreInput): Promise<StoreMutationResult>;
+export declare function prepareStoreCleanup(input: CleanupStoreInput): Promise<PreparedStoreCleanup>;
+export declare function unregisterStore(input: CleanupStoreInput): Promise<StoreCleanupResult>;
+export declare function removeStore(target: PreparedStoreCleanup): Promise<StoreCleanupResult>;
+export declare function listStores(): Promise<StoreListResult>;
+export declare function doctorStores(id?: string): Promise<StoreDoctorResult>;
+export declare function normalizeStorePathForComparison(targetPath: string): string;
+export {};
+//# sourceMappingURL=operations.d.ts.map