Function resolveNearestOrDeclaredRoot

src/core/root-selection.ts:291–347

(
  nearestRoot: string,
  globalDataDir?: string
)

}

async function resolveNearestOrDeclaredRoot(
  nearestRoot: string,
  globalDataDir?: string
): Promise<ResolvedOpenSpecRoot> {
  const { hasPlanningShape, pointer } = classifyOpenSpecDir(nearestRoot);

  if (hasPlanningShape) {
    if (pointer.value !== undefined) {
      console.error(
        `Warning: ${pointer.filePath} declares store '${pointer.value}', but this directory is a real OpenSpec root; the declaration is ignored.`
      );
    }
    return makeRoot(nearestRoot, 'nearest');
  }

  if (pointer.malformed) {
    const problem = storePointerProblem(pointer.malformed);
    throw new RootSelectionError(
      `Invalid store declaration in ${pointer.filePath}: ${problem}.`,
      'invalid_store_pointer',
      {
        target: 'store.pointer',
        fix:
          pointer.malformed === 'unparseable'
            ? `Fix the YAML syntax in ${pointer.filePath}.`
            : `Edit ${pointer.filePath} so the store key is a registered store id, or remove it.`,
      }
    );
  }

  if (pointer.value === undefined) {
    return makeRoot(nearestRoot, 'nearest');
  }

  try {
    return await resolveStoreRoot(pointer.value, globalDataDir, 'declared');
  } catch (error) {
    if (error instanceof RootSelectionError) {
      // Rewrap with the declaration origin. The unknown-store fix is
      // reshaped for the actual mistake: the user declared a pointer,
      // they did not pass --store.
      const declarationFix =
        error.diagnostic.code === 'unknown_store'
          ? `Register the store (openspec store register <path> --id ${pointer.value}) or edit ${pointer.filePath} to name a registered store.`
          : error.diagnostic.fix;
      throw new RootSelectionError(
        `Declared in ${pointer.filePath}: ${error.message}`,
        error.diagnostic.code,
        {
          ...(error.diagnostic.target ? { target: error.diagnostic.target } : {}),
          ...(declarationFix ? { fix: declarationFix } : {}),
        }
      );
    }
    throw error;
  }
}